The UMSMPEGPlayer object provides methods to play synchronized audio and video from MPEG1 files. It supports the playback of full MPEG1 movies, audio-only, and video-only files.
The UMSMPEGPlayer object uses the generic base classes of the UMSAudioDevice and UMSImageWindow, allowing playback on a range of audio and video adapters.
To learn more about the UMSMPEGPlayer object, see:
For introductory information, see Media Handler Objects.
To avoid name collision on defines, integer values have been captured as enumerated lists. The set of valid values from an enumerated list may vary with the application. The detailed method descriptions describe the valid or possible values for the specific use. The enumerated lists that are defined for this object are listed below:
The ReturnCode enum values are shared with the UMSMoviePlayer. Not all values may be returned by the UMSMPEGPlayer object.
enum ReturnCode {
Success, // Command completed successfully
NoFile, // No file has been specified.
NoFileObj, // The specified file object can
// not be accessed or created
NoConfigObj, // The configuration object
// does not exist or can not be
// created.
NoAlias, // The device alias is not found.
NoDevice, // Device not found or is invalid.
DeviceNotReady, // The device is not ready.
InvalidState, // The command is not currently valid.
WrongFormat, // File and set format are different.
InvalidCuepoint, // Cue point is invalid for this file.
OutOfRange, // Value is out of range for parameter.
Duplicate, // Cue point is a duplicate.
CueLimit, // Cue point maximum has been reached.
FileError, // Error reading or writing file.
InvalidFactor, // Invalid factor argument.
InvalidCommand, // Invalid command
WindowDefined, // A Window ID is currently in use
InvalidWindow, // Window ID can not be used
NoWindow, // A Window ID has not been defined
ColorMap, // Unable to load color map
Failure, // Command fail
DecompressFail, // Decompress frame failed
NoEventPending, // No event pending
InvalidTrack, // An invalid track was specified
InvalidParam, // A parameter is invalid or NULL
InvalidTimeFmt, // Invalid/unknown time format.
InvalidClass, // Invalid Device Class
MemoryError, // Unable to allocate memory
EndOfFile, // End of File encountered
NoAudio, // File has no audio tracks
ValueChanged, // Returned values different than requested
NoVideo // File has no video tracks
NotSupported // Method is not supported
};
enum AudioChannels {
Stereo,
JointStereo,
Dual,
Single };
enum AudioQuality {
Low,
Medium,
Full };
enum EventType {
PlayComplete,
uepoint,
PositionAdvise,
Error };
enum OnOff {
Off,
On };
enum SetClear {
Clear,
Set };
enum SourceType {
LocalFile };
enum TimeFormat {
Msecs,
Frames };
The following constants are defined for the UMSMPEGPlayer object.
const unsigned long PLAY_COMPLETE = 0x00000001; // play complete mask bit const unsigned long CUE_POINT = 0x00000002; // cue point mask bit const unsigned long POSITION_ADVISE = 0x00000004; // position advise mask bit const unsigned long PLAYER_ERROR = 0x80000000; // player error mask bit
The following structures are defined for the UMSMPEGPlayer object.
struct EventData {
EventType type;
unsigned long current_position;
unsigned long specific;
};
Since the decode of the MPEG-1 datastream is implemented entirely in software, its performance, in terms of the number of frames displayed per second, is affected by system hardware resources and system load. The UMSMPEGPlayer object performs best on 604-based systems; its requirements for CPU bandwidth may exceed what is available on slower systems. Factors influencing CPU bandwidth requirements include the size of the image, the frame rate, the audio quality level of the playback, and whether 2X software resizing is used (UMSImageWindow hardware resizing does not impact performance).
Insufficient CPU bandwidth on slower systems is evidenced by jerky motion as more video frames are skipped.
The UMSMPEGPlayer obtains a colormap once the UMSMPEGPlayer has received both the set_window and load (file) methods. The user should then issue the get_color_map method to obtain the colormap ID and install this colormap. This colormap ID may change whenever a new file is loaded.
To create a colormap, the UMSMPEGPlayer obtains entries 0-31 from the DefaultColormap and uniquely defines entries 32-255 (224 entry color table).
This section describes one of the many sequences of methods that may be used to play MPEG-1 files with the UMSMPEGPlayer object. This sequence assumes that the file is a full MPEG-1 movie with audio and video data and is to be played at its normal rate. For further reference see the mmovie_play.c example program in the $UMSDIR/Examples directory.
UMSMPEGPlayerNew UMSMPEGPlayer_load UMSMPEGPlayer_get_native_window_size If the file has video, then create a window and issue UMSMPEGPlayer_set_window UMSMPEGPlayer_set_display_size UMSMPEGPlayer_get_audio_channels If the file has audio, then UMSMPEGPlayer_open_audio UMSMPEGPlayer_set_volume UMSMPEGPlayer_set_balance UMSMPEGPlayer_set_audio_quality UMSMPEGPlayer_play Wait on the PlayComplete Event UMSMPEGPlayer_get_event_pending UMSMPEGPlayer_get_event Free the object
This method closes the previously specified audio device. If a window was set via set_window, then video will continue playing.
For this release, this method will terminate audio playback, but will not close the audio device. Other applications that attempt to open the audio device when the UMSMPEGPlayer object are active (and have a file loaded that contains audio data) will be unable to acquire the device. The applets that may use the UMSMPEGPlayer object include the mpeg_player, the media_player, and the movie_editor.
This method causes the file to be closed and all subtasks to be terminated. The UMSAudioDevice and UMSImageWindow objects are terminated, releasing any resources they had acquired.
This method returns NoWindow if both the load and set window methods have not been received.
This method starts play from the current location at 2 times the normal frame rate, with no audio. Play continues until the end of file is reached, at which time a PlayComplete event is issued.
This method returns NoWindow if both the load and set window methods have not been received.
The audio bit rate from the audio header is returned.
| out unsigned long audio_bit_rate | The file's audio bit rate. |
The type of the MPEG1 audio data, as defined in the audio header, is returned.
| out AudioChannels channels | The type of the MPEG1 audio data. |
The number of channels in the next frame of audio data for the selected audio track in the loaded movie file. A value of one indicates mono data while a value of two indicates stereo. If no file has been opened the ReturnCode value is NoFile.
| out long channels | The number of channels for the selected audio data is returned. |
The audio quality level currently in effect is returned.
| out AudioQuality a_quality | The audio quality level, Low, Medium, or Full, currently in effect. |
This method returns the current setting of the balance control.
| out long balance | The balance setting currently in effect. It is an integer in the range of from -100 to 100. |
This method returns the current X colormap id being used by the player. This allows the using application to install the colormap so that the input focus on the application can result in use of the desired colormap. Returns 0 if no colormap exists at this time.
This method returns NoWindow if both the load and set window methods have not been received.
| out unsigned long cmap | The colormap id being used to display the video. |
This method returns the current position of the media in units of Msec or Frames as specified by the setting of the time format parameter.
This method returns NoWindow if both the load and set window methods have not been received.
| out unsigned long current_position | The current position is returned in units of the active time format. If no file is loaded a 0 value is returned. |
The width and height of the image as it is actually displayed are returned.
This method returns NoWindow if both the load and set window methods have not been received.
| out long actual_width | The width in pixels of the displayed image. |
| out long actual_height | The height in pixels of the displayed image. |
Returns the next event in the space provided by event_data. It blocks if no event is available. Error event types return a ReturnCode in the specific field of the EventData indicating what the error is.
| out EventData event_data | An EventData structure is returned indicating the event and associated data. |
This method returns an event handle. The application can use this handle as a file descriptor on which to "select" and thereby query or block on events. If the file descriptor is "readable", an event is queued.
| out long event_handle | The value is a nonzero handle number for success and zero (0) for failure. The handle is a file descriptor upon which selects may be issued to query or block on events. |
Returns the current event_mask indicating which events are enabled.
| out unsigned long event_mask | The current event mask. This is the bit or'ed set of PLAY_COMPLETE, CUE_POINT, POSITION_ADVISE, and PLAYER_ERROR. |
This method checks the event queue to determine if any events are ready for processing. If an event is ready, TRUE is returned, otherwise, FALSE is returned.
| out boolean event_pending | TRUE if an event is available, FALSE otherwise. |
This method returns the length of the currently loaded file in units of Msec or Frames as specified by the setting of the time format parameter.
| out unsigned long length | The length of the file is returned in units of the current time format. If no file is loaded a 0 value is returned with a returncode of NoFile. |
This method returns the current setting of the mono flag (On or Off). When On, this flag forces audio into mono mode.
| out OnOff mono_flag | On if mono audio is active, otherwise Off. |
This method queries the normal width and height for playback of the loaded file. NoFile is returned if no file has been loaded, and NoVideo is returned if the file has no video data. In both cases the width and height are set to 0.
| out unsigned long width | The native width of the image data is returned. |
| out unsigned long height | The native height of the image data is returned. |
This method returns the normal play speed of the movie, in frames per second. NoFile is returned if no file has been loaded, and NoVideo is returned if the file has no video data. In both cases the normal_frame_rate is set to 0.
| out float normal_frame_rate | The nominal speed of the movie in frames per second. |
This method returns the current setting of the position advise interval.
| out unsigned long interval | The interval at which position advise events will be returned. |
This method returns the current setting for the repeat flag.
| out OnOff repeat_state | On if repeat play is active, otherwise Off. |
This method returns the samples per second of the file's audio data as defined in the audio header.
| out unsigned long sample_rate | The number of samples per second in the audio track. |
This method returns the current play speed as a percentage of the normal speed of the movie.
| out unsigned long speed | The current speed value. |
This method returns the current setting of the time format parameter (Msec or Frames).
| out TimeFormat format | The current time format value. |
The video bit rate from the video header is returned.
| out unsigned long video_bit_rate | The file's video bit rate. |
This method returns the current volume level.
| out unsigned long volume | The current volume setting, from 0 to 100. |
This method queries the display and window id for displaying the video image. NoWindow is returned if a set_window method has not been successfully executed.
| out string dp | The currently set display is returned. |
| out unsigned long wid | Returns the current window id or Null if not initialized. |
This method specifies the pathname of the file to be opened in the path parameter.
This method specifies the pathname of the file on the Video CD to be opened.
| in string path | Specifies the pathname of the file to open on the Video CD. |
This method uses an alias to specify which audio device should be used by the MPEGPlayer. The UMS_config file is accessed to relate the alias to a specific device name.
For this release, this method enables audio playback, but does not specifically acquire the device. The audio device is acquired when the later of the load and set_window methods is received, if the file has audio data and an open_audio method has been received.
If receive during play, this method enables playback of the audio data.
This method suspends play or fast forward. The audio device and file remain in an open state at the current location. The play and fast_forward methods will resume from the current location.
This method returns NoWindow if both the load and set window methods have not been received.
This method is used to start play from the current location and continues until the end of file is reached, at which time a PlayComplete event is issued. If repeat is On, play continues from the start of the file, and a PlayComplete event is issued each time the end of file is reached until play is explicitly terminated by a pause, stop, or rewind command.
This method returns NoWindow if both the load and set window methods have not been received.
This method releases a previously specified window. If the application wants to regain the window it must request it's release. A release_window must be issued before defining a new window or closing the current window.
For this release, this method is not supported. The eject method will release the window.
This method resets the current position to the start of the file. If received during play or fast forward, those modes are reset.
This method returns NoWindow if both the load and set window methods have not been received.
This method resets the current position to the specified location. If received during play or fast forward, those modes continue.
This method returns NoWindow if both the load and set window methods have not been received.
For this release, only seek(0) is supported. It is equivalent to rewind().
| in unsigned long location | Specifies the target seek location in current time units. |
This allows the user to specify the quality of the audio data decoded for playback. UMSAudioQuality_Full selects the decoding and playback of the full frequency range of the encoded audio data. Full provides the best audio quality, at the expense of the largest demand on processor cycles. UMSAudioQuality_Medium selects the decoding of one-half of the frequency range centered around the midband. UMSAudioQuality_Low selects the decoding of one-quarter of the frequency range, also centered about the midband. Typically "Low" is used for voice data only, and entails the lowest demand on processor cycles.
| in AudioQuality a_quality | The specified audio quality level for the decoding and playback of audio data. |
This method changes the balance of the audio between the left and right channels.
This method sets a cue point for play-back. This is specified as a time offset from the beginning of the file. When the cue point is reached, a Cue_Point event is generated. The maximum number of cue points allowed is 1024.
For this release, set_cuepoint is not supported.
The desired width and height of the output image are set. If this is different than the native size of the image, it implies that an additional resizing step is being requested.
The UMSMPEGPlayer object first determines if hardware resizing is available by passing the request to the UMSImageWindow. If the UMSImageWindow returns Success (that is, if hardware support for resizing is available), or if the UMSImageWindow returns ValueChanged and the actual width and height are different than the original image size (that is, if the hardware is doing any form of resizing) then no further action is taken.
If the UMSImageWindow does not support hardware resizing, a software resizing is assumed. In this case the requested width and height are snapped to the nearest 1X or 2X image size. (Width and height must both be 1X or they must both be 2X in size.) ValueChanged is returned to the user if the resulting width and height are not the same as the requested width and height.
This method returns NoWindow if both the load and set window methods have not been received.
Specifies the setting of a mask to enable or disable reporting of maskable events. The default is for these bits to be '1', and not masked. The PlayComplete and Error events are not maskable.
| in unsigned long event_mask | A bit or'ed set of bit flags enabling the corresponding events. PositionAdvise and Cuepoint are maskable events. |
This method sets the audio mono flag to On or Off. When On, this flag forces audio into mono mode.
| in OnOff mono_flag | On to force mono audio playback. |
This method sets the position change notification interval. A value of zero turns position advise off, a non-zero value replaces the previous value. Position advise events are sent at the given interval if that event type is enabled. Pausing and then continuing play does not change the locations at which the position advise events are issued.
| in unsigned long interval | Specifies the position advise interval in units of the current time format. |
This method turns On or Off (enables or disables) repeat play. When On the play method will continue playing from the beginning of the file when encountering the end of file. Repeat can take effect on the next or current play. During play, if repeat is set a PlayComplete event is generated as each repetition is completed.
| in OnOff flag | Specifies that repeat should be turned On or Off. |
This method sets the speed of the movie as a percentage of the normal speed. Automatic audio pitch correction is performed on the audio data when the speed is set to values other than 100 (normal speed).
| in unsigned long speed | The speed value as a percentage of the normal speed. The valid range of values is from 50 to 150, with normal speed represented as 100. |
This method sets the time format, which specifies the units to be used for all position, length, and interval parameters. Time parameters are specified as longs and assume the units of the current time format.
| in TimeFormat format | A value from the TimeFormat enumeration list specifying current time units. Valid values are Msecs or Frames. |
This method specifies the level of audio output as a percentage of the maximum volume.
| in long level | The requested volume level as a value from 0 to 100, with 100 representing maximum volume. |
This method passes the display and window identification to the player to be used to display the video. If a window has already been defined, or if the player can not connect to the specified window, an error is returned. If a window is defined to the player, the player handles exposure events.
| in string dp | A string specifying the display to be opened (i.e. unix:0). |
| in unsigned long wid | Specifies a Window ID to be used for the display. |
This method steps "count" frames forward or backward. Negative values move toward the start of the file. A value of zero does not modify the position in the file, but causes the frame at the current position to be displayed.
This method returns NoWindow if both the load and set window methods have not been received.
For this release, only step(1) is supported.
| in long count | Specifies the number of frames to advance. Positive values step forward (toward the end of file), negative values steps backward (toward the start of the file). |
This method terminates play or fast forward, and resets the current position to the start of the file.
For introductory information, see Media Handler Objects.