| 1 |
Quoting iain <[email protected]>: |
| 2 |
|
| 3 |
> If you could write a small thing about how to use the tagging, it'd be |
| 4 |
> appreciated. I think MArlin is going to be using it pretty extensively, |
| 5 |
> and so it'd be nice to get it in there and tested quickly. |
| 6 |
> |
| 7 |
Ok. A short writeup. |
| 8 |
|
| 9 |
|
| 10 |
Oh! Intro - Jellyman, offspring. Offspring, Jellyman. |
| 11 |
|
| 12 |
GStreamer manages tags in the form of GstTagList objects. A GstTagList (named |
| 13 |
taglist from now on) consists of zero or more different tags (this will be |
| 14 |
what I mean when I say tag) where each tag has one or more values attached to |
| 15 |
it. A tag is registered via gst_tag_register with it's name, translated name |
| 16 |
(glib calls that nick), a translated description, the GType values for this |
| 17 |
tag must have and an optional merge function. |
| 18 |
GStreamer provides default caps which are registered in gsttag.c. You can look |
| 19 |
them up there. |
| 20 |
|
| 21 |
|
| 22 |
You've got serious thrill issues, dude. |
| 23 |
|
| 24 |
A taglist is primarily thought about as a 1:1 tag:value mapping. Sometimes it |
| 25 |
is useful to have multiple values for the same tag however. (Multiple artists |
| 26 |
performing a song). If a merge function is provided at tag registration time, |
| 27 |
you can attach multiple values to a tag. These values are handled as an |
| 28 |
ordered list, so you can access each of them with an index. The merge function |
| 29 |
allows to merge all of them back into a single value. |
| 30 |
If no merge function is provided, only a single value is kept. |
| 31 |
|
| 32 |
|
| 33 |
Tell me, Dory, do you see anything? - Yeah, I see a light. |
| 34 |
|
| 35 |
There's a whole lot of API provided to change taglists. see gsttag.h for the |
| 36 |
whole glory. Most of that should be self explaining. Foreach functions, number |
| 37 |
of values per tag, getting tags and so on. The gst-launch code shows a usage |
| 38 |
example. The only thing that might be of interest is the merge mode. If you |
| 39 |
merge two tag lists (via _merge or _insert or even when only adding values via |
| 40 |
_add_tag) you have to provide a merge mode. The merge mode decides how to |
| 41 |
handle the merging of caps. If you merge new_tags into old_tags, the different |
| 42 |
merge modes do this: |
| 43 |
GST_TAG_MERGE_MODE_REPLACE_ALL: Remove all tags from old_tags, use only |
| 44 |
new_tags. |
| 45 |
GST_TAG_MERGE_MODE_REPLACE: Remove all tags from old_tags where tags from |
| 46 |
new_tags are available. Keep the others. Insert everything from new_tags. |
| 47 |
GST_TAG_MERGE_MODE_PREPEND: Prepend values from new_tags to the values from |
| 48 |
old_tags. For single value tags when both are set, use the new_tags tag. |
| 49 |
GST_TAG_MERGE_MODE_APPEND: Same as GST_TAG_MERGE_MODE_PREPEND with new_tags |
| 50 |
and old_tags swapped. |
| 51 |
GST_TAG_MERGE_MODE_KEEP: Same as GST_TAG_MERGE_MODE_REPLACE with new_tags and |
| 52 |
old_tags swapped. |
| 53 |
GST_TAG_MERGE_MODE_KEEP_ALL: Same as GST_TAG_MERGE_MODE_REPLACE_ALL with |
| 54 |
new_tags and old_tags swapped. |
| 55 |
This allows some powerful usage of taglists. I'll describe further down where |
| 56 |
it really makes sense. |
| 57 |
|
| 58 |
|
| 59 |
Now what? |
| 60 |
|
| 61 |
There are supposed to be two "producers" of taglists. The first are |
| 62 |
applications, the second are plugins. (In my tag world domination plans I |
| 63 |
simply assumed Rhythmbox would start using taglists internally.) Applications |
| 64 |
can easily create and access them with the API shown above. It should even be |
| 65 |
reasonably easy to put their values inside gtk objects via foreach loops and |
| 66 |
similar. Especially because they're all just GValues internally. |
| 67 |
Plugins extract tag lists from the GstBuffer data. They'll have to convert it |
| 68 |
to taglists obviously. (If you write plugins, please make sure to use the same |
| 69 |
mapping than other plugins that use the same format. Mappings and plugins for |
| 70 |
common tagging formats are kept in gst-plugins/gst/tags/* ) Once they have |
| 71 |
extracted the taglist, they signal they have found tags via the "found-tag" |
| 72 |
signal. After that they create a tag event and send that down the pipeline. |
| 73 |
There are convenience functions for this. See code that implements this. |
| 74 |
|
| 75 |
|
| 76 |
Oh, look at me, I'm a flippy little dolphin, let me flip for you! |
| 77 |
|
| 78 |
There are also supposed to be two "consumers" of taglists. Applications and - |
| 79 |
you guessed it - plugins. Applications obviously want to show the tags of the |
| 80 |
playing pipeline or store tags for a given file, use them as the basis for |
| 81 |
editing or whatever. |
| 82 |
Plugins that can set tags implement the GstTagSetter interface. Don't let |
| 83 |
yourself be fooled by the fact that this interface is an empty interface. Your |
| 84 |
plugin still has to do something. ;) The interface provides a way to attach |
| 85 |
tags to elements implementing the interface. Whenever the interface wants to |
| 86 |
write tags it has to do the following: |
| 87 |
1) Get the tags from the pipeline that you want to write. (This obviously |
| 88 |
includes storing tags that came in via tag events.) |
| 89 |
2) Merge the user set tags into these tags with the user set merge mode. This |
| 90 |
is the place where the merge mode allows all te flexibility you may want: |
| 91 |
adding tags, adding values to tags, overwriting all tags or overwriting only |
| 92 |
some tags. |
| 93 |
3) Write these tags to the buffer. |
| 94 |
|
| 95 |
|
| 96 |
Hey! You guys made me ink! |
| 97 |
|
| 98 |
I hope this exciting little intro answered some of your questions. If not, ask |
| 99 |
more specific questions next time, please. :) |
| 100 |
|
| 101 |
|
| 102 |
Benjamin |
| 103 |
|
| 104 |
|