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.