BMediaTrack

Derived from: none
Declared in:  be/media/MediaTrack.h
Library: libmedia.so
Allocation: BMediaFile::TrackAt() or BMediaFile::CreateTrack()
Summary:  more...

The BMediaTrack class provides access to a particular track in a media file. It's always instantiated using the BMediaFile::TrackAt() or BMediaFile::CreateTrack() function.

The BMediaTrack constructor searches for a codec that can handle the encoded data in the track; once that's been done, the track is ready to be used.

If you opened the file for writing, you can write data into the track. If you specified the B_MEDIA_FILE_REPLACE_MODE flag when constructing the BMediaFile, you can both read and write from the file. If no decoder is available for the track, you can still use ReadChunk() to access the encoded data directly.

After instantiating the BMediaTrack, using the BMediaFile functions for doing so, you should call InitCheck() to be sure the track is valid. You can then use ReadFrames() and WriteFrames() to read and write data to the file, as appropriate. For video data, you should work one frame at a time.

You can also seek particular times or frames using SeekToTime() or SeekToFrame().

For an example of how to use BMediaTrack to read and write tracks in media files, see "Reading and Writing Media Files"

As a general rule, you can't use wildcards in any structures used by BMediaTrack functions. You tell BMediaTrack what format you have, and BMediaTrack will simply tell you whether or not that format is supported.

Destructor

~BMediaTrack()

virtual ~BMediaTrack(void)

Destructor. You shouldn't delete a BMediaTrack directly; instead, use BMediaFile::ReleaseTrack() or BMediaFile::ReleaseAllTracks(), or let BMediaFile destroy the track objects when it's deleted.

Member Functions

AddCopyright()

status_t AddCopyright(const char *data) const

Sets the track's copyright notice to the text specified by data, replacing the existing copyright notice if one exists.

The BMediaTrack class doesn't automatically perform any locking to prevent multiple writes to the track from occurring at the same time. If you have multiple threads writing into the same BMediaTrack, you must use a locking mechanism (such as a semaphore) to keep writes from overlapping.

RETURN CODES

• B_OK. The copyright was set.

• EPERM. The file isn't opened for writing.

• Other errors, depending on the codec.

AddTrackInfo()

status_t AddTrackInfo(uint32 code, const void *data, size_t size,       uint32 flags = 0) const

Adds an informational record of the specified type to the track. The record is specified by the data pointer, and is size bytes long. flags contains flags that modify the operation (none are defined at this time).

The BMediaTrack class doesn't automatically perform any locking to prevent multiple writes to the track from occurring at the same time. If you have multiple threads writing into the same BMediaTrack, you must use a locking mechanism (such as a semaphore) to keep writes from overlapping.

RETURN CODES

• B_OK. The format was successfully returned.

• Other errors. The error returned depends on the codec interpreting the data.

CountFrames()

int64 CountFrames(void) const

Returns the total number of frames in the track.

CurrentFrame()

int64 CurrentFrame(void) const

Returns the current frame in the track (the frame that will be read next by GetNextFrames().

CurrentTime()

bigtime_t CurrentTime(void) const

Returns the current position within the track, expressed in microseconds since the start of the track.

DecodedFormat()

status_t DecodedFormat(media_format *ioFormat) const

Negotiates the format that the codec will output when decoding the track's data. Pass in ioFormat the format that you want (with wildcards as applicable). The codec will find and return in ioFormat its best matching format; this format will then be used when outputting decoded data via ReadFrames().

The format is typically of a B_MEDIA_RAW_AUDIO or B_MEDIA_RAW_VIDEO flavor.

RETURN CODES

• B_OK. The format was successfully negotiated and returned.

• B_ERROR. The BMediaTrack wasn't properly initialized, or there's no codec for the track's data.

• Other errors. The error returned depends on the codec interpreting the data.

Duration()

bigtime_t Duration(void) const

Returns the total duration of the track, in microseconds.

EncodedFormat()

status_t EncodedFormat(media_format *outFormat) const

Returns the "native" encoded format of the track's data. This is the format of the data returned by ReadChunk().

RETURN CODES

• B_OK. The format was successfully returned.

• Other errors. The error returned depends on the codec interpreting the data.

FindKeyFrameForTime() , FindKeyFrameForFrame()

status_t FindKeyFrameForTime(bigtime_t *inOutTime, int32 flags = 0) status_t FindKeyFrameForFrame(int64 *inOutFrame, int32 flags = 0)

FindKeyFrameForTime() accepts in inOutTime a time, and returns in inOutTime the time at which the closest key frame to that time begins. Likewise, FindKeyFrameForFrame() returns the closest key frame number to the specified frame.

The flags argument lets you indicate whether to seek forward or backward for the key frame.

If you want to find the nearest key frame before the indicated frame or time, specify B_MEDIA_SEEK_CLOSEST_BACKWARD in flags. If you want to find the nearest key frame after the indicated frame or time, specify B_MEDIA_SEEK_CLOSEST_FORWARD.

Flush()

status_t Flush(void)

Flushes all buffered encoded data to disk; you should call this function after you've finished writing the last frame to the track. This ensures that everything's flushed at the right offset into the file.

RETURN CODES

• B_OK. The buffers were flushed.

• Other errors, depending on the codec.

GetCodecInfo()

status_t GetCodecInfo(media_codec_info *codecInfo) const

Returns information about the codec being used to read or write the track's data.

RETURN CODES

• B_OK. The codec info was returned.

• B_BAD_TYPE. There's no valid codec in use by the track.

GetEncodeParameters() , SetEncodeParameters()

status_t GetEncodeParameters(encode_parameters *parameters) const status_t SetEncodeParameters(encode_parameters *parameters)

GetEncodeParameters() returns the encode_parameters being used when encoding data on the track.

SetEncodeParameters() changes the encode_parameters being used while encoding data.

GetParameterValue() see SetParameterValue()

GetParameterView()

BView *GetParameterView(void)

Returns a BView containing controls for adjusting the codec's and track's parameters. Returns NULL if there isn't a view available.

GetQuality() see SetQuality()

InitCheck()

status_t InitCheck(void) const

Returns a status code indicating whether or not the track was successfully and completely instantiated.

RETURN CODES

• B_OK. The track was constructed properly.

• B_BAD_VALUE. An error occurred setting up the track.

ReadChunk()

status_t ReadChunk(char **outBuffer, int32 *ioSize,       media_header *header = NULL)

Returns in outBuffer a pointer to the next ioSize bytes of the media track; the actual number of bytes returned is returned in ioSize; this may be different if the end of the track is reached. The header is set to describe the returned buffer.

The data returned by this function isn't decoded. Typically you'll only use this function if there's no codec available to decode the media data.

RETURN CODES

• B_OK. The format was successfully negotiated and returned.

• B_ERROR. The BMediaTrack wasn't properly initialized, or there's no codec for the track's data.

• Other errors. The error returned depends on the codec interpreting the data.

ReadFrames()

status_t ReadFrames(void *outBuffer, int64 *outFrameCount,       media_header *outHeader = NULL) status_t ReadFrames(void *outBuffer, int64 *outFrameCount,       media_header *outHeader = NULL,       media_decode_info *info)

Fills the buffer pointed to by outBuffer with the next frames or samples from the track, starting at the current position. For video tracks, the next frame of video is decoded and stored into the output buffer. For audio tracks, the buffer is filled with the number of frames negotiated using DecodedFormat(). If the end of the track is reached before the buffer is filled, a partial buffer will be returned.

On return, outFrameCount indicates the number of frames returned, and outHeader, if you specified a non-NULL value, contains the header of the buffer containing the frame or frames. You can obtain useful information (such as the media start time for the buffer) from the header.

The second form of this function lets you provide a media_decode_info structure to provide additional information to the decoder, such as how much time it's allowed to use to decode the data and format- and codec-specific information.

RETURN CODES

• B_OK. The frames have been returned.

• EPERM. The file wasn't opened for reading.

• Other errors. The error returned depends on the codec interpreting the data.

ReplaceFrames()

status_t ReplaceFrames(void *inBuffer, int64 *ioFrameCount,       media_header *header)

Replaces the number of frames specified in ioFrameCount in the track. inBuffer points to the source buffer for the new frames.

SeekToFrame() , SeekToTime()

status_t SeekToFrame(int64 *ioFrame, int32 flags = 0) status_t SeekToTime(bigtime_t *ioTime, int32 flags = 0)

Seeks to the specified position in the track. SeekToFrame() accepts a destination position as a frame number, and SeekToTime() accepts a destination position as time in microseconds. They each return (in ioFrame or in ioTime) the position to which they actually moved.

For example, if a video codec is only capable of seeking to key frames, the returned ioFrame might be different than the one specified on input.

If you want to seek explicitly to the nearest key frame before the current frame, specify B_MEDIA_SEEK_CLOSEST_BACKWARD in flags. If you want to find the nearest key frame after the current time, specify B_MEDIA_SEEK_CLOSEST_FORWARD.

RETURN CODES

• B_OK. The format was successfully returned.

• Other errors. The error returned depends on the codec interpreting the data.

SetEncodeParameters() see GetEncodeParameters()

SetParameterValue() , GetParameterValue()

status_t SetParameterValue(int32 id, const void *value, size_t size) status_t GetParameterValue(int32 id, const void *value, size_t *size)

SetParameterValue() sets the value of the parameter specified by id to the data pointed to by value; this data is size bytes long.

GetParameterValue() returns in value the value of the specified parameter, and the size of the value in bytes in the size argument.

RETURN CODES

• B_OK. No error.

• EPERM. The codec ins't configurable.

• Other errors, depending on the codec.

SetQuality() , GetQuality()

status_t SetQuality(float quality) status_t GetQuality(float *quality)

These functions set and return the codec's quality setting (where 1.0 means maximum quality).

RETURN CODES

• B_OK. No error.

• B_ERROR. The codec doesn't support a quality setting.

• Other errors, depending on the codec.

Web()

BParameterWeb *Web(void)

Returns a BParameterWeb that can be used for configuring the track and codec. Returns NULL if the codec doesn't support user configuration.

WriteChunk()

status_t WriteChunk(void *data, size_t size, int32 flags = 0)

Writes the data pointed to by data, which contains size bytes of data, into the track. Specify B_MEDIA_KEY_FRAME for flags if the frame is a key frame. It's assumed that the data is already encoded.

The BMediaTrack class doesn't automatically perform any locking to prevent multiple writes to the track from occurring at the same time. If you have multiple threads writing into the same BMediaTrack, you must use a locking mechanism (such as a semaphore) to keep writes from overlapping.

In general, you should only use WriteChunk() if you're reading compressed data from one file and copying it into another, without trying to interpret the data.

RETURN CODES

• B_OK. The frames have been written.

• EPERM. The file wasn't opened for writing.

• Other errors. The error returned depends on the codec writing the data.

WriteFrames()

status_t WriteFrames(void *data, int32 numFrames,       int32 flags = 0)

Writes the data pointed to by data, which contains numFrame frames, into the track. Specify B_MEDIA_KEY_FRAME for flags if the frame is a key frame.

The BMediaTrack class doesn't automatically perform any locking to prevent multiple writes to the track from occurring at the same time. If you have multiple threads writing into the same BMediaTrack, you must use a locking mechanism (such as a semaphore) to keep writes from overlapping.

You always have to select an encoder before writing frames into a media track, even if the data is raw audio or video. When writing raw audio or video data into a BMediaTrack, you need to use the raw encoder. Even though this doesn't transform the data, it sets up internal data that's necessary for the file to be played back properly after it's created.

RETURN CODES

• B_OK. The frames have been written.

• EPERM. The file wasn't opened for writing.

• Other errors. The error returned depends on the codec writing the data.

Constants

media_seek_type

Declared in:  be/media/MediaTrack.h

Constant	Description
B_MEDIA_SEEK_CLOSEST_FORWARD	Seek to the nearest key frame after the current position in the track.
B_MEDIA_SEEK_CLOSEST_BACKWARD	Seek to the nearest key frame before the current position in the track.
B_MEDIA_SEEK_DIRECTION_MASK	Mask the seek flags with this value to obtain the seek direction.

These flags, used when calling SeekToTime() and SeekToFrame(), let you look for the nearest key frame after or before the current position in the file, without having to guess the time or frame number at which it's located.