Debian Codegraph @

docs/random/company/tagging

raw
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