# MP4Player README

Feb, 2003
Bill May
Cisco Systems

This is the beginning of a README for mp4player that will answer some questions on how to use mp4player.
There is also a main README for the mpeg4ip project, as well as an internals guide to the player.

Command line arguments
Configuration Variables
Player Plugins
Player URLS
ISMA Href Support
MP4Player key shortcuts
Windows GUI
Known Problems

## Command line arguments

mp4player will take a -loop or --loop option (to loop). Both mp4player and gmp4player will take a file name/url to start playing. As of 1.1, mp4player and gmp4player will take configuration variables in the command line. Use --<variable>=<value>, and make sure that the correct case is used.

You can display the configuration variable list by using either -c or --config-vars

That's it.

Back to top

## Configuration Variables

Configuration variables are stored in the windows registry for Windows (see below), and in ~/.gmp4player_rc for every other OS.

Configuration variables are read at start, and apply to the entire session. Some can be changed with GUI knobs. The latest list of configuration variables can be found in our_config_file.cpp. LOG_* defines can be found in include/systems.h

Boolean values must be 0 or 1.

Here is the current list by categories:

History List
Name | Type | Default | Gui | Does
--- | --- | --- | --- | ---
File0 | String | NULL | yes | last file player
File1 | String | NULL | yes | before that one
File2 | String | NULL | yes | before that one
File3 | String | NULL | yes | before that one
PrevDirectory | String | NULL | yes | last directory looked at
Playing Status
Name | Type | Default | Gui | Does
Looped | Boolean | 0 | yes | loop session
LogFile | String | none | yes | File to save console output
Audio Knobs
Name | Type | Default | Gui | Does
PlayAudio | Boolean | 1 | yes | Enables/Disables audio stream
Volume | Integer | 75 | yes | volume percentage
AudioMuted | Boolan | 0 | yes | mutes audio
LimitAudioSdlBuffer | Boolean | 0 | no | See below
Video Knobs
Name | Type | Default | Gui | Does
PlayVideo | Boolean | 1 | yes | Enables/Disables video stream
AspectRatio | Integer | 0 | yes | Sets Aspect Ratio
FullScreen | Boolean | 0 | yes | Enable full screen on start.
Compatibility Knobs
Name | Type | Default | Gui | Does
UseOldMp4Lib | Boolean | 0 | yes | Uses Quicktime library for mp4 files
Streaming Knobs
Name | Type | Default | Gui | Does
RtpBufferTimeMsec | Integer | 2000 | no | Sets time of initial RTP buffering.
MulticastIf | String |  | no | Sets the interface to use for multicast receive
RxSocketSize | Integer | 0 | no | Set the receive buffer size (0 use default)
RtpIpPortMin | Integer | -1 | no | Sets local ip port to start with in RTSP session
RtpIpPortMax | Integer | -1 | no | Sets local ip port to end with in RTSP session
UseRtpOverRtsp | Boolean | 0 | yes | Use RTP over RTSP (rfc 2326, section 10.2)
SendRtcpInRtpOverRtsp | Boolean | 0 | no | Enables sending of RTCP msgs to server when using RTP over RTSP (If enabled, can crash DSS).
Mpeg2tPamWaitSecs | Integer | 30 | no | Sets time to wait for PAM in Mpeg2 transport session
UrlExec | String | NULL | no | path to executable for Href url dispatch (not in Windows))
Debugging Knobs
Name | Type | Default | Gui | Does
HttpDebug | Integer | LOG_ALERT | yes | Sets Http library debug level
RtspDebug | Integer | LOG_ALERT | yes | Sets RTSP library debug level
SdpDebug | Integer | LOG_ALERT | yes | Sets SDP library debug level
RtpDebug | Integer | LOG_ALERT | yes | Sets RTP library debug level
Mpeg2tDebug | Integer | LOG_ALERT | yes | Sets Mpeg2t library debug level
Mpeg2psDebug | Integer | LOG_ALERT | yes | Sets Mpeg2ps library debug level
DisplayDebug | boolean | 0 | yes | Display status every second (gmp4player only)
Plugin Knobs
Name | Type | Default | Gui | Does
Mpeg4IsoOnly | Boolean | 0 | yes | Forces ISO decoder over Xvid
UseFFmpeg | Boolean | 0 | no | Forces use of FFmpeg video decoder
UseFFmpegAudio | Boolean | 0 | no | Forces use of FFmpeg audio decoder

Back to top

## Player Plugins

Starting with version 0.9.3.2, we've gone to a plugin model for audio and video codecs for the player. This is true for both windows and linux platforms. As of 0.9.7, we also have plugins available for RTP byte streams. Release 1.3 adds text type plugins.

On linux (and linux like) platforms, the plugins should be in the mp4player_plugin directory, which is a sub directory of where the other mpeg4ip libraries will be stored. You must do a make install of the plugin when running/debugging with plugins - the player does not currently search for plugins. When installing a new version of the plugins, it is a good idea to purge this directory.

On Windows, the .dlls that get created must be in the same directory as the executable for mp4player.exe or wmp4client.exe. The project files should copy the plugin DLLs to the player/src directory, so when running the player, it should work fine.

The plugin pattern can be found in player/src/codec_plugin.h and in player/src/rtp_plugin.h. Both plugins contain a version number to enable detection of API changes.

Back to top

## Player URLS

We have 2 special type URLs for the player to play content. The first one is for mpeg2 transport streams. To play an mpeg2 transport stream over UDP, use the following url:

mpeg2t://<multicast address>:<multicast port>

The 2nd special URL is to play a stream from a Cisco IP/TV server, either broadcast or on demand. To do this, use the following url:

iptv://<iptv content manager>/<program id>

Where iptv content manager is the address of the IP/TV content manager, and program id is the session id that is created. You can find this out by looking at the program on the content manager, or get the session id by running the iptv_prog utility with the content manager as a parameter.

Back to top

## ISMA Href Support

In release 1.3, we implemented support for ISMA href. This is a method that allows timed opening of web pages to synchronize with audio and video.

There are 2 methods that can be used; automatically dispatching URLs, or click to dispatch. Normally, the cursor will be off in the video window while the video is running. Click to dispatch will enable the cursor in the window while active.

While using this feature, the browser should be set to open new urls in the existing window. In Firefox, this setting is in Preferences->Advanced->Tabbed Browsing. Make sure "Open Links From Other Applications" is set to "the most recent tab/window".

On Windows, the default browser will be used. On Mac OS X, the "open" command is used (which should use the default browser). On Linux, /usr/bin/firefox/firefox is tried. The browser in question can be set up by using the UrlExec configuration file setting; the full path to the browser should be used.

On Linux, Konquerer web browser can not be used, as it will open a different process for each url.

On Mac OS X, Safari should be avoided; there is no setting to open URLs in the same window, only in a new window or new tab.

## MP4Player key shortcuts

If you are using mp4player (or gmp4player), the following key short cuts can be used, assuming you've got a video window:

HOME | begin video from beginning
PAGE UP | increase video size (200% max)
PAGE DOWN | decrease video size (50% min)
ALT-ENTER | fullscreen
ESC | return from fullscreen
LEFT ARROW | go back 10 seconds
RIGHT ARROW | go forward 10 seconds
UP ARROW | volume up 1/10th
DOWN ARROW | volume down 1/10th
SPACE | pause or continue
CTRL-C | close video (mp4player - advance to next playlist)
CTRL-X | close mp4player
CTRL-0 | Default Aspect Ratio
CTRL-1 | Aspect Ratio of 3:4
CTRL-2 | Aspect Ratio of 16:9
CTRL-3 | Aspect Ratio of 1.85 Letterbox
CTRL-4 | Aspect Ratio of 2.35 Letterbox
CTRL-5 | Aspect Ratio of 1:1
CTRL-S | Seek dialog (gmp4player only)
CTRL-N | Next item in playlist (gmp4player only)

Back to top

## Windows GUI

First - if you're the type of person who wants the player to work with a nice interface, this isn't the place for you. Go see Quicktime or Envivio players.

We've created a simple windows GUI. It consists of 2 parts - wmp4player and wmp4client. wmp4player contains the GUI, and wmp4client is basically mp4player that will communicate with wmp4player.

wmp4client is launched as a seperate process, due to SDL limitations. The 2 processes communicate using file maps in memory. See the CMp4Process and CMP4If classes in wmp4player and CClientProcess in wmp4client.

To create this, look for the player60.dsw in player/src directory. This will make all 3 executables (mp4player, wmp4player.exe and wmp4client.exe, as well as all the plugins).

To install wmp4player, put the Release version (ie: versions from the Release folder) of wmp4player.exe, wmp4client.exe and SDL.dll in the same directory. We will not be writing any installers. In addition, make sure all desired plugins are in the same directory.

These programs will use the registry for storing information that Linux stores in .gmp4player_rc. Look for the Software\Mpeg4ip\Config registry entry. Our config file library is rigged to save this data there. mp4player will still use a gmp4player_rc file.

At this time, if it's broken, you're going to have to fix it. The same goes with GUI "nits" - we're not GUI writers. Currently, there is no playlist support, no loop support, no drag and drop support, no wmp4player command line support, no accelerator from the dialog window (accelerators from the video window still work).

Back to top

## Known Problems

- If you're playing through a NAT box, you may have to specify the default client IP ports. Use the command `RtpIpPortMin=<port>` and `RtpIpPortMax=<port>` in the .gmp4player_rc file created in your home directory. The IETF recommends a range of 6970 to 6999.

- The player for windows is sketchy at best. We have included project files that should build for Dev Studio 6.0. We recommend installing DirectX 8.1 or later. If that is not possible, and you have problems with video, try uncommenting out `#define OLD_SURFACE` in player/src/video.cpp.

  If you have problems with choppy playback, and you're using Windows 98, forget about it. The timer tick time is too slow (55 msec) for us to use effectively. Try Quicktime or Real with Envivio, or update to a newer Windows OS.

- FreeBSD based OS's have a problem with thread delays. This can cause the player to skip rendering many frames. If you have this problem update to the latest version of FreeBSD - the problem still can occur, but is reduced.

  This is due to an error in the thread scheduling code that causes a problem with a delay of less than the thread scheduler quantum (200 msec in some versions, 20 in others). Since the average delay used is 9 to 10 msec (less as we get closer to the video rendering time), this can have a great effect on video playback.

  You can get around this error by rebuilding your libc, after changing the `THREAD_SCHED_USECS` to 20000 (or lower) from 200000 in thread_private.h.

- If you're running on Linux, and trying to play a raw audio file, and notice that you get garbage, try setting the `LimitAudioSdlBuffer` config variable to 1 in the .gmp4player_rc file. This seems to occur on a Soundblaster Live, Red Hat 7.3 machine.

Back to top

=== END OF README ===