7 GStreamer makes a clear distinction between two types of metadata, and
8 has support for both types. The first is stream tags, which describe the
9 content of a stream in a non-technical way. Examples include the author
10 of a song, the title of that very same song or the album it is a part
11 of. The other type of metadata is stream-info, which is a somewhat
12 technical description of the properties of a stream. This can include
13 video size, audio samplerate, codecs used and so on. Tags are handled
14 using the GStreamer tagging system. Stream-info can be retrieved from a
15 `GstPad` by getting the current (negotiated) `GstCaps` for that pad.
19 Stream information can most easily be read by reading it from a
20 `GstPad`. This has already been discussed before in [Using capabilities
21 for metadata](manual-pads.md#using-capabilities-for-metadata).
22 Therefore, we will skip it here. Note that this requires access to all
23 pads of which you want stream information.
25 Tag reading is done through a bus in GStreamer, which has been discussed
26 previously in [Bus](manual-bus.md). You can listen for
27 `GST_MESSAGE_TAG` messages and handle them as you wish.
29 Note, however, that the `GST_MESSAGE_TAG` message may be fired multiple
30 times in the pipeline. It is the application's responsibility to put all
31 those tags together and display them to the user in a nice, coherent
32 way. Usually, using `gst_tag_list_merge ()` is a good enough way of
33 doing this; make sure to empty the cache when loading a new song, or
34 after every few minutes when listening to internet radio. Also, make
35 sure you use `GST_TAG_MERGE_PREPEND` as merging mode, so that a new
36 title (which came in later) has a preference over the old one for
39 The following example will extract tags from a file and print them:
43 * gcc -o tags tags.c `pkg-config --cflags --libs gstreamer-1.0` */
47 print_one_tag (const GstTagList * list, const gchar * tag, gpointer user_data)
51 num = gst_tag_list_get_tag_size (list, tag);
52 for (i = 0; i < num; ++i) {
55 /* Note: when looking for specific tags, use the gst_tag_list_get_xyz() API,
56 * we only use the GValue approach here because it is more generic */
57 val = gst_tag_list_get_value_index (list, tag, i);
58 if (G_VALUE_HOLDS_STRING (val)) {
59 g_print ("\t%20s : %s\n", tag, g_value_get_string (val));
60 } else if (G_VALUE_HOLDS_UINT (val)) {
61 g_print ("\t%20s : %u\n", tag, g_value_get_uint (val));
62 } else if (G_VALUE_HOLDS_DOUBLE (val)) {
63 g_print ("\t%20s : %g\n", tag, g_value_get_double (val));
64 } else if (G_VALUE_HOLDS_BOOLEAN (val)) {
65 g_print ("\t%20s : %s\n", tag,
66 (g_value_get_boolean (val)) ? "true" : "false");
67 } else if (GST_VALUE_HOLDS_BUFFER (val)) {
68 GstBuffer *buf = gst_value_get_buffer (val);
69 guint buffer_size = gst_buffer_get_size (buf);
71 g_print ("\t%20s : buffer of size %u\n", tag, buffer_size);
72 } else if (GST_VALUE_HOLDS_DATE_TIME (val)) {
73 GstDateTime *dt = g_value_get_boxed (val);
74 gchar *dt_str = gst_date_time_to_iso8601_string (dt);
76 g_print ("\t%20s : %s\n", tag, dt_str);
79 g_print ("\t%20s : tag of type '%s'\n", tag, G_VALUE_TYPE_NAME (val));
85 on_new_pad (GstElement * dec, GstPad * pad, GstElement * fakesink)
89 sinkpad = gst_element_get_static_pad (fakesink, "sink");
90 if (!gst_pad_is_linked (sinkpad)) {
91 if (gst_pad_link (pad, sinkpad) != GST_PAD_LINK_OK)
92 g_error ("Failed to link pads!");
94 gst_object_unref (sinkpad);
98 main (int argc, char ** argv)
100 GstElement *pipe, *dec, *sink;
104 gst_init (&argc, &argv);
107 g_error ("Usage: %s FILE or URI", argv[0]);
109 if (gst_uri_is_valid (argv[1])) {
110 uri = g_strdup (argv[1]);
112 uri = gst_filename_to_uri (argv[1], NULL);
115 pipe = gst_pipeline_new ("pipeline");
117 dec = gst_element_factory_make ("uridecodebin", NULL);
118 g_object_set (dec, "uri", uri, NULL);
119 gst_bin_add (GST_BIN (pipe), dec);
121 sink = gst_element_factory_make ("fakesink", NULL);
122 gst_bin_add (GST_BIN (pipe), sink);
124 g_signal_connect (dec, "pad-added", G_CALLBACK (on_new_pad), sink);
126 gst_element_set_state (pipe, GST_STATE_PAUSED);
129 GstTagList *tags = NULL;
131 msg = gst_bus_timed_pop_filtered (GST_ELEMENT_BUS (pipe),
133 GST_MESSAGE_ASYNC_DONE | GST_MESSAGE_TAG | GST_MESSAGE_ERROR);
135 if (GST_MESSAGE_TYPE (msg) != GST_MESSAGE_TAG) /* error or async_done */
138 gst_message_parse_tag (msg, &tags);
140 g_print ("Got tags from element %s:\n", GST_OBJECT_NAME (msg->src));
141 gst_tag_list_foreach (tags, print_one_tag, NULL);
143 gst_tag_list_unref (tags);
145 gst_message_unref (msg);
148 if (GST_MESSAGE_TYPE (msg) == GST_MESSAGE_ERROR) {
151 gst_message_parse_error (msg, &err, NULL);
152 g_printerr ("Got error: %s\n", err->message);
156 gst_message_unref (msg);
157 gst_element_set_state (pipe, GST_STATE_NULL);
158 gst_object_unref (pipe);
167 Tag writing is done using the
168 [`GstTagSetter`](http://gstreamer.freedesktop.org/data/doc/gstreamer/stable/gstreamer/html/GstTagSetter.html)
169 interface. All that's required is a tag-set-supporting element in your
170 pipeline. In order to see if any of the elements in your pipeline
171 supports tag writing, you can use the function
172 `gst_bin_iterate_all_by_interface (pipeline,
173 GST_TYPE_TAG_SETTER)`. On the resulting element, usually an encoder or
174 muxer, you can use `gst_tag_setter_merge
175 ()` (with a taglist) or `gst_tag_setter_add
176 ()` (with individual tags) to set tags on it.
178 A nice extra feature in GStreamer tag support is that tags are preserved
179 in pipelines. This means that if you transcode one file containing tags
180 into another media type, and that new media type supports tags too, then
181 the tags will be handled as part of the data stream and be merged into
182 the newly written media file, too.