1 /* GStreamer
2 * Copyright (C) 2003 Benjamin Otte <in7y118@public.uni-hamburg.de>
3 *
4 * gsttaglist.h: Header for tag support
5 *
6 * This library is free software; you can redistribute it and/or
7 * modify it under the terms of the GNU Library General Public
8 * License as published by the Free Software Foundation; either
9 * version 2 of the License, or (at your option) any later version.
10 *
11 * This library is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 * Library General Public License for more details.
15 *
16 * You should have received a copy of the GNU Library General Public
17 * License along with this library; if not, write to the
18 * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
19 * Boston, MA 02110-1301, USA.
20 */
21
22
23 #ifndef __GST_TAGLIST_H__
24 #define __GST_TAGLIST_H__
25
26 #include <gst/gstdatetime.h>
27 #include <gst/gstsample.h>
28 #include <gst/gstbuffer.h>
29 #include <gst/glib-compat.h>
30
31 G_BEGIN_DECLS
32
33 /**
34 * GstTagMergeMode:
35 * @GST_TAG_MERGE_UNDEFINED: undefined merge mode
36 * @GST_TAG_MERGE_REPLACE_ALL: replace all tags (clear list and append)
37 * @GST_TAG_MERGE_REPLACE: replace tags
38 * @GST_TAG_MERGE_APPEND: append tags
39 * @GST_TAG_MERGE_PREPEND: prepend tags
40 * @GST_TAG_MERGE_KEEP: keep existing tags
41 * @GST_TAG_MERGE_KEEP_ALL: keep all existing tags
42 * @GST_TAG_MERGE_COUNT: the number of merge modes
43 *
44 * The different tag merging modes are basically replace, overwrite and append,
45 * but they can be seen from two directions. Given two taglists: (A) the tags
46 * already in the element and (B) the ones that are supplied to the element (
47 * e.g. via gst_tag_setter_merge_tags() / gst_tag_setter_add_tags() or a
48 * %GST_EVENT_TAG), how are these tags merged?
49 * In the table below this is shown for the cases that a tag exists in the list
50 * (A) or does not exists (!A) and combinations thereof.
51 *
52 * <table frame="all" colsep="1" rowsep="1">
53 * <title>merge mode</title>
54 * <tgroup cols='5' align='left'>
55 * <thead>
56 * <row>
57 * <entry>merge mode</entry>
58 * <entry>A + B</entry>
59 * <entry>A + !B</entry>
60 * <entry>!A + B</entry>
61 * <entry>!A + !B</entry>
62 * </row>
63 * </thead>
64 * <tbody>
65 * <row>
66 * <entry>REPLACE_ALL</entry>
67 * <entry>B</entry>
68 * <entry>-</entry>
69 * <entry>B</entry>
70 * <entry>-</entry>
71 * </row>
72 * <row>
73 * <entry>REPLACE</entry>
74 * <entry>B</entry>
75 * <entry>A</entry>
76 * <entry>B</entry>
77 * <entry>-</entry>
78 * </row>
79 * <row>
80 * <entry>APPEND</entry>
81 * <entry>A, B</entry>
82 * <entry>A</entry>
83 * <entry>B</entry>
84 * <entry>-</entry>
85 * </row>
86 * <row>
87 * <entry>PREPEND</entry>
88 * <entry>B, A</entry>
89 * <entry>A</entry>
90 * <entry>B</entry>
91 * <entry>-</entry>
92 * </row>
93 * <row>
94 * <entry>KEEP</entry>
95 * <entry>A</entry>
96 * <entry>A</entry>
97 * <entry>B</entry>
98 * <entry>-</entry>
99 * </row>
100 * <row>
101 * <entry>KEEP_ALL</entry>
102 * <entry>A</entry>
103 * <entry>A</entry>
104 * <entry>-</entry>
105 * <entry>-</entry>
106 * </row>
107 * </tbody>
108 * </tgroup>
109 * </table>
110 */
111 typedef enum {
112 GST_TAG_MERGE_UNDEFINED,
113 GST_TAG_MERGE_REPLACE_ALL,
114 GST_TAG_MERGE_REPLACE,
115 GST_TAG_MERGE_APPEND,
116 GST_TAG_MERGE_PREPEND,
117 GST_TAG_MERGE_KEEP,
118 GST_TAG_MERGE_KEEP_ALL,
119 /* add more */
120 GST_TAG_MERGE_COUNT
121 } GstTagMergeMode;
122
123 #define GST_TAG_MODE_IS_VALID(mode) (((mode) > GST_TAG_MERGE_UNDEFINED) && ((mode) < GST_TAG_MERGE_COUNT))
124
125 /**
126 * GstTagFlag:
127 * @GST_TAG_FLAG_UNDEFINED: undefined flag
128 * @GST_TAG_FLAG_META: tag is meta data
129 * @GST_TAG_FLAG_ENCODED: tag is encoded
130 * @GST_TAG_FLAG_DECODED: tag is decoded
131 * @GST_TAG_FLAG_COUNT: number of tag flags
132 *
133 * Extra tag flags used when registering tags.
134 */
135 /* FIXME: these are not really flags .. */
136 typedef enum {
137 GST_TAG_FLAG_UNDEFINED,
138 GST_TAG_FLAG_META,
139 GST_TAG_FLAG_ENCODED,
140 GST_TAG_FLAG_DECODED,
141 GST_TAG_FLAG_COUNT
142 } GstTagFlag;
143
144 #define GST_TAG_FLAG_IS_VALID(flag) (((flag) > GST_TAG_FLAG_UNDEFINED) && ((flag) < GST_TAG_FLAG_COUNT))
145
146 /**
147 * GstTagList:
148 * @mini_object: the parent type
149 *
150 * Object describing tags / metadata.
151 */
152 typedef struct _GstTagList GstTagList;
153 struct _GstTagList {
154 GstMiniObject mini_object;
155 };
156
157 GST_API GType _gst_tag_list_type;
158
159 #define GST_TAG_LIST(x) ((GstTagList *) (x))
160 #define GST_TYPE_TAG_LIST (_gst_tag_list_type)
161 #define GST_IS_TAG_LIST(obj) (GST_IS_MINI_OBJECT_TYPE((obj), GST_TYPE_TAG_LIST))
162
163 /**
164 * GstTagForeachFunc:
165 * @list: the #GstTagList
166 * @tag: a name of a tag in @list
167 * @user_data: user data
168 *
169 * A function that will be called in gst_tag_list_foreach(). The function may
170 * not modify the tag list.
171 */
172 typedef void (*GstTagForeachFunc) (const GstTagList * list,
173 const gchar * tag,
174 gpointer user_data);
175
176 /**
177 * GstTagMergeFunc:
178 * @dest: the destination #GValue
179 * @src: the source #GValue
180 *
181 * A function for merging multiple values of a tag used when registering
182 * tags.
183 */
184 typedef void (* GstTagMergeFunc) (GValue *dest, const GValue *src);
185
186 GST_API
187 GType gst_tag_list_get_type (void);
188
189 /* tag registration */
190
191 GST_API
192 void gst_tag_register (const gchar * name,
193 GstTagFlag flag,
194 GType type,
195 const gchar * nick,
196 const gchar * blurb,
197 GstTagMergeFunc func);
198 GST_API
199 void gst_tag_register_static (const gchar * name,
200 GstTagFlag flag,
201 GType type,
202 const gchar * nick,
203 const gchar * blurb,
204 GstTagMergeFunc func);
205
206 /* some default merging functions */
207
208 GST_API
209 void gst_tag_merge_use_first (GValue * dest, const GValue * src);
210
211 GST_API
212 void gst_tag_merge_strings_with_comma (GValue * dest, const GValue * src);
213
214 /* basic tag support */
215
216 GST_API
217 gboolean gst_tag_exists (const gchar * tag);
218
219 GST_API
220 GType gst_tag_get_type (const gchar * tag);
221
222 GST_API
223 const gchar * gst_tag_get_nick (const gchar * tag);
224
225 GST_API
226 const gchar * gst_tag_get_description (const gchar * tag);
227
228 GST_API
229 GstTagFlag gst_tag_get_flag (const gchar * tag);
230
231 GST_API
232 gboolean gst_tag_is_fixed (const gchar * tag);
233
234 /* tag lists */
235
236 /**
237 * GstTagScope:
238 * @GST_TAG_SCOPE_STREAM: tags specific to this single stream
239 * @GST_TAG_SCOPE_GLOBAL: global tags for the complete medium
240 *
241 * GstTagScope specifies if a taglist applies to the complete
242 * medium or only to one single stream.
243 */
244 typedef enum {
245 GST_TAG_SCOPE_STREAM,
246 GST_TAG_SCOPE_GLOBAL
247 } GstTagScope;
248
249 GST_API
250 GstTagList * gst_tag_list_new_empty (void) G_GNUC_MALLOC;
251
252 GST_API
253 GstTagList * gst_tag_list_new (const gchar * tag, ...) G_GNUC_MALLOC;
254
255 GST_API
256 GstTagList * gst_tag_list_new_valist (va_list var_args) G_GNUC_MALLOC;
257
258 GST_API
259 void gst_tag_list_set_scope (GstTagList * list, GstTagScope scope);
260
261 GST_API
262 GstTagScope gst_tag_list_get_scope (const GstTagList * list);
263
264 GST_API
265 gchar * gst_tag_list_to_string (const GstTagList * list) G_GNUC_MALLOC;
266
267 GST_API
268 GstTagList * gst_tag_list_new_from_string (const gchar * str) G_GNUC_MALLOC;
269
270 GST_API
271 gint gst_tag_list_n_tags (const GstTagList * list);
272
273 GST_API
274 const gchar* gst_tag_list_nth_tag_name (const GstTagList * list, guint index);
275
276 GST_API
277 gboolean gst_tag_list_is_empty (const GstTagList * list);
278
279 GST_API
280 gboolean gst_tag_list_is_equal (const GstTagList * list1,
281 const GstTagList * list2);
282 GST_API
283 void gst_tag_list_insert (GstTagList * into,
284 const GstTagList * from,
285 GstTagMergeMode mode);
286 GST_API
287 GstTagList * gst_tag_list_merge (const GstTagList * list1,
288 const GstTagList * list2,
289 GstTagMergeMode mode) G_GNUC_MALLOC;
290 GST_API
291 guint gst_tag_list_get_tag_size (const GstTagList * list,
292 const gchar * tag);
293 GST_API
294 void gst_tag_list_add (GstTagList * list,
295 GstTagMergeMode mode,
296 const gchar * tag,
297 ...) G_GNUC_NULL_TERMINATED;
298 GST_API
299 void gst_tag_list_add_values (GstTagList * list,
300 GstTagMergeMode mode,
301 const gchar * tag,
302 ...) G_GNUC_NULL_TERMINATED;
303 GST_API
304 void gst_tag_list_add_valist (GstTagList * list,
305 GstTagMergeMode mode,
306 const gchar * tag,
307 va_list var_args);
308 GST_API
309 void gst_tag_list_add_valist_values (GstTagList * list,
310 GstTagMergeMode mode,
311 const gchar * tag,
312 va_list var_args);
313 GST_API
314 void gst_tag_list_add_value (GstTagList * list,
315 GstTagMergeMode mode,
316 const gchar * tag,
317 const GValue * value);
318 GST_API
319 void gst_tag_list_remove_tag (GstTagList * list,
320 const gchar * tag);
321 GST_API
322 void gst_tag_list_foreach (const GstTagList * list,
323 GstTagForeachFunc func,
324 gpointer user_data);
325 GST_API
326 const GValue *
327 gst_tag_list_get_value_index (const GstTagList * list,
328 const gchar * tag,
329 guint index);
330 GST_API
331 gboolean gst_tag_list_copy_value (GValue * dest,
332 const GstTagList * list,
333 const gchar * tag);
334
335 /* simplifications (FIXME: do we want them?) */
336
337 GST_API
338 gboolean gst_tag_list_get_boolean (const GstTagList * list,
339 const gchar * tag,
340 gboolean * value);
341 GST_API
342 gboolean gst_tag_list_get_boolean_index (const GstTagList * list,
343 const gchar * tag,
344 guint index,
345 gboolean * value);
346 GST_API
347 gboolean gst_tag_list_get_int (const GstTagList * list,
348 const gchar * tag,
349 gint * value);
350 GST_API
351 gboolean gst_tag_list_get_int_index (const GstTagList * list,
352 const gchar * tag,
353 guint index,
354 gint * value);
355 GST_API
356 gboolean gst_tag_list_get_uint (const GstTagList * list,
357 const gchar * tag,
358 guint * value);
359 GST_API
360 gboolean gst_tag_list_get_uint_index (const GstTagList * list,
361 const gchar * tag,
362 guint index,
363 guint * value);
364 GST_API
365 gboolean gst_tag_list_get_int64 (const GstTagList * list,
366 const gchar * tag,
367 gint64 * value);
368 GST_API
369 gboolean gst_tag_list_get_int64_index (const GstTagList * list,
370 const gchar * tag,
371 guint index,
372 gint64 * value);
373 GST_API
374 gboolean gst_tag_list_get_uint64 (const GstTagList * list,
375 const gchar * tag,
376 guint64 * value);
377 GST_API
378 gboolean gst_tag_list_get_uint64_index (const GstTagList * list,
379 const gchar * tag,
380 guint index,
381 guint64 * value);
382 GST_API
383 gboolean gst_tag_list_get_float (const GstTagList * list,
384 const gchar * tag,
385 gfloat * value);
386 GST_API
387 gboolean gst_tag_list_get_float_index (const GstTagList * list,
388 const gchar * tag,
389 guint index,
390 gfloat * value);
391 GST_API
392 gboolean gst_tag_list_get_double (const GstTagList * list,
393 const gchar * tag,
394 gdouble * value);
395 GST_API
396 gboolean gst_tag_list_get_double_index (const GstTagList * list,
397 const gchar * tag,
398 guint index,
399 gdouble * value);
400 GST_API
401 gboolean gst_tag_list_get_string (const GstTagList * list,
402 const gchar * tag,
403 gchar ** value);
404 GST_API
405 gboolean gst_tag_list_get_string_index (const GstTagList * list,
406 const gchar * tag,
407 guint index,
408 gchar ** value);
409 GST_API
410 gboolean gst_tag_list_peek_string_index (const GstTagList * list,
411 const gchar * tag,
412 guint index,
413 const gchar ** value);
414 GST_API
415 gboolean gst_tag_list_get_pointer (const GstTagList * list,
416 const gchar * tag,
417 gpointer * value);
418 GST_API
419 gboolean gst_tag_list_get_pointer_index (const GstTagList * list,
420 const gchar * tag,
421 guint index,
422 gpointer * value);
423 GST_API
424 gboolean gst_tag_list_get_date (const GstTagList * list,
425 const gchar * tag,
426 GDate ** value);
427 GST_API
428 gboolean gst_tag_list_get_date_index (const GstTagList * list,
429 const gchar * tag,
430 guint index,
431 GDate ** value);
432 GST_API
433 gboolean gst_tag_list_get_date_time (const GstTagList * list,
434 const gchar * tag,
435 GstDateTime ** value);
436 GST_API
437 gboolean gst_tag_list_get_date_time_index (const GstTagList * list,
438 const gchar * tag,
439 guint index,
440 GstDateTime ** value);
441 GST_API
442 gboolean gst_tag_list_get_sample (const GstTagList * list,
443 const gchar * tag,
444 GstSample ** sample);
445 GST_API
446 gboolean gst_tag_list_get_sample_index (const GstTagList * list,
447 const gchar * tag,
448 guint index,
449 GstSample ** sample);
450
451 /* refcounting */
452 /**
453 * gst_tag_list_ref:
454 * @taglist: the #GstTagList to reference
455 *
456 * Add a reference to a #GstTagList mini object.
457 *
458 * From this point on, until the caller calls gst_tag_list_unref() or
459 * gst_tag_list_make_writable(), it is guaranteed that the taglist object will
460 * not change. To use a #GstTagList object, you must always have a refcount on
461 * it -- either the one made implicitly by e.g. gst_tag_list_new(), or via
462 * taking one explicitly with this function.
463 *
464 * Returns: the same #GstTagList mini object.
465 */
466 static inline GstTagList *
gst_tag_list_ref(GstTagList * taglist)467 gst_tag_list_ref (GstTagList * taglist)
468 {
469 return (GstTagList *) gst_mini_object_ref (GST_MINI_OBJECT_CAST (taglist));
470 }
471
472 /**
473 * gst_tag_list_unref:
474 * @taglist: a #GstTagList.
475 *
476 * Unref a #GstTagList, and and free all its memory when the refcount reaches 0.
477 */
478 static inline void
gst_tag_list_unref(GstTagList * taglist)479 gst_tag_list_unref (GstTagList * taglist)
480 {
481 gst_mini_object_unref (GST_MINI_OBJECT_CAST (taglist));
482 }
483
484 /**
485 * gst_clear_tag_list: (skip)
486 * @taglist_ptr: a pointer to a #GstTagList reference
487 *
488 * Clears a reference to a #GstTagList.
489 *
490 * @taglist_ptr must not be %NULL.
491 *
492 * If the reference is %NULL then this function does nothing. Otherwise, the
493 * reference count of the taglist is decreased and the pointer is set to %NULL.
494 *
495 * Since: 1.16
496 */
497 static inline void
gst_clear_tag_list(GstTagList ** taglist_ptr)498 gst_clear_tag_list (GstTagList ** taglist_ptr)
499 {
500 gst_clear_mini_object ((GstMiniObject **) taglist_ptr);
501 }
502
503 /**
504 * gst_tag_list_copy:
505 * @taglist: a #GstTagList.
506 *
507 * Creates a new #GstTagList as a copy of the old @taglist. The new taglist
508 * will have a refcount of 1, owned by the caller, and will be writable as
509 * a result.
510 *
511 * Note that this function is the semantic equivalent of a gst_tag_list_ref()
512 * followed by a gst_tag_list_make_writable(). If you only want to hold on to a
513 * reference to the data, you should use gst_tag_list_ref().
514 *
515 * When you are finished with the taglist, call gst_tag_list_unref() on it.
516 *
517 * Returns: the new #GstTagList
518 */
519 static inline GstTagList *
gst_tag_list_copy(const GstTagList * taglist)520 gst_tag_list_copy (const GstTagList * taglist)
521 {
522 return GST_TAG_LIST (gst_mini_object_copy (GST_MINI_OBJECT_CAST (taglist)));
523 }
524
525 /**
526 * gst_tag_list_replace:
527 * @old_taglist: (inout) (transfer full) (nullable): pointer to a pointer to a
528 * #GstTagList to be replaced.
529 * @new_taglist: (transfer none) (allow-none): pointer to a #GstTagList that
530 * will replace the tag list pointed to by @old_taglist.
531 *
532 * Modifies a pointer to a #GstTagList to point to a different #GstTagList. The
533 * modification is done atomically (so this is useful for ensuring thread
534 * safety in some cases), and the reference counts are updated appropriately
535 * (the old tag list is unreffed, the new is reffed).
536 *
537 * Either @new_taglist or the #GstTagList pointed to by @old_taglist may be
538 * %NULL.
539 *
540 * Returns: %TRUE if @new_taglist was different from @old_taglist
541 *
542 * Since: 1.16
543 */
544 static inline gboolean
gst_tag_list_replace(GstTagList ** old_taglist,GstTagList * new_taglist)545 gst_tag_list_replace (GstTagList **old_taglist, GstTagList *new_taglist)
546 {
547 return gst_mini_object_replace ((GstMiniObject **) old_taglist,
548 (GstMiniObject *) new_taglist);
549 }
550
551 /**
552 * gst_tag_list_take:
553 * @old_taglist: (inout) (transfer full): pointer to a pointer to a #GstTagList
554 * to be replaced.
555 * @new_taglist: (transfer full) (allow-none): pointer to a #GstTagList that
556 * will replace the taglist pointed to by @old_taglist.
557 *
558 * Modifies a pointer to a #GstTagList to point to a different #GstTagList.
559 * This function is similar to gst_tag_list_replace() except that it takes
560 * ownership of @new_taglist.
561 *
562 * Returns: %TRUE if @new_taglist was different from @old_taglist
563 *
564 * Since: 1.16
565 */
566 static inline gboolean
gst_tag_list_take(GstTagList ** old_taglist,GstTagList * new_taglist)567 gst_tag_list_take (GstTagList **old_taglist, GstTagList *new_taglist)
568 {
569 return gst_mini_object_take ((GstMiniObject **) old_taglist,
570 (GstMiniObject *) new_taglist);
571 }
572
573 /**
574 * gst_tag_list_is_writable:
575 * @taglist: a #GstTagList
576 *
577 * Tests if you can safely modify @taglist. It is only safe to modify taglist
578 * when there is only one owner of the taglist - ie, the refcount is 1.
579 */
580 #define gst_tag_list_is_writable(taglist) gst_mini_object_is_writable (GST_MINI_OBJECT_CAST (taglist))
581
582 /**
583 * gst_tag_list_make_writable:
584 * @taglist: (transfer full): a #GstTagList
585 *
586 * Returns a writable copy of @taglist.
587 *
588 * If there is only one reference count on @taglist, the caller must be the
589 * owner, and so this function will return the taglist object unchanged. If on
590 * the other hand there is more than one reference on the object, a new taglist
591 * object will be returned (which will be a copy of @taglist). The caller's
592 * reference on @taglist will be removed, and instead the caller will own a
593 * reference to the returned object.
594 *
595 * In short, this function unrefs the taglist in the argument and refs the
596 * taglist that it returns. Don't access the argument after calling this
597 * function. See also: gst_tag_list_ref().
598 *
599 * Returns: (transfer full): a writable taglist which may or may not be the
600 * same as @taglist
601 */
602 #define gst_tag_list_make_writable(taglist) GST_TAG_LIST (gst_mini_object_make_writable (GST_MINI_OBJECT_CAST (taglist)))
603
604 /* GStreamer core tags */
605 /**
606 * GST_TAG_TITLE:
607 *
608 * commonly used title (string)
609 *
610 * The title as it should be displayed, e.g. 'The Doll House'
611 */
612 #define GST_TAG_TITLE "title"
613 /**
614 * GST_TAG_TITLE_SORTNAME:
615 *
616 * commonly used title, as used for sorting (string)
617 *
618 * The title as it should be sorted, e.g. 'Doll House, The'
619 */
620 #define GST_TAG_TITLE_SORTNAME "title-sortname"
621 /**
622 * GST_TAG_ARTIST:
623 *
624 * person(s) responsible for the recording (string)
625 *
626 * The artist name as it should be displayed, e.g. 'Jimi Hendrix' or
627 * 'The Guitar Heroes'
628 */
629 #define GST_TAG_ARTIST "artist"
630 /**
631 * GST_TAG_ARTIST_SORTNAME:
632 *
633 * person(s) responsible for the recording, as used for sorting (string)
634 *
635 * The artist name as it should be sorted, e.g. 'Hendrix, Jimi' or
636 * 'Guitar Heroes, The'
637 */
638 #define GST_TAG_ARTIST_SORTNAME "artist-sortname"
639 /**
640 * GST_TAG_ALBUM:
641 *
642 * album containing this data (string)
643 *
644 * The album name as it should be displayed, e.g. 'The Jazz Guitar'
645 */
646 #define GST_TAG_ALBUM "album"
647 /**
648 * GST_TAG_ALBUM_SORTNAME:
649 *
650 * album containing this data, as used for sorting (string)
651 *
652 * The album name as it should be sorted, e.g. 'Jazz Guitar, The'
653 */
654 #define GST_TAG_ALBUM_SORTNAME "album-sortname"
655 /**
656 * GST_TAG_ALBUM_ARTIST:
657 *
658 * The artist of the entire album, as it should be displayed.
659 */
660 #define GST_TAG_ALBUM_ARTIST "album-artist"
661 /**
662 * GST_TAG_ALBUM_ARTIST_SORTNAME:
663 *
664 * The artist of the entire album, as it should be sorted.
665 */
666 #define GST_TAG_ALBUM_ARTIST_SORTNAME "album-artist-sortname"
667 /**
668 * GST_TAG_COMPOSER:
669 *
670 * person(s) who composed the recording (string)
671 */
672 #define GST_TAG_COMPOSER "composer"
673 /**
674 * GST_TAG_CONDUCTOR:
675 *
676 * conductor/performer refinement (string)
677 *
678 * Since: 1.8
679 */
680 #define GST_TAG_CONDUCTOR "conductor"
681 /**
682 * GST_TAG_DATE:
683 *
684 * date the data was created (#GDate structure)
685 */
686 #define GST_TAG_DATE "date"
687 /**
688 * GST_TAG_DATE_TIME:
689 *
690 * date and time the data was created (#GstDateTime structure)
691 */
692 #define GST_TAG_DATE_TIME "datetime"
693 /**
694 * GST_TAG_GENRE:
695 *
696 * genre this data belongs to (string)
697 */
698 #define GST_TAG_GENRE "genre"
699 /**
700 * GST_TAG_COMMENT:
701 *
702 * free text commenting the data (string)
703 */
704 #define GST_TAG_COMMENT "comment"
705 /**
706 * GST_TAG_EXTENDED_COMMENT:
707 *
708 * key/value text commenting the data (string)
709 *
710 * Must be in the form of 'key=comment' or
711 * 'key[lc]=comment' where 'lc' is an ISO-639
712 * language code.
713 *
714 * This tag is used for unknown Vorbis comment tags,
715 * unknown APE tags and certain ID3v2 comment fields.
716 */
717 #define GST_TAG_EXTENDED_COMMENT "extended-comment"
718 /**
719 * GST_TAG_TRACK_NUMBER:
720 *
721 * track number inside a collection (unsigned integer)
722 */
723 #define GST_TAG_TRACK_NUMBER "track-number"
724 /**
725 * GST_TAG_TRACK_COUNT:
726 *
727 * count of tracks inside collection this track belongs to (unsigned integer)
728 */
729 #define GST_TAG_TRACK_COUNT "track-count"
730 /**
731 * GST_TAG_ALBUM_VOLUME_NUMBER:
732 *
733 * disc number inside a collection (unsigned integer)
734 */
735 #define GST_TAG_ALBUM_VOLUME_NUMBER "album-disc-number"
736 /**
737 * GST_TAG_ALBUM_VOLUME_COUNT:
738 *
739 * count of discs inside collection this disc belongs to (unsigned integer)
740 */
741 #define GST_TAG_ALBUM_VOLUME_COUNT "album-disc-count"
742 /**
743 * GST_TAG_LOCATION:
744 *
745 * Origin of media as a URI (location, where the original of the file or stream
746 * is hosted) (string)
747 */
748 #define GST_TAG_LOCATION "location"
749 /**
750 * GST_TAG_HOMEPAGE:
751 *
752 * Homepage for this media (i.e. artist or movie homepage) (string)
753 */
754 #define GST_TAG_HOMEPAGE "homepage"
755 /**
756 * GST_TAG_DESCRIPTION:
757 *
758 * short text describing the content of the data (string)
759 */
760 #define GST_TAG_DESCRIPTION "description"
761 /**
762 * GST_TAG_VERSION:
763 *
764 * version of this data (string)
765 */
766 #define GST_TAG_VERSION "version"
767 /**
768 * GST_TAG_ISRC:
769 *
770 * International Standard Recording Code - see http://www.ifpi.org/isrc/ (string)
771 */
772 #define GST_TAG_ISRC "isrc"
773 /**
774 * GST_TAG_ORGANIZATION:
775 *
776 * organization (string)
777 */
778 #define GST_TAG_ORGANIZATION "organization"
779 /**
780 * GST_TAG_COPYRIGHT:
781 *
782 * copyright notice of the data (string)
783 */
784 #define GST_TAG_COPYRIGHT "copyright"
785 /**
786 * GST_TAG_COPYRIGHT_URI:
787 *
788 * URI to location where copyright details can be found (string)
789 */
790 #define GST_TAG_COPYRIGHT_URI "copyright-uri"
791 /**
792 * GST_TAG_ENCODED_BY:
793 *
794 * name of the person or organisation that encoded the file. May contain a
795 * copyright message if the person or organisation also holds the copyright
796 * (string)
797 *
798 * Note: do not use this field to describe the encoding application. Use
799 * #GST_TAG_APPLICATION_NAME or #GST_TAG_COMMENT for that.
800 */
801 #define GST_TAG_ENCODED_BY "encoded-by"
802 /**
803 * GST_TAG_CONTACT:
804 *
805 * contact information (string)
806 */
807 #define GST_TAG_CONTACT "contact"
808 /**
809 * GST_TAG_LICENSE:
810 *
811 * license of data (string)
812 */
813 #define GST_TAG_LICENSE "license"
814 /**
815 * GST_TAG_LICENSE_URI:
816 *
817 * URI to location where license details can be found (string)
818 */
819 #define GST_TAG_LICENSE_URI "license-uri"
820 /**
821 * GST_TAG_PERFORMER:
822 *
823 * person(s) performing (string)
824 */
825 #define GST_TAG_PERFORMER "performer"
826 /**
827 * GST_TAG_DURATION:
828 *
829 * length in GStreamer time units (nanoseconds) (unsigned 64-bit integer)
830 */
831 #define GST_TAG_DURATION "duration"
832 /**
833 * GST_TAG_CODEC:
834 *
835 * codec the data is stored in (string)
836 */
837 #define GST_TAG_CODEC "codec"
838 /**
839 * GST_TAG_VIDEO_CODEC:
840 *
841 * codec the video data is stored in (string)
842 */
843 #define GST_TAG_VIDEO_CODEC "video-codec"
844 /**
845 * GST_TAG_AUDIO_CODEC:
846 *
847 * codec the audio data is stored in (string)
848 */
849 #define GST_TAG_AUDIO_CODEC "audio-codec"
850 /**
851 * GST_TAG_SUBTITLE_CODEC:
852 *
853 * codec/format the subtitle data is stored in (string)
854 */
855 #define GST_TAG_SUBTITLE_CODEC "subtitle-codec"
856 /**
857 * GST_TAG_CONTAINER_FORMAT:
858 *
859 * container format the data is stored in (string)
860 */
861 #define GST_TAG_CONTAINER_FORMAT "container-format"
862 /**
863 * GST_TAG_BITRATE:
864 *
865 * exact or average bitrate in bits/s (unsigned integer)
866 */
867 #define GST_TAG_BITRATE "bitrate"
868 /**
869 * GST_TAG_NOMINAL_BITRATE:
870 *
871 * nominal bitrate in bits/s (unsigned integer). The actual bitrate might be
872 * different from this target bitrate.
873 */
874 #define GST_TAG_NOMINAL_BITRATE "nominal-bitrate"
875 /**
876 * GST_TAG_MINIMUM_BITRATE:
877 *
878 * minimum bitrate in bits/s (unsigned integer)
879 */
880 #define GST_TAG_MINIMUM_BITRATE "minimum-bitrate"
881 /**
882 * GST_TAG_MAXIMUM_BITRATE:
883 *
884 * maximum bitrate in bits/s (unsigned integer)
885 */
886 #define GST_TAG_MAXIMUM_BITRATE "maximum-bitrate"
887 /**
888 * GST_TAG_SERIAL:
889 *
890 * serial number of track (unsigned integer)
891 */
892 #define GST_TAG_SERIAL "serial"
893 /**
894 * GST_TAG_ENCODER:
895 *
896 * encoder used to encode this stream (string)
897 */
898 #define GST_TAG_ENCODER "encoder"
899 /**
900 * GST_TAG_ENCODER_VERSION:
901 *
902 * version of the encoder used to encode this stream (unsigned integer)
903 */
904 #define GST_TAG_ENCODER_VERSION "encoder-version"
905 /**
906 * GST_TAG_TRACK_GAIN:
907 *
908 * track gain in db (double)
909 */
910 #define GST_TAG_TRACK_GAIN "replaygain-track-gain"
911 /**
912 * GST_TAG_TRACK_PEAK:
913 *
914 * peak of the track (double)
915 */
916 #define GST_TAG_TRACK_PEAK "replaygain-track-peak"
917 /**
918 * GST_TAG_ALBUM_GAIN:
919 *
920 * album gain in db (double)
921 */
922 #define GST_TAG_ALBUM_GAIN "replaygain-album-gain"
923 /**
924 * GST_TAG_ALBUM_PEAK:
925 *
926 * peak of the album (double)
927 */
928 #define GST_TAG_ALBUM_PEAK "replaygain-album-peak"
929 /**
930 * GST_TAG_REFERENCE_LEVEL:
931 *
932 * reference level of track and album gain values (double)
933 */
934 #define GST_TAG_REFERENCE_LEVEL "replaygain-reference-level"
935 /**
936 * GST_TAG_LANGUAGE_CODE:
937 *
938 * ISO-639-2 or ISO-639-1 code for the language the content is in (string)
939 *
940 * There is utility API in libgsttag in gst-plugins-base to obtain a translated
941 * language name from the language code: gst_tag_get_language_name()
942 */
943 #define GST_TAG_LANGUAGE_CODE "language-code"
944 /**
945 * GST_TAG_LANGUAGE_NAME:
946 *
947 * Name of the language the content is in (string)
948 *
949 * Free-form name of the language the content is in, if a language code
950 * is not available. This tag should not be set in addition to a language
951 * code. It is undefined what language or locale the language name is in.
952 */
953 #define GST_TAG_LANGUAGE_NAME "language-name"
954 /**
955 * GST_TAG_IMAGE:
956 *
957 * image (sample) (sample taglist should specify the content type and preferably
958 * also set "image-type" field as #GstTagImageType)
959 */
960 #define GST_TAG_IMAGE "image"
961 /**
962 * GST_TAG_PREVIEW_IMAGE:
963 *
964 * image that is meant for preview purposes, e.g. small icon-sized version
965 * (sample) (sample taglist should specify the content type)
966 */
967 #define GST_TAG_PREVIEW_IMAGE "preview-image"
968
969 /**
970 * GST_TAG_ATTACHMENT:
971 *
972 * generic file attachment (sample) (sample taglist should specify the content
973 * type and if possible set "filename" to the file name of the
974 * attachment)
975 */
976 #define GST_TAG_ATTACHMENT "attachment"
977
978 /**
979 * GST_TAG_BEATS_PER_MINUTE:
980 *
981 * number of beats per minute in audio (double)
982 */
983 #define GST_TAG_BEATS_PER_MINUTE "beats-per-minute"
984
985 /**
986 * GST_TAG_KEYWORDS:
987 *
988 * comma separated keywords describing the content (string).
989 */
990 #define GST_TAG_KEYWORDS "keywords"
991
992 /**
993 * GST_TAG_GEO_LOCATION_NAME:
994 *
995 * human readable descriptive location of where the media has been recorded or
996 * produced. (string).
997 */
998 #define GST_TAG_GEO_LOCATION_NAME "geo-location-name"
999
1000 /**
1001 * GST_TAG_GEO_LOCATION_LATITUDE:
1002 *
1003 * geo latitude location of where the media has been recorded or produced in
1004 * degrees according to WGS84 (zero at the equator, negative values for southern
1005 * latitudes) (double).
1006 */
1007 #define GST_TAG_GEO_LOCATION_LATITUDE "geo-location-latitude"
1008
1009 /**
1010 * GST_TAG_GEO_LOCATION_LONGITUDE:
1011 *
1012 * geo longitude location of where the media has been recorded or produced in
1013 * degrees according to WGS84 (zero at the prime meridian in Greenwich/UK,
1014 * negative values for western longitudes). (double).
1015 */
1016 #define GST_TAG_GEO_LOCATION_LONGITUDE "geo-location-longitude"
1017
1018 /**
1019 * GST_TAG_GEO_LOCATION_ELEVATION:
1020 *
1021 * geo elevation of where the media has been recorded or produced in meters
1022 * according to WGS84 (zero is average sea level) (double).
1023 */
1024 #define GST_TAG_GEO_LOCATION_ELEVATION "geo-location-elevation"
1025 /**
1026 * GST_TAG_GEO_LOCATION_COUNTRY:
1027 *
1028 * The country (english name) where the media has been produced (string).
1029 */
1030 #define GST_TAG_GEO_LOCATION_COUNTRY "geo-location-country"
1031 /**
1032 * GST_TAG_GEO_LOCATION_CITY:
1033 *
1034 * The city (english name) where the media has been produced (string).
1035 */
1036 #define GST_TAG_GEO_LOCATION_CITY "geo-location-city"
1037 /**
1038 * GST_TAG_GEO_LOCATION_SUBLOCATION:
1039 *
1040 * A location 'smaller' than GST_TAG_GEO_LOCATION_CITY that specifies better
1041 * where the media has been produced. (e.g. the neighborhood) (string).
1042 *
1043 * This tag has been added as this is how it is handled/named in XMP's
1044 * Iptc4xmpcore schema.
1045 */
1046 #define GST_TAG_GEO_LOCATION_SUBLOCATION "geo-location-sublocation"
1047 /**
1048 * GST_TAG_GEO_LOCATION_HORIZONTAL_ERROR:
1049 *
1050 * Represents the expected error on the horizontal positioning in
1051 * meters (double).
1052 */
1053 #define GST_TAG_GEO_LOCATION_HORIZONTAL_ERROR "geo-location-horizontal-error"
1054 /**
1055 * GST_TAG_GEO_LOCATION_MOVEMENT_SPEED:
1056 *
1057 * Speed of the capturing device when performing the capture.
1058 * Represented in m/s. (double)
1059 *
1060 * See also #GST_TAG_GEO_LOCATION_MOVEMENT_DIRECTION
1061 */
1062 #define GST_TAG_GEO_LOCATION_MOVEMENT_SPEED "geo-location-movement-speed"
1063 /**
1064 * GST_TAG_GEO_LOCATION_MOVEMENT_DIRECTION:
1065 *
1066 * Indicates the movement direction of the device performing the capture
1067 * of a media. It is represented as degrees in floating point representation,
1068 * 0 means the geographic north, and increases clockwise (double from 0 to 360)
1069 *
1070 * See also #GST_TAG_GEO_LOCATION_CAPTURE_DIRECTION
1071 */
1072 #define GST_TAG_GEO_LOCATION_MOVEMENT_DIRECTION "geo-location-movement-direction"
1073 /**
1074 * GST_TAG_GEO_LOCATION_CAPTURE_DIRECTION:
1075 *
1076 * Indicates the direction the device is pointing to when capturing
1077 * a media. It is represented as degrees in floating point representation,
1078 * 0 means the geographic north, and increases clockwise (double from 0 to 360)
1079 *
1080 * See also #GST_TAG_GEO_LOCATION_MOVEMENT_DIRECTION
1081 */
1082 #define GST_TAG_GEO_LOCATION_CAPTURE_DIRECTION "geo-location-capture-direction"
1083 /**
1084 * GST_TAG_SHOW_NAME:
1085 *
1086 * Name of the show, used for displaying (string)
1087 */
1088 #define GST_TAG_SHOW_NAME "show-name"
1089 /**
1090 * GST_TAG_SHOW_SORTNAME:
1091 *
1092 * Name of the show, used for sorting (string)
1093 */
1094 #define GST_TAG_SHOW_SORTNAME "show-sortname"
1095 /**
1096 * GST_TAG_SHOW_EPISODE_NUMBER:
1097 *
1098 * Number of the episode within a season/show (unsigned integer)
1099 */
1100 #define GST_TAG_SHOW_EPISODE_NUMBER "show-episode-number"
1101 /**
1102 * GST_TAG_SHOW_SEASON_NUMBER:
1103 *
1104 * Number of the season of a show/series (unsigned integer)
1105 */
1106 #define GST_TAG_SHOW_SEASON_NUMBER "show-season-number"
1107 /**
1108 * GST_TAG_LYRICS:
1109 *
1110 * The lyrics of the media (string)
1111 */
1112 #define GST_TAG_LYRICS "lyrics"
1113 /**
1114 * GST_TAG_COMPOSER_SORTNAME:
1115 *
1116 * The composer's name, used for sorting (string)
1117 */
1118 #define GST_TAG_COMPOSER_SORTNAME "composer-sortname"
1119 /**
1120 * GST_TAG_GROUPING:
1121 *
1122 * Groups together media that are related and spans multiple tracks. An
1123 * example are multiple pieces of a concerto. (string)
1124 */
1125 #define GST_TAG_GROUPING "grouping"
1126 /**
1127 * GST_TAG_USER_RATING:
1128 *
1129 * Rating attributed by a person (likely the application user).
1130 * The higher the value, the more the user likes this media
1131 * (unsigned int from 0 to 100)
1132 */
1133 #define GST_TAG_USER_RATING "user-rating"
1134 /**
1135 * GST_TAG_DEVICE_MANUFACTURER:
1136 *
1137 * Manufacturer of the device used to create the media (string)
1138 */
1139 #define GST_TAG_DEVICE_MANUFACTURER "device-manufacturer"
1140 /**
1141 * GST_TAG_DEVICE_MODEL:
1142 *
1143 * Model of the device used to create the media (string)
1144 */
1145 #define GST_TAG_DEVICE_MODEL "device-model"
1146 /**
1147 * GST_TAG_APPLICATION_NAME:
1148 *
1149 * Name of the application used to create the media (string)
1150 */
1151 #define GST_TAG_APPLICATION_NAME "application-name"
1152 /**
1153 * GST_TAG_APPLICATION_DATA:
1154 *
1155 * Arbitrary application data (sample)
1156 *
1157 * Some formats allow applications to add their own arbitrary data
1158 * into files. This data is application dependent.
1159 */
1160 #define GST_TAG_APPLICATION_DATA "application-data"
1161 /**
1162 * GST_TAG_IMAGE_ORIENTATION:
1163 *
1164 * Represents the 'Orientation' tag from EXIF. Defines how the image
1165 * should be rotated and mirrored for display. (string)
1166 *
1167 * This tag has a predefined set of allowed values:
1168 * "rotate-0"
1169 * "rotate-90"
1170 * "rotate-180"
1171 * "rotate-270"
1172 * "flip-rotate-0"
1173 * "flip-rotate-90"
1174 * "flip-rotate-180"
1175 * "flip-rotate-270"
1176 *
1177 * The naming is adopted according to a possible transformation to perform
1178 * on the image to fix its orientation, obviously equivalent operations will
1179 * yield the same result.
1180 *
1181 * Rotations indicated by the values are in clockwise direction and
1182 * 'flip' means an horizontal mirroring.
1183 */
1184 #define GST_TAG_IMAGE_ORIENTATION "image-orientation"
1185 /**
1186 * GST_TAG_PUBLISHER:
1187 *
1188 * Name of the label or publisher (string)
1189 *
1190 * Since: 1.2
1191 */
1192 #define GST_TAG_PUBLISHER "publisher"
1193 /**
1194 * GST_TAG_INTERPRETED_BY:
1195 *
1196 * Information about the people behind a remix and similar
1197 * interpretations of another existing piece (string)
1198 *
1199 * Since: 1.2
1200 */
1201 #define GST_TAG_INTERPRETED_BY "interpreted-by"
1202 /**
1203 * GST_TAG_MIDI_BASE_NOTE:
1204 *
1205 * <ulink url="http://en.wikipedia.org/wiki/Note#Note_designation_in_accordance_with_octave_name">Midi note number</ulink>
1206 * of the audio track. This is useful for sample instruments and in particular
1207 * for multi-samples.
1208 *
1209 * Since: 1.4
1210 */
1211 #define GST_TAG_MIDI_BASE_NOTE "midi-base-note"
1212 /**
1213 * GST_TAG_PRIVATE_DATA:
1214 *
1215 * Any private data that may be contained in tags (sample).
1216 *
1217 * It is represented by #GstSample in which #GstBuffer contains the
1218 * binary data and the sample's info #GstStructure may contain any
1219 * extra information that identifies the origin or meaning of the data.
1220 *
1221 * Private frames in ID3v2 tags ('PRIV' frames) will be represented
1222 * using this tag, in which case the GstStructure will be named
1223 * "ID3PrivateFrame" and contain a field named "owner" of type string
1224 * which contains the owner-identification string from the tag.
1225 *
1226 * Since: 1.8
1227 */
1228 #define GST_TAG_PRIVATE_DATA "private-data"
1229
1230 #ifdef G_DEFINE_AUTOPTR_CLEANUP_FUNC
1231 G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstTagList, gst_tag_list_unref)
1232 #endif
1233
1234 G_END_DECLS
1235
1236 #endif /* __GST_TAGLIST_H__ */
1237