diff options
Diffstat (limited to 'TAO/orbsvcs/tests/AVStreams/mpeg/vcr.1')
| -rw-r--r-- | TAO/orbsvcs/tests/AVStreams/mpeg/vcr.1 | 610 |
1 files changed, 610 insertions, 0 deletions
diff --git a/TAO/orbsvcs/tests/AVStreams/mpeg/vcr.1 b/TAO/orbsvcs/tests/AVStreams/mpeg/vcr.1 new file mode 100644 index 00000000000..24e9688f674 --- /dev/null +++ b/TAO/orbsvcs/tests/AVStreams/mpeg/vcr.1 @@ -0,0 +1,610 @@ +.\" Copyright (c) 1995 Oregon Graduate Institute +.TH vcr 1 "November 1995" "MPEG video audio player" + +.SH NAME +.B vcr vcrs +\- Distributed, real-time synchronized video audio player, version 2.0 +.SH SYNOPSIS + +.B vcrs +[ +.B \-rt +] [ +.B \-rm +] [ +.B \-s\fIsession_limit\fP +] [ +.B \-help +] + +.B vcr +[ +.B\-rt +] [ +.B \-shmem +] [ +.B \-rmsem +] +.ti +5n +[ +.BR \-dither " ordered\||\|ordered2\||\|fs4\||\|fs2\||\|fs2fast\||\|hybrid\||\| +.if n .ti +5n + hybrid2\||\|2x2\||\|gray\||\|color\||\|mono\||\|threshold +] +.if n .ti +5n +[ +.I X-window options +] +.if n .ti +5n +[ +.BR \-v " \fI[hostname:]video-filename\fP" +] +.if n .ti +5n +[ +.BR \-a " \fI[hostname:]audio-filename\fP" +] +.if n .ti +5n +[ +.BR \-p " \fImovie-file-name\fP" +] +.if n .ti +5n +[ +.BR \-l " \fImovie-list-file-name\fP" +] +.if n .ti +5n +[ +.BR \-quiet +] +.if n .ti +5n +[ +.BR \-help +] +.SH DESCRIPTION + +The player plays \fBMPEG\-1\fP video and \fB8\-bit mu\-law (Sun +Sparc)\fP audio. It supports +following \fBfour types\fP of playback: +.TP +\ \ \ \(bu +Plays both video and audio synchronously, in real-time mode. Video +frames, or even audio samples are dropped if needed. +.TP +\ \ \ \(bu +Plays video only, in real-time mode. Video frames are dropped if +needed. +.TP +\ \ \ \(bu +Plays video only, in best-effort mode, video frames are played as fast +as possible. +.TP +\ \ \ \(bu +Plays audio only, in real time mode. +.PP + +When video/audio is played in \fBreal-time\fP mode, play speed (defined in +terms of frames-per-second (fps) for video and samples-per-second (sps) +for audio) can be specified through a speed scale. If audio is played at a +speed other than the recording (normal) speed, samples are interpolated. + +When video is played in \fBbest-effort\fP mode, the player tries its +best to play video frame by frame, and not to drop frames. This mode +is not supported very well. Now and then some frames may be +dropped. Audio is disabled in this mode. + +As well as various types of playback, the player also supports other +common VCR functions such as fast forward, rewind, step +(forward), random positioning, etc.. + +The player is of \fBdistributed architecture\fP, with servers and +clients communicating across Internet. A \fBserver\fP resides on a +host, and services coming audio/video retrieval requests from clients. +A \fBclient\fP receives instructions from the user, makes connection +to servers, buffers incoming streams, decodes video frames, +interpolates audio samples, and outputs audio and video to +corresponding devices in a timely manner. A client can connect to +different servers for audio and video streams, and still plays them +synchronously. + + +.SH SERVER + +To start the server, type: + +.B vcrs +[ +.B \-rt +] [ +.B \-rm +] [ +.B \-s\fIsession_limit\fP +] [ +.B \-help +] + +One host can have a SINGLE server running, which responds to +connection requests from all clients to that host. Subsequent +invocation is terminated with an error message. + +\fBOptions\fP + +.IP "\fB-rt\fP" +On \fBhpux\fP, \fBsparc-sunos5.3\fP and \fBi86pc-solaris2.4\fP, if you +have real-time execution privilege, you can start the server with +the option \fB\-rt\fP to get better service. + +.IP "\fB-rm\fP" +With option \fB\-rm\fP, the server will try to remove socket names +left by previous crashed invocations before initialization. + +.IP "\fB-s\fIsession_limit\fP" + +With the option of \fB\-s\fP followed by a positive integer, e.g. +\fB-s2\fP, \fB-s4\fP or \fB-s10\fP, the number of sessions +serviced by the server at any time will be limited to be no more than +the given number. Both audio and video sessions are counted. The +default session number limit is \fB4\fI. + +.IP "\fB-help\fP" +This option tells the server to print all available options and then +quit. + +.PP + +In a video session, the server tries to find a +corresponding \fB.Info\fP file describing the structure of the MPEG +file of the session. If this fails, the server scans the MPEG file for +structure information and tries to create the \fB.Info\fP file. For +big MPEG files, this scanning process may take quite a few minutes +(some times even tens of minutes). If the \fB.Info\fP file is found, +the server simply reads structure information from it. + +.SH CLIENT + +The client program is available on \fBsun4\fP, \fBhpux\fP and +\fBi86pc-solaris2.4\fP. It needs a \fBMotif\fP environment, and +outputs audio to the default \fBAudioFile\fP server. If the client +fails to connect to the default AudioFile server, then the audio is +disabled. + +To start the client, type: + +.B vcr +[ +.B\-rt +] [ +.B \-shmem +] [ +.B \-rmsem +] +.ti +5n +[ +.BR \-dither " ordered\||\|ordered2\||\|fs4\||\|fs2\||\|fs2fast\||\|hybrid\||\| +.if n .ti +5n + hybrid2\||\|2x2\||\|gray\||\|color\||\|mono\||\|threshold +] +.if n .ti +5n +[ +.I X-window options +] +.if n .ti +5n +[ +.BR \-v " \fI[hostname:]video-filename\fP" +] +.if n .ti +5n +[ +.BR \-a " \fI[hostname:]audio-filename\fP" +] +.if n .ti +5n +[ +.BR \-p " \fImovie-file-name\fP" +] +.if n .ti +5n +[ +.BR \-l " \fImovie-list-file-name\fP" +] +.if n .ti +5n +[ +.BR \-quiet +] +.if n .ti +5n +[ +.BR \-help +] + +\fBOptions\fP + +.IP \fB-rt\fP +On \fBhpux\fP, and \fBi86pc-solaris2.4\fP, if you have real-time +execution privilege, with this option you may get better service. +.IP \fB-shmem\fP +With this option, the client tries to output video frames to the +X-server via shared memory instead of sockets. +.IP \fB-rmsem\fP +With this option, prior to initialization, the client tries to remove +\fBall\fP existing semaphore and shared memory ids you have access to. +\fBBe careful\fP, with this option, you also face the danger of +removing semaphores or shared memory ids being used by other programs, +as well as all the ones created by failed invocation of the player. See +\fBSemaphore ids and shared memory ids used up\fP in \fBKNOWN PROBLEMS\fP +section. +.IP "\fB-dither\fP ordered|ordered2|fs4|fs2|fs2fast|hybrid|" + hybrid2|2x2|gray|color|mono|threshold + +This option specifies the type of dithering performed on video frames +in order to be displayed on an X-window. The default is +\fIordered\fP. \fIcolor\fP only works with full color (24-bit) +displays. All others work with 8-bit color displays. \fImono\fP and +\fIthreshold\fP also work with mono displays. Different types of +dithering have different computational complexity and offer different +image quality. +.IP "\fIX-window options\fP" +All standard X-window Toolkit command line options are accepted +(see \fBX\fP(1)). +.IP "\fB-v\fP \fI[hostname:]video-filename\fP" +The very first program for the player can be specified in command line +with \fB-v\fP and/or \fB-a\fP options, for video and/or audio streams +respectively. + +This option specifies a video stream. If the \fIhostname\fP part is +given, the client tries to connect to a running server on the given +host, and plays the given file. If the hostname part is missing, the +client assumes there is a running server on the local host or tries to +fork one. and tries to connect to it. + +.IP "\fB-a\fP \fI[hostname:]audio-filename\fP" +This option specifies an audio stream of the very first program. +Only file names with suffix \fB.au\fP are accepted as audio files. +.IP "\fB-p\fP \fImovie-file-name\fP" +This option specifies a file specifying a movie to be played upon +client startup. A movies file contains \fBfive lines\fP lines: title, +video host name, video file path, audio host name, and audio file path. +.IP "\fB-l\fP \fImovie-list-file-name\fP" +This option specifies a movie list file to replace the default movie +list file \fI$(HOME)/.vcr/vcrPrograms\fP. A movie list file contains a +banner line, followed by a list of movies. +.IP "\fB-quiet\fP" +This option tells the client not to print any text message. This is +useful when the player is invoked from within a web browser. +.IP "\fB-help\fP" +This option tells the client to print all available options and quit. + +.PP + +\fBOperations\fP + +There are \fBtwelve buttons\fP and \fBfour scales\fP defined in the top-level window. +Buttons from left to right are: +.PP +.IP \fIExit\fP +Exits the client right away. +.IP \fIInfo\fP +Pops up a window containing information about the player. +.IP \fIPara\fP +Pops up a window with a list of parameters. Parameter values +can be viewed and modified through this window. +.IP \fIProg\fP +Pops up a window with a list of programs. You +can select a program from this list to play. +.IP \fIFile\fP +This is an alternative way to select programs. pressing this button +pops up a standard Motif file selection window. You can select +audio/video file on local host to play. The client assumes a running +server on local host, or tries to fork one. + +File names with suffix \fB.au\fP are accepted as audio, and file +names with suffices \fB.mpg\fP, or \fB.mpeg\fP (some or all letters in +the suffices can be upper-case ones) as MPEG video. Other types of +file names are rejected. + +Selection of a new program causes the current program to be discarded. +.IP \fILoop\fP +A toggle button. When pressed, the current program is played +repeatedly until stopped explicitly by the user, otherwise, playback stops when +program end is hit. This button has no effect on rewind and fast +forward. +.IP \fINorm\fP +Restores play speed to the normal (recording) speed. +.IP \fIRewind\fP +For video programs. Plays backward from the current position at a +speed given by the parameter \fI(Rewind frames-per-second)\fP. Only first +frames of MPEG picture groups (I-frames) are played. Audio is +disabled. +.IP \fIStop\fP +Stops active playback, fast forward or rewind. +.IP \fIFast-Forward\fP +For video programs. Plays forward from the current position at a speed +given by the parameter \fI(FF frames-per-second)\fP. Only first frames of MPEG +picture groups (I-frames) are played. Audio is disabled. +.IP \fIPlay\fP +Plays the program from the current position in one of the two modes, +depending on if video is involved and the value of an parameter \fI(Real +time(audio on)(tag))\fP: +.RS +.IP - +Best-effort mode, if the parameter is off (0), and video is involved. +.IP - +Real-time mode, otherwise. +.RE +.IP \fIStep\fP +Steps forward for one frame from the current position. +.PP +Clicking on buttons \fIRewind\fP, \fIFast-Forward\fP, \fIPlay\fP and +\fIStep\fP and dragging the \fIPlay-Speed\fP scale all stop current +active rewind, fast forward, or play. + +.B "Four scales \fP from left to right are:" + +.IP \fIBalance\fP +Currently not functional, because only mono audio is +supported. +.IP \fIVolume\fP +Audio volume. +.IP \fIPlay-Speed\fP +Specifies play speed for real-time mode playback. This scale is not +completely linear, with a special middle point (\fB50\fP). +.RS +.IP \fB50\fP +normal (recording) speed. +.IP "\fB[1 - 50)\fP" +linear speed value increase from zero to the normal speed. +.IP "\fB(50 - 100]\fP" +Linear speed value increase from the normal speed to the maximum +speed given by the parameter \fI(Video max frames-per-second)\fP when +video is involved in the current program, or \fI(Audio max +samples-per-second)\fP when only audio is involved. +.RE +This scale also defines the upper-limit of the best-effort playback +speed. +.IP \fIPosition\fP +This scale has multiple functionalities: +.RS +.IP - +Indicates the beginning position for rewind, fast forward and +playback. +.IP - +Shows the current position during rewind, fast forward, and playback. +.IP - +Random positioning: you can set the position by dragging the +slider. when video is involved, the first frame of the picture group +at the current position is displayed. +.RE +.PP +.B "Program list" + +.B Program list +is maintained through the \fBprogram list\fP window, which is popped up by +clicking the \fIProg\fP button in the main window. Currently only \fISelect\fP +and \fIDismiss\fP buttons are fully functional, and contents of a selected +program can be viewed (but not modified) by pressing the \fIModify\fP +button. To select a program, \fBhighlight\fP the desired item and +click \fISelect\fP. To modify the program list, edit the program file given +below. + +.B "Parameters" + +.B Parameters +are viewed and maintained through the parameter window, which is activated +by clicking the \fIPara\fP button in the main window. To update a parameter, +\fBhighlight\fP the item, enter the new value in the text window next +to the \fIUpdate\fP button, and press \fIUpdate\fP. Following parameters +are supported: + +.IP "\fIReal time (audio on)(tag)\fP" +Best-effort play mode when this parameter is 0 and video is involved +in the current program, otherwise real-time play mode. Default: 1, +range: 0, non-0. +.IP "\fIVideo max frames-per-second\fP" +For video programs, real-time mode play speed when speed scale has a +value of 100. Default: 60, range: > the normal speed. +.IP "\fIAudio max samples-per-second\fP" +For audio-only programs, play speed when speed scale has a value of +100. Default: 16000, range: > the normal speed. +.IP "\fIFF frames-per-second\fP" +Fast forward speed. Default: 150, range: > 0. +.IP "\fIRewind frames-per-second\fP" +Rewind speed. Default: 150, range: > 0. +.IP "\fIFeedback delay (msec)\fP" +Currently not used. +.IP "\fIAudio output mask\fP" +Currently not used. +.IP "\fIAudio_para.encodeType\fP" +Currently not used. +.IP "\fIAudio_para.channels\fP" +Currently not used. +.IP "\fIAudio_para.samplesPerSecond\fP" +Currently not used. +.IP "\fIAudio_para.bytesPerSamples\fP" +Currently not used. +.IP "\fIAudio timer interval (millisec)\fP" +For audio-only programs. Playback +timer interval in milliseconds. Playback of audio and video is +driven by a timer in the client. Default: 500, range: > 0. +.IP "\fIAudio buffered intervals\fP" +For audio-only programs. This number of timer intervals of audio +samples are to be buffered in the AudioFile server internal buffer. This +parameter and the previous one determine how many milliseconds of +audio samples are to be buffered in AudioFile. Buffering too +many samples reduces responsiveness, too few may degrade playback +quality. Default: 2, range: > 0. +.IP "\fIFrames per audio play\fP" +For audio+video programs, this parameter determines the ratio of the +audio timer interval over the video timer interval. Default: 4, +range: > 0. +.IP "\fIAudio forward (samples)\fP" +For audio+video programs, this number of samples of audio is +played ahead of video stream. This is supposed to compensate the +delay in AudioFile server. Default: 800, range: > 0. +.IP "\fIVS work-ahead (milli-seconds)\fP" +For video program, this number of milli-seconds the player tries to +keep the video server ahead of the client during playback, rewind and +fast forward. + +If the parameter \fISync effective\fP has a value of non-0, then this +parameter gives the initial value of the VS work-ahead time, and the +actual work ahead time is adjusted according to current network delay +jitter level. If a value less than the default is set, then the +default instead of the given one is used by the player. + +Default: 100, range: >= Default. + +.IP "\fIFrame rate limit (fps, float)\fP" +For video programs. In real-time play mode, if current play speed is +higher than the value of this parameter, then this +parameter defines the maximum frame rate the player tries to play. +Default: 60.0, range: >0. +.IP "\fICollect statistics(tag)\fP" +For video programs. If both the server and the client programs are compiled +with STAT defined, this tag indicates that, at the end of a playback +session, when \fIStop\fP button is pressed (or in loop-back mode when the +end of the program is reached) statistics is collected to file +stat.\fIn\fP in current directory (from which the client is +invoked). Default: 0, range: 0, non-0. +.IP "\fICollect video structure info(tag)\fP" +For video programs. If both the server and the client programs are compiled +with STAT defined, this tag indicates that, upon successful +initialization of a video stream, structure information of the MPEG +stream is collected to a file named struct.\fIn\fP in +current directory Default: 0, range: 0, non-0. +.IP "\fISync effective(tag)\fP" +For video programs, when set, server/client synchronization control is +effective during playback, rewind and fast forward. Default: 1, range: +0, non-0. +.IP "\fIQoS effective(tag)\fP" +For video programs, when set, automatic frame rate control is +effective during playback. Default: 1, range: 0, non-0. +.IP "\fIAudio offset(samples)\fP" +For audio+video programs. The player assumes that in a program, audio +and video are recorded strictly synchronously. But it is usually not +the case, and there is a certain amount of timing shift between audio +and video. This parameter specifies audio forward offset against video +in order to compensate the shift. Default: 0, range: integer +.IP "\fIFilter parameter(1/R or n-samples)\fP" +Parameter of the filters for client/server synchronization and frame rate +control. Default: 50, range: > 0. +.IP "\fIMax send pattern frames\fP" +This parameter sets the granularity of the frame rate control +algorithm. Default: 60, range: > 0. +.IP "\fIReliable byte-stream audio (tag)\fP" +In the case when the server is on a remote host, when this tag is set, +the client establishes a TCP connection to the server for shipping +audio samples, otherwise a UDP is used. The client always setup a TCP +connection to the server for control messages, no matter what value +the tag is. +.IP "\fIReliable byte-stream video (tag)\fP" +Similar effort as previous tag, but for video channel. +.IP "\fIVerbose message(tag)\fP" +If this tag is set, then verbose message is printed (provided that +command line option \fB-quiet\fP is not specified. Otherwise the +client will still print some, but less verbose message. +.PP +Parameter setting is for experienced user only. It is suggested that +you leave values of most parameters as default. If you like to change +some of them, be careful. It may make the player behave improperly. In +case you made some change, the player fails to work, and you are +unable to undo the change, delete the parameter file shown below and +restart the client. + +.SH FILES + +.IP "\fI($HOME)/.vcr/vcrPrograms\fP" +Program file. If this file is absent, it is created with a default +movie list of several basketball game sample movies in it. The movies +in the default movies list are maintained at CSE OGI. In a movie list +file, the first line is a banner. Following this line, each contiguous +four lines describe a movie: video host, MPEG file path, audio host, +audio file path. You may edit the movie list fileto include any movies +you like. + +.IP "\fI($HOME)/.vcr/vcrParameters\fP" +Parameter file. When absent, the system default parameter values +apply. Whenever you update a parameter, this parameter file is also +created or updated. + +.SH KNOWN PROBLEMS + +.B "The player stalls" +when or after playing audio program at very \fBlow speed\fP, or the +product of \fI(Audio timer interval)\fP and \fI(Audio buffered intervals)\fP +parameters \fBtoo large\fP, or \fI(Frames per audio play)\fP too +large. This is because the client tries to put too many audio +samples to AudioFile each time, blocking itself for output. + +In this version of the player, when an video+audio program is played, +some conditions are checked and low speed limit is enforced. You +are not able to set too low play speed (even if you set the speed +slider to 0 position). But the conditions might not be sufficient. + +.B "Play at too high speed\fP," +or \fI(Audio timer interval)\fP too small, or \fI(Video max +frames-per-second)\fP, \fI(FF frames-per-second)\fP, or \fI(Rewind +frames-per-second)\fP too high, presentation quality may be worse than +expected. This is because of the resolution limit of the UNIX interval +timer, which is about 10 milliseconds. + +.B "When Play speed jump from high to very low\fP," +a few seconds of worse-than-expected video presentation quality may be +experienced. Because at high speed, the video server usually drops +frames, and play speed changes, the player does not flush the video +pipeline. + +Various problems may be experienced if the \fBparameter\fP values are too +far from their default. The parameter values are seldomly guarded. + +.B "Audio doesn't work when played across the Internet\fP." +This is because audio is retrieved from the audio server to the +client via TCP, and the Internet TCP connection fails to provide +enough (e.g. 8KB/s) sustained bandwidth. In this case, all audio +samples would be too late showing up at the client, and thus are +dropped. + +.B "X shared memory problem\fP." +Parts of the user interface may not work correctly when the player +outputs to X-window via shared memory (with option \fB-shmem\fP). For +example, some of the buttons may not show up. Usually, the missing +buttons will show up by iconifying the user interface. + +.B "Core dump." +The player may core dump when playing a specific MPEG stream, at a +specific position. This may be because the parameters in the MPEG +stream is out of the ability of the decoder code. Upon core dump, you +may want to reproduce the problem, and recompile the player with +option -DNDEBUG, run the player again to see if any assertions fails. + +.B "Semaphore or shared memory ids used up\fP." +When this happens, an error shmget() or semget() is reported by the +player. This may happen if previous invocation(s) of the player have +exit abnormally causing core dump, and you try to run the player +again. Because semaphores and shared memory segments might not be +reclaimed when the player exits abnormally. You may run the client +with option \fB\-rmsem\fP to remove all existing semaphores and shared +memory ids accessable by you. See description of \fB\-rmsem\fP. If +\fB-rmsem\fP does not work, you may need to use tools like +\fBipcrm(1)\fP. + +.B "Undeleted UNIX socket pathes /tmp/vcrs*\fP" +Some UNIX socket names may remain in /tmp directory as "vcrs*", if the +server or the client has terminated abnormally. + +.SH BUG REPORT + +If you experience problems, look at the above KNOWN PROBLEM section +first. If the problem is not described, try to reproduce the problem, and +\fBreport bug\fP to \fBscen@cse.ogi.edu\fP. Thanks. + +.SH COPYRIGHT + +This software is covered by copyrights. It contains code contributed +by the author and several other parties. Please see the beginning of +source files and copyright file(s) in the root directory of the source +kit. + +.SH SEE ALSO + +.B "AF\fP(1), \fBX\fP(1)" + +.SH AUTHOR + + Shanwei Cen + Department of Computer Science and Engineering + Oregon Graduate Institute of Science and Technology + scen@cse.ogi.edu |