docs/pwg/advanced-types.xml

   1 <!-- ############ chapter ############# -->
   2
   3 <chapter id="chapter-building-types">
   4   <title>Types and Properties</title>
   5   <para>
   6     There is a very large set of possible types that may be used to pass data
   7     between elements. Indeed, each new element that is defined may use a new
   8     data format (though unless at least one other element recognises that
   9     format, it will be most likely be useless since nothing will be able to
  10     link with it).
  11   </para>
  12   <para>
  13     In order for types to be useful, and for systems like autopluggers to
  14     work, it is necessary that all elements agree on the type definitions,
  15     and which properties are required for each type. The &GStreamer; framework
  16     itself simply provides the ability to define types and parameters, but
  17     does not fix the meaning of types and parameters, and does not enforce
  18     standards on the creation of new types. This is a matter for a policy to
  19     decide, not technical systems to enforce.
  20   </para>
  21   <para>
  22     For now, the policy is simple:
  23     <itemizedlist>
  24       <listitem>
  25         <para>
  26           Do not create a new type if you could use one which already exists.
  27         </para>
  28       </listitem>
  29       <listitem>
  30         <para>
  31           If creating a new type, discuss it first with the other &GStreamer;
  32           developers, on at least one of: IRC, mailing lists.
  33         </para>
  34       </listitem>
  35       <listitem>
  36         <para>
  37           Try to ensure that the name for a new format is as unlikely to
  38           conflict with anything else created already, and is not a more
  39           generalised name than it should be. For example: "audio/compressed"
  40           would be too generalised a name to represent audio data compressed
  41           with an mp3 codec. Instead "audio/mp3" might be an appropriate name,
  42           or "audio/compressed" could exist and have a property indicating the
  43           type of compression used.
  44         </para>
  45       </listitem>
  46       <listitem>
  47         <para>
  48           Ensure that, when you do create a new type, you specify it clearly,
  49           and get it added to the list of known types so that other developers
  50           can use the type correctly when writing their elements.
  51         </para>
  52       </listitem>
  53     </itemizedlist>
  54   </para>
  55
  56   <!-- ############ sect1 ############# -->
  57
  58   <sect1 id="section-types-test" xreflabel="Building a Simple Format for Testing">
  59     <title>Building a Simple Format for Testing</title>
  60     <para>
  61       If you need a new format that has not yet been defined in our <xref
  62       linkend="section-types-definitions"/>, you will want to have some general
  63       guidelines on media type naming, properties and such. A media type would
  64       ideally be equivalent to the Mime-type defined by IANA; else, it should
  65       be in the form type/x-name, where type is the sort of data this media type
  66       handles (audio, video, ...) and name should be something specific for
  67       this specific type.  Audio and video media types should try to support the
  68       general audio/video properties (see the list), and can use their own
  69       properties, too. To get an idea of what properties we think are useful,
  70       see (again) the list.
  71     </para>
  72     <para>
  73       Take your time to find the right set of properties for your type. There
  74       is no reason to hurry. Also, experimenting with this is generally a good
  75       idea. Experience learns that theoretically thought-out types are good,
  76       but they still need practical use to assure that they serve their needs.
  77       Make sure that your property names do not clash with similar properties
  78       used in other types. If they match, make sure they mean the same thing;
  79       properties with different types but the same names are
  80       <emphasis>not</emphasis> allowed.
  81     </para>
  82   </sect1>
  83
  84   <!-- ############ sect1 ############# -->
  85
  86   <sect1 id="section-types-typefind" xreflabel="Typefind Functions and Autoplugging">
  87     <title>Typefind Functions and Autoplugging</title>
  88     <para>
  89       With only <emphasis>defining</emphasis> the types, we're not yet there.
  90       In order for a random data file to be recognized and played back as
  91       such, we need a way of recognizing their type out of the blue. For this
  92       purpose, <quote>typefinding</quote> was introduced. Typefinding is the
  93       process of detecting the type of a data stream. Typefinding consists of
  94       two separate parts: first, there's an unlimited number of functions
  95       that we call <emphasis>typefind functions</emphasis>, which are each
  96       able to recognize one or more types from an input stream. Then,
  97       secondly, there's a small engine which registers and calls each of
  98       those functions. This is the typefind core. On top of this typefind
  99       core, you would normally write an autoplugger, which is able to use
 100       this type detection system to dynamically build a pipeline around an
 101       input stream. Here, we will focus only on typefind functions.
 102     </para>
 103     <para>
 104       A typefind function usually lives in
 105       <filename>gst-plugins-base/gst/typefind/gsttypefindfunctions.c</filename>,
 106       unless there's a good reason (like library dependencies) to put it
 107       elsewhere. The reason for this centralization is to reduce the
 108       number of plugins that need to be loaded in order to detect a stream's
 109       type. Below is an example that will recognize AVI files, which start
 110       with a <quote>RIFF</quote> tag, then the size of the file and then an
 111       <quote>AVI </quote> tag:
 112     </para>
 113     <programlisting>
 114 static void
 115 gst_my_typefind_function (GstTypeFind *tf,
 116                           gpointer     data)
 117 {
 118   guint8 *data = gst_type_find_peek (tf, 0, 12);
 119
 120   if (data &amp;&amp;
 121       GUINT32_FROM_LE (&amp;((guint32 *) data)[0]) == GST_MAKE_FOURCC ('R','I','F','F') &amp;&amp;
 122       GUINT32_FROM_LE (&amp;((guint32 *) data)[2]) == GST_MAKE_FOURCC ('A','V','I',' ')) {
 123     gst_type_find_suggest (tf, GST_TYPE_FIND_MAXIMUM,
 124                            gst_caps_new_simple ("video/x-msvideo", NULL));
 125   }
 126 }
 127
 128 static gboolean
 129 plugin_init (GstPlugin *plugin)
 130 {
 131   static gchar *exts[] = { "avi", NULL };
 132   if (!gst_type_find_register (plugin, "", GST_RANK_PRIMARY,
 133                                gst_my_typefind_function, exts,
 134                                gst_caps_new_simple ("video/x-msvideo",
 135                                                     NULL), NULL))
 136     return FALSE;
 137 }
 138     </programlisting>
 139     <para>
 140       Note that
 141       <filename>gst-plugins/gst/typefind/gsttypefindfunctions.c</filename>
 142       has some simplification macros to decrease the amount of code. Make
 143       good use of those if you want to submit typefinding patches with new
 144       typefind functions.
 145     </para>
 146     <para>
 147       Autoplugging has been discussed in great detail in the Application
 148       Development Manual.
 149     </para>
 150   </sect1>
 151
 152   <!-- ############ sect1 ############# -->
 153
 154   <sect1 id="section-types-definitions" xreflabel="List of Defined Types">
 155     <title>List of Defined Types</title>
 156       <para>
 157         Below is a list of all the defined types in &GStreamer;. They are split
 158         up in separate tables for audio, video, container, subtitle and other
 159         types, for the sake of readability. Below each table might follow a
 160         list of notes that apply to that table. In the definition of each type,
 161         we try to follow the types and rules as defined by <ulink type="http"
 162         url="http://www.iana.org/assignments/media-types">
 163         IANA</ulink> for as far as possible.
 164       </para>
 165       <para>
 166         Jump directly to a specific table:
 167         <itemizedlist>
 168           <listitem>
 169             <para><xref linkend="table-audio-types"/></para>
 170           </listitem>
 171           <listitem>
 172             <para><xref linkend="table-video-types"/></para>
 173           </listitem>
 174           <listitem>
 175             <para><xref linkend="table-container-types"/></para>
 176           </listitem>
 177           <listitem>
 178             <para><xref linkend="table-subtitle-types"/></para>
 179           </listitem>
 180           <listitem>
 181             <para><xref linkend="table-other-types"/></para>
 182           </listitem>
 183         </itemizedlist>
 184       </para>
 185       <para>
 186         Note that many of the properties are not <emphasis>required</emphasis>,
 187         but rather <emphasis>optional</emphasis> properties. This means that
 188         most of these properties can be extracted from the container header,
 189         but that - in case the container header does not provide these - they
 190         can also be extracted by parsing the stream header or the stream
 191         content. The policy is that your element should provide the data that
 192         it knows about by only parsing its own content, not another element's
 193         content. Example: the AVI header provides samplerate of the contained
 194         audio stream in the header. MPEG system streams don't. This means that
 195         an AVI stream demuxer would provide samplerate as a property for MPEG
 196         audio streams, whereas an MPEG demuxer would not. A decoder needing
 197         this data would require a stream parser in between two extract this
 198         from the header or calculate it from the stream.
 199       </para>
 200
 201       <table frame="all" id="table-audio-types" xreflabel="Table of Audio Types">
 202         <title>Table of Audio Types</title>
 203         <tgroup cols="6" align="left" colsep="1" rowsep="1">
 204         <colspec colnum="1" colname="cola1" colwidth="1*"/>
 205         <colspec colnum="6" colname="cola6" colwidth="6*"/>
 206         <spanspec spanname="fullwidth" namest="cola1" nameend="cola6"/>
 207
 208         <thead>
 209           <row>
 210             <entry>Media Type</entry>
 211             <entry>Description</entry>
 212             <entry>Property</entry>
 213             <entry>Property Type</entry>
 214             <entry>Property Values</entry>
 215             <entry>Property Description</entry>
 216           </row>
 217         </thead>
 218
 219         <tbody valign="top">
 220
 221           <!-- ############ subtitle ############# -->
 222
 223           <row>
 224             <entry spanname="fullwidth">
 225               <emphasis>All audio types.</emphasis>
 226             </entry>
 227           </row>
 228
 229           <!-- ############ type ############# -->
 230
 231           <row>
 232             <entry morerows="4">audio/*</entry>
 233             <entry morerows="4">
 234               <emphasis>All audio types</emphasis>
 235             </entry>
 236             <entry>rate</entry>
 237             <entry>integer</entry>
 238             <entry>greater than 0</entry>
 239             <entry>
 240               The sample rate of the data, in samples (per channel) per second.
 241             </entry>
 242           </row>
 243           <row>
 244             <entry>channels</entry>
 245             <entry>integer</entry>
 246             <entry>greater than 0</entry>
 247             <entry>
 248               The number of channels of audio data.
 249             </entry>
 250           </row>
 251           <row>
 252             <entry>channel-mask</entry>
 253             <entry>bitmask</entry>
 254             <entry></entry>
 255             <entry>
 256               Channel positions present. See <quote>GstAudioChannelPosition</quote>.
 257               0 means unpositioned.
 258             </entry>
 259           </row>
 260           <row>
 261             <entry>format</entry>
 262             <entry>string</entry>
 263             <entry>
 264               S8 U8 S16LE S16BE U16LE U16BE S24_32LE S24_32BE U24_32LE U24_32BE S32LE S32BE U32LE U32BE
 265               S24LE S24BE U24LE U24BE S20LE S20BE U20LE U20BE S18LE S18BE U18LE U18BE F32LE F32BE F64LE F64BE
 266             </entry>
 267             <entry>
 268               The format of the sample data.
 269             </entry>
 270           </row>
 271           <row>
 272             <entry>layout</entry>
 273             <entry>string</entry>
 274             <entry>"interleaved" or "non-interleaved"</entry>
 275             <entry>
 276               Layout of channels within a buffer.
 277             </entry>
 278           </row>
 279
 280           <!-- ############ subtitle ############# -->
 281
 282           <row>
 283             <entry spanname="fullwidth">
 284               <emphasis>All raw audio types.</emphasis>
 285             </entry>
 286           </row>
 287
 288           <!-- ############ type ############# -->
 289
 290           <row>
 291             <entry>audio/x-raw</entry>
 292             <entry>
 293               Unstructured and uncompressed raw audio data.
 294             </entry>
 295             <entry></entry>
 296             <entry></entry>
 297             <entry></entry>
 298             <entry>
 299               All properties (except channel-mask, in the mono and stereo cases) are mandatory.
 300             </entry>
 301           </row>
 302
 303           <!-- ############ subtitle ############# -->
 304
 305           <row>
 306             <entry spanname="fullwidth">
 307               <emphasis>All encoded audio types.</emphasis>
 308             </entry>
 309           </row>
 310
 311           <!-- ############ type ############# -->
 312
 313           <row>
 314             <entry>audio/x-ac3</entry>
 315             <entry>AC-3 or A52 audio streams.</entry>
 316             <entry></entry>
 317             <entry></entry>
 318             <entry></entry>
 319             <entry>
 320               There are currently no specific properties defined or needed for
 321               this type.
 322             </entry>
 323           </row>
 324
 325           <!-- ############ type ############# -->
 326
 327           <row>
 328             <entry morerows="1">audio/x-adpcm</entry>
 329             <entry morerows="1">ADPCM Audio streams.</entry>
 330             <entry>layout</entry>
 331             <entry>string</entry>
 332             <entry>
 333               <quote>quicktime</quote>, <quote>dvi</quote>,
 334               <quote>microsoft</quote> or <quote>4xm</quote>.
 335             </entry>
 336             <entry>
 337               The layout defines the packing of the samples in the stream. In
 338               ADPCM, most formats store multiple samples per channel together.
 339               This number of samples differs per format, hence the different
 340               layouts. On the long term, we probably want this variable to die
 341               and use something more descriptive, but this will do for now.
 342             </entry>
 343           </row>
 344           <row>
 345             <entry>block_align</entry>
 346             <entry>integer</entry>
 347             <entry>
 348               Any
 349             </entry>
 350             <entry>
 351               Chunk buffer size.
 352             </entry>
 353           </row>
 354
 355           <!-- ############ type ############# -->
 356
 357           <row>
 358             <entry>audio/x-cinepak</entry>
 359             <entry>Audio as provided in a Cinepak (Quicktime) stream.</entry>
 360             <entry></entry>
 361             <entry></entry>
 362             <entry></entry>
 363             <entry>
 364               There are currently no specific properties defined or needed for
 365               this type.
 366             </entry>
 367           </row>
 368
 369           <!-- ############ type ############# -->
 370
 371           <row>
 372             <entry>audio/x-dv</entry>
 373             <entry>Audio as provided in a Digital Video stream.</entry>
 374             <entry></entry>
 375             <entry></entry>
 376             <entry></entry>
 377             <entry>
 378               There are currently no specific properties defined or needed for
 379               this type.
 380             </entry>
 381           </row>
 382
 383           <!-- ############ type ############# -->
 384
 385           <row>
 386             <entry>audio/x-flac</entry>
 387             <entry>Free Lossless Audio codec (FLAC).</entry>
 388             <entry></entry>
 389             <entry></entry>
 390             <entry></entry>
 391             <entry>
 392               There are currently no specific properties defined or needed for
 393               this type.
 394             </entry>
 395           </row>
 396
 397           <!-- ############ type ############# -->
 398
 399           <row>
 400             <entry>audio/x-gsm</entry>
 401             <entry>Data encoded by the GSM codec.</entry>
 402             <entry></entry>
 403             <entry></entry>
 404             <entry></entry>
 405             <entry>
 406               There are currently no specific properties defined or needed for
 407               this type.
 408             </entry>
 409           </row>
 410
 411           <!-- ############ type ############# -->
 412
 413           <row>
 414             <entry>audio/x-alaw</entry>
 415             <entry>A-Law Audio.</entry>
 416             <entry></entry>
 417             <entry></entry>
 418             <entry></entry>
 419             <entry>
 420               There are currently no specific properties defined or needed for
 421               this type.
 422             </entry>
 423           </row>
 424
 425           <!-- ############ type ############# -->
 426
 427           <row>
 428             <entry>audio/x-mulaw</entry>
 429             <entry>Mu-Law Audio.</entry>
 430             <entry></entry>
 431             <entry></entry>
 432             <entry></entry>
 433             <entry>
 434               There are currently no specific properties defined or needed for
 435               this type.
 436             </entry>
 437           </row>
 438
 439           <!-- ############ type ############# -->
 440
 441           <row>
 442             <entry>audio/x-mace</entry>
 443             <entry>MACE Audio (used in Quicktime).</entry>
 444             <entry>maceversion</entry>
 445             <entry>integer</entry>
 446             <entry>3 or 6</entry>
 447             <entry>
 448               The version of the MACE audio codec used to encode the stream.
 449             </entry>
 450           </row>
 451
 452           <!-- ############ type ############# -->
 453
 454           <row>
 455             <entry morerows="3">audio/mpeg</entry>
 456             <entry morerows="3">
 457               Audio data compressed using the MPEG audio encoding scheme.
 458             </entry>
 459             <entry>mpegversion</entry>
 460             <entry>integer</entry>
 461             <entry>1, 2 or 4</entry>
 462             <entry>
 463               The MPEG-version used for encoding the data. The value 1 refers
 464               to MPEG-1, -2 and -2.5 layer 1, 2 or 3. The values 2 and 4 refer
 465               to the MPEG-AAC audio encoding schemes.
 466             </entry>
 467           </row>
 468           <row>
 469             <entry>framed</entry>
 470             <entry>boolean</entry>
 471             <entry>0 or 1</entry>
 472             <entry>
 473               A true value indicates that each buffer contains exactly one
 474               frame. A false value indicates that frames and buffers do not
 475               necessarily match up.
 476             </entry>
 477           </row>
 478           <row>
 479             <entry>layer</entry>
 480             <entry>integer</entry>
 481             <entry>1, 2, or 3</entry>
 482             <entry>
 483               The compression scheme layer used to compress the data
 484               <emphasis>(only if mpegversion=1)</emphasis>.
 485             </entry>
 486           </row>
 487           <row>
 488             <entry>bitrate</entry>
 489             <entry>integer</entry>
 490             <entry>greater than 0</entry>
 491             <entry>
 492               The bitrate, in bits per second. For VBR (variable bitrate)
 493               MPEG data, this is the average bitrate.
 494             </entry>
 495           </row>
 496
 497           <!-- ############ type ############# -->
 498
 499           <row>
 500             <entry>audio/x-qdm2</entry>
 501             <entry>Data encoded by the QDM version 2 codec.</entry>
 502             <entry></entry>
 503             <entry></entry>
 504             <entry></entry>
 505             <entry>
 506               There are currently no specific properties defined or needed for
 507               this type.
 508             </entry>
 509           </row>
 510
 511           <!-- ############ type ############# -->
 512
 513           <row>
 514             <entry>audio/x-pn-realaudio</entry>
 515             <entry>Realmedia Audio data.</entry>
 516             <entry>raversion</entry>
 517             <entry>integer</entry>
 518             <entry>1 or 2</entry>
 519             <entry>
 520               The version of the Real Audio codec used to encode the stream.
 521               1 stands for a 14k4 stream, 2 stands for a 28k8 stream.
 522             </entry>
 523           </row>
 524
 525           <!-- ############ type ############# -->
 526
 527           <row>
 528             <entry>audio/x-speex</entry>
 529             <entry>Data encoded by the Speex audio codec</entry>
 530             <entry></entry>
 531             <entry></entry>
 532             <entry></entry>
 533             <entry>
 534               There are currently no specific properties defined or needed for
 535               this type.
 536             </entry>
 537           </row>
 538
 539           <!-- ############ type ############# -->
 540
 541           <row>
 542             <entry>audio/x-vorbis</entry>
 543             <entry>Vorbis audio data</entry>
 544             <entry></entry>
 545             <entry></entry>
 546             <entry></entry>
 547             <entry>
 548               There are currently no specific properties defined or needed for
 549               this type.
 550             </entry>
 551           </row>
 552
 553           <!-- ############ type ############# -->
 554
 555           <row>
 556             <entry>audio/x-wma</entry>
 557             <entry>Windows Media Audio</entry>
 558             <entry>wmaversion</entry>
 559             <entry>integer</entry>
 560             <entry>1,2 or 3</entry>
 561             <entry>
 562               The version of the WMA codec used to encode the stream.
 563             </entry>
 564           </row>
 565
 566           <!-- ############ type ############# -->
 567
 568           <row>
 569             <entry>audio/x-paris</entry>
 570             <entry>Ensoniq PARIS audio</entry>
 571             <entry></entry>
 572             <entry></entry>
 573             <entry></entry>
 574             <entry>
 575               There are currently no specific properties defined or needed for
 576               this type.
 577             </entry>
 578           </row>
 579
 580           <!-- ############ type ############# -->
 581
 582           <row>
 583             <entry>audio/x-svx</entry>
 584             <entry>Amiga IFF / SVX8 / SV16 audio</entry>
 585             <entry></entry>
 586             <entry></entry>
 587             <entry></entry>
 588             <entry>
 589               There are currently no specific properties defined or needed for
 590               this type.
 591             </entry>
 592           </row>
 593
 594           <!-- ############ type ############# -->
 595
 596           <row>
 597             <entry>audio/x-nist</entry>
 598             <entry>Sphere NIST audio</entry>
 599             <entry></entry>
 600             <entry></entry>
 601             <entry></entry>
 602             <entry>
 603               There are currently no specific properties defined or needed for
 604               this type.
 605             </entry>
 606           </row>
 607
 608           <!-- ############ type ############# -->
 609
 610           <row>
 611             <entry>audio/x-voc</entry>
 612             <entry>Sound Blaster VOC audio</entry>
 613             <entry></entry>
 614             <entry></entry>
 615             <entry></entry>
 616             <entry>
 617               There are currently no specific properties defined or needed for
 618               this type.
 619             </entry>
 620           </row>
 621
 622           <!-- ############ type ############# -->
 623
 624           <row>
 625             <entry>audio/x-ircam</entry>
 626             <entry>Berkeley/IRCAM/CARL audio</entry>
 627             <entry></entry>
 628             <entry></entry>
 629             <entry></entry>
 630             <entry>
 631               There are currently no specific properties defined or needed for
 632               this type.
 633             </entry>
 634           </row>
 635
 636           <!-- ############ type ############# -->
 637
 638           <row>
 639             <entry>audio/x-w64</entry>
 640             <entry>Sonic Foundry's 64 bit RIFF/WAV</entry>
 641             <entry></entry>
 642             <entry></entry>
 643             <entry></entry>
 644             <entry>
 645               There are currently no specific properties defined or needed for
 646               this type.
 647             </entry>
 648           </row>
 649
 650         </tbody>
 651         </tgroup>
 652       </table>
 653
 654       <table frame="all" id="table-video-types" xreflabel="Table of Video Types">
 655         <title>Table of Video Types</title>
 656         <tgroup cols="6" align="left" colsep="1" rowsep="1">
 657         <colspec colnum="1" colname="colv1" colwidth="1*"/>
 658         <colspec colnum="6" colname="colv6" colwidth="6*"/>
 659         <spanspec spanname="fullwidth" namest="colv1" nameend="colv6"/>
 660
 661         <thead>
 662           <row>
 663             <entry>Media Type</entry>
 664             <entry>Description</entry>
 665             <entry>Property</entry>
 666             <entry>Property Type</entry>
 667             <entry>Property Values</entry>
 668             <entry>Property Description</entry>
 669           </row>
 670         </thead>
 671
 672         <tbody valign="top">
 673
 674           <!-- ############ subtitle ############# -->
 675
 676           <row>
 677             <entry spanname="fullwidth">
 678               <emphasis>All video types.</emphasis>
 679             </entry>
 680           </row>
 681
 682           <!-- ############ type ############# -->
 683
 684           <row>
 685             <entry morerows="9">video/*</entry>
 686             <entry morerows="9">
 687               <emphasis>All video types</emphasis>
 688             </entry>
 689             <entry>width</entry>
 690             <entry>integer</entry>
 691             <entry>greater than 0</entry>
 692             <entry>The width of the video image</entry>
 693           </row>
 694           <row>
 695             <entry>height</entry>
 696             <entry>integer</entry>
 697             <entry>greater than 0</entry>
 698             <entry>The height of the video image</entry>
 699           </row>
 700           <row>
 701             <entry>framerate</entry>
 702             <entry>fraction</entry>
 703             <entry>greater or equal 0; default 0/1</entry>
 704             <entry>
 705               The (average) framerate in frames per second. Note that this
 706               property does not guarantee in <emphasis>any</emphasis> way that
 707               it will actually come close to this value. If you need a fixed
 708               framerate, please use an element that provides that (such as
 709               <quote>videorate</quote>). 0/1 means a variable framerate.
 710             </entry>
 711           </row>
 712           <row>
 713             <entry>max-framerate</entry>
 714             <entry>fraction</entry>
 715             <entry>greater or equal 0; default as framerate</entry>
 716             <entry>
 717               For variable framerates, the maximum framerate that is expected.
 718               Only valid when framerate is 0/1.
 719             </entry>
 720           </row>
 721           <row>
 722             <entry>views</entry>
 723             <entry>integer</entry>
 724             <entry>greater than 0; default 1</entry>
 725             <entry>
 726               The number of views for multiview video. Each buffer contains
 727               multiple <quote>GstVideoMeta</quote> buffers that describe each view. Use the
 728               frame ID to get access to the different views.
 729             </entry>
 730           </row>
 731           <row>
 732             <entry>interlace-mode</entry>
 733             <entry>string</entry>
 734             <entry>progressive, interleaved, mixed, fields; default progressive</entry>
 735             <entry>
 736               The interlace mode. Extra buffer flags describe the frame and fields.
 737             </entry>
 738           </row>
 739           <row>
 740             <entry>chroma-site</entry>
 741             <entry>string</entry>
 742             <entry>jpeg, mpeg2, dv; default UNKNOWN</entry>
 743             <entry>
 744               The chroma siting of the video frames.
 745             </entry>
 746           </row>
 747           <row>
 748             <entry>colorimetry</entry>
 749             <entry>string</entry>
 750             <entry>bt601, bt709, smpte240m; default UNKNOWN</entry>
 751             <entry>
 752               The colorimetry of the video frames.
 753             </entry>
 754           </row>
 755           <row>
 756             <entry>pixel-aspect-ratio</entry>
 757             <entry>fraction</entry>
 758             <entry>greater than 0; default 1/1</entry>
 759             <entry>
 760               The pixel aspect ratio of the video.
 761             </entry>
 762           </row>
 763           <row>
 764             <entry>format</entry>
 765             <entry>string</entry>
 766             <entry>
 767               I420 YV12 YUY2 UYVY AYUV RGBx BGRx xRGB xBGR RGBA BGRA ARGB ABGR RGB BGR Y41B Y42B
 768               YVYU Y444 v210 v216 NV12 NV21 GRAY8 GRAY16_BE GRAY16_LE
 769               v308 RGB16 BGR16 RGB15 BGR15 UYVP A420 RGB8P YUV9 YVU9
 770               IYU1 ARGB64 AYUV64 r210 I420_10LE I420_10BE I422_10LE I422_10BE
 771             </entry>
 772             <entry>
 773               The format of the video. See <ulink type="http"
 774               url="http://www.fourcc.org/">FourCC definition site</ulink>
 775               for references and definitions. YUY2, YVYU and UYVY are 4:2:2
 776               packed-pixel, Y41P is 4:1:1 packed-pixel and IYU2 is 4:4:4
 777               packed-pixel. Y42B is 4:2:2 planar, YV12 and I420 are 4:2:0
 778               planar, Y41B is 4:1:1 planar and YUV9 and YVU9 are 4:1:0 planar.
 779               Y800 contains Y-samples only (black/white).
 780             </entry>
 781           </row>
 782
 783           <!-- ############ subtitle ############# -->
 784
 785           <row>
 786             <entry spanname="fullwidth">
 787               <emphasis>All raw video types.</emphasis>
 788             </entry>
 789           </row>
 790
 791           <!-- ############ type ############# -->
 792
 793           <row>
 794             <entry>video/x-raw</entry>
 795             <entry>Unstructured and uncompressed raw video data.</entry>
 796             <entry></entry>
 797             <entry></entry>
 798             <entry></entry>
 799             <entry>
 800               The properties width, height and format are mandatory.
 801             </entry>
 802           </row>
 803
 804           <!-- ############ subtitle ############# -->
 805
 806           <row>
 807             <entry spanname="fullwidth">
 808               <emphasis>All encoded video types.</emphasis>
 809             </entry>
 810           </row>
 811
 812           <!-- ############ type ############# -->
 813
 814           <row>
 815             <entry>video/x-3ivx</entry>
 816             <entry>3ivx video.</entry>
 817             <entry></entry>
 818             <entry></entry>
 819             <entry></entry>
 820             <entry>
 821               There are currently no specific properties defined or needed for
 822               this type.
 823             </entry>
 824           </row>
 825
 826           <!-- ############ type ############# -->
 827
 828           <row>
 829             <entry>video/x-divx</entry>
 830             <entry>DivX video.</entry>
 831             <entry>divxversion</entry>
 832             <entry>integer</entry>
 833             <entry>3, 4 or 5</entry>
 834             <entry>
 835               Version of the DivX codec used to encode the stream.
 836             </entry>
 837           </row>
 838
 839           <!-- ############ type ############# -->
 840
 841           <row>
 842             <entry>video/x-dv</entry>
 843             <entry>Digital Video.</entry>
 844             <entry>systemstream</entry>
 845             <entry>boolean</entry>
 846             <entry>FALSE</entry>
 847             <entry>
 848               Indicates that this stream is <emphasis>not</emphasis> a system
 849               container stream.
 850             </entry>
 851           </row>
 852
 853           <!-- ############ type ############# -->
 854
 855           <row>
 856             <entry>video/x-ffv</entry>
 857             <entry>FFMpeg video.</entry>
 858             <entry>ffvversion</entry>
 859             <entry>integer</entry>
 860             <entry>1</entry>
 861             <entry>
 862               Version of the FFMpeg video codec used to encode the stream.
 863             </entry>
 864           </row>
 865
 866           <!-- ############ type ############# -->
 867
 868           <row>
 869             <entry morerows="1">video/x-h263</entry>
 870             <entry morerows="1">H-263 video.</entry>
 871             <entry>variant</entry>
 872             <entry>string</entry>
 873             <entry>itu, lead, microsoft, vdolive, vivo, xirlink </entry>
 874             <entry>
 875               Vendor specific variant of the format. 'itu' is the standard.
 876             </entry>
 877           </row>
 878           <row>
 879             <entry>h263version</entry>
 880             <entry>string</entry>
 881             <entry>h263, h263p, h263pp</entry>
 882             <entry>
 883               Enhanced versions of the h263 codec.
 884             </entry>
 885           </row>
 886
 887           <!-- ############ type ############# -->
 888
 889           <row>
 890             <entry>video/x-h264</entry>
 891             <entry>H-264 video.</entry>
 892             <entry>variant</entry>
 893             <entry>string</entry>
 894             <entry>itu, videosoft</entry>
 895             <entry>
 896               Vendor specific variant of the format. 'itu' is the standard.
 897             </entry>
 898           </row>
 899
 900           <!-- ############ type ############# -->
 901
 902           <row>
 903             <entry>video/x-huffyuv</entry>
 904             <entry>Huffyuv video.</entry>
 905             <entry></entry>
 906             <entry></entry>
 907             <entry></entry>
 908             <entry>
 909               There are currently no specific properties defined or needed for
 910               this type.
 911             </entry>
 912           </row>
 913
 914           <!-- ############ type ############# -->
 915
 916           <row>
 917             <entry>video/x-indeo</entry>
 918             <entry>Indeo video.</entry>
 919             <entry>indeoversion</entry>
 920             <entry>integer</entry>
 921             <entry>3</entry>
 922             <entry>
 923               Version of the Indeo codec used to encode this stream.
 924             </entry>
 925           </row>
 926
 927           <!-- ############ type ############# -->
 928
 929           <row>
 930             <entry>video/x-intel-h263</entry>
 931             <entry>H-263 video.</entry>
 932             <entry>variant</entry>
 933             <entry>string</entry>
 934             <entry>intel</entry>
 935             <entry>
 936               Vendor specific variant of the format.
 937             </entry>
 938           </row>
 939
 940           <!-- ############ type ############# -->
 941
 942           <row>
 943             <entry>video/x-jpeg</entry>
 944             <entry>Motion-JPEG video.</entry>
 945             <entry></entry>
 946             <entry></entry>
 947             <entry></entry>
 948             <entry>
 949               There are currently no specific properties defined or needed for
 950               this type. Note that video/x-jpeg only applies to Motion-JPEG
 951               pictures (YUY2 colourspace). RGB colourspace JPEG images are
 952               referred to as image/jpeg (JPEG image).
 953             </entry>
 954           </row>
 955
 956           <!-- ############ type ############# -->
 957
 958           <row>
 959             <entry morerows="1">video/mpeg</entry>
 960             <entry morerows="1">MPEG video.</entry>
 961             <entry>mpegversion</entry>
 962             <entry>integer</entry>
 963             <entry>1, 2 or 4</entry>
 964             <entry>
 965               Version of the MPEG codec that this stream was encoded with.
 966               Note that we have different media types for 3ivx, XviD, DivX and
 967               "standard" ISO MPEG-4. This is <emphasis>not</emphasis> a good
 968               thing and we're fully aware of this. However, we do not have a
 969               solution yet.
 970             </entry>
 971           </row>
 972           <row>
 973             <entry>systemstream</entry>
 974             <entry>boolean</entry>
 975             <entry>FALSE</entry>
 976             <entry>
 977               Indicates that this stream is <emphasis>not</emphasis> a system
 978               container stream.
 979             </entry>
 980           </row>
 981
 982           <!-- ############ type ############# -->
 983
 984           <row>
 985             <entry>video/x-msmpeg</entry>
 986             <entry>Microsoft MPEG-4 video deviations.</entry>
 987             <entry>msmpegversion</entry>
 988             <entry>integer</entry>
 989             <entry>41, 42 or 43</entry>
 990             <entry>
 991               Version of the MS-MPEG-4-like codec that was used to encode this
 992               version. A value of 41 refers to MS MPEG 4.1, 42 to 4.2 and 43
 993               to version 4.3.
 994             </entry>
 995           </row>
 996
 997           <!-- ############ type ############# -->
 998
 999           <row>
1000             <entry>video/x-msvideocodec</entry>
1001             <entry>Microsoft Video 1 (oldish codec).</entry>
1002             <entry>msvideoversion</entry>
1003             <entry>integer</entry>
1004             <entry>1</entry>
1005             <entry>
1006               Version of the codec - always 1.
1007             </entry>
1008           </row>
1009
1010           <!-- ############ type ############# -->
1011
1012           <row>
1013             <entry>video/x-pn-realvideo</entry>
1014             <entry>Realmedia video.</entry>
1015             <entry>rmversion</entry>
1016             <entry>integer</entry>
1017             <entry>1, 2 or 3</entry>
1018             <entry>
1019               Version of the Real Video codec that this stream was encoded
1020               with.
1021             </entry>
1022           </row>
1023
1024           <!-- ############ type ############# -->
1025
1026           <row>
1027             <entry morerows="2">video/x-rle</entry>
1028             <entry morerows="2">RLE animation format.</entry>
1029             <entry>layout</entry>
1030             <entry>string</entry>
1031             <entry>"microsoft" or "quicktime"</entry>
1032             <entry>
1033               The RLE format inside the Microsoft AVI container has a
1034               different byte layout than the RLE format inside Apple's
1035               Quicktime container; this property keeps track of the
1036               layout.
1037             </entry>
1038           </row>
1039           <row>
1040             <entry>depth</entry>
1041             <entry>integer</entry>
1042             <entry>1 to 64</entry>
1043             <entry>
1044               Bit depth of the used palette. This means that the palette
1045               that belongs to this format defines 2^depth colors.
1046             </entry>
1047           </row>
1048           <row>
1049             <entry>palette_data</entry>
1050             <entry>GstBuffer</entry>
1051             <entry></entry>
1052             <entry>
1053               Buffer containing a color palette (in native-endian RGBA) used
1054               by this format. The buffer is of size 4*2^depth.
1055             </entry>
1056           </row>
1057
1058           <!-- ############ type ############# -->
1059
1060           <row>
1061             <entry>video/x-svq</entry>
1062             <entry>Sorensen Video.</entry>
1063             <entry>svqversion</entry>
1064             <entry>integer</entry>
1065             <entry>1 or 3</entry>
1066             <entry>
1067               Version of the Sorensen codec that the stream was encoded with.
1068             </entry>
1069           </row>
1070
1071           <!-- ############ type ############# -->
1072
1073           <row>
1074             <entry>video/x-tarkin</entry>
1075             <entry>Tarkin video.</entry>
1076             <entry></entry>
1077             <entry></entry>
1078             <entry></entry>
1079             <entry>
1080               There are currently no specific properties defined or needed for
1081               this type.
1082             </entry>
1083           </row>
1084
1085           <!-- ############ type ############# -->
1086
1087           <row>
1088             <entry>video/x-theora</entry>
1089             <entry>Theora video.</entry>
1090             <entry></entry>
1091             <entry></entry>
1092             <entry></entry>
1093             <entry>
1094               There are currently no specific properties defined or needed for
1095               this type.
1096             </entry>
1097           </row>
1098
1099           <!-- ############ type ############# -->
1100
1101           <row>
1102             <entry>video/x-vp3</entry>
1103             <entry>VP-3 video.</entry>
1104             <entry></entry>
1105             <entry></entry>
1106             <entry></entry>
1107             <entry>
1108               There are currently no specific properties defined or needed for
1109               this type. Note that we have different media types for VP-3 and
1110               Theora, which is not necessarily a good idea. This could probably
1111               be improved.
1112             </entry>
1113           </row>
1114
1115           <!-- ############ type ############# -->
1116
1117           <row>
1118             <entry>video/x-wmv</entry>
1119             <entry>Windows Media Video</entry>
1120             <entry>wmvversion</entry>
1121             <entry>integer</entry>
1122             <entry>1,2 or 3</entry>
1123             <entry>
1124               Version of the WMV codec that the stream was encoded with.
1125             </entry>
1126           </row>
1127
1128           <!-- ############ type ############# -->
1129
1130           <row>
1131             <entry>video/x-xvid</entry>
1132             <entry>XviD video.</entry>
1133             <entry></entry>
1134             <entry></entry>
1135             <entry></entry>
1136             <entry>
1137               There are currently no specific properties defined or needed for
1138               this type.
1139             </entry>
1140           </row>
1141
1142           <!-- ############ subtitle ############# -->
1143
1144           <row>
1145             <entry spanname="fullwidth">
1146               <emphasis>All image types.</emphasis>
1147             </entry>
1148           </row>
1149
1150           <!-- ############ type ############# -->
1151
1152           <row>
1153             <entry>image/gif</entry>
1154             <entry>Graphics Interchange Format.</entry>
1155             <entry></entry>
1156             <entry></entry>
1157             <entry></entry>
1158             <entry>
1159               There are currently no specific properties defined or needed for
1160               this type.
1161             </entry>
1162           </row>
1163
1164           <!-- ############ type ############# -->
1165
1166           <row>
1167             <entry>image/jpeg</entry>
1168             <entry>Joint Picture Expert Group Image.</entry>
1169             <entry></entry>
1170             <entry></entry>
1171             <entry></entry>
1172             <entry>
1173               There are currently no specific properties defined or needed for
1174               this type. Note that image/jpeg only applies to RGB-colourspace
1175               JPEG images; YUY2-colourspace JPEG pictures are referred to as
1176               video/x-jpeg ("Motion JPEG").
1177             </entry>
1178           </row>
1179
1180           <!-- ############ type ############# -->
1181
1182           <row>
1183             <entry>image/png</entry>
1184             <entry>Portable Network Graphics Image.</entry>
1185             <entry></entry>
1186             <entry></entry>
1187             <entry></entry>
1188             <entry>
1189               There are currently no specific properties defined or needed for
1190               this type.
1191             </entry>
1192           </row>
1193
1194           <!-- ############ type ############# -->
1195
1196           <row>
1197             <entry>image/tiff</entry>
1198             <entry>Tagged Image File Format.</entry>
1199             <entry></entry>
1200             <entry></entry>
1201             <entry></entry>
1202             <entry>
1203               There are currently no specific properties defined or needed for
1204               this type.
1205             </entry>
1206           </row>
1207         </tbody>
1208         </tgroup>
1209       </table>
1210
1211       <table frame="all" id="table-container-types" xreflabel="Table of Container Types">
1212         <title>Table of Container Types</title>
1213         <tgroup cols="6" align="left" colsep="1" rowsep="1">
1214         <colspec colnum="1" colname="colc1" colwidth="1*"/>
1215         <colspec colnum="6" colname="colc6" colwidth="6*"/>
1216         <spanspec spanname="fullwidth" namest="colc1" nameend="colc6"/>
1217
1218         <thead>
1219           <row>
1220             <entry>Media Type</entry>
1221             <entry>Description</entry>
1222             <entry>Property</entry>
1223             <entry>Property Type</entry>
1224             <entry>Property Values</entry>
1225             <entry>Property Description</entry>
1226           </row>
1227         </thead>
1228
1229         <tbody valign="top">
1230
1231           <!-- ############ type ############# -->
1232
1233           <row>
1234             <entry>video/x-ms-asf</entry>
1235             <entry>Advanced Streaming Format (ASF).</entry>
1236             <entry></entry>
1237             <entry></entry>
1238             <entry></entry>
1239             <entry>
1240               There are currently no specific properties defined or needed for
1241               this type.
1242             </entry>
1243           </row>
1244
1245           <!-- ############ type ############# -->
1246
1247           <row>
1248             <entry>video/x-msvideo</entry>
1249             <entry>AVI.</entry>
1250             <entry></entry>
1251             <entry></entry>
1252             <entry></entry>
1253             <entry>
1254               There are currently no specific properties defined or needed for
1255               this type.
1256             </entry>
1257           </row>
1258
1259           <!-- ############ type ############# -->
1260
1261           <row>
1262             <entry>video/x-dv</entry>
1263             <entry>Digital Video.</entry>
1264             <entry>systemstream</entry>
1265             <entry>boolean</entry>
1266             <entry>TRUE</entry>
1267             <entry>
1268               Indicates that this is a container system stream rather than an
1269               elementary video stream.
1270             </entry>
1271           </row>
1272
1273           <!-- ############ type ############# -->
1274
1275           <row>
1276             <entry>video/x-matroska</entry>
1277             <entry>Matroska.</entry>
1278             <entry></entry>
1279             <entry></entry>
1280             <entry></entry>
1281             <entry>
1282               There are currently no specific properties defined or needed for
1283               this type.
1284             </entry>
1285           </row>
1286
1287           <!-- ############ type ############# -->
1288
1289           <row>
1290             <entry>video/mpeg</entry>
1291             <entry>Motion Pictures Expert Group System Stream.</entry>
1292             <entry>systemstream</entry>
1293             <entry>boolean</entry>
1294             <entry>TRUE</entry>
1295             <entry>
1296               Indicates that this is a container system stream rather than an
1297               elementary video stream.
1298             </entry>
1299           </row>
1300
1301           <!-- ############ type ############# -->
1302
1303           <row>
1304             <entry>application/ogg</entry>
1305             <entry>Ogg.</entry>
1306             <entry></entry>
1307             <entry></entry>
1308             <entry></entry>
1309             <entry>
1310               There are currently no specific properties defined or needed for
1311               this type.
1312             </entry>
1313           </row>
1314
1315           <!-- ############ type ############# -->
1316
1317           <row>
1318             <entry>video/quicktime</entry>
1319             <entry>Quicktime.</entry>
1320             <entry></entry>
1321             <entry></entry>
1322             <entry></entry>
1323             <entry>
1324               There are currently no specific properties defined or needed for
1325               this type.
1326             </entry>
1327           </row>
1328
1329           <!-- ############ type ############# -->
1330
1331           <row>
1332             <entry>application/vnd.rn-realmedia</entry>
1333             <entry>RealMedia.</entry>
1334             <entry></entry>
1335             <entry></entry>
1336             <entry></entry>
1337             <entry>
1338               There are currently no specific properties defined or needed for
1339               this type.
1340             </entry>
1341           </row>
1342
1343           <!-- ############ type ############# -->
1344
1345           <row>
1346             <entry>audio/x-wav</entry>
1347             <entry>WAV.</entry>
1348             <entry></entry>
1349             <entry></entry>
1350             <entry></entry>
1351             <entry>
1352               There are currently no specific properties defined or needed for
1353               this type.
1354             </entry>
1355           </row>
1356           </tbody>
1357         </tgroup>
1358       </table>
1359
1360       <table frame="all" id="table-subtitle-types" xreflabel="Table of Subtitle Types">
1361         <title>Table of Subtitle Types</title>
1362         <tgroup cols="6" align="left" colsep="1" rowsep="1">
1363         <colspec colnum="1" colname="colt1" colwidth="1*"/>
1364         <colspec colnum="6" colname="colt6" colwidth="6*"/>
1365         <spanspec spanname="fullwidth" namest="colt1" nameend="colt6"/>
1366
1367         <thead>
1368           <row>
1369             <entry>Media Type</entry>
1370             <entry>Description</entry>
1371             <entry>Property</entry>
1372             <entry>Property Type</entry>
1373             <entry>Property Values</entry>
1374             <entry>Property Description</entry>
1375           </row>
1376         </thead>
1377
1378         <tbody valign="top">
1379
1380           <!-- ############ type ############# -->
1381
1382           <row>
1383             <entry></entry>
1384             <entry></entry>
1385             <entry></entry>
1386             <entry></entry>
1387             <entry></entry>
1388             <entry>
1389               None defined yet.
1390             </entry>
1391           </row>
1392           </tbody>
1393         </tgroup>
1394       </table>
1395
1396       <table frame="all" id="table-other-types" xreflabel="Table of Other Types">
1397         <title>Table of Other Types</title>
1398         <tgroup cols="6" align="left" colsep="1" rowsep="1">
1399         <colspec colnum="1" colname="colo1" colwidth="1*"/>
1400         <colspec colnum="6" colname="colo6" colwidth="6*"/>
1401         <spanspec spanname="fullwidth" namest="colo1" nameend="colo6"/>
1402
1403         <thead>
1404           <row>
1405             <entry>Media Type</entry>
1406             <entry>Description</entry>
1407             <entry>Property</entry>
1408             <entry>Property Type</entry>
1409             <entry>Property Values</entry>
1410             <entry>Property Description</entry>
1411           </row>
1412         </thead>
1413
1414         <tbody valign="top">
1415
1416           <!-- ############ type ############# -->
1417
1418           <row>
1419             <entry></entry>
1420             <entry></entry>
1421             <entry></entry>
1422             <entry></entry>
1423             <entry></entry>
1424             <entry>
1425               None defined yet.
1426             </entry>
1427           </row>
1428           </tbody>
1429         </tgroup>
1430       </table>
1431   </sect1>
1432 </chapter>