The Media Kit: BMediaFile

The Media Kit Table of Contents | The Media Kit Index

# BMediaFile

Derived from: none

Declared in: be/media/MediaFile.h

Library: libmedia.so

Allocation: Constructor only

###### Summary

The BMediaFile class represents a file containing media data. When instantiated a BMediaFile with an `entry_ref` to an existing media file, it sniffs the file and figures out the right codecs to use when accessing that file.

To read an existing media file, you can then call `GetTrack()` to instantiate BMediaTrack objects fot the file's tracks; these can in turn be used to decode media data from the file.

You can also write data to the file. In this case, you construct the object by specifying an `entry_ref` and a `media_file_format` specification describing the format of the media data you plan to write into the file. You then call `CreateTrack()` to create each track you want to write into the file. Once each track has been created (but is still empty), you call `CommitHeader()` to write the file's header to disk, and you can use BMediaTrack functions to write the actual media data into the tracks.

Call `CloseFile()` when you're finished writing to it (you don't need to call this if you're reading the file).

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

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

## Constructor and Destructor

### BMediaFile()

`BMediaFile(`

const entry_ref *ref`)`

`BMediaFile(`BDataIO *source`)`
`BMediaFile(`const entry_ref *ref, int32 flags = 0`)`
`BMediaFile(`BDataIO *source, int32 flags = 0`)`
`BMediaFile(`const entry_ref *ref, const media_file_format *fileFormat, int32 flags = 0`)`
`BMediaFile(`BDataIO *destination, const media_file_format *fileFormat, int32 flags = 0`)`

The first four forms of the constructor initializes the BMediaFile to read the file specified by ref or by source. Once this has been done, be sure to call `InitCheck()` to ensure that the file was successfully sniffed. If sniffing was successful, the BMediaFile object can then be used to instantiate the BMediaTrack objects necessary to read the file's data.

The second two forms prepare a BMediaFile object for writing to a media file, which is specified by either ref or destination. The format of the file to be written is specified by fileFormat.

The flags can be a combination of the following values:

Constant | Description
--- | ---
`B_MEDIA_FILE_REPLACE_MODE` | Replace any existing media file, if writing.
`B_MEDIA_FILE_NO_READ_AHEAD` | Don't read ahead in the file.
`B_MEDIA_FILE_UNBUFFERED` | Use smaller reads. This can be handy if you're trying to stream low-bitrate files withou;waiting for the extractor to fill a large outgoing buffer.
`B_MEDIA_FILE_BIG_BUFFERS` | Use large buffers.

### ~BMediaFile()

virtual `~BMediaFile(`void`)`

Destructor.

## Member Functions

### AddChunk()

status_t `AddChunk(`int32 type, const void *data, size_t size`)`

Writes a user-defined chunk of data to the file (if doing so is supported by the encoder). The type argument indicates the chunk type, data points to the data to be written, and size indicates the size of the data to write to the file.

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

RETURN CODES

`B_OK`. No error.

- `B_BAD_TYPE`. The BMediaFile doesn't reference a valid file.

- Other errors, depending on the codec.

### AddCopyright() , Copyright()

status_t *`AddCopyright(`const char *data`) `
const char *`Copyright(`void`)` const

`AddCopyright()` sets the file's copyright notice to the string specified by data. Any existing notice is replaced. The string is copied, so the original belongs to you.

`Copyright()` returns the media file's copyright notice, or `NULL` if there isn't one. This string belongs to the BMediaFile, so don't delete or change it.

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

RETURN CODES

`B_OK`. No error. (`AddCopyright()` only)

- `B_BAD_TYPE`. The BMediaFile doesn't reference a valid file. (`AddCopyright()` only)

- Other errors, depending on the codec. (`AddCopyright()` only)

### CloseFile()

status_t `CloseFile(`void`) `

Once all media data has been written to all tracks, you need to call `CloseFile()` so the BMediaFile object can tidy up the file and finish the writing tasks. If you forget to call `CloseFile()`, the resulting file may not be complete.

RETURN CODES

`B_OK`. No error.

- `B_BAD_TYPE`. The BMediaFile doesn't reference a valid file.

- Other errors, depending on the codec.

### CommitHeader()

status_t `CommitHeader(`void`)`

After you've finished adding new tracks to a file, you need to call `CommitHeader()` to let the BMediaFile set up the file's header. This helps optimize the file writing process.

RETURN CODES

`B_OK`. No error.

- `B_BAD_TYPE`. The BMediaFile doesn't reference a valid file.

- Other errors, depending on the codec.

### Copyright() see AddCopyright()

### CountTracks()

int32 `CountTracks(`void`)` const` `

Returns the number of tracks in the media file. The return value is undefined if the initialization failed.

### CreateTrack()

BMediaTrack *`CreateTrack(`media_format *mediaFormat, const media_codec_info *codecInfo`) `
BMediaTrack *`CreateTrack(`media_format *mediaFormat`) `

Creates a new track in the file and returns a BMediaTrack object referencing it. The track is configured to use the media format specified by mediaFormat, and will be written using the codec described by codecInfo. You can only use `BMediaTrack::WriteFrames()` to write into the track.

If you use the second form of the constructor, without a codecInfo argument, the track will be written containing raw media data. You can only use `BMediaTrack::WriteChunk()` to write into the track.

The mediaFormat indicates the format of the buffers you'll be passing along to the write function, and codecInfo specifies the codec you want to use to encode the data into the track.

| The mediaFormat can't contain any wildcards; you have to specify the exact format that you're going to be providing. mediaFormat must also be the same structure you passed to `get_net_encoder()`.

When writing new media files, you should create all your tracks at once before writing any media data. Once all the tracks have been created, be sure to call `CommitHeader()` to write the header to disk. This is necessary since the header size may vary depending on the number of tracks you put in the file, and once you start writing media data into the tracks, it would be difficult (and inefficient) to resize the header.

If an error occurs while creating the new track, `NULL` is returned.

### GetFileFormatInfo()

status_t `GetFileFormatInfo(`media_file_format *info`)` const

Fills the specified `media_file_format` structure with information describing the file format of the file referenced by the BMediaFile object.

RETURN CODES

`B_OK`. No error.

- `B_NO_INIT`. The BMediaFile doesn't reference a valid file.

### GetParameterValue() see SetParameterValue()

### GetParameterView()

BView *`GetParameterView(`void`) `

Returns a BView containing controls for adjusting the file format's parameters. Returns `NULL` if there isn't a view available.

### InitCheck()

status_t `InitCheck(`void`)` const` `

Returns the result code from the constructor. You should always call this after instantiating a BMediaFile object, but before using it.

RETURN CODES

`B_OK`. No error.

- `B_MEDIA_NO_HANDLER`. No codec available for the required or requested format.

- `B_NO_MEMORY`. Not enough memory to set up the codec (writing).

- `B_BAD_INDEX`. The required add-on wasn't found (writing).

- `B_MISSING_SYMBOL`. The add-on doesn't support writing.

### ReleaseTrack() , ReleaseAllTracks()

status_t `ReleaseTrack(` BMediaTrack *track`) `
status_t `ReleaseAllTracks(`void`) `

`ReleaseTrack()` releases the resources used by the specified track. Doing so reduces your application's memory usage. If you want to release every track you're using, you can call `ReleaseAllTracks()`.

Once released, a track can't be used any longer until you use `TrackAt()` again.

If the BMediaFile wasn't properly initialized, or the index is invalid, `NULL` is returned.

RETURN CODES

`B_OK`. No error.

- `B_ERROR`. Couldn't release the track (it may be invalid, or not actually in use).

### 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.

- `B_NO_INIT`. The BMediaFile doesn't reference a valid file.

### TrackAt()

BMediaTrack *`TrackAt(`int32 index`) `

Returns a BMediaTrack object referencing the track at the specified index into the file. The index must be a value between 0 and `CountTracks()` - 1.

If the BMediaFile wasn't properly initialized, or the index is invalid, `NULL` is returned.

| You must call `ReleaseTrack()` when you're finished with the track.

### Web()

BParameterWeb *`Web(`void`) `

Returns a BParameterWeb that can be used for configuring the file format's parameters. Returns `NULL` if the codec doesn't support user configuration.

## Constants

### Constructor Flags

Declared in: be/media/MediaFile.h

Constant | Description
--- | ---
`B_MEDIA_FILE_REPLACE_MODE` | Replace any existing media file, if writing.
`B_MEDIA_FILE_NO_READ_AHEAD` | Don't read ahead in the file.
`B_MEDIA_FILE_UNBUFFERED` | Use smaller reads. This can be handy if you're trying to stream low-bitrate files withou;waiting for the extractor to fill a large outgoing buffer.
`B_MEDIA_FILE_BIG_BUFFERS` | Use large buffers.

These flags control the behavior of the constructor.

The Media Kit Table of Contents | The Media Kit Index

The Be Book,
...in lovely HTML...
for BeOS Release 5.

Copyright © 2000 Be, Inc. All rights reserved..