Movie Player

Ultimedia Services Version 2 for AIX: Programmer's Guide and Reference

Movie Player

UMSMoviePlayer provides a high-level interface to allow application software to play movie files with synchronous audio to an AIXwindows window and an available audio device. Methods such as load, play, scan and record provide a high-level interface similar in function to controls on audio and video entertainment equipment. The movie file formats supported by UMSMoviePlayer depend on the available implementations of UMSMovieFileReader and UMSVideoDecoder classes as well as the audio format types supported by the UMSAudioDevice being used.

Ultimedia Services provides implementations of UMSVideoDecoder for Ultimotion Matinee, Motion JPEG, RTV2.0, and Indeo 2.1. UMSAVIMovieFileReader supports RIFF AVI movie files that have 1:1 Audio/Video interleave with or without audio preroll. All UMSAudioDevice implementations support PCM, A-law, and mu-law audio data types. Example programs for using UMSMoviePlayer are in the /UMS/install/Examples directory.

To learn more about the movie player, see:

For introductory information, see Programming with Media Handler Objects.

Movie Player Methods

Movie player methods include player controls, media play controls, audio device controls, media attribute controls, and media monitoring controls.

Player Controls

Player controls include:

open_audio	Opens audio device.
close_audio	Closes audio device.
load	Loads file.
info	Returns file name and device alias.
get_state	Returns current player state.
get_window	Returns the current AIXwindows display ID and window ID.
set_window	Sets AIXwindows display ID and window ID for video frame display.
release_window	Releases AIXwindows window back to application.
get_color_map	Returns the AIXwindows window color map ID used.

Media Play Controls

Media play controls include:

get_time_format	Returns the current time format.
get_repeat	Returns the current setting of the repeat flag.
play	Plays media from current position to end of file.
play_to	Similar to play but stops at given position.
pause	Pauses play.
resume	Resumes play.
seek	Seeks to location in file.
cue	Cues media for play.
step	Steps forward or backward.
freeze	Freezes video while continuing to play audio.
scan	Scans forward through video frames only.
scan_to	Scans to position in media.
stop	Stops play.
set_time_format	Sets the time format to milliseconds or frames.
set_repeat	Enables or disables repeated play.

Audio Device Controls

Audio device controls include:

get_volume	Returns the current volume setting.
get_balance	Returns the current balance setting.
set_volume	Sets volume.
set_balance	Sets balance.
get_audio_device_inout_aliases	Returns the audio device inputs and outputs aliases.
enable_audio_master_settings	Enables setting of shared device-specific parameters.
disable_audio_master_settings	Disables setting of shared device-specific parameters.
get_audio_master_settings	Returns the current master settings mode.
get_audio_device_class	Returns the specific audio device class.
get_audio_device_pathname	Returns the path to the audio device in use.
get_audio_device_master_exec	Returns the pathname of the master_exec executable.

Media Attribute Controls

Media attribute controls include:

set_speed_factor	Sets speed as a percentage of normal play rate.
set_current_track	Sets the audio track to play.
get_video_compression	Returns the video compression method used.
get_iframe_locations	Returns the location of the nearest I frames.
get_native_window_size	Returns the normal width and height of the video frames.
get_normal_speed	Returns normal play rate.
get_current_speed	Returns current play rate.
get_bits_sample	Returns number of bits per sample for audio data.
get_audio_format_type	Returns audio data format.
get_samples_second	Returns the sample rate.
get_current_position	Returns the current position in the media.
get_length	Returns the data length of the media.
get_file_format_alias	Returns the current file format alias.
get_audio_number_of_channels	Returns the number of channels in the next frame of audio data.
get_audio_bits_per_sample	Returns the number of bits per sample of audio data.
get_video_format_type	Returns the current video format type.
set_display_size	Sets the output image width and height.

Media Monitoring Controls

Media monitoring controls include:

set_cuepoint	Sets or clears one of 20 possible cuepoints.
set_position_advise	Sets position-advise event interval.
set_event_mask	Specifies which events to return.
get_event_mask	Returns the current event mask.
get_event	Gets the next event.
event_pending	Determines whether an event is available.
get_event_handle	Returns file descriptor for event communication.

File Formats

The movie file formats supported by UMSMoviePlayer depend on the available implementations of UMSMovieFileReader and UMSVideoDecoder classes as well as the audio format types supported by the UMSAudioDevice being used. Ultimedia Services provides implementations of UMSVideoDecoder for Ultimotion Matinee, Motion JPEG, RTV2.0, and Indeo 2.1. UMSAVIMovieFileReader supports RIFF AVI movie files that have 1:1 Audio/Video interleave with or without audio preroll. All UMSAudioDevice implementations support PCM, A-law, and mu-law audio data types. The object set can be extended by you if you have access to SOM development environment. UMSMoviePlayer makes use of new class implementations that are properly implemented and configured in the configuration file.

Movie Playback and AIXwindows Environment

The following can influence how well the movie player plays the movie:

Number of frames per second.
Video compression method used.
How often reference frames (I frames) occur.
Image size.
Video content.
Subsampling factor (JPEG).

For instance, in an Ultimotion Matinee AVI file, if there are few I frames in the file, seeking to position in a file can appear slow because the movie player occasionally needs I frames to reconstruct complete video frames. When you seek to a position, the movie player seeks the nearest I frame before the position and begins reconstructing the images.

The number of frames per second used when creating the movie file also affects movie playback. During playback of a movie created at 30 frames per second, the movie player must navigate to the next frame, extract the video and audio data, decompress the video frame, and send it to an AIXwindows window for display while trying to synchronize the playback of the audio with the video. This must occur 30 times per second while leaving enough CPU cycles for other work. Other factors such as CPU speed and system load also influence how the movie can be played.

The movie player needs an AIXwindows window to display the video frame. It relies on the application to initialize the AIXwindows display and to create a window that has a width and height suitable for image display in each frame. After creating the window, pass the window ID to the movie player with set_window so that the movie player can manage the repair of the window on exposure events. When you want to manage the window, request the movie player to release_window.

Playing a Movie File

To play a movie file, do the following:

Initialize the SOM environment.
Create an instance of a UMSMoviePlayer object.
Open (using the open method) an audio device using an alias, which is defined in the configuration file. The configuration object uses this alias to determine which device to open.
Load the file (using the load method) and extract the width and height for the video frames.
Open the AIXwindows display and create a window. Pass the window to the movie player.
Play the file (using the play method).
Wait for the PlayComplete event to signal when the movie player is finished playing the file.

Using the Audio Device

The open_audio and close_audio methods allow applications to intelligently use the audio resources on your system. The audio device on your system can or cannot be shareable between more than one application at a time. The open_audio and close_audio methods enable applications to decide whether to use the audio device during playback. Not all movies have an audio track, and there are occasions where hearing the audio during playback is either not desirable or not possible. If open_audio is not successful, the application can decide to continue playing only the video frames since the movie player does not require the audio device to play a movie.

Video Playback Controls

The movie player provides scan, step, and freeze methods, which emulate VCR-like controls. Also included is the set_speed_factor method used for fast and slow motion effects during playback.

scan	This method displays the video frames, without discarding any frames, at the highest possible rate attainable on your system. During a scan, the audio is not presented.
step	This method allows you to step forward or backward N frames at a time. Negative frame counts move backward in the media while positive counts move forward. A step of 0 displays the current video frame again.
freeze	This method allows you to freeze the current frame while continuing to play the audio track.
set_speed_factor	This method can be used for fast- and slow-motion effects during playback. The speed factor is a percentage of the normal speed (the speed at which the media was recorded). Fast-forward effects can also be achieved by successively seeking the next I frame and using a step of 0 to display the frame.

For introductory information, see Programming with Media Handler Objects.