docs/random/mimetypes

   1 Mimetypes in GStreamer
   2 ======================
   3
   4 1) What is a mimetype
   5 ---------------------
   6 A mimetype is a combination of two (short) strings (words), the content
   7 type and the content subtype, that make up a pair that describes a file
   8 content type. In multimedia, mime types are used to describe the media
   9 streamtype . In GStreamer, obsiously, we use mimetypes in the same way.
  10 They are part of a GstCaps, that describes a media stream. Besides a
  11 mimetype, a GstCaps also contains stream properties (GstProps), which
  12 are combinations of key/value pairs, and a name.
  13
  14 An example of a mimetype is 'video/mpeg'. A corresponding GstCaps could
  15 be created using:
  16 GstCaps *caps = gst_caps_new("video_mpeg_type",
  17                              "video/mpeg",
  18                              gst_props_new("width",  GST_PROPS_INT(384),
  19                                            "height", GST_PROPS_INT(288),
  20                                            NULL));
  21
  22 Obviously, mimetypes and their corresponding properties are of major
  23 importance in GStreamer for uniquely identifying media streams.
  24
  25 2) The problems
  26 ---------------
  27 Some streams may have mimetypes or GstCaps that do not fully describe
  28 the stream. In most cases, this is not a problem, though. For a stream
  29 that contains Ogg/Vorbis data, we don't need to know the samplerate of
  30 the raw audio stream, for example, since we can't play it back anyway.
  31 The samplerate _is_ important for _raw_ audio, so a decoder would need
  32 to retrieve the samplerate from the Ogg/Vorbis stream headers (that are
  33 part of the bytestream) in order to pass it on in the GstCaps that
  34 belongs to the decoded audio ('audio/raw').
  35
  36 Another problem is that many media types can be defined in multiple ways.
  37 For example, MJPEG video can be defined as video/jpeg, video/mjpeg,
  38 image/jpeg, video/avi with a compression of (fourcc) MJPG, etc. None of
  39 these is really official, since there isn't an official mimetype for
  40 encoded MJPEG video.
  41
  42 The main focus of this document is to propose a standardized set of
  43 mimetypes and properties that will be used by the GStreamer plugins.
  44
  45 3) Different types of streams
  46 -----------------------------
  47 There are several types of media streams. The most important distinction
  48 will be container formats, audio codecs and video codecs. Container
  49 formats are bytestreams that contain one or more substreams inside it,
  50 and don't provide any direct media data itself. Examples are Quicktime,
  51 AVI or MPEG (bytestream). They mostly contain of a set of headers that
  52 define the media stream(s) that is packed inside the container and the
  53 media data itself.
  54 Video codecs and audio codecs describe encoded audio or video data.
  55 Examples are MPEG-1 video, DivX ;-) video, MPEG-1 layer 3 (MP3) audio
  56 or Ogg/Vorbis audio. Actually, Ogg is a container format too (for Vorbis
  57 audio), but these are usually used in conjunction with each other.
  58
  59 3a) Container formats
  60 1 - AVI (Microsoft RIFF/AVI)
  61   mimetype: video/x-msvideo
  62 2 - Quicktime (Apple)
  63   mimetype: video/x-quicktime
  64 3 - MPEG (MPEG LA)
  65   mimetype: video/mpeg
  66   properties: 'systemstream' = 1 (INT)
  67 4 - ASF (Microsoft)
  68   mimetype: video/x-asf
  69 5 - WAV (PCM)
  70   mimetype: audio/x-wav
  71 6 - RealMedia (Real)
  72   mimetype: video/realmedia
  73 7 - DV (Digital Video)
  74   mimetype: video/dv
  75   properties: 'systemstream' = 1 (INT)
  76 8 - Ogg
  77   mimetypes: media/ogg
  78
  79 3b) Video codecs
  80 For convenience, the fourcc codes used in the AVI container format will be
  81 listed along with the mimetype and optional properties. All video codecs
  82 share the properties 'width' and 'height', both INT, which define the size
  83 of the frame (in pixels).
  84 1a - Raw Video (YUV/YCbCr)
  85   mimetype: video/raw
  86   properties: 'format' = 'XXXX' (fourcc)
  87   known fourccs: YUY2, IYUV/I420, Y41P, etc.
  88 1b - Raw Video (RGB)
  89   mimetype: video/raw
  90   properties: 'format' = 'RGB ' (fourcc)
  91               'endianness' = 1234/4321 (INT) <- endianness
  92               'r_mask' = bitmask (0x..) (INT) <- red pixel mask
  93               'g_mask' = bitmask (0x..) (INT) <- green pixel mask
  94               'b_mask' = bitmask (0x..) (INT) <- blue pixel mask
  95               'depth' = 15/16/24/32 (INT) <- bits per pixel (depth)
  96               'bpp' = 16/24/32 (INT) <- bits per pixel (in memory)
  97 2 - MPEG-1, -2 and -4 video (ISO/LA MPEG)
  98   mimetype: video/mpeg
  99   properties: 'systemstream' = 0 (INT)
 100               'mpegversion' = 1/2/4 (INT)
 101   known fourccs: MPEG, MPGI
 102 3 - DivX ;-) 3.x, 4.x and 5.x video
 103   mimetype: video/divx
 104   properties: 'divxversion' = 3/4/5 (INT)
 105   known fourccs: DIV3, DIV4, DIV5, DIVX, DX50, DIVX, divx
 106 4 - Microsoft MPEG 4.1, 4.2 and 4.3
 107   mimetype: video/x-msmpeg
 108   properties: 'mpegversion' = 41/42/43 (INT)
 109   known fourccs: MPG4, MP42, MP43
 110 5 - Motion-JPEG (official and extended)
 111   mimetype: video/jpeg
 112   known fourccs: MJPG (YUY2 MJPEG), JPEG (any), PIXL (Pinnacle/Miro), VIXL
 113 6 - Sorensen (Quicktime - SVQ1/SVQ3)
 114   mimetypes: video/x-svq
 115   properties: 'svqversion' = 1/3 (INT)
 116 7 - H263 and related codecs
 117   mimetype: video/h263
 118   known fourccs: H263, i263, M263, x263, VDOW, VIVO
 119 8 - RealVideo (Real)
 120   mimetype: video/realvideo
 121 9 - Digital Video (DV)
 122   mimetype: video/dv
 123   properties: 'systemstream' = 0 (INT)
 124   known fourccs: DVSD, dvsd
 125 10 - Windows Media Video 1 and 2 (WMV)
 126   mimetype: video/wmv
 127   properties: 'wmvversion' = 1/2 (INT)
 128 11 - XviD
 129   mimetype: video/xvid
 130   known fourccs: xvid, XVID
 131 12 - 3IVX
 132   mimetype: video/3ivx
 133   known fourccs: 3IV1, 3IV2
 134 13 - Ogg/Tarkin
 135   mimetype: video/x-ogg-tarkin
 136 14 - Ogg/Theora
 137   mimetype: video/x-ogg-theora
 138 15 - Huffyuv
 139   mimetype: video/x-huffyuv
 140   known fourccs: HFYU
 141
 142 3c) Audio Codecs
 143 for convenience, the two-byte hexcodes (as are being used for identification
 144 in AVI files) are also given
 145 1 - Raw Audio
 146   mimetype: audio/raw
 147   properties: 'rate' = X (INT) <- samplerate
 148               'width' = X (INT) <- audio bitsize
 149               'depth' = X (INT) <- same?
 150               'law' = 0/1/2 (INT) <- no law (0), alaw (1) or mulaw (2)
 151               'signedness' = X (BOOLEAN)
 152               'channels' = X (INT) <- number of audio channels
 153               'endianness' = 1234/4321 <- endianness of audio stream
 154 2 - MPEG-1 layer 1/2/3 audio
 155   mimetype: audio/mpeg
 156   properties: 'mpegversion' = 1/2/3 (INT)
 157 3 - Ogg/Vorbis
 158   mimetype: application/x-ogg
 159 4 - Windows Media Audio 1 and 2 (WMA)
 160   mimetype: audio/wma
 161 5 - AC3
 162   mimetype: audio/ac3
 163
 164 4 - Status of this document
 165 ---------------------------
 166 This document is currently under construction and the types listed in here
 167 are purely imaginary. Don't take this as your starting point (yet).
 168
 169 Blame Ronald Bultje <rbultje@ronald.bitfreak.net> aka BBB for any mistakes
 170 in this document.