The UMSMovieFileReader object is a base class. Specific movie file reader implementations inherit their interface from this class. Objects, such as the UMSMoviePlayer, and applications can achieve movie file type independence by accessing movie file data through the methods of the base class. This allows the application to transparently support any movie file types for which a UMSMovieFileReader object is provided without the need to know the specific object implementation being used.
A metaclass (reference documentation for UMSMovieFileReaderMClass) is provided with a method to construct a specific movie file reader based on a user specified pathname to a movie file, a Detector alias, and data in the configuration file. The construction method in the metaclass invokes the series of detectors specified by the Detector alias. If the file type is recognized by one of the detectors, the corresponding specific movie file reader object is instantiated and returned. This allows applications to be extended to support new movie file types by adding new movie file reader objects and corresponding detectors.
This is the preferred construction technique for applications. Alternatively, a specific movie file reader object can be constructed by the standard ObjectNameNew method.
The object presents a paradigm of audio and video data being organized as frames. For each video frame in the file, there is a block of audio data that is to be played while the video frame is being displayed. The true underlying organization of the file may or may not exhibit this organization, but is presented with this paradigm at the UMSMovieFileReader method interface. The object permits multiple tracks of audio and video data. File position is specified by frame number.
To learn more about the UMSMovieFileReader object, see:
For introductory information, see Formatted File Access 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 as follows:
enum ReturnCode {
Success,
Failure,
UnsupportedFormat,
UnsupportedAlgorithm,
OutOfRange,
Uninitialized,
OutOfMemory,
FormatChange,
UnrecognizedType,
InsufficientBufferLength,
EndOfFile,
NoAudio
};
enum VideoFrameType {
I frame,
I frameAndDelta,
I frameAndDeltaAndBidirectionalDelta
};
The object defines the following data types:
typedef sequence<octet> CompressedAudio; typedef sequence<octet> CompressedVideo;
This method closes a previously opened file.
The number of bits per sample for the next frame of audio data for the selected audio track is returned. If no file has been opened, the ReturnCode value is Uninitialized.
| inout long bits_per_sample | The number of bits per sample for the next frame of audio data for the selected track. |
The format of the next frame of audio data for the selected audio track is returned. If no file has been opened, the ReturnCode value is Uninitialized.
| out string audio_format_string | The format of the next frame of audio data for the selected track. |
Returns the audio data for the specified audio track and frame number. This method provides random access to the audio data in the file. A ReturnCode of Uninitialized is returned if no file is open. A value of OutOfRange is returned if the requested data does not exist. A value of InsufficientBufferLength is returned if the buffer space in the provided sequence is not sufficient to hold the requested data.
The number of channels in the next frame of audio data for the selected audio track is returned. A value of one signifies mono data, while a value of 2 signifies stereo data. If no file has been opened, the ReturnCode value is Uninitialized.
| inout long audio_number_of_channels | The number of channels for the next frame of audio data for the selected track. |
The number of samples per second for the next frame of audio data for the selected audio track is returned. If no file has been opened the ReturnCode value is Uninitialized.
| inout long samples_per_second | The number of samples per second for the next frame of audio data for the selected track. |
The current value of the selected audio track is returned. The default audio_track_id at file open is track 0. If the file contains multiple audio tracks, the first audio track in the file is track 0, the second audio track is track 1, and so forth. The selected audio track is significant to many of the other methods on the object. When querying audio formats, I frames, or when accessing data with the get_next_movie_movie_frame method, the currently selected audio track is assumed. If no file has been opened the ReturnCode value is Uninitialized.
| inout long audio_track_id | This parameter returns the current value specifying the selected audio track. |
The current position in the file is returned as a frame number. The first frame in a file is frame 0. The file is positioned to frame 0 at open.
| inout long presentation_frame_number | The current file position is returned as a frame number. |
The current frame rate for the selected video_track is returned as a float. If no file is open a ReturnCode value of Uninitialized is returned.
| inout float frame_rate | The current frame rate for the selected video_track. |
The location (frame number) of the previous and next I frame in relation to the reference frame is returned, as well as a Boolean indicating whether the reference frame itself is an I frame. If no file is open, a ReturnCode value of Uninitialized is returned. An I frame is a frame that contains all the data necessary to construct the video image, as opposed to a delta frame which only describes the image difference for the frame relative to another frame. Processing of video data for display must begin at an I frame and continuously process successive frames up to the frame of interest.
The current dimensions in pixels for the selected video_track is returned. If no file is open, a ReturnCode value of Uninitialized is returned.
| inout long width | The width of the next video image for the selected track. |
| inout long height | The height of the next video image for the selected track. |
The maximum buffer size that will be required to receive audio frames given the selected audio track. If no file is open a ReturnCode value of Uninitialized is returned.
| inout long buffer_size | The maximum required audio buffer size is returned. |
The maximum buffer size that will be required to receive video frames given the selected video track. If no file is open a ReturnCode value of Uninitialized is returned.
| inout long buffer_size | The maximum required video buffer size is returned. |
The number of frames in the file given the selected video track. If the number of frames is unknown, a value of -1 is returned as the number_of_frames. If no file is open a ReturnCode value of Uninitialized is returned.
| inout long number_of_frames | The number of frames in the file is returned. |
This method provides efficient sequential access to the audio and video frame data for the selected audio and video track. The next frame of audio and video data is returned in the audio_buffer and video_buffer data sequences respectively. By convention, data is returned in the order it needs processed for display. The presentation_frame_number is returned to indicate the presentation order of the data. If the video frame data returned is not the next sequential frame, the frame being returned is required next for processing, even though the frame is not the next to be displayed. The interface allows midstream format changes to be reported by a ReturnCode value of FormatChange. This should be used to report midstream audio or video changes (for example, format, sample rate, and image size). All such values should be queried and reestablished. The object continues to report the format change until all changed values have been queried.
Note: No compression formats currently supported by Ultimedia Services require non-sequential processing of frames and no movie file objects support midstream changes. These interfaces capabilities are introduced for future extensions but are not supported in this release.
If a null value for audio_buffer or video_buffer is passed in, the respective data is not returned. This method call advances the current file position by one frame. If the end of the file is encountered while attempting to access the requested data a ReturnCode value of EndOfFile is returned.
The number of audio tracks in the file is returned. If no file is opened a ReturnCode value of Uninitialized is returned.
| inout long number_audio_tracks | The number of audio tracks in the file is returned. |
The number of video tracks in the file is returned. If no file is opened a ReturnCode value of Uninitialized is returned.
| inout long number_video_tracks | The number of video tracks in the file is returned. |
The aspect ratio for the pixel data in the file is returned. If this is unknown for the specific implementation a value of 1 should be returned. The aspect ratio is expressed as a ratio of the (pixel height)/(pixel width).
| inout float video_aspect_ratio | The pixel aspect ratio is returned. |
The format of the next frame of video data for the selected video track is returned. If no file has been opened the ReturnCode value is Uninitialized.
| out string video_format_string | The video compression type for the next frame of video data for the selected track. |
Returns the video data for the specified video track and frame number. This method provides random access to the video data in the file. A ReturnCode of Uninitialized is returned if no file is open. A value of OutOfRange is returned if the requested data does not exist. A value of InsufficientBufferLength is returned if the buffer space in the provided sequence is not sufficient to hold the requested data.
A value from the VideoFrameType enumeration list is returned which defines the type of video data contained in the currently selected video track. Possible values include:
Most video compression algorithms fit one of these categories. It is anticipated that applications may require unique processing at times for these different video types (for example, accessing random frames or skipping video frames for fast forward).
| inout VideoFrameType video_frame_type | The video_frame_type is returned. |
The current value of the selected video track is returned. The default video_track_id at file open is track 0. If the file contains multiple video tracks, the first video track in the file is track 0, the second video track is track 1, and so forth. The selected video track is significant to many of the other methods on the object. When querying video formats, I frames, or when accessing data with the get_next_movie_frame method, the currently selected video track is assumed. If no file has been opened the ReturnCode value is Uninitialized.
| inout long video_track_id | This parameter returns the current value specifying the selected video track. |
If a file is currently opened, it is closed and the file specified by the string file_name is opened. If the file cannot be accessed a ReturnCode value of failure is returned. ReturnCode values may also indicate that the file format is not supported, the compression algorithm is not supported or the video type is unrecognized. The method is provided for use of a specific object constructed by the standard object nameNew method. The preferred construction is via the metaclass which detects the file type and returns a UMSMovieFileReader object with an opened file.
| in string file_name | The input string specifies the file to open. |
The current file position is moved to the specified frame number. If the frame number is not valid, a ReturnCode of OutOfRange is returned.
| in long frame_number | The input parameter specifies the desired file position. |
The specified audio track becomes the currently selected audio track.
| in long audio_track_id | The input parameter specifies the desired audio track. |
This method allows the application to indicate to the file object that the data to be accessed with the get_next_movie_frame method will be accessing the data at a frame rate that is the normal rate scaled by the speed_factor. A specific UMSMovieFileReader object may or may not make use of this data.
| in unsigned long percent | The input parameter specifies a percentage to scale the speed by. A value of 50 is one-half normal speed; a value of 400 is four times normal speed. |
The specified video track becomes the currently selected video track.
| in long video_track_id | The input parameter specifies the desired video track. |
This method returns the byte order setting as a string value.
| out string byte_order | The byte order setting as a string value of MSB or LSB. |
This method returns the number format setting as a string value. Values of signed, unsigned, and twos complement may be supported by the specific object.
| out string number_format | The number format setting as a string value. |
For introductory information, see Formatted File Access Objects.