gstreamer/docs/manual/advanced-metadata.xml

<chapter id="chapter-metadata">
  <title>Metadata</title>

  <para>
    &GStreamer; makes a clear distinction between two types of metadata, and
    has support for both types. The first is stream tags, which describe the
    content of a stream in a non-technical way. Examples include the author
    of a song, the title of that very same song or the album it is a part of.
    The other type of metadata is stream-info, which is a somewhat technical
    description of the properties of a stream. This can include video size,
    audio samplerate, codecs used and so on. Tags are handled using the
    &GStreamer; tagging system. Stream-info can be retrieved from a
    <classname>GstPad</classname>.
  </para>

  <sect1 id="section-streaminfo">
    <title>Stream information</title>

    <para>
      Stream information can most easily be read by reading them from a
      <classname>GstPad</classname>. This has already been discussed before
      in <xref linkend="section-caps-metadata"/>. Therefore, we will skip
      it here.
    </para>
  </sect1>

  <sect1 id="section-tags-read">
    <title>Tag reading</title>

    <para>
      Tag reading is remarkably simple in &GStreamer; Every element supports
      the <quote>found-tag</quote> signal, which will be fired each the time
      the element reads tags from the stream. A <classname>GstBin</classname>
      will conveniently forward tags found by its childs. Therefore, in most
      applications, you will only need to connect to the
      <quote>found-tag</quote> signal on the top-most bin in your pipeline,
      and you will automatically retrieve all tags from the stream.
    </para>
    <para>
      Note, however, that the <quote>found-tag</quote> might be fired
      multiple times and by multiple elements in the pipeline. It is the
      application's responsibility to put all those tags together and
      display them to the user in a nice, coherent way.
    </para>
  </sect1>

  <sect1 id="section-tags-write">
    <title>Tag writing</title>

    <para>
      WRITEME
    </para>
  </sect1>
</chapter>