markdown/design/draft-metadata.md

   1 # Metadata
   2
   3 This draft recaps the current metadata handling in GStreamer and
   4 proposes some additions.
   5
   6 ## Supported Metadata standards
   7
   8 The paragraphs below list supported native metadata standards sorted by
   9 type and then in alphabetical order. Some standards have been extended
  10 to support additional metadata. GStreamer already supports all of those
  11 to some extend. This is showns in the table below as either `[--]`,
  12 `[r-]`, `[-w]` or `[rw]` depending on read/write support (08.Feb.2010).
  13
  14 ### Audio
  15 - mp3
  16   * ID3v2: `[rw]`
  17      * http://www.id3.org/Developer_Information
  18   * ID3v1: `[rw]`
  19     * http://www.id3.org/ID3v1
  20   * XMP: `[--]` (inside ID3v2 PRIV tag of owner XMP)
  21     * http://www.adobe.com/devnet/xmp/
  22 - ogg/vorbis
  23   * vorbiscomment: `[rw]`
  24     * http://www.xiph.org/vorbis/doc/v-comment.html
  25     * http://wiki.xiph.org/VorbisComment
  26 - wav
  27   * LIST/INFO chunk: `[rw]`
  28     * http://www.sno.phy.queensu.ca/~phil/exiftool/TagNames/RIFF.html#Info
  29     * http://www.kk.iij4u.or.jp/~kondo/wave/mpidata.txt
  30   * XMP: `[--]`
  31     * http://www.adobe.com/devnet/xmp/
  32
  33 ### Video
  34 - 3gp
  35   * {moov,trak}.udta:  `[rw]`
  36      * http://www.3gpp.org/ftp/Specs/html-info/26244.htm
  37   * ID3V2: `[--]`
  38      * http://www.3gpp.org/ftp/Specs/html-info/26244.htm
  39      * http://www.mp4ra.org/specs.html#id3v2
  40 - avi
  41   * LIST/INFO chunk: `[rw]`
  42     * http://www.sno.phy.queensu.ca/~phil/exiftool/TagNames/RIFF.html#Info
  43     * http://www.kk.iij4u.or.jp/~kondo/wave/mpidata.txt
  44   * XMP: `[--]` (inside "_PMX" chunk)
  45     * http://www.adobe.com/devnet/xmp/
  46 - asf
  47   * ??:
  48   * XMP: `[--]`
  49     * http://www.adobe.com/devnet/xmp/
  50 - flv `[--]`
  51   * XMP: (inside onXMPData script data tag)
  52     * http://www.adobe.com/devnet/xmp/
  53 - mkv
  54   * tags: `[rw]`
  55     * http://www.matroska.org/technical/specs/tagging/index.html
  56 - mov
  57   * XMP: `[--]` (inside moov.udta.XMP_ box)
  58     * http://www.adobe.com/devnet/xmp/
  59 - mp4
  60   * {moov,trak}.udta: `[rw]`
  61     * http://standards.iso.org/ittf/PubliclyAvailableStandards/c051533_ISO_IEC_14496-12_2008.zip
  62   * moov.udta.meta.ilst: `[rw]`
  63     * http://atomicparsley.sourceforge.net/
  64     * http://atomicparsley.sourceforge.net/mpeg-4files.html
  65   * ID3v2: `[--]`
  66     * http://www.mp4ra.org/specs.html#id3v2
  67   * XMP: `[--]` (inside UUID box)
  68     * http://www.adobe.com/devnet/xmp/
  69 - mxf
  70   * ??
  71
  72 ### Images
  73 - gif
  74   * XMP: `[--]`
  75     * http://www.adobe.com/devnet/xmp/
  76 - jpg
  77   * jif: `[rw]` (only comments)
  78   * EXIF: `[rw]` (via metadata plugin)
  79     * http://www.exif.org/specifications.html
  80   * IPTC: `[rw]` (via metadata plugin)
  81     * http://www.iptc.org/IPTC4XMP/
  82   * XMP: `[rw]` (via metadata plugin)
  83     * http://www.adobe.com/devnet/xmp/
  84 - png
  85   * XMP: `[--]`
  86     * http://www.adobe.com/devnet/xmp/
  87
  88 ### further Links:
  89
  90 http://age.hobba.nl/audio/tag_frame_reference.html
  91 http://wiki.creativecommons.org/Tracker_CC_Indexing
  92
  93 ## Current Metadata handling
  94
  95 When reading files, demuxers or parsers extract the metadata. It will be
  96 sent a `GST_EVENT_TAG` to downstream elements. When a sink element
  97 receives a tag event, it will post a `GST_MESSAGE_TAG` message on the
  98 bus with the contents of the tag event.
  99
 100 Elements receiving `GST_EVENT_TAG` events can mangle them, mux them into
 101 the buffers they send or just pass them through. Usually is muxers that
 102 will format the tag data into the form required by the format they mux.
 103 Such elements would also implement the `GstTagSetter` interface to receive
 104 tags from the application.
 105
 106 ```
 107  +----------+
 108  | demux    |
 109 sink       src --> GstEvent(tag) over GstPad to downstream element
 110  +----------+
 111
 112            method call over GstTagSetter interface from application
 113                                                           |
 114                                                           v
 115                                                     +----------+
 116                                                     | mux      |
 117 GstEvent(tag) over GstPad from upstream element --> sink       src
 118                                                     +----------+
 119 ```
 120
 121 The data used in all those interfaces is `GstTagList`. It is based on a
 122 `GstStructure` which is like a hash table with differently typed entries.
 123 The key is always a string/GQuark. Many keys are predefined in GStreamer
 124 core. More keys are defined in gst-plugins-base/gst-libs/gst/tag/tag.h.
 125 If elements and applications use predefined types, it is possible to
 126 transcode a file from one format into another while preserving all known
 127 and mapped metadata.
 128
 129 ## Issues
 130
 131 ### Unknown/Unmapped metadata
 132
 133 Right now GStreamer can lose metadata when transcoding and/or remuxing
 134 content. This can happens as we don’t map all metadata fields to generic
 135 ones.
 136
 137 We should probably also add the whole metadata blob to the `GstTagList`.
 138 We would need a `GST_TAG_SYSTEM_xxx` define (e.g.
 139 `GST_TAG_SYSTEM_ID3V2`) for each standard. The content is not printable
 140 and should be treated as binary if not known. The tag is not mergeable -
 141 call `gst_tag_register()` with `GstTagMergeFunc=NULL`. Also the tag data
 142 is only useful for upstream elements, not for the application.
 143
 144 A muxer would first scan a taglist for known system tags. Unknown tags
 145 are ignored as already. It would first populate its own metadata store
 146 with the entries from the system tag and the update the entries with the
 147 data in normal tags.
 148
 149 Below is an initial list of tag systems: `ID3V1` - `GST_TAG_SYSTEM_ID3V1`
 150 `ID3V2` - `GST_TAG_SYSTEM_ID3V2` `RIFF_INFO` -
 151 `GST_TAG_SYSTEM_RIFF_INFO` XMP - `GST_TAG_SYSTEM_XMP`
 152
 153 We would basically need this for each container format.
 154
 155 See also <https://bugzilla.gnome.org/show_bug.cgi?id=345352>
 156
 157 ### Lost metadata
 158
 159 A case slighly different from the previous is that when an application
 160 sets a `GstTagList` on a pipeline. Right elements consuming tags do not
 161 report which tags have been consumed. Especially when using elements
 162 that make metadata persistent, we have no means of knowing which of the
 163 tags made it into the target stream and which were not serialized.
 164 Ideally the application would like to know which kind of metadata is
 165 accepted by a pipleine to reflect that in the UI.
 166
 167 Although it is in practise so that elements implementing `GstTagSetter`
 168 are the ones that serialize, this does not have to be so. Otherwise we
 169 could add a means to that interface, where elements add the tags they
 170 have serialized. The application could build one list from all the tag
 171 messages and then query all the serialized tags from tag-setters. The
 172 delta tells what has not been serialized.
 173
 174 A different approach would be to query the list of supported tags in
 175 advance. This could be a query (`GST_QUERY_TAG_SUPPORT`). The query
 176 result could be a list of elements and their tags. As a convenience we
 177 could flatten the list of tags for the top-level element (if the query
 178 was sent to a bin) and add that.
 179
 180 ### Tags are per Element
 181
 182 In many cases we want tags per stream. Even metadata standards like
 183 mp4/3gp metadata supports that. Right now `GST_MESSAGE_SRC(tags)` is the
 184 element. We tried changing that to the pad, but that broke applications.
 185 Also we miss the symmetric functionality in `GstTagSetter`. This interface
 186 is usually implemented by
 187 elements.
 188
 189 ### Open bugs
 190
 191 <https://bugzilla.gnome.org/buglist.cgi?query_format=advanced;short_desc=tag;bug_status=UNCONFIRMED;bug_status=NEW;bug_status=ASSIGNED;bug_status=REOPENED;bug_status=NEEDINFO;short_desc_type=allwordssubstr;product=GStreamer>
 192