diff --git a/docs/random/company/tagging b/docs/random/company/tagging new file mode 100644 index 0000000000..c6a71c0137 --- /dev/null +++ b/docs/random/company/tagging @@ -0,0 +1,104 @@ +Quoting iain : + +> If you could write a small thing about how to use the tagging, it'd be +> appreciated. I think MArlin is going to be using it pretty extensivly, +> and so it'd be nice to get it in there and tested quickly. +> +Ok. A short writeup. + + +Oh! Intro - Jellyman, offspring. Offspring, Jellyman. + +GStreamer manages tags in the form of GstTagList objects. A GstTagList (named +taglist from now on) consists of zero or more different tags (this will be +what I mean when I say tag) where each tag has one or more values attached to +it. A tag is registered via gst_tag_register with it's name, translated name +(glib calls that nick), a translated description, the GType values for this +tag must have and an optional merge function. +GStreamer provides default caps which are registered in gsttag.c. You can look +them up there. + + +You've got serious thrill issues, dude. + +A taglist is primarily thought about as a 1:1 tag:value mapping. Sometimes it +is useful to have multiple values for the same tag however. (Multiple artists +performing a song). If a merge function is provided at tag registration time, +you can attach multiple values to a tag. These values are handled as an +ordered list, so you can access each of them with an index. The merge function +allows to merge all of them back into a single value. +If no merge function is provided, only a single value is kept. + + +Tell me, Dory, do you see anything? - Yeah, I see a light. + +There's a whole lot of API provided to change taglists. see gsttag.h for the +whole glory. Most of that should be self explaining. Foreach functions, number +of values per tag, getting tags and so on. The gst-launch code shows a usage +example. The only thing that might be of interest is the merge mode. If you +merge two tag lists (via _merge or _insert or even when only adding values via +_add_tag) you have to provide a merge mode. The merge mode decides how to +handle the merging of caps. If you merge new_tags into old_tags, the different +merge modes do this: +GST_TAG_MERGE_MODE_REPLACE_ALL: Remove all tags from old_tags, use only +new_tags. +GST_TAG_MERGE_MODE_REPLACE: Remove all tags from old_tags where tags from +new_tags are available. Keep the others. Insert everything from new_tags. +GST_TAG_MERGE_MODE_PREPEND: Prepend values from new_tags to the values from +old_tags. For single value tags when both are set, use the new_tags tag. +GST_TAG_MERGE_MODE_APPEND: Same as GST_TAG_MERGE_MODE_PREPEND with new_tags +and old_tags swapped. +GST_TAG_MERGE_MODE_KEEP: Same as GST_TAG_MERGE_MODE_REPLACE with new_tags and +old_tags swapped. +GST_TAG_MERGE_MODE_KEEP_ALL: Same as GST_TAG_MERGE_MODE_REPLACE_ALL with +new_tags and old_tags swapped. +This allows some powerful usage of taglists. I'll describe further down where +it really makes sense. + + +Now what? + +There are supposed to be two "producers" of taglists. The first are +applications, the second are plugins. (In my tag world domination plans I +simply assumed Rhythmbox would start using taglists internally.) Applications +can easily create and access them with the API shown above. It should even be +reasonably easy to put their values inside gtk objects via foreach loops and +similar. Especially because they're all just GValues internally. +Plugins extract tag lists from the GstBuffer data. They'll have to convert it +to taglists obviously. (If you write plugins, please make sure to use the same +mapping than other plugins that use the same format. Mappings and plugins for +common tagging formats are kept in gst-plugins/gst/tags/* ) Once they have +extracted the taglist, they signal they have found tags via the "found-tag" +signal. After that they create a tag event and send that down the pipeline. +There are convenience functions for this. See code that implements this. + + +Oh, look at me, I'm a flippy little dolphin, let me flip for you! + +There are also supposed to be two "consumers" of taglists. Applications and - +you guessed it - plugins. Applications obviously want to show the tags of the +playing pipeline or store tags for a given file, use them as the basis for +editing or whatever. +Plugins that can set tags implement the GstTagSetter interface. Don't let +yourself be fooled by the fact that this interface is an empty interface. Your +plugin still has to do something. ;) The interface provides a way to attach +tags to elements implementing the interface. Whenever the interface wants to +write tags it has to do the following: +1) Get the tags from the pipeline that you want to write. (This obviously +includes storing tags that came in via tag events.) +2) Merge the user set tags into these tags with the user set merge mode. This +is the place where the merge mode allows all te flexibility you may want: +adding tags, adding values to tags, overwriting all tags or overwriting only +some tags. +3) Write these tags to the buffer. + + +Hey! You guys made me ink! + +I hope this exciting little intro answered some of your questions. If not, ask +more specific questions next time, please. :) + + +Benjamin + +