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