2 This is a dual-plugin for VDR.
3 The "MP3-Plugin" allows playback of MP3 and other audio files.
4 The "MPlayer-Plugin" is used to call MPlayer for playback of video
7 Written by: Stefan Hülswitt <s.huelswitt@gmx.de>
8 Project's homepage: http://www.muempf.de/
9 Latest version available at: http://www.muempf.de/down/
11 See the file COPYING for license information.
13 ----------------------------------------------------------------------
15 For install instructions see the README file.
16 For MPlayer plugin documentation skip to the end this file.
24 The basic concept of the MP3 plugin is to use playlists for the songs you want
25 to play. So most things designed toward playlists, but you can play directories
26 and single files as well.
28 Available audio codecs:
29 libmad Supports MPEG-1/2/2.5 with layers 1/2/3.
30 libsndfile Supports MS WAV/A-law/u-law; Apple/SGI AIFF/AIFC; Sun/NeXT AU/SND;
31 Amiga IFF/8SVX/16SV and more.
32 libvorbis Supports OGG.
34 The starting point for all MP3 actions (or more generally: all song actions)
35 is the MP3 menu. Select the MP3 entry from VDR's main menu to enter
41 A list of available playlists is displayed (only playlists in your base
42 directory of the selected source are displayed, there is no recursive scanning
43 for playlists). Select the a playlist with "up" and "down". Press "OK" to start
44 playback with the selected playlist.
46 Press the "blue" key to see a second level of buttons. If you are on the second
47 level, press the "red" button to return to the first level.
49 If you are on the first level, press "red" to enter the playlist editor with
50 the selected playlist (see Playlist editor). Press "green" to enter the source
51 selector (see Sources). Press "yellow" to enter the file browser (see Browsing
52 and instant playlists).
54 On the second level, press "green" to create a new, empty playlist and enter
55 the playlist editor. The new playlist will be named "unnamed" followed by a
56 number. Press "yellow" to delete a playlist. There is a double confirmation
57 needed to really delete the playlist. Press "blue" to rename a playlist. You
58 are prompted for a new name. Press "back" to abort renaming.
63 During playback you will see the channel which was tuned last or a black screen
64 depending on what you choose in setup (see Setup options). You can use some
65 keys to control playback:
67 Down skips back to the start of current song or to previous song if you
68 are at the beginning of current song.
70 Up skips forward to the start of next song.
72 Right/Left skips back/forward 3 seconds in current song. Hold key to scan
75 Red enters jump mode. Enter the number of minutes/seconds you want to
76 jump with the number keys. Press "left" to jump backwards, "right"
77 to jump forward and "up" to jump to the absolute position. Press
78 "blue" to toggle the jump unit between minute (m) and seconds (s).
79 Any other key cancels jump mode.
80 Note: jumping forward requires to scan all frame headers until
81 the new position. On slow media or with long jumps this may be
82 visible in the progress display.
84 Green toggles loop and shuffle mode. Press once to enable loop, twice for
85 loop and shuffle and three times for shuffle only. To disable
86 shuffle, wait >4 seconds and press again.
88 Yellow is pause/unpause.
92 Back aborts playback and returns to MP3 menu.
94 Ok toggles progress display. If "ok" is pressed again within 4
95 seconds, the playlist window is opened (playlist window is
96 available with classic progress display mode only). The color bar
97 marks the current song. If the playlist window is open, you can
98 page through the playlist with "left" and "right". If available
99 title/artist is displayed. This is true for songs already played or
100 which have been scanned in background (see Setup options).
102 Menu enters VDR's main menu.
104 0-9 direct song selection. Selection timeout is 1 second.
106 The progress display shows various information bits which are flipped every few
107 seconds. You can adjust which information is shown (see Setup options).
112 In the playlist editor you can add and remove files and shuffle them around.
114 Press "red" to add songs to the playlist. A directory browser is started. You
115 will see the directories and files you created beneath you the base directory
116 of the current source. The entries surrounded by [ ] are directories. If you
117 press "ok" on a directory, you will decent to this directory. Press "red" to
118 add the current file/directory to the playlist. Selecting a directory adds
119 recursively all files from the directory and subdirectories. If you have
120 selected more than one file, you have to confirm the action. The new file(s)
121 will be inserted below the currently selected file in the playlist.
123 Press "green" to toggle between display of filenames and titles/artists (if
124 available). The initial display of title/artist may take some time as all the
125 files have to be scanned. You can configure if the editor is started with
126 title/artist or filename display (see Setup options). Press "ok" over an entry
127 to display a information page for this file.
129 Song information which have been scanned in the playlist editor or during
130 playback are saved to a file called "id3info.cache" located in the video
131 directory. This file is used to speed up display of title/artist for files you
132 already touched. The file is loaded on startup and saved regularly while VDR is
135 Press "yellow" to remove a song from the playlist (the file IS NOT removed from
136 disk, of course). Press "blue" to reorder the songs in the playlist.
138 Browsing and instant playlists:
139 -------------------------------
141 If you enter the browser you can browser through your song files. You can
142 start playback for individual files, playlists and whole directories from here
145 Position on a file or directory and select "red" to start playback. A "instant"
146 playlist is created which contains either the selected file or all files from
147 the selected directory and its subdirectories. When scanning directories, all
148 files matching "*.m3u" (playlists) are ignored. The "instant" playlist is
149 deleted if you stop playback.
151 In the basedir you can press "yellow" to play all files in all directories.
152 Press "blue" over an entry to display the song information page.
154 Sources and playlists:
155 ----------------------
157 It's fine to have all your songs on harddisk, but may be you have some CDROM's
158 with song files on them and you want to play them directly from CDROM? Then
159 this is what you are looking for!
161 You can define multiple sources from which your songs could be played. At
162 runtime you can select which source to use, you can mount, unmount and eject
163 the source at runtime, too. This is done through a config file and a simple
166 First you have to create a config file named "mp3sources.conf" located in the
167 "plugins" subdirectory of the directory where you keep the other config files
168 for VDR (e.g. if your VDR configfiles are in "/video" you must create the files
169 as "/video/plugins/mp3sources.conf").
171 Every line defines a source (see the example config file which comes with the
172 archive). You need three information for a source: the base directory, a
173 description and a flag which determines if a mount/unmount/eject command is
174 applicable to this source. Optionally you can give a fourth information to
175 specify which kind of files should be used on this source. The fields must be
176 separated by a semicolon. The basedir must be a real directory. Using a symlink
177 to a directory will not work.
179 So a valid line could be:
181 This means that the base directory is /mp3, the description say that these are
182 local files and mount/unmount/eject commands can not be applied here.
184 If you want to ignore all files without the ".mp3" extension, you could use:
185 /mp3;Local files;0;*.mp3
186 You can give multiple patterns separated with a slash:
187 /mp3;Local files;0;*.mp3/*.ogg/*.wav
191 This means that the base directory is /cdrom, which is obviously a CDROM drive
192 and mount/unmount/eject commands can be applied here.
194 Note some important things for using mount/unmount/eject commands here:
195 - You must have defined an entry in your /etc/fstab for the base directory.
196 - The user running VDR must have permission to mount/unmount the device (e.g.
197 add "users" to the options in /etc/fstab).
198 - You must have a mount script which can be called from VDR (see below).
200 The actual mount/unmount/eject action is done with a script. See the README
201 file and the example "mount.sh" which comes with the archive.
203 You can create arbitrary directories below the base directory to group your
204 songs. BUT all playlists have to be located in the base directory (the tree is
205 not scanned recursively for playlists).
207 A playlist is a simple text file which contains the paths of the songs to play.
208 One path/filename on every line. The paths must be relative to the base
209 directory (e.g. if you have a MP3 file /mp3/rock/bon_jovi/sample.mp3 a proper
210 line in a playlist would be rock/bon_jovi/sample.mp3). All playlist must have
211 the extension ".m3u".
213 You also can load WinAmp-style playlists, this means that comment lines
214 starting with "#" are ignored and if a line "#EXTM3U" is found, the pathnames
215 are converted from DOS-style to UNIX-style (changing "\" to "/"). The DOS-style
216 pathnames must not contain "/" for proper conversion.
221 If you enter this menu, you will get the list of the sources which you have
222 defined in "mp3sources.conf". Entries marked with ">" can be mounted/unmounted.
223 An entry marked with "*" is currently mounted.
225 Use the "red" key to select a source. All playback and editing functions will
226 refer only to the selected source. Press "green" to mount the source, "yellow"
227 to unmount and "blue" to eject the media.
232 There are various configuration options which can be changed from the plugin
233 setup menu. Select VDR's setup menu, select "Plugins" and select "mp3" to enter
236 Audio output mode: The MP3 plugin supports alternative sound output modes
237 (if activated at compile time). Use this option to
238 select the desired output mode.
240 Audio mode: The MP3 decoder of libmad delivers 24bit data which must
241 be scaled to 16bit for output. You can select how this is
242 done. "round" simply cuts of the LSB bits, while "dither"
243 implements a error diffusion strategy. "dither" takes
244 slightly more CPU power (about 1% on my 400Mhz Celeron).
246 Use 48kHz mode only: Forces the plugin to use the default DVB samplerate of
247 48kHz only. All other are resampled to this value.
249 Display mode: Choose which information is shown in the progress
251 1 - shows only title and artist.
252 2 - additionally shows album and year.
253 3 - additionally shows samplerate, bitrate and number
256 Background mode: Choose what you want to see during playback:
257 Black - a black screen
258 Live - live video from the last tuned channel
259 Images - display cover images (if available)
261 Initial loop mode: Choose if loop mode should be enabled by default.
263 Initial shuffle mode: Choose if shuffle mode should be enabled by default.
265 Abort player at end of list: If you set this option to "no" and the end of
266 playlist is reached, the player is kept idle. To restart
267 playback select a song to restart from there or "up" to
268 restart from the beginning.
270 Background mode: Choose if the background scanner is enabled during
271 playback. In the playlist window, title/artist is shown
272 only for songs already played or which have been scanned
273 in background. There are two scan modes: "ID3 only"
274 gathers information from ID3 tags only, while "ID3 &
275 Level" pre-calculates the level for the normalizer as
276 well. Note that level scan requires to decode the
277 complete song. This is done on a separate thread with
278 nice 5 but nevertheless it needs CPU cycles. If you have
279 a slow CPU your system may crawl.
281 Editor display mode: Choose if the playlist editor shows title/artist or
282 filenames by default. Be warned: the initial display of
283 the title/artist may take some time, as all the files in
284 the playlist have to be scanned. This is specially true
285 for slower storage media.
287 Main menu mode: Choose if you want to see your playlists or if you want
288 to jump to the directory browser when entering the MP3
291 Normalizer level: The volume level for the normalizer. Allowed range is
292 0-50. If set to zero the normalizer is disabled (see The
295 Limiter level: The volume level for the limiter. Samples above this
296 level are limited. Allowed range is 25-100. If set to 100
297 the limiter is disabled (see The normalizer).
299 Use HTTP proxy: Enables use of a HTTP proxy server when playing
300 Shoutcast/Icecast streams.
302 HTTP proxy host: The hostname of the HTTP proxy (used only if you have
303 enabled HTTP proxy option above).
305 HTTP proxy port: The port number to use on the HTTP proxy server (used
306 only if you have enabled HTTP proxy option above).
308 CDDB for CD-Audio: Enables lookups to the CDDB database if cd-audio is
309 played via cdfs. You can choose between local only and
310 local&remote lookups.
312 CDDB server: The hostname of the CDDB server (used only if you have
313 enabled remote lookups above).
315 CDDB port: The port number to use on the CDDB server (used only if
316 you have enabled remote lookups above).
318 Playing Shoutcast/Icecast streams:
319 ----------------------------------
321 The plugin is able to play Shoutcast and Icecast streams (which in fact are
322 just streamed MP3's). This feature needs some special setup:
324 First, your VDR machine must have a connection to the internet (either directly
327 Second, you have to create a simple text file in any of your MP3 source
328 directories for every stream you want to play. The file must contain a single
329 line of text with the complete URL of the stream. E.g. the file could contain
330 (no guarantee that this link still works):
331 http://152.163.134.164:80/stream/1012
332 The link must point to the stream itself and not to any kind of playlist.
334 To play the stream, add the text file to a playlist or select the file from the
335 browser. You cannot pause, FWD or REW a stream.
338 - If you internet connection doesn't provides the bandwidth the stream
339 requires, playback will be distorted.
340 - Any network operation has a timeout of 30 seconds (in case the stream server
341 stalls). You should not set VDR's watchdog timer below this value.
342 - If the stream server provides special Icecast headers or metadata, these
343 values are displayed in the progress display.
348 Very often songs from different albums are recorded at different volume levels.
349 If you have playlists with songs from different albums, it's very likely that
350 you keep adjusting the volume at you amplifier all the time. This is why the
351 MP3 plugin has a function to normalize the volume level of all songs to a
354 The algorithm to calculate and to adjust the volume level was taken from the
355 normalize project <http://www.cs.columbia.edu/~cvaill/normalize/> (version 0.7)
356 from Chris Vaill. Basically the song is divided into chunks, for which the peak
357 level is calculated. From the peak level a moving average value is calculated
358 and the maximum of this is considered a measure for the perceived volume.
359 Please refer to the normalize homepage for more details.
361 This approach has one drawback: you must first decode the complete file to
362 calculate the volume level. For this reason, the normalize function can not be
363 applied if you are listening a song for the very first time. In this case the
364 volume level is calculated and stored to the song cache file. If you are
365 listening to the same songs again, the volume level is read back and the
366 normalize function is applied.
368 There are two parameters for the normalize function which can be changed via
371 The "target level": this is the volume level to which all songs are normalized.
372 The allowed range is 0-50, while useful values are between 25 and 30. Setting
373 the target level to zero disables the normalize function. You shouldn't use
374 this parameter as a volume adjustment (volume adjustment should be done at your
375 amplifier). You should set this parameter slightly above the average volume
376 level of your songs (in my case this is 27). You can use the normalize tool
377 from <http://www.cs.columbia.edu/~cvaill/normalize/> to calculate the volume
378 level for all your songs (if invoked with --fractions, normalize returns a
379 volume level which must be multiplied with 100 to be comparable).
381 The "limiter level": this is the volume level for the limiter function. When
382 boosting up the volume of a songs, it may very well happen that individual
383 samples exceed the allowed range. In this case, one could simply clip the
384 sample to the allowed range, but this would remove too much information from
385 the audio data. So a kind of dynamic compression is applied to the exceeding
386 samples to bring them back to the allowed range without loosing to much. The
387 dynamic compression is applied to all sample above the limiter level. The
388 allowed range is 25-100. Setting the limiter level to 100 disables the dynamic
389 compression and returns to clipping. I'm not sure about the useful range of
390 this parameter. While normalize uses 25, I prefer 70 as this leaves much more
391 audio data untouched.
399 The MPlayer plugin is basically a front-end to MPlayer
400 <http://www.MPlayerHQ.hu/>. You can select a video file from a browser which
401 then is replayed with MPlayer.
406 The MPlayer menu is very similar to the the directory browser of the MP3
407 plugin. You will see the directories and files you created beneath you the base
408 directory of the current source (how to define sources is explained in "Sources
409 and playlists" in the MP3 plugin section, but the config file is named
410 "mplayersources.conf"). The entries surrounded by [ ] are directories. If you
411 press "ok" on a directory, you will descend to this directory. Press "green" to
412 return to the parent directory. Use "yellow" to select a different source (see
413 "The sources menu" in the MP3 plugin section).
415 Press "red" to start replay of the current file. MPlayer will be started with
416 this file through a shell script (see README file).
418 There are two different ways to control MPlayer during replay. The control mode
419 is selected from the MPlayer plugin setup menu.
421 The traditional mode:
422 ---------------------
424 In traditional mode, only "blue" from VDR's remote is active to abort the
425 replay. No other action is passed to MPlayer. It's up to you to configure
426 MPlayer to use whatever control device you want (e.g. LIRC, keyboard).
431 In slave mode the MPlayer plugin acts as a control frontend to MPlayer. All
432 important actions are passed from VDR's remote to MPlayer (see README file on
433 how to setup your mplayer.sh script for this mode). You can use the following
434 keys to control playback:
436 Down is pause/unpause.
438 Up returns to normal replay.
440 Right/Left skips back/forward 10 seconds.
442 Red enters jump mode. Enter the number of minutes/percent you want to
443 jump with the number keys. Press "left" to jump backwards, "right"
444 to jump forward and "up" to jump to the absolute position. Press
445 "blue" to toggle the jump unit between minute (m) and percent (%).
446 Any other key cancels jump mode.
448 Green skips back 60 seconds.
450 Yellow skips forward 60 seconds.
452 Blue/Back aborts playback.
454 Ok toggles progress display.
456 0-9 send MPlayer slave command (configurable in plugin setup menu).
458 In addition the "Volume+","Volume-" and "Mute" keys are routed to MPlayer.
463 There are some configuration options which can be changed from the plugin setup
464 menu. Select VDR's setup menu, select "Plugins" and select "mplayer" to enter
467 Control mode: The MPlayer plugin supports two control modes during
468 replay: traditional and slave (see description above).
470 Resume mode: Selects the mode for resuming playback. "local first"
471 means that the plugin first tries to use a resume file in
472 the directory of the video file. Only if this directory is
473 non-writeable the global resume file is used. "global
474 only" will use the global file only and "disabled"
475 disables resume completely.
477 Slave command key: Customize the slave commands which are send to MPlayer
478 when the remote keys "0" to "9" are pressed.
480 Hide main menu entry: Hides the MPlayer menu entry from the main menu.