From 8acbecfd60e92bce94537b33e7cd1547f6a27df0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tim-Philipp=20M=C3=BCller?= Date: Sun, 25 May 2008 16:13:38 +0000 Subject: [PATCH] docs/pwg/advanced-tagging.xml: Small docs update, can't be bothered to rewrite the nonsensical examples right now. Original commit message from CVS: * docs/pwg/advanced-tagging.xml: Small docs update, can't be bothered to rewrite the nonsensical examples right now. --- ChangeLog | 6 +++++ docs/pwg/advanced-tagging.xml | 47 +++++++++++++++++++---------------- 2 files changed, 32 insertions(+), 21 deletions(-) diff --git a/ChangeLog b/ChangeLog index a838eeda53..024e04eea9 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,9 @@ +2008-05-25 Tim-Philipp Müller + + * docs/pwg/advanced-tagging.xml: + Small docs update, can't be bothered to rewrite the nonsensical + examples right now. + 2008-05-25 Tim-Philipp Müller * gst/gstevent.h: diff --git a/docs/pwg/advanced-tagging.xml b/docs/pwg/advanced-tagging.xml index 107db7035f..90047e6811 100644 --- a/docs/pwg/advanced-tagging.xml +++ b/docs/pwg/advanced-tagging.xml @@ -1,5 +1,8 @@ Tagging (Metadata and Streaminfo) + + + Overview Tags are pieces of information stored in a stream that are not the content itself, but they rather describe the content. Most @@ -32,19 +35,20 @@ once as streaminfo. - - A tag reading element is called TagGetter in - &GStreamer;. + There is no special name for tag reading elements in &GStreamer;. There are + specialised elements (e.g. id3demux) that do nothing besides tag reading, + but any &GStreamer; element may extract tags while processing data, and + most decoders, demuxers and parsers do. + + A tag writer is called TagSetter. An element supporting both can be used in a tag editor for quick tag - changing. + changing (note: in-place tag editing is still poorly supported at the time + of writing and usually requires tag extraction/stripping and remuxing of + the stream with new tags). + Reading Tags from Streams @@ -54,19 +58,20 @@ . An element that is reading tags from a stream should create an empty taglist and fill this with individual tags. Empty tag lists can be created with gst_tag_list_new (). Then, - the element can fill the list using gst_tag_list_add_values () - . Note that an element probably reads metadata as strings, but - values might not necessarily be strings. Be sure to use + the element can fill the list using gst_tag_list_add () + or gst_tag_list_add_values (). + Note that elements often read metadata as strings, but the + values in the taglist might not necessarily be strings - they need to be + of the type the tag was registered as (the API documentation for each + predefined tag should contain the type). Be sure to use functions like gst_value_transform () to make sure that your data is of the right type. After data reading, the application can be notified of the new taglist by calling - gst_element_found_tags (). The tags should also be - part of the datastream, so they should be pushed over all source pads. - The function gst_event_new_tag () creates an event - from a taglist. This can be pushed over source pads using - gst_pad_push (). Simple elements with only one - source pad can combine all these steps all-in-one by using the function - gst_element_found_tags_for_pad (). + gst_element_found_tags () or + gst_element_found_tags_for_pad () (if they only + refer to a specific sub-stream). These functions will post a tag message + on the pipeline's GstBus for the application to pick up, but also send + tag events downstream, either over all source pad or the pad specified. The following example program will parse a file and parse the data as @@ -79,7 +84,7 @@