FILE:        README
DESCRIPTION: readme for 'mplay.sh'
AUTHOR:      Thomas Hildebrandt <toxym@web.de>
VERSION:     0.5.3
DATE:        28/04/2007

See the file COPYING for license information.


 MOTIVATION
--------------------------------
The (with no doubt very good) script 'mplayer.sh' shows some limitations,
which I wish to eliminate with the development of this script.

Concrete:
* displaying in OSD of VDR
  I found the displaying of the complete file name (incl. extension) never
  particularly stylish. I like an entry, appearing only with the name of the
  movie.
* mixed playlists with different file types
  Every file of a playlist can have it's own configuration.
  I think, this can't be realized with MPlayer's '-playlist' option.


 FEATURES
--------------------------------
* extensible concept
  every file type and every stream within a file can have its own
  configuration
* playlists
  up to now only text files, one file per line; m3u works well, if the paths
  are okay


 PREQUISITES
--------------------------------
* MPlayer-1.0rc1
  (former versions may work, but with no warranty)


 PERSPECTIVE
--------------------------------
Wouldn't it be cool, if the complete logic of such a MPlayer calling script
could be coded in a plugin........ ;-)


 INSTALLATION
--------------------------------
see INSTALL


 OPERATION
--------------------------------
'mplay.sh' is a direct substitution for the 'mplayer.sh'. Therefore it should
and have to work with the MPlayer plugin without changes.
Details can be found in 'INSTALL'.

The underlying concept is similar to 'mplayer.sh':
>>> Get a file and play it and do it smart. <<<

The informations to do so 'mplay.sh' finds in its configuration files.
Based on this informations the script builds a command line to start MPlayer.


 EXAMPLES
--------------------------------
The process is best explained with some examples. The following system
configuration is supposed:

configuration directory:               /etc/vdr/plugins/mplay
media directory:                       /media
display directory for MPlayer plugin:  /media/sets
 (example entry for mplayersources.conf: /media/sets;Movies;0)

*** Playing an AVI (from the media directory)
  The file is assumed as '/media/movies/Movie.avi'. To display this movie in
  MPlayer plugin without its extension, you have to create an (empty) file
  in '/media/sets' with the name 'Movie' (touch /media/sets/Movie).
  On calling, 'mplay.sh' gets the file '/media/sets/Movie' as argument,
  find this file without an extension and empty, assumes, there is a 'Movie'
  with appropriate extension in '/media' (or subdirectories) and searches
  for it. What it is searching for comes from 'mplayrc' (parameter
  MPLAY_TYPES).
  If the file to play was found, 'mplay.sh' loads the settings from
  '/etc/vdr/plugins/mplay/avi.conf', if this file can be found.
  After this (normally) comes the identifying of the several data streams
  (video and audio). When, for instance, the fourcc 'XVID' and an 'A52'
  audio stream can be identified, the script tries to load settings from
  '/etc/vdr/plugins/mplay/xvid.conf' and
  '/etc/vdr/plugins/mplay/video-a52.conf'.
  Now are all options found, the file can be played.

*** Playing an AVI (from DVD)
  The file is assumed as '/mnt/dvd/Movie.avi'. The mounting of the DVD is
  done by the MPlayer plugin, 'mplay.sh' simply gets the file name.
  The file owns the correct extension and no search in '/media' is needed.
  The further process is as already described.

*** Playing a M3U playlist
  The file is assumed as '/media/music/MySongs.m3u', the content my be
  something like this:
    ...
    /media/music/pop/poppy.mp3
    rock/rocky.aac
    ...

  Hint: You can either create a file named 'MySongs' in the display
        directory (configure 'mplay.sh' to search also for 'm3u') or
        define a source in 'mplayersources.conf' to a directory with
        all your M3U's.

  For 'm3u' is MPLAY_PLAYLIST defined. This causes 'mplay.sh' to get
  every single file from the M3U and do the complete identification
  process for it.

*** Playing an AAC or MP3
  Process goes like described no video output will be generated because
  no video stream can be found.

*** DD 5.1
  When identifying an AC3 data stream ('A52'), audio options will be set
  according to 'a52.conf' or 'video-a52.conf'.
  In addition you can pimp normal stereo files (mp3, aac) to 5.1. Simply
  use in 'mp3.conf' and/or 'aac.conf' the row '. "$CONFDIR/music.conf"'
  to load additional options. MPlayer creates now 3 more channels and
  distribute them to front and rear speakers plus subwoofer.


 DOLBY DIGITAL
--------------------------------
Current configuration is more conservative with output to the DVB card.
This causes MPlayer to calculate a stereo signal from the 5.1 stream.
If you want 'real' 5.1 sound, have a look at 'mplayrc' and 'video-52.conf'.
* 5.1 output by sound card (ALSA)
  in 'mplayrc'       : MPLAY_AO=alsa
  in 'video-a52.conf': activate MPLAY_TYPE_OPTIONS="-channels 6" and maybe
                       MPLAY_DD20
* route AC3 data stream to external decoder/receiver
  in 'video-a52.conf': activate MPLAY_TYPE_OPTIONS="-ac hwac3,"
                       (untested, maybe some experiments needed)


 SUBTITLE
--------------------------------
Subtitle are identified and processed like usually done by MPlayer (file name
of subtitle file is identically to the movie file name except the extension).
To handle subtitles as flexible as the other file types, 'mplay.sh' searches
for and loads an appropriate configuration file after identifying the subtitle
file. Therefore global options can be set and specials too for several subtitle
types.

Example: If for a 'movie.avi' a 'movie.srt' can be found, this will be
recognized and a 'srt.conf' will be load, if it exists.


 HINTS
--------------------------------
* IMPORTANT: The files/sets in the display directory MUST NOT be links, but
  real files
* The configuration files for audio data are separated in files for pure
  audio and for audio within video. The configuration for playing i.e. a
  simple MP3 may be different from the configuration of playing a MP3
  audio stream of a video.
  A special configuration file can be created. Example: 'video-mp3.conf'
  'mplay.sh' tries to read the 'video-mp3.conf' instead of 'mp3.conf'
  when a video stream can be identified.
* There is no parameter like 'SLOWCPU' or so. If your machine doesn't run
  with 720x576 (video jerks) set 'MPLAY_RES1=352x288' and leave
  MPLAY_RES2 and MPLAY_RES3 unset.
* Default audio out is the FF-card ('mpegpes'). If you want to hear 5.1-sound,
  set 'MPLAY_AOUT=alsa' and take a look at the settings in 'video.conf' and
  maybe in 'music.conf'.
  ATTENTION: Take care for appropriate volume control of your soundcard in
             this case.


 PARAMETER
--------------------------------
All of the following parameters can by principle go into every config file.
This way, parameters can be completed or overwritten.

MPLAY_AF
  regularly defined in: SET file
         default value: <not set>
           description: parameter for MPlayer's audio filter (-af)

MPLAY_AOUT
  regularly defined in: mplayrc
         default value: mpegpes
           description: the audio output device for MPlayer

MPLAY_ASPECT
  regularly defined in: mplayrc
         default value: yes
           description: if set, 'mplay.sh' tries to calculate the correct
	                video resolution according to the identification
			values from MPlayer

MPLAY_DD20
  regularly defined in: video-a52.conf
         default value: see 'video-a52.conf'
           description: special parameter, if an AC3 audio stream is identified
	                but this stream is 2.0 only

MPLAY_DEBUG
  regularly defined in: mplayrc
         default value: <not set>
           description: if set (to any value) some messages will be written
                        to the system log

MPLAY_DIRECT
  regularly defined in: SET file
         default value: <not set>
           description: setting this option causes a call of MPlayer with
                        (only) this parameters and the file to play;
            'mplay.sh' exits after this

MPLAY_FILE
  regularly defined in: SET file
         default value: <not set>
           description: defines in a SET file the file to play

MPLAY_FIXVDRSOUND
  regularly defined in: mplayrc
         default value: <not set>
           description: If 'MPLAY_AOUT' is set to 'alsa', the VDR sound maybe
	                doesn't stop, when playing with 'mplay.sh'. Set this
			to 'yes' and 'mplay.sh' will do a workaround.
			Minor detail: After 'mplay.sh', VDR stays muted until
			you change the VDR volume.

MPLAY_GLOBAL
  regularly defined in: mplayrc
         default value: "-quiet -nolirc -cache 8192"
           description: global options for MPlayer

MPLAY_IDENTIFY
  regularly defined in: mplayrc
         default value: yes
           description: causes the an identification try for the file to play
                        (ATTENTION: If this is not set to 'yes', every single
                        parameter have to be set manually in the SET file[s])

MPLAY_LAVC
  regularly defined in: mplayrc
         default value: 4600:25
           description: concerns MPlayer's 'lavc' video filter and describes
                        the date rate for the on-the-fly MPEG1 data stream
                        creation by MPlayer. The value depends on the
                        performance of your system.
                        As start point '4000:25' may be good. The value
                        (before the colon) can be increased until your video
                        begins to jerk.

MPLAY_LOGGER
  regularly defined in: mplayrc
         default value: "logger -i -t mplay.sh"
           description: if set 'MPLAY_DEBUG', this is the program to do the
                        logging

MPLAY_MEDIA_DIR
  regularly defined in: mplayrc
         default value: an existing directory
           description: the directory with your files to play (can contain
                        subdirectories as you like it)

MPLAY_MULTI
  regularly defined in: mplayrc
         default value: <not set>
           description: if you intend to use 'mplayer-multi', set this to the
	                programs name or path

MPLAY_MPLAYER
  regularly defined in: mplayrc
         default value: mplayer
           description: the command to call MPlayer

MPLAY_PADDING
  regularly defined in: any configuration file
         default value: <not set>
           description: creates a black border around the video
                        (overscan compensation for TV sets)

MPLAY_PLAY
  regularly defined in: mplayrc
         default value: ~/mplay.play
           description: for playing, 'mplay.sh' creates a temporary file
                        with the complete MPlayer call. This parameter tells
                        'mplay.sh' where to create this file.

MPLAY_PLAYLIST
  regularly defined in: file type configuration file
         default value: <not set>
           description: marks this file type as a playlist

MPLAY_PP
  regularly defined in: mplayrc
         default value: <not set>
           description: options for MPlayer's 'pp' video filter

MPLAY_RES1
MPLAY_RES2
MPLAY_RES3
  regularly defined in: mplayrc
        default values: 720x576
                        640x480
                        352x288
           description: Up to 3 output resolutions can be defined. The highest
                        one goes to MPLAY_RES1. 'mplay.sh' scales a video,
                        depending on MPLAY_SCALE, to the next available
                        resolution.
                        MPLAY_RES1 is always mandatory. MPLAY_RES3 will not be
                        noted, when MPLAY_RES2 is not defined
                        (HINT: The resolution 640x480 results on some cards
                        to a corrupt output.)

MPLAY_RESOLUTION
  regularly defined in: SET file
         default value: <not set>
           description: forces a certain output resolution
                        (ATTENTION: NOT every solution is supported by normal
                        FF cards.)

MPLAY_SCALE_ALWAYS
  regularly defined in: SET file
         default value: <not set>
           description: forces the MPlayer video filter option 'scale=...',
                        even, if this seems to be not necessary
                        (helps in case of image interferences)

MPLAY_SCALE
  regularly defined in: mplayrc
         default value: up
           description: When set to 'up', video output will be scaled to the
                        next higher resolution, else to the next lower
                        (Example: Video may be 640x272, possible resolutions
                         may be 720x576 and 352x288. With 'MPLAY_SCALE=up'
                         playing is done with 720x576, without the parameter
                         with 352x288.)

MPLAY_SOUNDSET
  regularly defined in: SET file
         default value: <not set>
           description: defines, which Soundset should be used for this file
                        (see 'MPLAY_WITH_SNDCTL')

MPLAY_SUB_SHOW
  regularly defined in: mplayrc
         default value: yes
	   description: causes 'mplay.sh' to show subtitles, if indentified

MPLAY_SUB_POS
  regularly defined in: mplayrc
         default value: 95
	   description: vertical position of subtitles in % of the screen
	                height

MPLAY_SUB_WIDTH
  regularly defined in: mplayrc
         default value: 95
	   description: maximum width of subtitles in % of screen width

MPLAY_SUB_DELAY
  regularly defined in: mplayrc
         default value: <not set>
	   description: delay, when displaying subtitles (in seconds)

MPLAY_SUB_BG_ALPHA
  regularly defined in: mplayrc
         default value: <not set>
	   description: background transparency for subtitles (and OSD)

MPLAY_SUB_BG_COLOR
  regularly defined in: mplayrc
         default value: <not set>
	   description: background color for subtitles (and OSD)

MPLAY_SVDR
  regularly defined in: mplayrc
         default value: svdrpsend.pl
	   description: program to send SVDR commands to VDR
	                (needed e.g. by 'MPLAY_WITH_SNDCTL')

MPLAY_TV
  regularly defined in: mplayrc
         default value: <not set>
	   description: TV aspect correction factor
	                This value is simply multiplied with the calculated
			(and aspect corrected) vertical video resolution.
			(Use a fraction like "7/5" instead of "1.4".)

MPLAY_TYPE_OPTIONS
  regularly defined in: file type configuration file
         default value: <not set>
           description: special options for this file type are defined here

MPLAY_TYPES
  regularly defined in: mplayrc
         default value: "avi mpg"
           description: defines the file types to search for within the media
                        directory

MPLAY_VF
  regularly defined in: SET file
         default value: <not set>
           description: parameter for MPLayer's video filter (-vf)

MPLAY_VOUT
  regularly defined in: mplayrc
         default value: mpegpes
           description: the video output device for MPlayer

MPLAY_WITH_SNDCTL
  regularly defined in: mplayrc
         default value: <not set>
           description: when set to 'yes' 'mplay.sh' tries to do a handling of
	                sound sets (by 'sndctl' plugin)
			(set 'MPLAY_SVDR' properly to get this working)
