The Media Kit: Global Functions, Constants, and Defined Types

This section lists parts of the Media Kit that aren't contained in classes.

Global Functions

format_is_compatible()

bool format_is_compatible(const media_format &format1, const media_format &format2)

Returns true if media data of format format1 can be fed into a consumer that accepts data in media_format format2; otherwise, returns false.

string_for_format()

bool string_for_format(const media_format &format, char *outBuffer, size_t bufferSize)

Fills the buffer specified by outBuffer with a string describing the specified format. The buffer's size is specified by the bufferSize argument. The string may not be pretty, but it will list all kinds of interesting information about the format.

If a description is returned, this function returns true. Otherwise, the result is false.

Constants

Data Endianness

Constant	Description
`B_MEDIA_BIG_ENDIAN`	The media data is big-endian
`B_MEDIA_LITTLE_ENDIAN`	The media data is little-endian.

These values indicate whether media data is little-endian or big-endian.

Media Message Size

   
   const size_t B_MEDIA_MESSAGE_SIZE = 16384;

The B_MEDIA_MESSAGE_SIZE constant specifies the maximum possible size a message a node's service thread can receive. 16k is an upper limit and won't be exceeded. Your thread can simply create a buffer this large, read_port() into it, and call HandleMessage() to process it.

Notification Message "what" Codes

Constant	Meaning
`B_MEDIA_NODE_CREATED`	A new node has been created
`B_MEDIA_NODE_DELETED`	Not sent in R4.
`B_MEDIA_CONNECTION_MADE`	Not sent in R4.
`B_MEDIA_CONNECTION_BROKEN`	Not sent in R4.
`B_MEDIA_BUFFER_CREATED`	Not sent in R4.
`B_MEDIA_BUFFER_DELETED`	Not sent in R4.
`B_MEDIA_TRANSPORT_STATE`	Not sent in R4.
`B_MEDIA_PARAMETER_CHANGED`	Indicates that a parameter in a BPa rameterWeb has changed.
`B_MEDIA_FORMAT_CHANGED`	Not sent in R4.
`B_MEDIA_WEB_CHANGED`	Indicates that a node's BParameter Web has changed.

Messages with these 'what' are sent by the media server to any application that's registered to receive notifications by calling BMediaRoster::StartWatching().

The B_MEDIA_TRANSPORT_STATE message isn't sent in BeOS R4.

The B_MEDIA_NODE_CREATED and B_MEDIA_NODE_DELETED messages both have one field:

Field	Type Code	Description
"be:media_node_id"	`B_INT32_TYPE`	The ID of the media_node that was created or deleted.

The B_MEDIA_CONNECTION_MADE message has three data fields:

Field	Type Code	Description
"be:output"	`B_RAW_TYPE`	A media_output structure describing the connection's output.
"be:input"	`B_RAW_TYPE`	A media_input structure describing the connection's input.
"be:format"	`B_RAW_TYPE`	A media_format structure describing the format of the data that flows across the connection.

The B_MEDIA_CONNECTION_BROKEN message has two data fields:

Field	Type Code	Description
"be:destination"	`B_RAW_TYPE`	A media_destination structure describing the destination of the connection that's been broken.
"be:source"	`B_RAW_TYPE`	A media_source structure describing the source of the connection that's been broken.

The B_MEDIA_BUFFER_CREATED message has one field:

Field	Type Code	Description
"be:clone_info"	`B_RAW_TYPE`	An area_info structure describing the buffer's location in memory. This is an array, one entry per buffer created.

The B_MEDIA_BUFFER_DELETED message has one field:

Field	Type Code	Description
"be:media_buffer_id"	`B_INT32_TYPE`	The buffer ID number of the buffer being deleted. This is an array, one entry per buffer deleted.

The B_MEDIA_FORMAT_CHANGED message has three data fields:

Field	Type Code	Description
"be:source"	`B_RAW_TYPE`	A media_source structure describing the source of the connection whose format changed.
"be:destination"	`B_RAW_TYPE`	A media_source structure describing the source of the connection whose format changed.
"be:format"	`B_RAW_TYPE`	A media_format structure describing the new format.

The B_MEDIA_PARAMETER_CHANGED message has two data fields:

Field	Type Code	Description
"be:node"	`B_RAW_TYPE`	A media_node structure indicating which node's parameter web has changed.
"be:parameter"	`B_INT32_TYPE`	The ID number of the parameter whose value has changed.

The B_MEDIA_WEB_CHANGED message has one data field:

Field	Type Code	Description
"be:node"	`B_RAW_TYPE`	A media_node structure indicating which node's parameter web has changed.

Producer Data Status Values

Constant	Description
`B_DATA_NOT_AVAILABLE`	There aren't any buffers ready for the destination.
`B_DATA_AVAILABLE`	There are buffers ready for the destination.

These values can be specified when your producer node calls BBufferProducer::SendDataStatus() to tell the consumer it's feeding whether or not data is available for it to process.

media_flags

Constant	Description
`B_MEDIA_FLAGS_VERSION`	Returns the Media Kit version as an int32 value.

The media_flags indicate values you can pass to BMediaRoster::MediaFlags() to get information about the version of the Media Kit that your application is running under.

media_type

Constant	Description
`B_MEDIA_NO_TYPE`	Typeless media data.
`B_MEDIA_UNKNOWN_TYPE`	Unknown media type.
`B_MEDIA_RAW_AUDIO`	Uncompressed, linear audio.
`B_MEDIA_RAW_VIDEO`	Uncompressed, linear video.
`B_MEDIA_VBL`	Raw data from VBL area.
`B_MEDIA_TIMECODE`	Timecode data. Undetermined format.
`B_MEDIA_MIDI`	MIDI.
`B_MEDIA_TEXT`	Text data; typically closed-captioning information.
`B_MEDIA_HTML`	HTML data.
`B_MEDIA_MULTISTREAM`	Multi-stream media data, such as AVI or QuickTime.
`B_MEDIA_PARAMETERS`	BControllable change data.
`B_MEDIA_ENCODED_AUDIO`	Encoded audio (such as AC3 or DTS).
`B_MEDIA_ENCODED_VIDEO`	Encoded video (such as Indeo or MPEG).
`B_MEDIA_PRIVATE`	Base value for private Be media types.
`B_MEDIA_FIRST_USER_TYPE`	Base value for user-defined media types.

Types of media data.

node_kind

Constant	Description
`B_BUFFER_PRODUCER`	The flavor implements BBufferProducer.
`B_BUFFER_CONSUMER`	The flavor implements BBufferConsumer.
`B_TIME_SOURCE`	The flavor implements BTimeSource.
`B_CONTROLLABLE`	The flavor implements BControllable.
`B_FILE_INTERFACE`	The flavor implements BFileInterface.
`B_ENTITY_INTERFACE`	The flavor implements BEntityInterface (not available for R4).
`B_PHYSICAL_INPUT`	The flavor represents a physical input point (such as an input jack).
`B_PHYSICAL_OUTPUT`	The flavor represents a physical output point (such as line output).
`B_SYSTEM_MIXER`	The flavor represents the system mixer.

Defines the type or types of node that a particular flavor supports. Note that a flavor can implement more than one type of node, so you can combine these values using a bitwise or.

video_orientation

Constant	Description
`B_VIDEO_TOP_LEFT_RIGHT`	Typical progressive scan: top to bottom, left to right.
`B_VIDEO_BOTTOM_LEFT_RIGHT`	Bottom to top, left to right (BMP and TGA graphics are oriented this way).

Indicates the orientation of video data (whether the data is oriented top to bottom or bottom to top).

Defined Types

live_node_info

   struct live_node_info {
      live_node_info();
      ~live_node_info();
      media_node node;
      BPoint hint_point;
      char name[B_MEDIA_NAME_LENGTH];
   
   private:
      reserved[160];
   };

The live_node_info structure describes an active node, and is returned by BMediaRoster::GetLiveNodes().

node specifies which node the live_node_info structure describes.
hint_point is reserved for future use. Pass a BPoint with x and y both set to 0.

media_addon_id

   typdef int32 media_addon_id;

A media add-on ID number.

media_audio_header

   struct media_audio_header {
      int32 _reserved_[16];
   };

Defines the header of an audio buffer. There are no Be-defined fields in this structure as of the release of BeOS R4; however, you may append fields to the end of this structure if you wish.

media_buffer_id

   typdef int32 media_buffer_id;

A media buffer ID number.

media_destination

   struct media_destination {
      media_destination(port_id, int32);
      media_destination(const media_destination &clone);
      media_destination & operator=(const media_destination &clone);
      media_destination();
      ~media_destination();
      port_id port;
      int32 id;
   static media_destination null;
   private:
      uint32 _reserved_media_destination_[2];
   };

Describes the destination end of a media connection between two nodes. The port indicates the port ID on which the destination communicates. This can be different from the media_node.port value.

media_encoded_audio_format

   struct media_encoded_audio_format {
      enum audio_encoding {   
         B_ANY = 0,
         B_AC3 = 100,
         B_MPEG1,
         B_MPEG2,
         B_PRIVATE = 90000,
         B_FIRST_USER_TYPE = 100000
      };
      media_raw_audio_format output;
      audio_encoding encoding;
      float bit_rate;
      size_t frame_size;
   static media_encoded_audio_format wildcard;
   };

Describes the format of encoded audio data.

output indicates the raw audio format that results from decoding the encoded audio.
encoding specifies the encoding format.
bit_rate specifies the bit rate (not byte rate) of the data stream.
frame_size indicates the size of each frame of audio, in bytes.

media_encoded_audio_header

   struct media_encoded_audio_header {
      int32 _reserved_0[15];
      uchar unused_mask;
      uchar _reserved_2[3];
   };

Defines the header of a an encoded audio buffer. As of the release of BeOS R4, there is only one Be-defined field: unused_mask, which indicates which bits of the last byte in the buffer are unused (since encoded audio may result in a number of bits that doesn't fill up the last byte in the buffer).

If you wish, you can add more fields to the end of the header.

media_encoded_video_format

   struct media_encoded_video_format {
      enum video_encoding {   
         B_ANY = 0,
         B_CINEPAK = 200,
         B_INDEO,
         B_DV,
         B_MPEG1,
         B_MPEG2,
         B_PRIVATE = 90000,
         B_FIRST_USER_TYPE = 100000
      };
      media_raw_video_format output;
      float avg_bit_rate;
      float max_bit_rate;
      video_encoding encoding;
      size_t frame_size;
   
   static media_encoded_video_format wildcard;
   };

Describes the format of encoded video data.

output specifies the raw video format that results from decoding the video.
avg_bit_rate indicates the average bit rate of the video, and max_bit_rate specifies the maximum bit rate that occurs at any point in the video.
encoding indicates the encoding type used by the video data.
frame_size indicates the size in bytes of a frame of data.

media_encoded_video_header

   struct media_encoded_video_header {
      uint32 _reserved_1[11];
      uchar unused_mask;
      uchar _reserved_2[3];
      float field_gamma;
      uint32 field_sequence;
      uint16 field_number;
      uint16 _reserved_3;
      uint16 pulldown_number;
      uint32 first_active_line;
      uint32 line_count;
   };

Defines the header of a video buffer. The fields in this buffer are the same as those in the media_video_header structure, except for the reserved fields, and the unused_mask, which indicates which bits are unused in the last byte of the video buffer.

You may add fields to the end of this buffer if your video format requires them.

media_file_format

   struct media_file_format {
      enum {   
         B_READABLE = 0x1,
         B_WRITABLE = 0x2,
         B_PERFECTLY_SEEKABLE = 0x4,
         B_IMPERFECTLY_SEEKABLE = 0x8,
         B_KNOWS_VIDEO = 0x10,
         B_KNOWS_AUDIO = 0x20,
         B_KNOWS_MIDI = 0x40,
         B_KNOWS_OTHER = 0x1000000,
         B_KNOWS_ANYTHING = 0x2000000
      };
      uint32 flags;
      uint32 _reserved_[31];
      char mime_type[256];
   };

Describes a media file format.

flags is a bitfield providing informational flags describing the file format's capabilities.
B_READABLE indicates that the file format is readable.
B_WRITABLE indicates that the format can be written.
B_PERFECTLY_SEEKABLE indicates that seek operations are precise.
B_IMPERFECTLY_SEEKABLE indicates that seek operations may not be totally accurate.
B_KNOWS_VIDEO indicates that the file format can handle video.
B_KNOWS_AUDIO indicates that the format can handle audio.
B_KNOWS_MIDI indicates that the format can handle MIDI data.
B_KNOWS_OTHER indicates that the format can handle other media information, such as text, clipping, control changes, and so forth.
B_KNOWS_ANYTHING indicates that the format can handle any kind of media data.
mime_type specifies the MIME type string that identifies the file format.

media_format

   struct media_format {
      media_type type;
      type_code user_data_type;
      uchar user_data[64];
      uint32 _reserved_[6];
      union {
         media_raw_audio_format raw_audio;
         media_raw_video_format raw_video;
         media_multistream_format multistream;
         media_encoded_audio_format encoded_audio;
         media_encoded_video_format encoded_video;
         char _reserved_[96];
      } u;
   };

The media_format structure can describe any media data format the BeOS can support.

type indicates the type of media the format describes.
user_data_type and user_data allow the application to store custom data in the media_format structure; user_data_type specifies the type of data stored in user_data (B_INT32_TYPE, B_STRING_TYPE, etc).
The union, u, permits the selection of a specific media format, such as raw audio or multistream data, and contains the descriptive information specific to that media format.

If any field is 0, it's treated as a wildcard.

media_header

   struct media_header {
      media_type type;
      media_buffer_id buffer;
      uint32 destination;
      media_node_id time_source;
      uint32 change_tag
      uint32 size_used;
      bigtime_t start_time;
      port_id owner;
      type_code user_data_type;
      uchar user_data[64];
      uint32 _reserved_[6];
      union {
         media_raw_audio_format raw_audio;
         media_raw_video_format raw_video;
         media_multistream_format multistream;
         media_encoded_audio_format encoded_audio;
         media_encoded_video_format encoded_video;
         char _reserved_[64];
      } u;
   };

Defines the header of a media data buffer.

type indicates the type of media the format describes.
buffer indicates what buffer the header goes with. This field is filled out by the BBufferProducer::SendBuffer() function.
destination specifies the ID number of the media_destination to which the buffer is being sent. This field is filled out by the BBufferProducer::SendBuffer() function.
time_source indicates the ID number of the node that encoded the start_time.
change_tag increases each time the format is changed. This field is filled out by the BBufferProducer::SendBuffer() function.
size_used specifies how many bytes of the buffer actually contain data.
start_time indicates the performance time at which the buffer should be performed.
owner specifies the port ID of the buffer's owner.
user_data_type and user_data allow the application to store custom data in the media_format structure; user_data_type specifies the type of data stored in user_data (B_INT32_TYPE, B_STRING_TYPE, etc).
The union, u, permits the selection of a specific media format, such as raw audio or multistream data, and contains the descriptive information specific to that media format.

media_input

   struct media_input {
      media_input();
      ~media_input();
      media_node node;
      media_source source;
      media_destination destination;
      media_format format;
      char name[B_MEDIA_NAME_LENGTH];
   
   private:
      _reserved_media_input_[4];
   };

The media_input structure describes a complete connection between a media_source and media_destination, from the point-of-view of the consumer (the destination).

node is the media_node that owns the input.
source is the source socket from which the data is being sent.
destination is the destination socket at which the data is arriving.
format is the format of the data.
name is the input's name.

media_multistream_format

   struct media_multistream_format {
      enum {   
         B_ANY = 0,
         B_VID = 1,
         B_AVI,
         B_MPEG1,
         B_MPEG2,
         B_QUICKTIME,
         B_PRIVATE = 90000,
         B_FIRST_USER_TYPE = 100000
      };
      float avg_bit_rate;
      float max_bit_rate;
      uint32 avg_chunk_size;
      uint32 max_chunk_size;
      enum {
         B_HEADER_HAS_FLAGS = 0x1,
         B_CLEAN_BUFFERS = 0x2,
         B_HOMOGENOUS_BUFFERS = 0x4
      };
      uint32 flags;
      int32 format;
      uint32 _reserved_[2];
   
      struct vid_info {
         float frame_rate;
         uint16 width;
         uint16 height;
         color_space space;
   
         float sampling_rate;
         uint32 sample_format;
         uint16 byte_order;
         uint16 channel_count;
      };
      struct avi_info {
         uint32 us_per_frame;
         uint16 width;
         uint16 height;
         uint16 _reserved_;
         uint16 type_count;
         media_type types[5];
      };
   
      union {
         vid_info vid;
         avi_info avi;
      } u;
   
   static media_multistream_format wildcard;
   };

Describes the format of multistream media data, such as a QuickTime, AVI, or MPEG movie.

avg_bit_rate and max_bit_rate indicate the average and maximum bit rates of the media data.
avg_chunk_size and max_chunk_size indicate the average and maximum buffer sizes; if all buffers are the same size, these two values should be equal.
flags provides informational flags for the buffers. B_HEADER_HAS_FLAGS indicates that the buffers' headers have valid flags; B_CLEAN_BUFFERS indicates that each buffer represents an integral number of frames, and B_HOMOGENOUS_BUFFERS indicates that each buffer has only one format in it.
format indicates the multistream data format (B_AVI, B_QUICKTIME, etc).
The union u contains either a vid_info or avi_info structure that describes the video stream:

vid_info

frame_rate specifies the video frame rate (in frames per second).
width and height indicate the width and height of the video, in pixels.
space indicates the video's color space.
sampling_rate, sample_format, byte_order, and channel_count specify the sampling rate, sample format, byte order, and number of channels (stereo or mono) of the media's audio.

avi_info

us_per_frame specifies the number of microseconds each frame should be displayed.
width and height indicate the width and height of the video in pixels.
type_count indicates the number of media_types used in the AVI movie.
types is a list of the media_types used.

media_multistream_header

   struct media_multistream_header {
      uint32 _reserved_[14];
      uchar unused_mask;
      uchar _reserved_2[3];
      enum {
         B_MASTER_HEADER = 0x1,
         B_SUBSTREAM_HEADER = 0x2,
         B_COMPLETE_BUFFER = 0x4
      };
      uint32 flags;
   };

Defines the header of a multistream media buffer.

unused_mask indicates which bits of the last byte in the buffer are unused.
flags provides informational flags about the buffer. If B_MASTER_HEADER is specified, master stream header data is in the buffer; B_SUBSTREAM_HEADER indicates that the buffer contains substream header information. B_COMPLETE_BUFFER indicates that the buffer's data represents an integral number of frames.

You may add fields to the end of this structure if your multistream media format requires them.

media_node

   class media_node {
   public:
      media_node();
      ~media_node();
   
      media_node_id node;
      port_id port;
      uint32 kind;
   
   static media_node null;
   
   private:
      uint32 _reserved_[3];
   };

The media_node structure is the class that defines a node to client applications; interactions with the BMediaRoster regarding nodes is done using media_node objects.

node indicates the node's ID number.
port specifies the port ID number of the node's control port.
kind specifies the node's media kind. See node_kind for a list of node kinds.
null represents a null node

Applications will usually treat this as a black box.

media_node_id

   typdef int32 media_node_id;

A node ID number.

media_output

   struct media_output {
      media_output();
      ~media_output();
      media_node node;
      media_source source;
      media_destination destination;
      media_format format;
      char name[B_MEDIA_NAME_LENGTH];
   
   private:
      _reserved_media_output_[4];
   };

The media_output structure describes a complete connection between a media_source and media_destination, from the point-of-view of the consumer (the destination).

node is the media_node that owns the output.
source is the source socket from which the data is being sent.
destination is the destination socket to which the data is being sent.
format is the format of the data.
name is the output's name.

media_raw_audio_format

   struct media_raw_audio_format {
      enum {   
         B_AUDIO_UCHAR = 0x11,
         B_AUDIO_SHORT = 0x2,
         B_AUDIO_FLOAT = 0x24,
         B_AUDIO_INT = 0x4
      };
      float   frame_rate;
      uint32   channel_count;
      uint32   format;
      uint32   byte_order;
      size_t   buffer_size;
   
   static media_raw_audio_format wildcard;
   };

Describes the format of raw audio data.

The frame_rate indicates the frame rate, in Hertz.

The channel_count indicates the number of channels of audio (typically this is either 1 for mono or 2 for stereo).

The format specifies the sample format (for compressed formats, see media_encoded_audio_format):

B_AUDIO_UCHAR. Each sample is one byte; 128 is the midpoint, 1 is the bottom, 255 is the top.
B_AUDIO_SHORT. Each sample is two bytes; 0 is the middle, -32767 is the bottom, 32767 is the top.
B_AUDIO_FLOAT. Each sample is four bytes; 0 is the middle, -1.0 is the bottom, 1.0 is the top.
B_AUDIO_INT. Each sample is four bytes; 0 is the middle, 0x80000001 is the bottom, 0x7FFFFFFF is the top.

The byte_order indicates the endianness of the data (either B_MEDIA_BIG_ENDIAN or B_MEDIA_LITTLE_ENDIAN).

buffer_size indicates the size of each buffer.

media_raw_video_format

   struct media_raw_video_format {
      float field_rate;
      uint32 interlace;
      uint32 first_active;
      uint32 last_active;
      uint32 orientation;
      uint16 pixel_width_aspect;
      uint16 pixel_height_aspect;
      media_video_display_info display
   
   static media_raw_video_format wildcard;
   };

Describes the format of raw video data.

field_rate indicates the field rate. This is 59.94 for NTSC and 50.0 for PAL. If you use BT848 in non-interlaced mode (thereby picking out only every other field), you'd specify 29.97.
interlace specifies how many fields there are per frame. A value of 1 indicates that the video is progressive (non-interlaced). NTSC video is interlaced such that there are two fields per frame, so for standard NTSC video, this value is 2.
first_active and last_active indicate where the VBL lines at the top of the frame end, and where they resume at the bottom of the frame; video data is confined between these two scan lines.
orientation indicates the orientation of the video; this is typically B_VIDEO_TOP_LEFT_RIGHT.
pixel_width_aspect and pixel_height_aspect specify the numerator and denominator of the video's aspect ratio. If the aspect ration is 4:3, these values will be 4 and 3, respectively.

media_source

   struct media_source {
      media_source(port_id, int32);
      media_source(const media_source &clone);
      media_source & operator=(const media_source &clone);
      media_source();
      ~media_source();
      port_id port;
      int32 id;
   static media_source null;
   private:
      uint32 _reserved_media_source_[2];
   };

Describes the source end of a media connection between two nodes. The port field indicates the port ID on which the source communicates. This must be the same as the media_node.port value.

media_video_display_info

   struct media_video_display_info {
      color_space format;
      uint32 line_width;
      uint32 line_count;
      uint32 bytes_per_row;
      uint32 pixel_offset;
      uint32 line_offset;
      uint32 _reserved_[4];
   static media_video_display_info wildcard;
   };

Describes a video buffer in terms of how its contents should be interpreted in order to display it on the screen.

format specifies the buffer's color space.
line_width and line_count indicate the total width of the buffer in pixels, and the total height of the buffer in lines.
bytes_per_row specifies the number of bytes wide the buffer's image is, including any slop space.
pixel_offset indicates the number of bytes between the start of the buffer and the start of the video field.
line_offset specifies the offset between the start of the buffer and the start of the field, in lines.

media_video_header

   struct media_video_header {
      uint32 _reserved_[11];
      float field_gamma;
      uint32 field_sequence;
      uint16 field_number;
      uint16 pulldown_number;
      uint32 first_active_line;
      uint32 line_count;
   };

Defines the header of a video buffer.

field_gamma specifies the gamma at which the video was captured.
field_sequence is an identifying number assigned to the field when it was captured. They progress in sequence; you can tell if a field was dropped by looking for skips in the sequence. Note that this value doesn't necessarily start at 0, and it can wrap back around to 0.
field_number indicates which field of a video frame the buffer represents. It's 0 for field 1, 1 for field 2, and so forth.
pulldown_number indicates that the field represented by the buffer is a duplicate of a field pulldown_number fields back. If this value is 0, it's not a duplicate field. This is used in cases when the video has been converted from one field rate to another, resulting in duplication of fields; these duplicated fields can be marked using pulldown numbers so video hardware and software can optimize their performance by knowing that duplicate fields exist.
first_active_line indicates the topmost line that actually contains video data (instead of VBL data). line_count indicates the number of active video lines in the field.

You may add fields to the end of this buffer if your video format requires them.

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

Last modified November 10, 1998.

Museum

The Media Kit: Global Functions, Constants, and Defined Types