mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-09-27 14:31:01 +00:00
eb87b3f6bf
Original commit message from CVS: * docs/pwg/advanced-types.xml: Another typo.
1332 lines
46 KiB
XML
1332 lines
46 KiB
XML
<!-- ############ chapter ############# -->
|
|
|
|
<chapter id="chapter-building-types">
|
|
<title>Types and Properties</title>
|
|
<para>
|
|
There is a very large set of possible types that may be used to pass data
|
|
between elements. Indeed, each new element that is defined may use a new
|
|
data format (though unless at least one other element recognises that
|
|
format, it will be most likely be useless since nothing will be able to
|
|
link with it).
|
|
</para>
|
|
<para>
|
|
In order for types to be useful, and for systems like autopluggers to
|
|
work, it is necessary that all elements agree on the type definitions,
|
|
and which properties are required for each type. The &GStreamer; framework
|
|
itself simply provides the ability to define types and parameters, but
|
|
does not fix the meaning of types and parameters, and does not enforce
|
|
standards on the creation of new types. This is a matter for a policy to
|
|
decide, not technical systems to enforce.
|
|
</para>
|
|
<para>
|
|
For now, the policy is simple:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
Do not create a new type if you could use one which already exists.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
If creating a new type, discuss it first with the other &GStreamer;
|
|
developers, on at least one of: IRC, mailing lists.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Try to ensure that the name for a new format is as unlikely to
|
|
conflict with anything else created already, and is not a more
|
|
generalised name than it should be. For example: "audio/compressed"
|
|
would be too generalised a name to represent audio data compressed
|
|
with an mp3 codec. Instead "audio/mp3" might be an appropriate name,
|
|
or "audio/compressed" could exist and have a property indicating the
|
|
type of compression used.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Ensure that, when you do create a new type, you specify it clearly,
|
|
and get it added to the list of known types so that other developers
|
|
can use the type correctly when writing their elements.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
|
|
<!-- ############ sect1 ############# -->
|
|
|
|
<sect1 id="section-types-test" xreflabel="Building a Simple Format for Testing">
|
|
<title>Building a Simple Format for Testing</title>
|
|
<para>
|
|
If you need a new format that has not yet been defined in our <xref
|
|
linkend="section-types-definitions"/>, you will want to have some general
|
|
guidelines on mimetype naming, properties and such. A mimetype would
|
|
ideally be one defined by IANA; else, it should be in the form
|
|
type/x-name, where type is the sort of data this mimetype handles (audio,
|
|
video, ...) and name should be something specific for this specific type.
|
|
Audio and video mimetypes should try to support the general audio/video
|
|
properties (see the list), and can use their own properties, too. To get
|
|
an idea of what properties we think are useful, see (again) the list.
|
|
</para>
|
|
<para>
|
|
Take your time to find the right set of properties for your type. There
|
|
is no reason to hurry. Also, experimenting with this is generally a good
|
|
idea. Experience learns that theoretically thought-out types are good,
|
|
but they still need practical use to assure that they serve their needs.
|
|
Make sure that your property names do not clash with similar properties
|
|
used in other types. If they match, make sure they mean the same thing;
|
|
properties with different types but the same names are
|
|
<emphasis>not</emphasis> allowed.
|
|
</para>
|
|
</sect1>
|
|
|
|
<!-- ############ sect1 ############# -->
|
|
|
|
<sect1 id="section-types-typefind" xreflabel="Typefind Functions and Autoplugging">
|
|
<title>Typefind Functions and Autoplugging</title>
|
|
<para>
|
|
With only <emphasis>defining</emphasis> the types, we're not yet there.
|
|
In order for a random data file to be recognized and played back as
|
|
such, we need a way of recognizing their type out of the blue. For this
|
|
purpose, <quote>typefinding</quote> was introduced. Typefinding is the
|
|
process of detecting the type of a datastream. Typefinding consists of
|
|
two separate parts: first, there's an unlimited number of functions
|
|
that we call <emphasis>typefind functions</emphasis>, which are each
|
|
able to recognize one or more types from an input stream. Then,
|
|
secondly, there's a small engine which registers and calls each of
|
|
those functions. This is the typefind core. On top of this typefind
|
|
core, you would normally write an autoplugger, which is able to use
|
|
this type detection system to dynamically build a pipeline around an
|
|
input stream. Here, we will focus only on typefind functions.
|
|
</para>
|
|
<para>
|
|
A typefind function ususally lives in
|
|
<filename>gst-plugins/gst/typefind/gsttypefindfunctions.c</filename>,
|
|
unless there's a good reason (like library dependencies) to put it
|
|
elsewhere. The reason for this centralization is to decreate the
|
|
number of plugins that need to be loaded in order to detect a stream's
|
|
type. Below is an example that will recognize AVI files, which start
|
|
with a <quote>RIFF</quote> tag, then the size of the file and then an
|
|
<quote>AVI </quote> tag:
|
|
</para>
|
|
<programlisting>
|
|
static void
|
|
gst_my_typefind_function (GstTypeFind *tf,
|
|
gpointer data)
|
|
{
|
|
guint8 *data = gst_type_find_peek (tf, 0, 12);
|
|
|
|
if (data &&
|
|
GUINT32_FROM_LE (&((guint32 *) data)[0]) == GST_MAKE_FOURCC ('R','I','F','F') &&
|
|
GUINT32_FROM_LE (&((guint32 *) data)[2]) == GST_MAKE_FOURCC ('A','V','I',' ')) {
|
|
gst_type_find_suggest (tf, GST_TYPE_FIND_MAXIMUM,
|
|
gst_caps_new_simple ("video/x-msvideo", NULL));
|
|
}
|
|
}
|
|
|
|
static gboolean
|
|
plugin_init (GstPlugin *plugin)
|
|
{
|
|
static gchar *exts[] = { "avi", NULL };
|
|
if (!gst_type_find_register (plugin, "", GST_RANK_PRIMARY,
|
|
gst_my_typefind_function, exts,
|
|
gst_caps_new_simple ("video/x-msvideo",
|
|
NULL), NULL))
|
|
return FALSE;
|
|
}
|
|
</programlisting>
|
|
<para>
|
|
Note that
|
|
<filename>gst-plugins/gst/typefind/gsttypefindfunctions.c</filename>
|
|
has some simplification macros to decrease the amount of code. Make
|
|
good use of those if you want to submit typefinding patches with new
|
|
typefind functions.
|
|
</para>
|
|
<para>
|
|
Autoplugging will be discussed in great detail in the chapter called
|
|
<xref linkend="chapter-other-autoplugger"/>.
|
|
</para>
|
|
</sect1>
|
|
|
|
<!-- ############ sect1 ############# -->
|
|
|
|
<sect1 id="section-types-definitions" xreflabel="List of Defined Types">
|
|
<title>List of Defined Types</title>
|
|
<para>
|
|
Below is a list of all the defined types in &GStreamer;. They are split
|
|
up in separate tables for audio, video, container, subtitle and other
|
|
types, for the sake of readability. Below each table might follow a
|
|
list of notes that apply to that table. In the definition of each type,
|
|
we try to follow the types and rules as defined by <ulink type="http"
|
|
url="http://www.isi.edu/in-notes/iana/assignments/media-types/media-types">
|
|
IANA</ulink> for as far as possible.
|
|
</para>
|
|
<para>
|
|
Jump directly to a specific table:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><xref linkend="table-audio-types"/></para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><xref linkend="table-video-types"/></para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><xref linkend="table-container-types"/></para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><xref linkend="table-subtitle-types"/></para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><xref linkend="table-other-types"/></para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
<para>
|
|
Note that many of the properties are not <emphasis>required</emphasis>,
|
|
but rather <emphasis>optional</emphasis> properties. This means that
|
|
most of these properties can be extracted from the container header,
|
|
but that - in case the container header does not provide these - they
|
|
can also be extracted by parsing the stream header or the stream
|
|
content. The policy is that your element should provide the data that
|
|
it knows about by only parsing its own content, not another element's
|
|
content. Example: the AVI header provides samplerate of the contained
|
|
audio stream in the header. MPEG system streams don't. This means that
|
|
an AVI stream demuxer would provide samplerate as a property for MPEG
|
|
audio streams, whereas an MPEG demuxer would not. A decoder needing
|
|
this data would require a stream parser in between two extract this
|
|
from the header or calculate it from the stream.
|
|
</para>
|
|
|
|
<table frame="all" id="table-audio-types" xreflabel="Table of Audio Types">
|
|
<title>Table of Audio Types</title>
|
|
<tgroup cols="6" align="left" colsep="1" rowsep="1">
|
|
<colspec colnum="1" colname="cola1" colwidth="1*"/>
|
|
<colspec colnum="6" colname="cola6" colwidth="6*"/>
|
|
<spanspec spanname="fullwidth" namest="cola1" nameend="cola6"/>
|
|
|
|
<thead>
|
|
<row>
|
|
<entry>Mime Type</entry>
|
|
<entry>Description</entry>
|
|
<entry>Property</entry>
|
|
<entry>Property Type</entry>
|
|
<entry>Property Values</entry>
|
|
<entry>Property Description</entry>
|
|
</row>
|
|
</thead>
|
|
|
|
<tbody valign="top">
|
|
|
|
<!-- ############ subtitle ############# -->
|
|
|
|
<row>
|
|
<entry spanname="fullwidth">
|
|
<emphasis>All audio types.</emphasis>
|
|
</entry>
|
|
</row>
|
|
|
|
<!-- ############ type ############# -->
|
|
|
|
<row>
|
|
<entry morerows="1">audio/*</entry>
|
|
<entry morerows="1">
|
|
<emphasis>All audio types</emphasis>
|
|
</entry>
|
|
<entry>rate</entry>
|
|
<entry>integer</entry>
|
|
<entry>greater than 0</entry>
|
|
<entry>
|
|
The sample rate of the data, in samples (per channel) per second.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>channels</entry>
|
|
<entry>integer</entry>
|
|
<entry>greater than 0</entry>
|
|
<entry>
|
|
The number of channels of audio data.
|
|
</entry>
|
|
</row>
|
|
|
|
<!-- ############ subtitle ############# -->
|
|
|
|
<row>
|
|
<entry spanname="fullwidth">
|
|
<emphasis>All raw audio types.</emphasis>
|
|
</entry>
|
|
</row>
|
|
|
|
<!-- ############ type ############# -->
|
|
|
|
<row>
|
|
<entry morerows="3">audio/x-raw-int</entry>
|
|
<entry morerows="3">
|
|
Unstructured and uncompressed raw fixed-integer audio data.
|
|
</entry>
|
|
<entry>endianness</entry>
|
|
<entry>integer</entry>
|
|
<entry>G_BIG_ENDIAN (1234) or G_LITTLE_ENDIAN (4321)</entry>
|
|
<entry>
|
|
The order of bytes in a sample. The value G_LITTLE_ENDIAN (4321)
|
|
means <quote>little-endian</quote> (byte-order is <quote>least
|
|
significant byte first</quote>). The value G_BIG_ENDIAN (1234)
|
|
means <quote>big-endian</quote> (byte order is <quote>most
|
|
significant byte first</quote>).
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>signed</entry>
|
|
<entry>boolean</entry>
|
|
<entry>TRUE or FALSE</entry>
|
|
<entry>
|
|
Whether the values of the integer samples are signed or not.
|
|
Signed samples use one bit to indicate sign (negative or
|
|
positive) of the value. Unsigned samples are always positive.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>width</entry>
|
|
<entry>integer</entry>
|
|
<entry>greater than 0</entry>
|
|
<entry>
|
|
Number of bits allocated per sample.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>depth</entry>
|
|
<entry>integer</entry>
|
|
<entry>greater than 0</entry>
|
|
<entry>
|
|
The number of bits used per sample. This must be less than or
|
|
equal to the width: If the depth is less than the width, the
|
|
low bits are assumed to be the ones used. For example, a width
|
|
of 32 and a depth of 24 means that each sample is stored in a
|
|
32 bit word, but only the low 24 bits are actually used.
|
|
</entry>
|
|
</row>
|
|
|
|
<!-- ############ type ############# -->
|
|
|
|
<row>
|
|
<entry morerows="2">audio/x-raw-float</entry>
|
|
<entry morerows="2">
|
|
Unstructured and uncompressed raw floating-point audio data.
|
|
</entry>
|
|
<entry>endianness</entry>
|
|
<entry>integer</entry>
|
|
<entry>G_BIG_ENDIAN (1234) or G_LITTLE_ENDIAN (4321)</entry>
|
|
<entry>
|
|
The order of bytes in a sample. The value G_LITTLE_ENDIAN (4321)
|
|
means <quote>little-endian</quote> (byte-order is <quote>least
|
|
significant byte first</quote>). The value G_BIG_ENDIAN (1234)
|
|
means <quote>big-endian</quote> (byte order is <quote>most
|
|
significant byte first</quote>).
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>width</entry>
|
|
<entry>integer</entry>
|
|
<entry>greater than 0</entry>
|
|
<entry>
|
|
The amount of bits used and allocated per sample.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>buffer-frames</entry>
|
|
<entry>integer</entry>
|
|
<entry>greater than 0</entry>
|
|
<entry>
|
|
The number of frames per buffer. The reason for this property
|
|
is that the element does not need to reuse buffers or use data
|
|
spanned over multiple buffers, so this property - when used
|
|
rightly - will decrease latency. Note that some people think that
|
|
this property is very ugly, whereas others think it is vital for
|
|
the use of &GStreamer; in professional audio applications.
|
|
</entry>
|
|
</row>
|
|
|
|
<!-- ############ subtitle ############# -->
|
|
|
|
<row>
|
|
<entry spanname="fullwidth">
|
|
<emphasis>All encoded audio types.</emphasis>
|
|
</entry>
|
|
</row>
|
|
|
|
<!-- ############ type ############# -->
|
|
|
|
<row>
|
|
<entry>audio/x-ac3</entry>
|
|
<entry>AC-3 or A52 audio streams.</entry>
|
|
<entry></entry>
|
|
<entry></entry>
|
|
<entry></entry>
|
|
<entry>
|
|
There are currently no specific properties defined or needed for
|
|
this type.
|
|
</entry>
|
|
</row>
|
|
|
|
<!-- ############ type ############# -->
|
|
|
|
<row>
|
|
<entry morerows="1">audio/x-adpcm</entry>
|
|
<entry morerows="1">ADPCM Audio streams.</entry>
|
|
<entry>layout</entry>
|
|
<entry>string</entry>
|
|
<entry>
|
|
<quote>quicktime</quote>, <quote>dvi</quote>,
|
|
<quote>microsoft</quote> or <quote>4xm</quote>.
|
|
</entry>
|
|
<entry>
|
|
The layout defines the packing of the samples in the stream. In
|
|
ADPCM, most formats store multiple samples per channel together.
|
|
This number of samples differs per format, hence the different
|
|
layouts. On the long term, we probably want this variable to die
|
|
and use something more descriptive, but this will do for now.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>block_align</entry>
|
|
<entry>integer</entry>
|
|
<entry>
|
|
Any
|
|
</entry>
|
|
<entry>
|
|
Chunk buffer size.
|
|
</entry>
|
|
</row>
|
|
|
|
<!-- ############ type ############# -->
|
|
|
|
<row>
|
|
<entry>audio/x-cinepak</entry>
|
|
<entry>Audio as provided in a Cinepak (Quicktime) stream.</entry>
|
|
<entry></entry>
|
|
<entry></entry>
|
|
<entry></entry>
|
|
<entry>
|
|
There are currently no specific properties defined or needed for
|
|
this type.
|
|
</entry>
|
|
</row>
|
|
|
|
<!-- ############ type ############# -->
|
|
|
|
<row>
|
|
<entry>audio/x-dv</entry>
|
|
<entry>Audio as provided in a Digital Video stream.</entry>
|
|
<entry></entry>
|
|
<entry></entry>
|
|
<entry></entry>
|
|
<entry>
|
|
There are currently no specific properties defined or needed for
|
|
this type.
|
|
</entry>
|
|
</row>
|
|
|
|
<!-- ############ type ############# -->
|
|
|
|
<row>
|
|
<entry>audio/x-flac</entry>
|
|
<entry>Free Lossless Audio codec (FLAC).</entry>
|
|
<entry></entry>
|
|
<entry></entry>
|
|
<entry></entry>
|
|
<entry>
|
|
There are currently no specific properties defined or needed for
|
|
this type.
|
|
</entry>
|
|
</row>
|
|
|
|
<!-- ############ type ############# -->
|
|
|
|
<row>
|
|
<entry>audio/x-gsm</entry>
|
|
<entry>Data encoded by the GSM codec.</entry>
|
|
<entry></entry>
|
|
<entry></entry>
|
|
<entry></entry>
|
|
<entry>
|
|
There are currently no specific properties defined or needed for
|
|
this type.
|
|
</entry>
|
|
</row>
|
|
|
|
<!-- ############ type ############# -->
|
|
|
|
<row>
|
|
<entry>audio/x-alaw</entry>
|
|
<entry>A-Law Audio.</entry>
|
|
<entry></entry>
|
|
<entry></entry>
|
|
<entry></entry>
|
|
<entry>
|
|
There are currently no specific properties defined or needed for
|
|
this type.
|
|
</entry>
|
|
</row>
|
|
|
|
<!-- ############ type ############# -->
|
|
|
|
<row>
|
|
<entry>audio/x-mulaw</entry>
|
|
<entry>Mu-Law Audio.</entry>
|
|
<entry></entry>
|
|
<entry></entry>
|
|
<entry></entry>
|
|
<entry>
|
|
There are currently no specific properties defined or needed for
|
|
this type.
|
|
</entry>
|
|
</row>
|
|
|
|
<!-- ############ type ############# -->
|
|
|
|
<row>
|
|
<entry>audio/x-mace</entry>
|
|
<entry>MACE Audio (used in Quicktime).</entry>
|
|
<entry>maceversion</entry>
|
|
<entry>integer</entry>
|
|
<entry>3 or 6</entry>
|
|
<entry>
|
|
The version of the MACE audio codec used to encode the stream.
|
|
</entry>
|
|
</row>
|
|
|
|
<!-- ############ type ############# -->
|
|
|
|
<row>
|
|
<entry morerows="3">audio/mpeg</entry>
|
|
<entry morerows="3">
|
|
Audio data compressed using the MPEG audio encoding scehem.
|
|
</entry>
|
|
<entry>mpegversion</entry>
|
|
<entry>integer</entry>
|
|
<entry>1, 2 or 4</entry>
|
|
<entry>
|
|
The MPEG-version used for encoding the data. The value 1 refers
|
|
to MPEG-1, -2 and -2.5 layer 1, 2 or 3. The values 2 and 4 refer
|
|
to the MPEG-AAC audio encoding schemes.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>framed</entry>
|
|
<entry>boolean</entry>
|
|
<entry>0 or 1</entry>
|
|
<entry>
|
|
A true value indicates that each buffer contains exactly one
|
|
frame. A false value indicates that frames and buffers do not
|
|
necessarily match up.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>layer</entry>
|
|
<entry>integer</entry>
|
|
<entry>1, 2, or 3</entry>
|
|
<entry>
|
|
The compression scheme layer used to compress the data
|
|
<emphasis>(only if mpegversion=1)</emphasis>.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>bitrate</entry>
|
|
<entry>integer</entry>
|
|
<entry>greater than 0</entry>
|
|
<entry>
|
|
The bitrate, in bits per second. For VBR (variable bitrate)
|
|
MPEG data, this is the average bitrate.
|
|
</entry>
|
|
</row>
|
|
|
|
<!-- ############ type ############# -->
|
|
|
|
<row>
|
|
<entry>audio/x-qdm2</entry>
|
|
<entry>Data encoded by the QDM version 2 codec.</entry>
|
|
<entry></entry>
|
|
<entry></entry>
|
|
<entry></entry>
|
|
<entry>
|
|
There are currently no specific properties defined or needed for
|
|
this type.
|
|
</entry>
|
|
</row>
|
|
|
|
<!-- ############ type ############# -->
|
|
|
|
<row>
|
|
<entry>audio/x-pn-realaudio</entry>
|
|
<entry>Realmedia Audio data.</entry>
|
|
<entry>raversion</entry>
|
|
<entry>integer</entry>
|
|
<entry>1 or 2</entry>
|
|
<entry>
|
|
The version of the Real Audio codec used to encode the stream.
|
|
1 stands for a 14k4 stream, 2 stands for a 28k8 stream.
|
|
</entry>
|
|
</row>
|
|
|
|
<!-- ############ type ############# -->
|
|
|
|
<row>
|
|
<entry>audio/x-speex</entry>
|
|
<entry>Data encoded by the Speex audio codec</entry>
|
|
<entry></entry>
|
|
<entry></entry>
|
|
<entry></entry>
|
|
<entry>
|
|
There are currently no specific properties defined or needed for
|
|
this type.
|
|
</entry>
|
|
</row>
|
|
|
|
<!-- ############ type ############# -->
|
|
|
|
<row>
|
|
<entry>audio/x-vorbis</entry>
|
|
<entry>Vorbis audio data</entry>
|
|
<entry></entry>
|
|
<entry></entry>
|
|
<entry></entry>
|
|
<entry>
|
|
There are currently no specific properties defined or needed for
|
|
this type.
|
|
</entry>
|
|
</row>
|
|
|
|
<!-- ############ type ############# -->
|
|
|
|
<row>
|
|
<entry>audio/x-wma</entry>
|
|
<entry>Windows Media Audio</entry>
|
|
<entry>wmaversion</entry>
|
|
<entry>integer</entry>
|
|
<entry>1,2 or 3</entry>
|
|
<entry>
|
|
The version of the WMA codec used to encode the stream.
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
|
|
<table frame="all" id="table-video-types" xreflabel="Table of Video Types">
|
|
<title>Table of Video Types</title>
|
|
<tgroup cols="6" align="left" colsep="1" rowsep="1">
|
|
<colspec colnum="1" colname="colv1" colwidth="1*"/>
|
|
<colspec colnum="6" colname="colv6" colwidth="6*"/>
|
|
<spanspec spanname="fullwidth" namest="colv1" nameend="colv6"/>
|
|
|
|
<thead>
|
|
<row>
|
|
<entry>Mime Type</entry>
|
|
<entry>Description</entry>
|
|
<entry>Property</entry>
|
|
<entry>Property Type</entry>
|
|
<entry>Property Values</entry>
|
|
<entry>Property Description</entry>
|
|
</row>
|
|
</thead>
|
|
|
|
<tbody valign="top">
|
|
|
|
<!-- ############ subtitle ############# -->
|
|
|
|
<row>
|
|
<entry spanname="fullwidth">
|
|
<emphasis>All video types.</emphasis>
|
|
</entry>
|
|
</row>
|
|
|
|
<!-- ############ type ############# -->
|
|
|
|
<row>
|
|
<entry morerows="2">video/*</entry>
|
|
<entry morerows="2">
|
|
<emphasis>All video types</emphasis>
|
|
</entry>
|
|
<entry>width</entry>
|
|
<entry>integer</entry>
|
|
<entry>greater than 0</entry>
|
|
<entry>The width of the video image</entry>
|
|
</row>
|
|
<row>
|
|
<entry>height</entry>
|
|
<entry>integer</entry>
|
|
<entry>greater than 0</entry>
|
|
<entry>The height of the video image</entry>
|
|
</row>
|
|
<row>
|
|
<entry>framerate</entry>
|
|
<entry>double</entry>
|
|
<entry>greater than 0</entry>
|
|
<entry>
|
|
The (average) framerate in frames per second. Note that this
|
|
property does not guarantee in <emphasis>any</emphasis> way that
|
|
it will actually come close to this value. If you need a fixed
|
|
framerate, please use an element that provides that (such as
|
|
<quote>videodrop</quote>).
|
|
</entry>
|
|
</row>
|
|
|
|
<!-- ############ subtitle ############# -->
|
|
|
|
<row>
|
|
<entry spanname="fullwidth">
|
|
<emphasis>All raw video types.</emphasis>
|
|
</entry>
|
|
</row>
|
|
|
|
<!-- ############ type ############# -->
|
|
|
|
<row>
|
|
<entry>video/x-raw-yuv</entry>
|
|
<entry>YUV (or Y'Cb'Cr) video format.</entry>
|
|
<entry>format</entry>
|
|
<entry>fourcc</entry>
|
|
<entry>
|
|
YUY2, YVYU, UYVY, Y41P, IYU2, Y42B, YV12, I420, Y41B, YUV9, YVU9,
|
|
Y800
|
|
</entry>
|
|
<entry>
|
|
The layout of the video. See <ulink type="http"
|
|
url="http://www.fourcc.org/">FourCC definition site</ulink>
|
|
for references and definitions. YUY2, YVYU and UYVY are 4:2:2
|
|
packed-pixel, Y41P is 4:1:1 packed-pixel and IYU2 is 4:4:4
|
|
packed-pixel. Y42B is 4:2:2 planar, YV12 and I420 are 4:2:0
|
|
planar, Y41B is 4:1:1 planar and YUV9 and YVU9 are 4:1:0 planar.
|
|
Y800 contains Y-samples only (black/white).
|
|
</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry morerows="3">video/x-raw-rgb</entry>
|
|
<entry morerows="3">Red-Green-Blue (RBG) video.</entry>
|
|
<entry>bpp</entry>
|
|
<entry>integer</entry>
|
|
<entry>greater than 0</entry>
|
|
<entry>
|
|
The number of bits allocated per pixel. This is usually 16, 24
|
|
or 32.
|
|
</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>depth</entry>
|
|
<entry>integer</entry>
|
|
<entry>greater than 0</entry>
|
|
<entry>
|
|
The number of bits used per pixel by the R/G/B components. This
|
|
is usually 15, 16 or 24.
|
|
</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>endianness</entry>
|
|
<entry>integer</entry>
|
|
<entry>G_BIG_ENDIAN (1234) or G_LITTLE_ENDIAN (4321)</entry>
|
|
<entry>
|
|
The order of bytes in a sample. The value G_LITTLE_ENDIAN (4321)
|
|
means <quote>little-endian</quote> (byte-order is <quote>least
|
|
significant byte first</quote>). The value G_BIG_ENDIAN (1234)
|
|
means <quote>big-endian</quote> (byte order is <quote>most
|
|
significant byte first</quote>). For 24/32bpp, this should always
|
|
be big endian because the byte order can be given in both.
|
|
</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>red_mask, green_mask and blue_mask</entry>
|
|
<entry>integer</entry>
|
|
<entry>any</entry>
|
|
<entry>
|
|
The masks that cover all the bits used by each of the samples.
|
|
The mask should be given in the endianness specified above. This
|
|
means that for 24/32bpp, the masks might be opposite to host byte
|
|
order (if you are working on little-endian computers).
|
|
</entry>
|
|
</row>
|
|
|
|
<!-- ############ subtitle ############# -->
|
|
|
|
<row>
|
|
<entry spanname="fullwidth">
|
|
<emphasis>All encoded video types.</emphasis>
|
|
</entry>
|
|
</row>
|
|
|
|
<!-- ############ type ############# -->
|
|
|
|
<row>
|
|
<entry>video/x-3ivx</entry>
|
|
<entry>3ivx video.</entry>
|
|
<entry></entry>
|
|
<entry></entry>
|
|
<entry></entry>
|
|
<entry>
|
|
There are currently no specific properties defined or needed for
|
|
this type.
|
|
</entry>
|
|
</row>
|
|
|
|
<!-- ############ type ############# -->
|
|
|
|
<row>
|
|
<entry>video/x-divx</entry>
|
|
<entry>DivX video.</entry>
|
|
<entry>divxversion</entry>
|
|
<entry>integer</entry>
|
|
<entry>3, 4 or 5</entry>
|
|
<entry>
|
|
Version of the DivX codec used to encode the stream.
|
|
</entry>
|
|
</row>
|
|
|
|
<!-- ############ type ############# -->
|
|
|
|
<row>
|
|
<entry>video/x-dx</entry>
|
|
<entry>Digital Video.</entry>
|
|
<entry>systemstream</entry>
|
|
<entry>boolean</entry>
|
|
<entry>FALSE</entry>
|
|
<entry>
|
|
Indicates that this stream is <emphasis>not</emphasis> a system
|
|
container stream.
|
|
</entry>
|
|
</row>
|
|
|
|
<!-- ############ type ############# -->
|
|
|
|
<row>
|
|
<entry>video/x-ffv</entry>
|
|
<entry>FFMpeg video.</entry>
|
|
<entry>ffvversion</entry>
|
|
<entry>integer</entry>
|
|
<entry>1</entry>
|
|
<entry>
|
|
Version of the FFMpeg video codec used to encode the stream.
|
|
</entry>
|
|
</row>
|
|
|
|
<!-- ############ type ############# -->
|
|
|
|
<row>
|
|
<entry>video/x-h263</entry>
|
|
<entry>H-263 video.</entry>
|
|
<entry></entry>
|
|
<entry></entry>
|
|
<entry></entry>
|
|
<entry>
|
|
There are currently no specific properties defined or needed for
|
|
this type.
|
|
</entry>
|
|
</row>
|
|
|
|
<!-- ############ type ############# -->
|
|
|
|
<row>
|
|
<entry>video/x-h264</entry>
|
|
<entry>H-264 video.</entry>
|
|
<entry></entry>
|
|
<entry></entry>
|
|
<entry></entry>
|
|
<entry>
|
|
There are currently no specific properties defined or needed for
|
|
this type.
|
|
</entry>
|
|
</row>
|
|
|
|
<!-- ############ type ############# -->
|
|
|
|
<row>
|
|
<entry>video/x-huffyuv</entry>
|
|
<entry>Huffyuv video.</entry>
|
|
<entry></entry>
|
|
<entry></entry>
|
|
<entry></entry>
|
|
<entry>
|
|
There are currently no specific properties defined or needed for
|
|
this type.
|
|
</entry>
|
|
</row>
|
|
|
|
<!-- ############ type ############# -->
|
|
|
|
<row>
|
|
<entry>video/x-indeo</entry>
|
|
<entry>Indeo video.</entry>
|
|
<entry>indeoversion</entry>
|
|
<entry>integer</entry>
|
|
<entry>3</entry>
|
|
<entry>
|
|
Version of the Indeo codec used to encode this stream.
|
|
</entry>
|
|
</row>
|
|
|
|
<!-- ############ type ############# -->
|
|
|
|
<row>
|
|
<entry>video/x-jpeg</entry>
|
|
<entry>Motion-JPEG video.</entry>
|
|
<entry></entry>
|
|
<entry></entry>
|
|
<entry></entry>
|
|
<entry>
|
|
There are currently no specific properties defined or needed for
|
|
this type. Note that video/x-jpeg only applies to Motion-JPEG
|
|
pictures (YUY2 colourspace). RGB colourspace JPEG images are
|
|
referred to as image/jpeg (JPEG image).
|
|
</entry>
|
|
</row>
|
|
|
|
<!-- ############ type ############# -->
|
|
|
|
<row>
|
|
<entry morerows="1">video/mpeg</entry>
|
|
<entry morerows="1">MPEG video.</entry>
|
|
<entry>mpegversion</entry>
|
|
<entry>integer</entry>
|
|
<entry>1, 2 or 4</entry>
|
|
<entry>
|
|
Version of the MPEG codec that this stream was encoded with.
|
|
Note that we have different mimetypes for 3ivx, XviD, DivX and
|
|
"standard" ISO MPEG-4. This is <emphasis>not</emphasis> a good
|
|
thing and we're fully aware of this. However, we do not have a
|
|
solution yet.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>systemstream</entry>
|
|
<entry>boolean</entry>
|
|
<entry>FALSE</entry>
|
|
<entry>
|
|
Indicates that this stream is <emphasis>not</emphasis> a system
|
|
container stream.
|
|
</entry>
|
|
</row>
|
|
|
|
<!-- ############ type ############# -->
|
|
|
|
<row>
|
|
<entry>video/x-msmpeg</entry>
|
|
<entry>Microsoft MPEG-4 video deviations.</entry>
|
|
<entry>msmpegversion</entry>
|
|
<entry>integer</entry>
|
|
<entry>41, 42 or 43</entry>
|
|
<entry>
|
|
Version of the MS-MPEG-4-like codec that was used to encode this
|
|
version. A value of 41 refers to MS MPEG 4.1, 42 to 4.2 and 43
|
|
to version 4.3.
|
|
</entry>
|
|
</row>
|
|
|
|
<!-- ############ type ############# -->
|
|
|
|
<row>
|
|
<entry>video/x-msvideocodec</entry>
|
|
<entry>Microsoft Video 1 (oldish codec).</entry>
|
|
<entry>msvideoversion</entry>
|
|
<entry>integer</entry>
|
|
<entry>1</entry>
|
|
<entry>
|
|
Version of the codec - always 1.
|
|
</entry>
|
|
</row>
|
|
|
|
<!-- ############ type ############# -->
|
|
|
|
<row>
|
|
<entry>video/x-pn-realvideo</entry>
|
|
<entry>Realmedia video.</entry>
|
|
<entry>rmversion</entry>
|
|
<entry>integer</entry>
|
|
<entry>1, 2 or 3</entry>
|
|
<entry>
|
|
Version of the Real Video codec that this stream was encoded
|
|
with.
|
|
</entry>
|
|
</row>
|
|
|
|
<!-- ############ type ############# -->
|
|
|
|
<row>
|
|
<entry morerows="2">video/x-rle</entry>
|
|
<entry morerows="2">RLE animation format.</entry>
|
|
<entry>layout</entry>
|
|
<entry>string</entry>
|
|
<entry>"microsoft" or "quicktime"</entry>
|
|
<entry>
|
|
The RLE format inside the Microsoft AVI container has a
|
|
different byte layout than the RLE format inside Apple's
|
|
Quicktime container; this property keeps track of the
|
|
layout.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>depth</entry>
|
|
<entry>integer</entry>
|
|
<entry>1 to 64</entry>
|
|
<entry>
|
|
Bitdepth of the used palette. This means that the palette
|
|
that belongs to this format defines 2^depth colors.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>palette_data</entry>
|
|
<entry>GstBuffer</entry>
|
|
<entry></entry>
|
|
<entry>
|
|
Buffer containing a color palette (in native-endian RGBA) used
|
|
by this format. The buffer is of size 4*2^depth.
|
|
</entry>
|
|
</row>
|
|
|
|
<!-- ############ type ############# -->
|
|
|
|
<row>
|
|
<entry>video/x-svq</entry>
|
|
<entry>Sorensen Video.</entry>
|
|
<entry>svqversion</entry>
|
|
<entry>integer</entry>
|
|
<entry>1 or 3</entry>
|
|
<entry>
|
|
Version of the Sorensen codec that the stream was encoded with.
|
|
</entry>
|
|
</row>
|
|
|
|
<!-- ############ type ############# -->
|
|
|
|
<row>
|
|
<entry>video/x-tarkin</entry>
|
|
<entry>Tarkin video.</entry>
|
|
<entry></entry>
|
|
<entry></entry>
|
|
<entry></entry>
|
|
<entry>
|
|
There are currently no specific properties defined or needed for
|
|
this type.
|
|
</entry>
|
|
</row>
|
|
|
|
<!-- ############ type ############# -->
|
|
|
|
<row>
|
|
<entry>video/x-theora</entry>
|
|
<entry>Theora video.</entry>
|
|
<entry></entry>
|
|
<entry></entry>
|
|
<entry></entry>
|
|
<entry>
|
|
There are currently no specific properties defined or needed for
|
|
this type.
|
|
</entry>
|
|
</row>
|
|
|
|
<!-- ############ type ############# -->
|
|
|
|
<row>
|
|
<entry>video/x-vp3</entry>
|
|
<entry>VP-3 video.</entry>
|
|
<entry></entry>
|
|
<entry></entry>
|
|
<entry></entry>
|
|
<entry>
|
|
There are currently no specific properties defined or needed for
|
|
this type. Note that we have different mimetypes for VP-3 and
|
|
Theora, which is not necessarily a good idea. This could probably
|
|
be improved.
|
|
</entry>
|
|
</row>
|
|
|
|
<!-- ############ type ############# -->
|
|
|
|
<row>
|
|
<entry>video/x-wmv</entry>
|
|
<entry>Windows Media Video</entry>
|
|
<entry>wmvversion</entry>
|
|
<entry>integer</entry>
|
|
<entry>1,2 or 3</entry>
|
|
<entry>
|
|
Version of the WMV codec that the stream was encoded with.
|
|
</entry>
|
|
</row>
|
|
|
|
<!-- ############ type ############# -->
|
|
|
|
<row>
|
|
<entry>video/x-xvid</entry>
|
|
<entry>XviD video.</entry>
|
|
<entry></entry>
|
|
<entry></entry>
|
|
<entry></entry>
|
|
<entry>
|
|
There are currently no specific properties defined or needed for
|
|
this type.
|
|
</entry>
|
|
</row>
|
|
|
|
<!-- ############ subtitle ############# -->
|
|
|
|
<row>
|
|
<entry spanname="fullwidth">
|
|
<emphasis>All image types.</emphasis>
|
|
</entry>
|
|
</row>
|
|
|
|
<!-- ############ type ############# -->
|
|
|
|
<row>
|
|
<entry>image/jpeg</entry>
|
|
<entry>Joint Picture Expert Group Image.</entry>
|
|
<entry></entry>
|
|
<entry></entry>
|
|
<entry></entry>
|
|
<entry>
|
|
There are currently no specific properties defined or needed for
|
|
this type. Note that image/jpeg only applies to RGB-colourspace
|
|
JPEG images; YUY2-colourspace JPEG pictures are referred to as
|
|
video/x-jpeg ("Motion JPEG").
|
|
</entry>
|
|
</row>
|
|
|
|
<!-- ############ type ############# -->
|
|
|
|
<row>
|
|
<entry>image/png</entry>
|
|
<entry>Portable Network Graphics Image.</entry>
|
|
<entry></entry>
|
|
<entry></entry>
|
|
<entry></entry>
|
|
<entry>
|
|
There are currently no specific properties defined or needed for
|
|
this type.
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
|
|
<table frame="all" id="table-container-types" xreflabel="Table of Container Types">
|
|
<title>Table of Container Types</title>
|
|
<tgroup cols="6" align="left" colsep="1" rowsep="1">
|
|
<colspec colnum="1" colname="colc1" colwidth="1*"/>
|
|
<colspec colnum="6" colname="colc6" colwidth="6*"/>
|
|
<spanspec spanname="fullwidth" namest="colc1" nameend="colc6"/>
|
|
|
|
<thead>
|
|
<row>
|
|
<entry>Mime Type</entry>
|
|
<entry>Description</entry>
|
|
<entry>Property</entry>
|
|
<entry>Property Type</entry>
|
|
<entry>Property Values</entry>
|
|
<entry>Property Description</entry>
|
|
</row>
|
|
</thead>
|
|
|
|
<tbody valign="top">
|
|
|
|
<!-- ############ type ############# -->
|
|
|
|
<row>
|
|
<entry>video/x-ms-asf</entry>
|
|
<entry>Advanced Streaming Format (ASF).</entry>
|
|
<entry></entry>
|
|
<entry></entry>
|
|
<entry></entry>
|
|
<entry>
|
|
There are currently no specific properties defined or needed for
|
|
this type.
|
|
</entry>
|
|
</row>
|
|
|
|
<!-- ############ type ############# -->
|
|
|
|
<row>
|
|
<entry>video/x-msvideo</entry>
|
|
<entry>AVI.</entry>
|
|
<entry></entry>
|
|
<entry></entry>
|
|
<entry></entry>
|
|
<entry>
|
|
There are currently no specific properties defined or needed for
|
|
this type.
|
|
</entry>
|
|
</row>
|
|
|
|
<!-- ############ type ############# -->
|
|
|
|
<row>
|
|
<entry>video/x-dv</entry>
|
|
<entry>Digital Video.</entry>
|
|
<entry>systemstream</entry>
|
|
<entry>boolean</entry>
|
|
<entry>TRUE</entry>
|
|
<entry>
|
|
Indicates that this is a container system stream rather than an
|
|
elementary video stream.
|
|
</entry>
|
|
</row>
|
|
|
|
<!-- ############ type ############# -->
|
|
|
|
<row>
|
|
<entry>video/x-matroska</entry>
|
|
<entry>Matroska.</entry>
|
|
<entry></entry>
|
|
<entry></entry>
|
|
<entry></entry>
|
|
<entry>
|
|
There are currently no specific properties defined or needed for
|
|
this type.
|
|
</entry>
|
|
</row>
|
|
|
|
<!-- ############ type ############# -->
|
|
|
|
<row>
|
|
<entry>video/mpeg</entry>
|
|
<entry>Motion Pictures Expert Group System Stream.</entry>
|
|
<entry>systemstream</entry>
|
|
<entry>boolean</entry>
|
|
<entry>TRUE</entry>
|
|
<entry>
|
|
Indicates that this is a container system stream rather than an
|
|
elementary video stream.
|
|
</entry>
|
|
</row>
|
|
|
|
<!-- ############ type ############# -->
|
|
|
|
<row>
|
|
<entry>application/ogg</entry>
|
|
<entry>Ogg.</entry>
|
|
<entry></entry>
|
|
<entry></entry>
|
|
<entry></entry>
|
|
<entry>
|
|
There are currently no specific properties defined or needed for
|
|
this type.
|
|
</entry>
|
|
</row>
|
|
|
|
<!-- ############ type ############# -->
|
|
|
|
<row>
|
|
<entry>video/quicktime</entry>
|
|
<entry>Quicktime.</entry>
|
|
<entry></entry>
|
|
<entry></entry>
|
|
<entry></entry>
|
|
<entry>
|
|
There are currently no specific properties defined or needed for
|
|
this type.
|
|
</entry>
|
|
</row>
|
|
|
|
<!-- ############ type ############# -->
|
|
|
|
<row>
|
|
<entry>video/x-pn-realvideo</entry>
|
|
<entry>Digital Video.</entry>
|
|
<entry>systemstream</entry>
|
|
<entry>boolean</entry>
|
|
<entry>TRUE</entry>
|
|
<entry>
|
|
Indicates that this is a container system stream rather than an
|
|
elementary video stream.
|
|
</entry>
|
|
</row>
|
|
|
|
<!-- ############ type ############# -->
|
|
|
|
<row>
|
|
<entry>audio/x-wav</entry>
|
|
<entry>WAV.</entry>
|
|
<entry></entry>
|
|
<entry></entry>
|
|
<entry></entry>
|
|
<entry>
|
|
There are currently no specific properties defined or needed for
|
|
this type.
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
|
|
<table frame="all" id="table-subtitle-types" xreflabel="Table of Subtitle Types">
|
|
<title>Table of Subtitle Types</title>
|
|
<tgroup cols="6" align="left" colsep="1" rowsep="1">
|
|
<colspec colnum="1" colname="colt1" colwidth="1*"/>
|
|
<colspec colnum="6" colname="colt6" colwidth="6*"/>
|
|
<spanspec spanname="fullwidth" namest="colt1" nameend="colt6"/>
|
|
|
|
<thead>
|
|
<row>
|
|
<entry>Mime Type</entry>
|
|
<entry>Description</entry>
|
|
<entry>Property</entry>
|
|
<entry>Property Type</entry>
|
|
<entry>Property Values</entry>
|
|
<entry>Property Description</entry>
|
|
</row>
|
|
</thead>
|
|
|
|
<tbody valign="top">
|
|
|
|
<!-- ############ type ############# -->
|
|
|
|
<row>
|
|
<entry></entry>
|
|
<entry></entry>
|
|
<entry></entry>
|
|
<entry></entry>
|
|
<entry></entry>
|
|
<entry>
|
|
None defined yet.
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
|
|
<table frame="all" id="table-other-types" xreflabel="Table of Other Types">
|
|
<title>Table of Other Types</title>
|
|
<tgroup cols="6" align="left" colsep="1" rowsep="1">
|
|
<colspec colnum="1" colname="colo1" colwidth="1*"/>
|
|
<colspec colnum="6" colname="colo6" colwidth="6*"/>
|
|
<spanspec spanname="fullwidth" namest="colo1" nameend="colo6"/>
|
|
|
|
<thead>
|
|
<row>
|
|
<entry>Mime Type</entry>
|
|
<entry>Description</entry>
|
|
<entry>Property</entry>
|
|
<entry>Property Type</entry>
|
|
<entry>Property Values</entry>
|
|
<entry>Property Description</entry>
|
|
</row>
|
|
</thead>
|
|
|
|
<tbody valign="top">
|
|
|
|
<!-- ############ type ############# -->
|
|
|
|
<row>
|
|
<entry></entry>
|
|
<entry></entry>
|
|
<entry></entry>
|
|
<entry></entry>
|
|
<entry></entry>
|
|
<entry>
|
|
None defined yet.
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect1>
|
|
</chapter>
|