2 title: Tagging (Metadata and Streaminfo)
5 # Tagging (Metadata and Streaminfo)
9 Tags are pieces of information stored in a stream that are not the
10 content itself, but they rather *describe* the content. Most media
11 container formats support tagging in one way or another. Ogg uses
12 VorbisComment for this, MP3 uses ID3, AVI and WAV use RIFF's INFO list
13 chunk, etc. GStreamer provides a general way for elements to read tags
14 from the stream and expose this to the user. The tags (at least the
15 metadata) will be part of the stream inside the pipeline. The
16 consequence of this is that transcoding of files from one format to
17 another will automatically preserve tags, as long as the input and
18 output format elements both support tagging.
20 Tags are separated in two categories in GStreamer, even though
21 applications won't notice anything of this. The first are called
22 *metadata*, the second are called *streaminfo*. Metadata are tags that
23 describe the non-technical parts of stream content. They can be changed
24 without needing to re-encode the stream completely. Examples are
25 “author”, “title” or “album”. The container format might still need
26 to be re-written for the tags to fit in, though. Streaminfo, on the
27 other hand, are tags that describe the stream contents technically. To
28 change them, the stream needs to be re-encoded. Examples are “codec” or
29 “bitrate”. Note that some container formats (like ID3) store various
30 streaminfo tags as metadata in the file container, which means that they
31 can be changed so that they don't match the content in the file any
32 more. Still, they are called metadata because *technically*, they can be
33 changed without re-encoding the whole stream, even though that makes
34 them invalid. Files with such metadata tags will have the same tag
35 twice: once as metadata, once as streaminfo.
37 There is no special name for tag reading elements in GStreamer. There
38 are specialised elements (e.g. id3demux) that do nothing besides tag
39 reading, but any GStreamer element may extract tags while processing
40 data, and most decoders, demuxers and parsers do.
42 A tag writer is called
43 [`TagSetter`](../../gstreamer/html/GstTagSetter.html). An element
44 supporting both can be used in a tag editor for quick tag changing
45 (note: in-place tag editing is still poorly supported at the time of
46 writing and usually requires tag extraction/stripping and remuxing of
47 the stream with new tags).
49 ## Reading Tags from Streams
51 The basic object for tags is a [`GstTagList
52 `](../../gstreamer/html/GstTagList.html). An element that is reading
53 tags from a stream should create an empty taglist and fill this with
54 individual tags. Empty tag lists can be created with `gst_tag_list_new
55 ()`. Then, the element can fill the list using `gst_tag_list_add ()
56 ` or `gst_tag_list_add_values ()`. Note that elements often read
57 metadata as strings, but the values in the taglist might not necessarily
58 be strings - they need to be of the type the tag was registered as (the
59 API documentation for each predefined tag should contain the type). Be
60 sure to use functions like `gst_value_transform ()` to make sure that
61 your data is of the right type. After data reading, you can send the
62 tags downstream with the TAG event. When the TAG event reaches the sink,
63 it will post the TAG message on the pipeline's GstBus for the
64 application to pick up.
66 We currently require the core to know the GType of tags before they are
67 being used, so all tags must be registered first. You can add new tags
68 to the list of known tags using `gst_tag_register ()`. If you think the
69 tag will be useful in more cases than just your own element, it might be
70 a good idea to add it to `gsttag.c` instead. That's up to you to decide.
71 If you want to do it in your own element, it's easiest to register the
72 tag in one of your class init functions, preferably `_class_init ()`.
77 gst_my_filter_class_init (GstMyFilterClass *klass)
80 gst_tag_register ("my_tag_name", GST_TAG_FLAG_META,
83 _("a tag that is specific to my own element"),
91 ## Writing Tags to Streams
93 Tag writers are the opposite of tag readers. Tag writers only take
94 metadata tags into account, since that's the only type of tags that have
95 to be written into a stream. Tag writers can receive tags in three ways:
96 internal, application and pipeline. Internal tags are tags read by the
97 element itself, which means that the tag writer is - in that case - a
98 tag reader, too. Application tags are tags provided to the element via
99 the TagSetter interface (which is just a layer). Pipeline tags are tags
100 provided to the element from within the pipeline. The element receives
101 such tags via the `GST_EVENT_TAG` event, which means that tags writers
102 should implement an event handler. The tag writer is responsible for
103 combining all these three into one list and writing them to the output
106 The example below will receive tags from both application and pipeline,
107 combine them and write them to the output stream. It implements the tag
108 setter so applications can set tags, and retrieves pipeline tags from
111 Warning, this example is outdated and doesn't work with the 1.0 version
112 of GStreamer anymore.
117 gst_my_filter_get_type (void)
120 static const GInterfaceInfo tag_setter_info = {
126 g_type_add_interface_static (my_filter_type,
133 gst_my_filter_init (GstMyFilter *filter)
143 gst_my_filter_write_tag (const GstTagList *taglist,
144 const gchar *tagname,
147 GstMyFilter *filter = GST_MY_FILTER (data);
149 guint num_values = gst_tag_list_get_tag_size (list, tag_name), n;
153 g_value_init (&to, G_TYPE_STRING);
155 for (n = 0; n < num_values; n++) {
159 from = gst_tag_list_get_value_index (taglist, tagname, n);
160 g_value_transform (from, &to);
162 data = g_strdup_printf ("%s:%s", tagname,
163 g_value_get_string (&to));
164 size = strlen (data);
166 buf = gst_buffer_new_wrapped (data, size);
167 gst_pad_push (filter->srcpad, buf);
174 gst_my_filter_task_func (GstElement *element)
176 GstMyFilter *filter = GST_MY_FILTER (element);
177 GstTagSetter *tagsetter = GST_TAG_SETTER (element);
180 gboolean eos = FALSE;
181 GstTagList *taglist = gst_tag_list_new ();
184 data = gst_pad_pull (filter->sinkpad);
186 /* We're not very much interested in data right now */
187 if (GST_IS_BUFFER (data))
188 gst_buffer_unref (GST_BUFFER (data));
189 event = GST_EVENT (data);
191 switch (GST_EVENT_TYPE (event)) {
193 gst_tag_list_insert (taglist, gst_event_tag_get_list (event),
194 GST_TAG_MERGE_PREPEND);
195 gst_event_unref (event);
199 gst_event_unref (event);
202 gst_pad_event_default (filter->sinkpad, event);
207 /* merge tags with the ones retrieved from the application */
208 if ((gst_tag_setter_get_tag_list (tagsetter)) {
209 gst_tag_list_insert (taglist,
210 gst_tag_setter_get_tag_list (tagsetter),
211 gst_tag_setter_get_tag_merge_mode (tagsetter));
215 gst_tag_list_foreach (taglist, gst_my_filter_write_tag, filter);
218 gst_pad_push (filter->srcpad, gst_event_new (GST_EVENT_EOS));
224 Note that normally, elements would not read the full stream before
225 processing tags. Rather, they would read from each sinkpad until they've
226 received data (since tags usually come in before the first data buffer)