This is a dual-plugin for VDR. The "MP3-Plugin" allows playback of MP3 and other audio files. The "MPlayer-Plugin" is used to call MPlayer for playback of video files (e.g. DivX) Written by: Stefan Hülswitt <s.huelswitt@gmx.de> Project's homepage: http://www.muempf.de/ Latest version available at: http://www.muempf.de/down/ See the file COPYING for license information. ---------------------------------------------------------------------- For install instructions see the README file. For MPlayer plugin documentation skip to the end this file. **** **** **** MP3 plugin **** **** The basic concept of the MP3 plugin is to use playlists for the songs you want to play. So most things designed toward playlists, but you can play directories and single files as well. Available audio codecs: libmad Supports MPEG-1/2/2.5 with layers 1/2/3. libsndfile Supports MS WAV/A-law/u-law; Apple/SGI AIFF/AIFC; Sun/NeXT AU/SND; Amiga IFF/8SVX/16SV and more. libvorbis Supports OGG. The starting point for all MP3 actions (or more generally: all song actions) is the MP3 menu. Select the MP3 entry from VDR's main menu to enter this menu. The MP3 menu: ------------- A list of available playlists is displayed (only playlists in your base directory of the selected source are displayed, there is no recursive scanning for playlists). Select the a playlist with "up" and "down". Press "OK" to start playback with the selected playlist. Press the "blue" key to see a second level of buttons. If you are on the second level, press the "red" button to return to the first level. If you are on the first level, press "red" to enter the playlist editor with the selected playlist (see Playlist editor). Press "green" to enter the source selector (see Sources). Press "yellow" to enter the file browser (see Browsing and instant playlists). On the second level, press "green" to create a new, empty playlist and enter the playlist editor. The new playlist will be named "unnamed" followed by a number. Press "yellow" to delete a playlist. There is a double confirmation needed to really delete the playlist. Press "blue" to rename a playlist. You are prompted for a new name. Press "back" to abort renaming. During playback: ---------------- During playback you will see the channel which was tuned last or a black screen depending on what you choose in setup (see Setup options). You can use some keys to control playback: Down skips back to the start of current song or to previous song if you are at the beginning of current song. Up skips forward to the start of next song. Right/Left skips back/forward 3 seconds in current song. Hold key to scan through song. Red enters jump mode. Enter the number of minutes/seconds you want to jump with the number keys. Press "left" to jump backwards, "right" to jump forward and "up" to jump to the absolute position. Press "blue" to toggle the jump unit between minute (m) and seconds (s). Any other key cancels jump mode. Note: jumping forward requires to scan all frame headers until the new position. On slow media or with long jumps this may be visible in the progress display. Green toggles loop and shuffle mode. Press once to enable loop, twice for loop and shuffle and three times for shuffle only. To disable shuffle, wait >4 seconds and press again. Yellow is pause/unpause. Blue aborts playback. Back aborts playback and returns to MP3 menu. Ok toggles progress display. If "ok" is pressed again within 4 seconds, the playlist window is opened (playlist window is available with classic progress display mode only). The color bar marks the current song. If the playlist window is open, you can page through the playlist with "left" and "right". If available title/artist is displayed. This is true for songs already played or which have been scanned in background (see Setup options). Menu enters VDR's main menu. 0-9 direct song selection. Selection timeout is 1 second. The progress display shows various information bits which are flipped every few seconds. You can adjust which information is shown (see Setup options). The playlist editor: -------------------- In the playlist editor you can add and remove files and shuffle them around. Press "red" to add songs to the playlist. A directory browser is started. You will see the directories and files you created beneath you the base directory of the current source. The entries surrounded by [ ] are directories. If you press "ok" on a directory, you will decent to this directory. Press "red" to add the current file/directory to the playlist. Selecting a directory adds recursively all files from the directory and subdirectories. If you have selected more than one file, you have to confirm the action. The new file(s) will be inserted below the currently selected file in the playlist. Press "green" to toggle between display of filenames and titles/artists (if available). The initial display of title/artist may take some time as all the files have to be scanned. You can configure if the editor is started with title/artist or filename display (see Setup options). Press "ok" over an entry to display a information page for this file. Song information which have been scanned in the playlist editor or during playback are saved to a file called "id3info.cache" located in the video directory. This file is used to speed up display of title/artist for files you already touched. The file is loaded on startup and saved regularly while VDR is running. Press "yellow" to remove a song from the playlist (the file IS NOT removed from disk, of course). Press "blue" to reorder the songs in the playlist. Browsing and instant playlists: ------------------------------- If you enter the browser you can browser through your song files. You can start playback for individual files, playlists and whole directories from here too. Position on a file or directory and select "red" to start playback. A "instant" playlist is created which contains either the selected file or all files from the selected directory and its subdirectories. When scanning directories, all files matching "*.m3u" (playlists) are ignored. The "instant" playlist is deleted if you stop playback. In the basedir you can press "yellow" to play all files in all directories. Press "blue" over an entry to display the song information page. Sources and playlists: ---------------------- It's fine to have all your songs on harddisk, but may be you have some CDROM's with song files on them and you want to play them directly from CDROM? Then this is what you are looking for! You can define multiple sources from which your songs could be played. At runtime you can select which source to use, you can mount, unmount and eject the source at runtime, too. This is done through a config file and a simple shell script. First you have to create a config file named "mp3sources.conf" located in the "plugins" subdirectory of the directory where you keep the other config files for VDR (e.g. if your VDR configfiles are in "/video" you must create the files as "/video/plugins/mp3sources.conf"). Every line defines a source (see the example config file which comes with the archive). You need three information for a source: the base directory, a description and a flag which determines if a mount/unmount/eject command is applicable to this source. Optionally you can give a fourth information to specify which kind of files should be used on this source. The fields must be separated by a semicolon. The basedir must be a real directory. Using a symlink to a directory will not work. So a valid line could be: /mp3;Local files;0 This means that the base directory is /mp3, the description say that these are local files and mount/unmount/eject commands can not be applied here. If you want to ignore all files without the ".mp3" extension, you could use: /mp3;Local files;0;*.mp3 You can give multiple patterns separated with a slash: /mp3;Local files;0;*.mp3/*.ogg/*.wav Another useful one: /cdrom;CDROM;1 This means that the base directory is /cdrom, which is obviously a CDROM drive and mount/unmount/eject commands can be applied here. Note some important things for using mount/unmount/eject commands here: - You must have defined an entry in your /etc/fstab for the base directory. - The user running VDR must have permission to mount/unmount the device (e.g. add "users" to the options in /etc/fstab). - You must have a mount script which can be called from VDR (see below). The actual mount/unmount/eject action is done with a script. See the README file and the example "mount.sh" which comes with the archive. You can create arbitrary directories below the base directory to group your songs. BUT all playlists have to be located in the base directory (the tree is not scanned recursively for playlists). A playlist is a simple text file which contains the paths of the songs to play. One path/filename on every line. The paths must be relative to the base directory (e.g. if you have a MP3 file /mp3/rock/bon_jovi/sample.mp3 a proper line in a playlist would be rock/bon_jovi/sample.mp3). All playlist must have the extension ".m3u". You also can load WinAmp-style playlists, this means that comment lines starting with "#" are ignored and if a line "#EXTM3U" is found, the pathnames are converted from DOS-style to UNIX-style (changing "\" to "/"). The DOS-style pathnames must not contain "/" for proper conversion. The sources menu: ----------------- If you enter this menu, you will get the list of the sources which you have defined in "mp3sources.conf". Entries marked with ">" can be mounted/unmounted. An entry marked with "*" is currently mounted. Use the "red" key to select a source. All playback and editing functions will refer only to the selected source. Press "green" to mount the source, "yellow" to unmount and "blue" to eject the media. Setup options: -------------- There are various configuration options which can be changed from the plugin setup menu. Select VDR's setup menu, select "Plugins" and select "mp3" to enter the setup menu. Audio output mode: The MP3 plugin supports alternative sound output modes (if activated at compile time). Use this option to select the desired output mode. Audio mode: The MP3 decoder of libmad delivers 24bit data which must be scaled to 16bit for output. You can select how this is done. "round" simply cuts of the LSB bits, while "dither" implements a error diffusion strategy. "dither" takes slightly more CPU power (about 1% on my 400Mhz Celeron). Use 48kHz mode only: Forces the plugin to use the default DVB samplerate of 48kHz only. All other are resampled to this value. Display mode: Choose which information is shown in the progress display: 1 - shows only title and artist. 2 - additionally shows album and year. 3 - additionally shows samplerate, bitrate and number of channels. Background mode: Choose what you want to see during playback: Black - a black screen Live - live video from the last tuned channel Images - display cover images (if available) Initial loop mode: Choose if loop mode should be enabled by default. Initial shuffle mode: Choose if shuffle mode should be enabled by default. Abort player at end of list: If you set this option to "no" and the end of playlist is reached, the player is kept idle. To restart playback select a song to restart from there or "up" to restart from the beginning. Background mode: Choose if the background scanner is enabled during playback. In the playlist window, title/artist is shown only for songs already played or which have been scanned in background. There are two scan modes: "ID3 only" gathers information from ID3 tags only, while "ID3 & Level" pre-calculates the level for the normalizer as well. Note that level scan requires to decode the complete song. This is done on a separate thread with nice 5 but nevertheless it needs CPU cycles. If you have a slow CPU your system may crawl. Editor display mode: Choose if the playlist editor shows title/artist or filenames by default. Be warned: the initial display of the title/artist may take some time, as all the files in the playlist have to be scanned. This is specially true for slower storage media. Main menu mode: Choose if you want to see your playlists or if you want to jump to the directory browser when entering the MP3 menu. Normalizer level: The volume level for the normalizer. Allowed range is 0-50. If set to zero the normalizer is disabled (see The normalizer). Limiter level: The volume level for the limiter. Samples above this level are limited. Allowed range is 25-100. If set to 100 the limiter is disabled (see The normalizer). Use HTTP proxy: Enables use of a HTTP proxy server when playing Shoutcast/Icecast streams. HTTP proxy host: The hostname of the HTTP proxy (used only if you have enabled HTTP proxy option above). HTTP proxy port: The port number to use on the HTTP proxy server (used only if you have enabled HTTP proxy option above). CDDB for CD-Audio: Enables lookups to the CDDB database if cd-audio is played via cdfs. You can choose between local only and local&remote lookups. CDDB server: The hostname of the CDDB server (used only if you have enabled remote lookups above). CDDB port: The port number to use on the CDDB server (used only if you have enabled remote lookups above). Playing Shoutcast/Icecast streams: ---------------------------------- The plugin is able to play Shoutcast and Icecast streams (which in fact are just streamed MP3's). This feature needs some special setup: First, your VDR machine must have a connection to the internet (either directly or through a proxy). Second, you have to create a simple text file in any of your MP3 source directories for every stream you want to play. The file must contain a single line of text with the complete URL of the stream. E.g. the file could contain (no guarantee that this link still works): http://152.163.134.164:80/stream/1012 The link must point to the stream itself and not to any kind of playlist. To play the stream, add the text file to a playlist or select the file from the browser. You cannot pause, FWD or REW a stream. Note: - If you internet connection doesn't provides the bandwidth the stream requires, playback will be distorted. - Any network operation has a timeout of 30 seconds (in case the stream server stalls). You should not set VDR's watchdog timer below this value. - If the stream server provides special Icecast headers or metadata, these values are displayed in the progress display. The normalizer: --------------- Very often songs from different albums are recorded at different volume levels. If you have playlists with songs from different albums, it's very likely that you keep adjusting the volume at you amplifier all the time. This is why the MP3 plugin has a function to normalize the volume level of all songs to a common level. The algorithm to calculate and to adjust the volume level was taken from the normalize project <http://www.cs.columbia.edu/~cvaill/normalize/> (version 0.7) from Chris Vaill. Basically the song is divided into chunks, for which the peak level is calculated. From the peak level a moving average value is calculated and the maximum of this is considered a measure for the perceived volume. Please refer to the normalize homepage for more details. This approach has one drawback: you must first decode the complete file to calculate the volume level. For this reason, the normalize function can not be applied if you are listening a song for the very first time. In this case the volume level is calculated and stored to the song cache file. If you are listening to the same songs again, the volume level is read back and the normalize function is applied. There are two parameters for the normalize function which can be changed via setup menu: The "target level": this is the volume level to which all songs are normalized. The allowed range is 0-50, while useful values are between 25 and 30. Setting the target level to zero disables the normalize function. You shouldn't use this parameter as a volume adjustment (volume adjustment should be done at your amplifier). You should set this parameter slightly above the average volume level of your songs (in my case this is 27). You can use the normalize tool from <http://www.cs.columbia.edu/~cvaill/normalize/> to calculate the volume level for all your songs (if invoked with --fractions, normalize returns a volume level which must be multiplied with 100 to be comparable). The "limiter level": this is the volume level for the limiter function. When boosting up the volume of a songs, it may very well happen that individual samples exceed the allowed range. In this case, one could simply clip the sample to the allowed range, but this would remove too much information from the audio data. So a kind of dynamic compression is applied to the exceeding samples to bring them back to the allowed range without loosing to much. The dynamic compression is applied to all sample above the limiter level. The allowed range is 25-100. Setting the limiter level to 100 disables the dynamic compression and returns to clipping. I'm not sure about the useful range of this parameter. While normalize uses 25, I prefer 70 as this leaves much more audio data untouched. **** **** **** MPlayer plugin **** **** The MPlayer plugin is basically a front-end to MPlayer <http://www.MPlayerHQ.hu/>. You can select a video file from a browser which then is replayed with MPlayer. The MPlayer menu: ----------------- The MPlayer menu is very similar to the the directory browser of the MP3 plugin. You will see the directories and files you created beneath you the base directory of the current source (how to define sources is explained in "Sources and playlists" in the MP3 plugin section, but the config file is named "mplayersources.conf"). The entries surrounded by [ ] are directories. If you press "ok" on a directory, you will descend to this directory. Press "green" to return to the parent directory. Use "yellow" to select a different source (see "The sources menu" in the MP3 plugin section). Press "red" to start replay of the current file. MPlayer will be started with this file through a shell script (see README file). There are two different ways to control MPlayer during replay. The control mode is selected from the MPlayer plugin setup menu. The traditional mode: --------------------- In traditional mode, only "blue" from VDR's remote is active to abort the replay. No other action is passed to MPlayer. It's up to you to configure MPlayer to use whatever control device you want (e.g. LIRC, keyboard). The slave mode: --------------- In slave mode the MPlayer plugin acts as a control frontend to MPlayer. All important actions are passed from VDR's remote to MPlayer (see README file on how to setup your mplayer.sh script for this mode). You can use the following keys to control playback: Down is pause/unpause. Up returns to normal replay. Right/Left skips back/forward 10 seconds. Red enters jump mode. Enter the number of minutes/percent you want to jump with the number keys. Press "left" to jump backwards, "right" to jump forward and "up" to jump to the absolute position. Press "blue" to toggle the jump unit between minute (m) and percent (%). Any other key cancels jump mode. Green skips back 60 seconds. Yellow skips forward 60 seconds. Blue/Back aborts playback. Ok toggles progress display. 0-9 send MPlayer slave command (configurable in plugin setup menu). In addition the "Volume+","Volume-" and "Mute" keys are routed to MPlayer. Setup options: -------------- There are some configuration options which can be changed from the plugin setup menu. Select VDR's setup menu, select "Plugins" and select "mplayer" to enter the setup menu. Control mode: The MPlayer plugin supports two control modes during replay: traditional and slave (see description above). Resume mode: Selects the mode for resuming playback. "local first" means that the plugin first tries to use a resume file in the directory of the video file. Only if this directory is non-writeable the global resume file is used. "global only" will use the global file only and "disabled" disables resume completely. Slave command key: Customize the slave commands which are send to MPlayer when the remote keys "0" to "9" are pressed. Hide main menu entry: Hides the MPlayer menu entry from the main menu.