pwg-building-types.md

   1 ---
   2 title: Types and Properties
   3 ...
   4
   5 # Types and Properties
   6
   7 There is a very large set of possible types that may be used to pass
   8 data between elements. Indeed, each new element that is defined may use
   9 a new data format (though unless at least one other element recognises
  10 that format, it will be most likely be useless since nothing will be
  11 able to link with it).
  12
  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
  21 For now, the policy is simple:
  22
  23   - Do not create a new type if you could use one which already exists.
  24
  25   - If creating a new type, discuss it first with the other GStreamer
  26     developers, on at least one of: IRC, mailing lists.
  27
  28   - Try to ensure that the name for a new format is as unlikely to
  29     conflict with anything else created already, and is not a more
  30     generalised name than it should be. For example: "audio/compressed"
  31     would be too generalised a name to represent audio data compressed
  32     with an mp3 codec. Instead "audio/mp3" might be an appropriate name,
  33     or "audio/compressed" could exist and have a property indicating the
  34     type of compression used.
  35
  36   - Ensure that, when you do create a new type, you specify it clearly,
  37     and get it added to the list of known types so that other developers
  38     can use the type correctly when writing their elements.
  39
  40 ## Building a Simple Format for Testing
  41
  42 If you need a new format that has not yet been defined in our [List of
  43 Defined Types](#list-of-defined-types), you will want to have some
  44 general guidelines on media type naming, properties and such. A media
  45 type would ideally be equivalent to the Mime-type defined by IANA; else,
  46 it should be in the form type/x-name, where type is the sort of data
  47 this media type handles (audio, video, ...) and name should be something
  48 specific for this specific type. Audio and video media types should try
  49 to support the general audio/video properties (see the list), and can
  50 use their own properties, too. To get an idea of what properties we
  51 think are useful, see (again) the list.
  52
  53 Take your time to find the right set of properties for your type. There
  54 is no reason to hurry. Also, experimenting with this is generally a good
  55 idea. Experience learns that theoretically thought-out types are good,
  56 but they still need practical use to assure that they serve their needs.
  57 Make sure that your property names do not clash with similar properties
  58 used in other types. If they match, make sure they mean the same thing;
  59 properties with different types but the same names are *not* allowed.
  60
  61 ## Typefind Functions and Autoplugging
  62
  63 With only *defining* the types, we're not yet there. In order for a
  64 random data file to be recognized and played back as such, we need a way
  65 of recognizing their type out of the blue. For this purpose,
  66 “typefinding” was introduced. Typefinding is the process of detecting
  67 the type of a data stream. Typefinding consists of two separate parts:
  68 first, there's an unlimited number of functions that we call *typefind
  69 functions*, which are each able to recognize one or more types from an
  70 input stream. Then, secondly, there's a small engine which registers and
  71 calls each of those functions. This is the typefind core. On top of this
  72 typefind core, you would normally write an autoplugger, which is able to
  73 use this type detection system to dynamically build a pipeline around an
  74 input stream. Here, we will focus only on typefind functions.
  75
  76 A typefind function usually lives in
  77 `gst-plugins-base/gst/typefind/gsttypefindfunctions.c`, unless there's a
  78 good reason (like library dependencies) to put it elsewhere. The reason
  79 for this centralization is to reduce the number of plugins that need to
  80 be loaded in order to detect a stream's type. Below is an example that
  81 will recognize AVI files, which start with a “RIFF” tag, then the size
  82 of the file and then an “AVI” tag:
  83
  84 ``` c
  85 static void
  86 gst_my_typefind_function (GstTypeFind *tf,
  87               gpointer     data)
  88 {
  89   guint8 *data = gst_type_find_peek (tf, 0, 12);
  90
  91   if (data &&
  92       GUINT32_FROM_LE (&((guint32 *) data)[0]) == GST_MAKE_FOURCC ('R','I','F','F') &&
  93       GUINT32_FROM_LE (&((guint32 *) data)[2]) == GST_MAKE_FOURCC ('A','V','I',' ')) {
  94     gst_type_find_suggest (tf, GST_TYPE_FIND_MAXIMUM,
  95                gst_caps_new_simple ("video/x-msvideo", NULL));
  96   }
  97 }
  98
  99 static gboolean
 100 plugin_init (GstPlugin *plugin)
 101 {
 102   if (!gst_type_find_register (plugin, "", GST_RANK_PRIMARY,
 103                    gst_my_typefind_function, "avi",
 104                    gst_caps_new_simple ("video/x-msvideo",
 105                             NULL), NULL))
 106     return FALSE;
 107 }
 108
 109 ```
 110
 111 Note that `gst-plugins/gst/typefind/gsttypefindfunctions.c` has some
 112 simplification macros to decrease the amount of code. Make good use of
 113 those if you want to submit typefinding patches with new typefind
 114 functions.
 115
 116 Autoplugging has been discussed in great detail in the Application
 117 Development Manual.
 118
 119 ## List of Defined Types
 120
 121 Below is a list of all the defined types in GStreamer. They are split up
 122 in separate tables for audio, video, container, subtitle and other
 123 types, for the sake of readability. Below each table might follow a list
 124 of notes that apply to that table. In the definition of each type, we
 125 try to follow the types and rules as defined by
 126 [IANA](http://www.iana.org/assignments/media-types) for as far as
 127 possible.
 128
 129 Jump directly to a specific table:
 130
 131   - [Table of Audio Types](#table-of-audio-types)
 132
 133   - [Table of Video Types](#table-of-video-types)
 134
 135   - [Table of Container Types](#table-of-container-types)
 136
 137   - [Table of Subtitle Types](#table-of-subtitle-types)
 138
 139   - [Table of Other Types](#table-of-other-types)
 140
 141 Note that many of the properties are not *required*, but rather
 142 *optional* properties. This means that most of these properties can be
 143 extracted from the container header, but that - in case the container
 144 header does not provide these - they can also be extracted by parsing
 145 the stream header or the stream content. The policy is that your element
 146 should provide the data that it knows about by only parsing its own
 147 content, not another element's content. Example: the AVI header provides
 148 samplerate of the contained audio stream in the header. MPEG system
 149 streams don't. This means that an AVI stream demuxer would provide
 150 samplerate as a property for MPEG audio streams, whereas an MPEG demuxer
 151 would not. A decoder needing this data would require a stream parser in
 152 between two extract this from the header or calculate it from the
 153 stream.
 154
 155 <table>
 156 <caption>Table of Audio Types</caption>
 157 <colgroup>
 158 <col width="14%" />
 159 <col width="85%" />
 160 </colgroup>
 161 <thead>
 162 <tr class="header">
 163 <th>Media Type</th>
 164 <th>Description</th>
 165 </tr>
 166 </thead>
 167 <tbody>
 168 <tr class="odd">
 169 <td><em>All audio types.</em></td>
 170 </tr>
 171 <tr class="even">
 172 <td>audio/*</td>
 173 <td><em>All audio types</em></td>
 174 </tr>
 175 <tr class="odd">
 176 <td>channels</td>
 177 <td>integer</td>
 178 </tr>
 179 <tr class="even">
 180 <td>channel-mask</td>
 181 <td>bitmask</td>
 182 </tr>
 183 <tr class="odd">
 184 <td>format</td>
 185 <td>string</td>
 186 </tr>
 187 <tr class="even">
 188 <td>layout</td>
 189 <td>string</td>
 190 </tr>
 191 <tr class="odd">
 192 <td><em>All raw audio types.</em></td>
 193 </tr>
 194 <tr class="even">
 195 <td>audio/x-raw</td>
 196 <td>Unstructured and uncompressed raw audio data.</td>
 197 </tr>
 198 <tr class="odd">
 199 <td><em>All encoded audio types.</em></td>
 200 </tr>
 201 <tr class="even">
 202 <td>audio/x-ac3</td>
 203 <td>AC-3 or A52 audio streams.</td>
 204 </tr>
 205 <tr class="odd">
 206 <td>audio/x-adpcm</td>
 207 <td>ADPCM Audio streams.</td>
 208 </tr>
 209 <tr class="even">
 210 <td>block_align</td>
 211 <td>integer</td>
 212 </tr>
 213 <tr class="odd">
 214 <td>audio/x-cinepak</td>
 215 <td>Audio as provided in a Cinepak (Quicktime) stream.</td>
 216 </tr>
 217 <tr class="even">
 218 <td>audio/x-dv</td>
 219 <td>Audio as provided in a Digital Video stream.</td>
 220 </tr>
 221 <tr class="odd">
 222 <td>audio/x-flac</td>
 223 <td>Free Lossless Audio codec (FLAC).</td>
 224 </tr>
 225 <tr class="even">
 226 <td>audio/x-gsm</td>
 227 <td>Data encoded by the GSM codec.</td>
 228 </tr>
 229 <tr class="odd">
 230 <td>audio/x-alaw</td>
 231 <td>A-Law Audio.</td>
 232 </tr>
 233 <tr class="even">
 234 <td>audio/x-mulaw</td>
 235 <td>Mu-Law Audio.</td>
 236 </tr>
 237 <tr class="odd">
 238 <td>audio/x-mace</td>
 239 <td>MACE Audio (used in Quicktime).</td>
 240 </tr>
 241 <tr class="even">
 242 <td>audio/mpeg</td>
 243 <td>Audio data compressed using the MPEG audio encoding scheme.</td>
 244 </tr>
 245 <tr class="odd">
 246 <td>framed</td>
 247 <td>boolean</td>
 248 </tr>
 249 <tr class="even">
 250 <td>layer</td>
 251 <td>integer</td>
 252 </tr>
 253 <tr class="odd">
 254 <td>bitrate</td>
 255 <td>integer</td>
 256 </tr>
 257 <tr class="even">
 258 <td>audio/x-qdm2</td>
 259 <td>Data encoded by the QDM version 2 codec.</td>
 260 </tr>
 261 <tr class="odd">
 262 <td>audio/x-pn-realaudio</td>
 263 <td>Realmedia Audio data.</td>
 264 </tr>
 265 <tr class="even">
 266 <td>audio/x-speex</td>
 267 <td>Data encoded by the Speex audio codec</td>
 268 </tr>
 269 <tr class="odd">
 270 <td>audio/x-vorbis</td>
 271 <td>Vorbis audio data</td>
 272 </tr>
 273 <tr class="even">
 274 <td>audio/x-wma</td>
 275 <td>Windows Media Audio</td>
 276 </tr>
 277 <tr class="odd">
 278 <td>audio/x-paris</td>
 279 <td>Ensoniq PARIS audio</td>
 280 </tr>
 281 <tr class="even">
 282 <td>audio/x-svx</td>
 283 <td>Amiga IFF / SVX8 / SV16 audio</td>
 284 </tr>
 285 <tr class="odd">
 286 <td>audio/x-nist</td>
 287 <td>Sphere NIST audio</td>
 288 </tr>
 289 <tr class="even">
 290 <td>audio/x-voc</td>
 291 <td>Sound Blaster VOC audio</td>
 292 </tr>
 293 <tr class="odd">
 294 <td>audio/x-ircam</td>
 295 <td>Berkeley/IRCAM/CARL audio</td>
 296 </tr>
 297 <tr class="even">
 298 <td>audio/x-w64</td>
 299 <td>Sonic Foundry's 64 bit RIFF/WAV</td>
 300 </tr>
 301 </tbody>
 302 </table>
 303
 304 <table>
 305 <caption>Table of Video Types</caption>
 306 <colgroup>
 307 <col width="14%" />
 308 <col width="85%" />
 309 </colgroup>
 310 <thead>
 311 <tr class="header">
 312 <th>Media Type</th>
 313 <th>Description</th>
 314 </tr>
 315 </thead>
 316 <tbody>
 317 <tr class="odd">
 318 <td><em>All video types.</em></td>
 319 </tr>
 320 <tr class="even">
 321 <td>video/*</td>
 322 <td><em>All video types</em></td>
 323 </tr>
 324 <tr class="odd">
 325 <td>height</td>
 326 <td>integer</td>
 327 </tr>
 328 <tr class="even">
 329 <td>framerate</td>
 330 <td>fraction</td>
 331 </tr>
 332 <tr class="odd">
 333 <td>max-framerate</td>
 334 <td>fraction</td>
 335 </tr>
 336 <tr class="even">
 337 <td>views</td>
 338 <td>integer</td>
 339 </tr>
 340 <tr class="odd">
 341 <td>interlace-mode</td>
 342 <td>string</td>
 343 </tr>
 344 <tr class="even">
 345 <td>chroma-site</td>
 346 <td>string</td>
 347 </tr>
 348 <tr class="odd">
 349 <td>colorimetry</td>
 350 <td>string</td>
 351 </tr>
 352 <tr class="even">
 353 <td>pixel-aspect-ratio</td>
 354 <td>fraction</td>
 355 </tr>
 356 <tr class="odd">
 357 <td>format</td>
 358 <td>string</td>
 359 </tr>
 360 <tr class="even">
 361 <td><em>All raw video types.</em></td>
 362 </tr>
 363 <tr class="odd">
 364 <td>video/x-raw</td>
 365 <td>Unstructured and uncompressed raw video data.</td>
 366 </tr>
 367 <tr class="even">
 368 <td><em>All encoded video types.</em></td>
 369 </tr>
 370 <tr class="odd">
 371 <td>video/x-3ivx</td>
 372 <td>3ivx video.</td>
 373 </tr>
 374 <tr class="even">
 375 <td>video/x-divx</td>
 376 <td>DivX video.</td>
 377 </tr>
 378 <tr class="odd">
 379 <td>video/x-dv</td>
 380 <td>Digital Video.</td>
 381 </tr>
 382 <tr class="even">
 383 <td>video/x-ffv</td>
 384 <td>FFMpeg video.</td>
 385 </tr>
 386 <tr class="odd">
 387 <td>video/x-h263</td>
 388 <td>H-263 video.</td>
 389 </tr>
 390 <tr class="even">
 391 <td>h263version</td>
 392 <td>string</td>
 393 </tr>
 394 <tr class="odd">
 395 <td>video/x-h264</td>
 396 <td>H-264 video.</td>
 397 </tr>
 398 <tr class="even">
 399 <td>video/x-huffyuv</td>
 400 <td>Huffyuv video.</td>
 401 </tr>
 402 <tr class="odd">
 403 <td>video/x-indeo</td>
 404 <td>Indeo video.</td>
 405 </tr>
 406 <tr class="even">
 407 <td>video/x-intel-h263</td>
 408 <td>H-263 video.</td>
 409 </tr>
 410 <tr class="odd">
 411 <td>video/x-jpeg</td>
 412 <td>Motion-JPEG video.</td>
 413 </tr>
 414 <tr class="even">
 415 <td>video/mpeg</td>
 416 <td>MPEG video.</td>
 417 </tr>
 418 <tr class="odd">
 419 <td>systemstream</td>
 420 <td>boolean</td>
 421 </tr>
 422 <tr class="even">
 423 <td>video/x-msmpeg</td>
 424 <td>Microsoft MPEG-4 video deviations.</td>
 425 </tr>
 426 <tr class="odd">
 427 <td>video/x-msvideocodec</td>
 428 <td>Microsoft Video 1 (oldish codec).</td>
 429 </tr>
 430 <tr class="even">
 431 <td>video/x-pn-realvideo</td>
 432 <td>Realmedia video.</td>
 433 </tr>
 434 <tr class="odd">
 435 <td>video/x-rle</td>
 436 <td>RLE animation format.</td>
 437 </tr>
 438 <tr class="even">
 439 <td>depth</td>
 440 <td>integer</td>
 441 </tr>
 442 <tr class="odd">
 443 <td>palette_data</td>
 444 <td>GstBuffer</td>
 445 </tr>
 446 <tr class="even">
 447 <td>video/x-svq</td>
 448 <td>Sorensen Video.</td>
 449 </tr>
 450 <tr class="odd">
 451 <td>video/x-tarkin</td>
 452 <td>Tarkin video.</td>
 453 </tr>
 454 <tr class="even">
 455 <td>video/x-theora</td>
 456 <td>Theora video.</td>
 457 </tr>
 458 <tr class="odd">
 459 <td>video/x-vp3</td>
 460 <td>VP-3 video.</td>
 461 </tr>
 462 <tr class="even">
 463 <td>video/x-wmv</td>
 464 <td>Windows Media Video</td>
 465 </tr>
 466 <tr class="odd">
 467 <td>video/x-xvid</td>
 468 <td>XviD video.</td>
 469 </tr>
 470 <tr class="even">
 471 <td><em>All image types.</em></td>
 472 </tr>
 473 <tr class="odd">
 474 <td>image/gif</td>
 475 <td>Graphics Interchange Format.</td>
 476 </tr>
 477 <tr class="even">
 478 <td>image/jpeg</td>
 479 <td>Joint Picture Expert Group Image.</td>
 480 </tr>
 481 <tr class="odd">
 482 <td>image/png</td>
 483 <td>Portable Network Graphics Image.</td>
 484 </tr>
 485 <tr class="even">
 486 <td>image/tiff</td>
 487 <td>Tagged Image File Format.</td>
 488 </tr>
 489 </tbody>
 490 </table>
 491
 492 <table>
 493 <caption>Table of Container Types</caption>
 494 <colgroup>
 495 <col width="14%" />
 496 <col width="85%" />
 497 </colgroup>
 498 <thead>
 499 <tr class="header">
 500 <th>Media Type</th>
 501 <th>Description</th>
 502 </tr>
 503 </thead>
 504 <tbody>
 505 <tr class="odd">
 506 <td>video/x-ms-asf</td>
 507 <td>Advanced Streaming Format (ASF).</td>
 508 </tr>
 509 <tr class="even">
 510 <td>video/x-msvideo</td>
 511 <td>AVI.</td>
 512 </tr>
 513 <tr class="odd">
 514 <td>video/x-dv</td>
 515 <td>Digital Video.</td>
 516 </tr>
 517 <tr class="even">
 518 <td>video/x-matroska</td>
 519 <td>Matroska.</td>
 520 </tr>
 521 <tr class="odd">
 522 <td>video/mpeg</td>
 523 <td>Motion Pictures Expert Group System Stream.</td>
 524 </tr>
 525 <tr class="even">
 526 <td>application/ogg</td>
 527 <td>Ogg.</td>
 528 </tr>
 529 <tr class="odd">
 530 <td>video/quicktime</td>
 531 <td>Quicktime.</td>
 532 </tr>
 533 <tr class="even">
 534 <td>application/vnd.rn-realmedia</td>
 535 <td>RealMedia.</td>
 536 </tr>
 537 <tr class="odd">
 538 <td>audio/x-wav</td>
 539 <td>WAV.</td>
 540 </tr>
 541 </tbody>
 542 </table>
 543
 544 <table>
 545 <caption>Table of Subtitle Types</caption>
 546 <colgroup>
 547 <col width="14%" />
 548 <col width="85%" />
 549 </colgroup>
 550 <thead>
 551 <tr class="header">
 552 <th>Media Type</th>
 553 <th>Description</th>
 554 </tr>
 555 </thead>
 556 <tbody>
 557 <tr class="odd">
 558 <td></td>
 559 <td></td>
 560 </tr>
 561 </tbody>
 562 </table>
 563
 564 <table>
 565 <caption>Table of Other Types</caption>
 566 <colgroup>
 567 <col width="14%" />
 568 <col width="85%" />
 569 </colgroup>
 570 <thead>
 571 <tr class="header">
 572 <th>Media Type</th>
 573 <th>Description</th>
 574 </tr>
 575 </thead>
 576 <tbody>
 577 <tr class="odd">
 578 <td></td>
 579 <td></td>
 580 </tr>
 581 </tbody>
 582 </table>
 583