[ Previous | Next | Contents | Glossary | Home | Search ]
Ultimedia Services Version 2 for AIX: Programmer's Guide and Reference

Using Media Handler Objects

Media Handler objects provide an interface that allows application software to play and record audio files through an available audio device or 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 an interface similar in function to controls on audio and video equipment.

The objects are implemented with multiple execution threads providing an asynchronous interface, which relieves the application of the complexities of managing synchronization and real-time device control. These objects employ parent class implementations of other objects such as UMSAudioDevice, UMSAudioFile, UMSMovieFileReader and UMSVideoDecoder. This allows the function of the media handler objects to be extended to new devices, new file formats, and new compression algorithms when new implementations of these base classes are available. The extensions are inherited automatically when the new objects are added to the configuration file.

To learn more about the media handler objects, see:

For introductory information, see Programming with Media Handler Objects.

Media Handler Object Methods

The load method moves a file from disk to memory where the file can be changed and saved back to disk, if the object is capable of changing it.

The play and play_to methods are asynchronous commands: playing continues after the flow of control has returned to the caller. Both methods begin at the current position in the media, which is set with the seek method.

The get_current_position method can be used to determine where the player currently is in the media. An event facility is provided that can issue periodic position events (set_position_advise) or events associated with specified points (set_cuepoint).

The playing typically stops when the stop method is called or when the end of the file is reached; however, the play_to method allows the establishment of a stopping point before the end. The pause method also stops the media (but unlike stop, the media is still cued to play). You can detect the difference between pause and stop by using get_state to read the state of the player; get_state also indicates if the media is currently playing.

The set_repeat and get_repeat methods offer repeat capability that can be set on or off. When it is set and the player reaches the end of the media, the media repeats from its starting position.

Both play and play_to call the cue method. The cue method causes all the prior checks to be made, and any appropriate buffers to be filled, in anticipation of media play beginning. The cue method should be called after any setting of the starting point, by way of seek, and before calling play. If cue has been called to prime the media, the play or play_to methods run immediately. If cue is not called or if the media is repositioned, the play command performs the work of cueing the media before beginning to play it.

Media Input and Output

Audio adapter cards often have choices for input and output lines, such as microphone or line in, allowing more than one plug or connector to be used for the source or destination of an audio signal. The enable_input method allows some control of the card's ability to select which connector to use for operation. The connector settings must be consistent with how the devices, such as microphones and speakers, are plugged into the audio adapter card. The set of inputs and outputs selectable on an audio device are listed in the configuration file under the Audio Inputs Alias and Audio Outputs Alias (see Chapter 7, "Programming with Audio Filter Objects").

Time Formats

During normal playback of real-time media, synchronization between the media and real-world time occurs as the media proceeds through the data physically, as measured in the samples of audio or the frames of video, or progresses through time, as measured in seconds.

Because these two measurements of progress are tightly related, any sample of audio or frame of video can be thought of as having a time stamp association that represents the usual time to be played, relative to the beginning of the piece. If the playback of the media is altered, such as speeding play, the time stamp association would not be consistent with real time but would be useful as a reference specifying a consistent position in the media.

Software using a media handler object can reference positions in the media in terms of time, as measured in seconds, or in terms more specific to the media, such as video frames. The set_time_format method can be used to tell a media handler object to refer to positions along the media in either of these terms. Parameters that specify locations in media, such as the get_current_position method, must use the units specified by the most recent set_time_format call for that object.

Event Types

Once a play or record is started, the player object manages the movement of data through the system without intervention by the application. There are occasions where the application needs to know when specific locations in the data stream are reached, either to begin some other operation not handled by the player object or to provide feedback to you. Player objects can notify applications of such occasions through events. Event types supported by the player objects are Cuepoint, PositionAdvise, PlayComplete, and Error.

Cuepoint A discrete position within the media stream. When a position associated with a cuepoint is encountered, the player object returns a cuepoint event. The set_cuepoint method is used to set or clear cuepoints. A cuepoint is identified by its location because there can only be one cuepoint associated with any one location. The cuepoint location is always interpreted using the current time format. A cuepoint is enabled when it is set (SET) and disabled when it is cleared (CLEAR). Cuepoints can be set at any position in the media, regardless of the player's current position within the media stream. Cuepoints remain set after they are encountered but are cleared when the media is loaded. There is a maximum of 20 cuepoints at any one time.

Cuepoints have meaning only during play operations; Cuepoint events are not sent when a cuepoint is encountered during a seek.

Cuepoints are also specific to the media and cannot be set when no file is loaded. In addition, cuepoints are removed when a new file is loaded.

PositionAdvise While Cuepoint events provide notification when a discrete location is reached in the media, PositionAdvise events provide periodic notification of elapsed time. The set_position_advise method is used to set the elapsed time interval between PositionAdvise events in the current time format. The PositionAdvise event returns the actual position in the media in the current time format. Only one position-advise frequency can be active at any one time.

Position-advise notifications have meaning only during play operations; PositionAdvise events are not sent during a seek.

PlayComplete Because the player objects manage the movement of the media through the system when it is played, PlayComplete events are necessary to indicate that the player has completed its task and is ready for another task. No further events would be expected after a PlayComplete event. PlayComplete events are always returned and cannot be disabled.
Error Error events are always returned and cannot be disabled.

Applications must select which events to receive. Error and PlayComplete events are always returned and cannot be disabled. Other events must be selected using the set_event_mask method. The CUE_POINT and POSITION_ADVISE constants can be bit-wise ORed together to form the event mask.

The get_event method is used to return the next available event. While the player is in an active state such as Play, Freeze, or Scan, the method blocks while waiting for the next available event. Otherwise, while in any other state, and event type Error is returned. The event_pending method is useful in determining if there are events available. Using the event_pending method allows the application to query whether there are any events available before using the get_event method.

Internally, events are sent by the player objects to the application through an event handle. Each instance of a player object has a unique event handle. The application can use this event handle as a file descriptor on which to select and query. The get_event_handle method returns the event handle unique to that object. This event handle is necessary when writing programs that combine media handler objects with AIXwindows environment.

For introductory information, see Programming with Media Handler Objects.


[ Previous | Next | Contents | Glossary | Home | Search ]