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 the user manual see the MANUAL file.
21 By default the Makefile builds both plugins. If you want to use only one of
22 them, you can add one of "WITHOUT_MP3=1" or "WITHOUT_MPLAYER=1" to your
25 In the past month the plugins only have been tested with VDR 1.4.x and 1.5.x.
26 While the plugins probably can be compiled with VDR down to version 1.1.29, this
27 is not tested nor supported.
29 By default any mentioned plugin config file should be located in the "plugins"
30 subdirectory of your VDR config directory (see commandline option -S to specify
31 an plugin specific subdirectory). For a complete description of the config
32 files, see the MANUAL file.
34 The MP3 plugin needs some external libraries (some optionally):
36 You must have installed libmad and libid3tag from
37 <http://www.underbit.com/products/mad/> for decoding MP3 and ID3 support.
38 Recommended version is 0.15.1b. To compile and install I suggest the following
39 sequence from the source directory (libmad and libid3tag are installed
40 separately, so you must execute this once for each directory):
47 For playback of WAV and other sound files you must have installed libsndfile
48 <http://www.mega-nerd.com/libsndfile/> on your system. Recommended version is
49 1.0.11 or newer. The old 0.0.x series doesn't work due to some API changes. To
50 compile and install libsndfile I suggest the following sequence from the
51 libsndfile source directory:
58 If you don't want to install libsndfile, you must add "WITHOUT_LIBSNDFILE=1" to
61 If you want to listen to CD audio, you can use cdfs
62 <http://www.elis.rug.ac.be/~ronsse/cdfs/> (version 0.5c suggested). I suggest
63 that you create a new entry in /etc/fstab and mp3sources.conf for cdfs. The
64 /etc/fstab entry could look like:
65 /dev/hdc /mnt/cdfs cdfs ro,noauto,user 0 0
66 The entry for mp3sources.conf could look like:
68 Or if you want only WAV files to be displayed:
69 /mnt/cdfs;CD-Audio;1;*.wav
70 If you don't like cdfs, you could use any other filesystems which allows to
71 access the CD audio data as WAV files.
73 For playback of OGG files you must have installed libvorbis and libvorbisfile
74 <http://www.xiph.org/ogg/vorbis/> on your system. Most Linux distributions
75 include packages for this.
76 If you don't want to install the vorbis libraries, you must add
77 "WITHOUT_LIBVORBISFILE=1" to your Make.config.
79 The MP3 plugin can output the sound to an OSS soundcard. To compile this
80 support add "WITH_OSS_OUTPUT=1" to your Make.config. The output device defaults
81 to "/dev/dsp" (see commandline option -D too). Don't forget to enable OSS
82 output in the plugin setup menu.
84 Before compiling the plugin, you could have a look at "mp3-config.h". This file
85 includes a number of defines to set options and values at compile time. You
86 should only change defines, if you have understand the source code parts which
87 deal with the define. Improper settings can make the MP3 plugin to fail or to
88 operate unsmoothly. So you should know what you are doing.
90 To build the plugin(s) type:
92 from the VDR source directory.
94 To make the progressbar work with the MPlayer plugin and slave mode you need to
95 apply a small patch to mplayer. Select an appropriate patch file for your
96 MPlayer version from the patches subdirectory. Apply the patch and recompile
99 Early 0.90rc versions of MPlayer need a patch to enabled HEAD driver support
100 too. You will find one for 0.90rc1 in the patches subdirectory. Probably you'll
101 have to point configure to the new DVB include files with
102 --with-extraincdir=/usr/local/src/DVB/include or where ever you have stored the
103 files. MPlayer versions later as 0.90rc5 allow to select HEAD support with a
104 configure option or even detect this automatically.
109 For both plugins it's possible to give an additional configuration subdirectory
110 with commandline option -S/--sources, i.e. the given directory name is appended
111 to the default plugin config directory path.
113 Both plugins have a commandline option -m/--mount to define the name and
114 location of the mount script. The default mount script is "mount.sh". This
115 script is called from the plugin with 2 options on the commandline. The first
116 is one of mount/unmount/eject/status and gives the action to perform. The
117 second one is the base directory as defined in "mp3sources.conf" or
118 "mplayersources.conf". The script must return the exit code 0 if the action was
119 successful and 1 if the action failed (see the comments in the example
120 "mount.sh" script which comes with the archive).
122 The MP3 plugin maintains a cache for information scanned from song files (e.g.
123 ID3 tags). This information is saved to the id3info.cache file by default
124 located in the video directory. You can use commandline option -C/--cache to
125 specify a different directory for this file.
127 If you are using cdfs, the MP3 plugin is able to query a CDDB database for the
128 song information (like title, artist). Local CDDB lookups can be enable from
129 the setup menu and you must give the path to your local CDDB files with
130 commandline option -B/--cddb. The database layout follows the xmcd standard
131 (one subdirectory level for the categories, individual files for every disc).
132 The settings for remote CDDB lookups can be found in the setup menu, too. Any
133 information retrieved from a remote host is stored to your local CDDB database,
134 so the user running VDR needs write access to this directory.
136 If you are using any of the networking capabilities and you have a dial-up
137 network, you can use the commandline option -n/--network to give a script name.
138 This script is called before and after any network access and receives one
139 option on commandline. This can either be "up" or "down", depending on if it's
140 before or after the network access. In the "up" case the script should not
141 return before the network is connected and useable. By default the plugin
142 assumes that network access can be done at any time without prior action.
144 If you want to use the OSS output capability but your soundcard device is not
145 "/dev/dsp" (which is the default) you can use the commandline option -D/--dsp
146 to give an alternative soundcard device.
148 If you want to use the cover image display, you have to provide an image
149 converting script. Usually your covers are in a common image format like e.g.
150 JPEG or PNG, but the MP3 plugin can only display MPEG (still) frames. The
151 conversion is done by the script, which takes two arguments: first the filename
152 of the image file and second the filename or the resulting MPEG file. The
153 script also has to take care that any needed subdirectories in the cache are
154 created e.g. mkdir -p. You will find an example script in the examples
155 subdirectory. By default the script is called "image_convert.sh", but you can
156 use the commandline option -i/--iconv to change the name and location of the
158 To speed up consecutive accesses to the same image, the converted frames are
159 cached on disk. The default cache directory is "/var/cache/images/mp3". You can
160 change this location with the commandline option -c/--icache.
161 Don't forget to enable the image display in the plugin setup menu.
162 The search order for images is:
163 - An image in the same directory as the song, named like the song but with the
164 song extension replaced with the image format extension
165 e.g. test.mp3 -> test.jpg
166 - An image named "cover" with the image format extension in the same directory
167 as the song (album cover).
169 - An image named "artist" with the image format extension in the parent
170 directory of the song (artist image).
172 - An image named "background" with the image format extension in the base
173 directory of the MP3 source.
174 For all locations the extensions "jpg", "png" & "gif" are checked (in that
175 order). If no image can be found, a full screen black image is displayed (this
176 is included statically in the plugin).
178 MPlayer is called through a script called "mplayer.sh" with the filename to
179 play as first argument and the phrase SLAVE as second argument if slave mode is
180 enabled. You can use the commandline option -M/--mplayer to change the name and
181 location of the mplayer script. The script has to call MPlayer with all the
184 The script should parse the SLAVE keyword too and give appropriate options to
185 MPlayer. To enable slave mode you must give at least the "-slave" option, while
186 I suggest "-slave -nolirc -quiet".
188 You can use the mplayer.sh.example file, which comes with the archive, as a
189 starting point. Juri Haberland maintains a full featured mplayer.sh file which
190 is available at <http://batleth.sapienti-sat.org/projects/VDR/>.
192 For the MPlayer plugin you can give a location for the global resume file with
193 commandline option -R/--resume.
196 Summary of commandline options:
197 -------------------------------
200 -m CMD, --mount=CMD use CMD to mount/unmount/eject mp3 sources
201 -n CMD, --network=CMD execute CMD before & after network access
202 -B DIR, --cddb=DIR search CDDB files in DIR
203 -C DIR, --cache=DIR store ID3 cache file in DIR
204 -D DIR, --dsp=DIR device for OSS output
205 -i CMD, --iconv=CMD use CMD to convert background images
206 -c DIR, --icache=DIR cache converted images in DIR
207 -S SUB, --sources=SUB search sources config in SUB subdirectory
210 -m CMD, --mount=CMD use CMD to mount/unmount/eject mplayer sources
211 -M CMD, --mplayer=CMD use CMD when calling MPlayer
212 -S SUB, --sources=SUB search sources config in SUB subdirectory
213 -R DIR, --resume=DIR store global resume file in DIR