docs/random/company/tagging - mtk-gstreamer - Git at Google

 Quoting iain <iain@prettypeople.org>:

 > 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
	Quoting iain <iain@prettypeople.org>:

	> 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