readme

网络MPEG4IP流媒体开发源代码

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.

Command line arguments
======================

Since I never really knew how to use getopt very well, there are very
few command line arguments that are accepted.

mp4player will take a -l option (to loop).  Both mp4player and gmp4player
will take a file name/url to start playing.

That's it.

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.

Boolean values must be 0 or 1.

Here is the current list by categories:

History list
Name                   Type     Default  Gui knob  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 knob  Does
---------------------------------------------------------------
Looped                Boolean      0       yes  loop session

Audio Knobs
Name                   Type     Default  Gui knob  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 knob  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 knob  Does
---------------------------------------------------------------
Mpeg4IsoOnly          boolean      0       yes  Forces ISO decoder over Xvid
UseOldMp4Lib          Boolean      0       yes  Uses Quicktime library for mp4 
	                                        files
Streaming Knobs
Name                   Type     Default  Gui knob  Does
---------------------------------------------------------------
RtpBufferTimeMsec     Integer     2000     no   Sets time of initial RTP 
                                                buffering.
RtpBufferTime         Integer      2       no   Do not use
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

Debugging Knobs
Name                   Type     Default  Gui knob  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


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.

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.  It
is bound to change fairly rapidly for the next couple of CVS releases.

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.


MP4Player key shortcuts
=======================

If you are using mp4player, 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 (next if running 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

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 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).

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.

* Mac OSX player sometimes will lock up, or stop playing video while
  continuing the audio - we need someone to help us add the sound buffer 
  delay to get really good audio/video sync.

* 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.

=== END OF README ===