2 * Copyright (C) 2003 Benjamin Otte <in7y118@public.uni-hamburg.de>
3 * Copyright (C) 2006-2011 Tim-Philipp Müller <tim centricular net>
5 * This library is free software; you can redistribute it and/or
6 * modify it under the terms of the GNU Library General Public
7 * License as published by the Free Software Foundation; either
8 * version 2 of the License, or (at your option) any later version.
10 * This library is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 * Library General Public License for more details.
15 * You should have received a copy of the GNU Library General Public
16 * License along with this library; if not, write to the
17 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
18 * Boston, MA 02111-1307, USA.
22 #ifndef __GST_TAG_TAG_H__
23 #define __GST_TAG_TAG_H__
32 * GST_TAG_MUSICBRAINZ_TRACKID
34 * MusicBrainz track ID
36 #define GST_TAG_MUSICBRAINZ_TRACKID "musicbrainz-trackid"
38 * GST_TAG_MUSICBRAINZ_ARTISTID
40 * MusicBrainz artist ID
42 #define GST_TAG_MUSICBRAINZ_ARTISTID "musicbrainz-artistid"
44 * GST_TAG_MUSICBRAINZ_ALBUMID
46 * MusicBrainz album ID
48 #define GST_TAG_MUSICBRAINZ_ALBUMID "musicbrainz-albumid"
50 * GST_TAG_MUSICBRAINZ_ALBUMARTISTID
52 * MusicBrainz album artist ID
54 #define GST_TAG_MUSICBRAINZ_ALBUMARTISTID "musicbrainz-albumartistid"
56 * GST_TAG_MUSICBRAINZ_TRMID
58 * MusicBrainz track TRM ID
60 #define GST_TAG_MUSICBRAINZ_TRMID "musicbrainz-trmid"
62 /* FIXME 0.11: remove GST_TAG_MUSICBRAINZ_SORTNAME */
63 #ifndef GST_DISABLE_DEPRECATED
65 * GST_TAG_MUSICBRAINZ_SORTNAME
67 * MusicBrainz artist sort name
69 * Deprecated. Use GST_TAG_ARTIST_SORTNAME instead.
71 #define GST_TAG_MUSICBRAINZ_SORTNAME GST_TAG_ARTIST_SORTNAME
77 * Annodex CMML stream element tag
79 #define GST_TAG_CMML_STREAM "cmml-stream"
83 * Annodex CMML head element tag
86 #define GST_TAG_CMML_HEAD "cmml-head"
90 * Annodex CMML clip element tag
92 #define GST_TAG_CMML_CLIP "cmml-clip"
97 * GST_TAG_CDDA_CDDB_DISCID:
99 * CDDB disc id in its short form (e.g. 'aa063d0f')
101 #define GST_TAG_CDDA_CDDB_DISCID "discid"
104 * GST_TAG_CDDA_CDDB_DISCID_FULL:
106 * CDDB disc id including all details
108 #define GST_TAG_CDDA_CDDB_DISCID_FULL "discid-full"
111 * GST_TAG_CDDA_MUSICBRAINZ_DISCID:
113 * Musicbrainz disc id (e.g. 'ahg7JUcfR3vCYBphSDIogOOWrr0-')
115 #define GST_TAG_CDDA_MUSICBRAINZ_DISCID "musicbrainz-discid"
118 * GST_TAG_CDDA_MUSICBRAINZ_DISCID_FULL:
120 * Musicbrainz disc id details
122 #define GST_TAG_CDDA_MUSICBRAINZ_DISCID_FULL "musicbrainz-discid-full"
125 * GST_TAG_CAPTURING_SHUTTER_SPEED:
127 * Shutter speed used when capturing an image, in seconds. (fraction)
131 #define GST_TAG_CAPTURING_SHUTTER_SPEED "capturing-shutter-speed"
134 * GST_TAG_CAPTURING_FOCAL_RATIO:
136 * Focal ratio (f-number) used when capturing an image. (double)
138 * The value stored is the denominator of the focal ratio (f-number).
139 * For example, if this tag value is 2, the focal ratio is f/2.
143 #define GST_TAG_CAPTURING_FOCAL_RATIO "capturing-focal-ratio"
146 * GST_TAG_CAPTURING_FOCAL_LENGTH:
148 * Focal length used when capturing an image, in mm. (double)
152 #define GST_TAG_CAPTURING_FOCAL_LENGTH "capturing-focal-length"
155 * GST_TAG_CAPTURING_DIGITAL_ZOOM_RATIO:
157 * Digital zoom ratio used when capturing an image. (double)
161 #define GST_TAG_CAPTURING_DIGITAL_ZOOM_RATIO "capturing-digital-zoom-ratio"
164 * GST_TAG_CAPTURING_ISO_SPEED:
166 * ISO speed used when capturing an image. (integer)
170 #define GST_TAG_CAPTURING_ISO_SPEED "capturing-iso-speed"
173 * GST_TAG_CAPTURING_EXPOSURE_PROGRAM:
175 * Type of exposure control used when capturing an image. (string)
177 * The allowed values are:
180 * "normal" - automatically controlled
181 * "aperture-priority" - user selects aperture value
182 * "shutter-priority" - user selects shutter speed
183 * "creative" - biased towards depth of field
184 * "action" - biased towards fast shutter speed
185 * "portrait" - closeup, leaving background out of focus
186 * "landscape" - landscape photos, background in focus
190 #define GST_TAG_CAPTURING_EXPOSURE_PROGRAM "capturing-exposure-program"
193 * GST_TAG_CAPTURING_EXPOSURE_MODE:
195 * Exposure mode used when capturing an image. (string)
197 * The allowed values are:
204 #define GST_TAG_CAPTURING_EXPOSURE_MODE "capturing-exposure-mode"
207 * GST_TAG_CAPTURING_EXPOSURE_COMPENSATION:
209 * Exposure compensation using when capturing an image in EV. (double)
213 #define GST_TAG_CAPTURING_EXPOSURE_COMPENSATION "capturing-exposure-compensation"
216 * GST_TAG_CAPTURING_SCENE_CAPTURE_TYPE:
218 * Scene mode used when capturing an image. (string)
220 * The allowed values are:
228 #define GST_TAG_CAPTURING_SCENE_CAPTURE_TYPE "capturing-scene-capture-type"
231 * GST_TAG_CAPTURING_GAIN_ADJUSTMENT:
233 * Gain adjustment applied to an image. (string)
235 * The allowed values are:
244 #define GST_TAG_CAPTURING_GAIN_ADJUSTMENT "capturing-gain-adjustment"
247 * GST_TAG_CAPTURING_WHITE_BALANCE:
249 * White balance mode used when capturing an image. (string)
251 * The allowed values are:
258 * "fluorescent h" (newer daylight-calibrated fluorescents)
263 #define GST_TAG_CAPTURING_WHITE_BALANCE "capturing-white-balance"
266 * GST_TAG_CAPTURING_CONTRAST:
268 * Direction of contrast processing applied when capturing an image. (string)
270 * The allowed values are:
277 #define GST_TAG_CAPTURING_CONTRAST "capturing-contrast"
280 * GST_TAG_CAPTURING_SATURATION:
282 * Direction of saturation processing applied when capturing an image. (string)
284 * The allowed values are:
291 #define GST_TAG_CAPTURING_SATURATION "capturing-saturation"
294 * GST_TAG_CAPTURING_SHARPNESS:
296 * Direction of sharpness processing applied when capturing an image. (string)
298 * The allowed values are:
305 #define GST_TAG_CAPTURING_SHARPNESS "capturing-sharpness"
308 * GST_TAG_CAPTURING_FLASH_FIRED:
310 * If flash was fired during the capture of an image. (boolean)
312 * Note that if this tag isn't present, it should not be assumed that
313 * the flash did not fire. It should be treated as unknown.
317 #define GST_TAG_CAPTURING_FLASH_FIRED "capturing-flash-fired"
320 * GST_TAG_CAPTURING_FLASH_MODE:
322 * The flash mode selected during the capture of an image. (string)
324 * The allowed values are:
331 #define GST_TAG_CAPTURING_FLASH_MODE "capturing-flash-mode"
334 * GST_TAG_CAPTURING_METERING_MODE:
336 * Defines the way a camera determines the exposure. (string)
338 * The allowed values are:
341 * "center-weighted-average"
350 #define GST_TAG_CAPTURING_METERING_MODE "capturing-metering-mode"
353 * GST_TAG_CAPTURING_SOURCE:
355 * Indicates the source of capture. The device/medium used to do the
358 * Allowed values are:
359 * "dsc" (= digital still camera)
360 * "transparent-scanner"
366 #define GST_TAG_CAPTURING_SOURCE "capturing-source"
369 * GST_TAG_IMAGE_HORIZONTAL_PPI:
371 * Media (image/video) intended horizontal pixel density in ppi. (double)
375 #define GST_TAG_IMAGE_HORIZONTAL_PPI "image-horizontal-ppi"
377 * GST_TAG_IMAGE_VERTICAL_PPI:
379 * Media (image/video) intended vertical pixel density in ppi. (double)
383 #define GST_TAG_IMAGE_VERTICAL_PPI "image-vertical-ppi"
386 /* additional information for image tags */
390 * @GST_TAG_IMAGE_TYPE_NONE : No image type. Can be used to
391 * tell functions such as gst_tag_image_data_to_image_buffer() that no
392 * image type should be set. (Since: 0.10.20)
393 * @GST_TAG_IMAGE_TYPE_UNDEFINED : Undefined/other image type
394 * @GST_TAG_IMAGE_TYPE_FRONT_COVER : Cover (front)
395 * @GST_TAG_IMAGE_TYPE_BACK_COVER : Cover (back)
396 * @GST_TAG_IMAGE_TYPE_LEAFLET_PAGE : Leaflet page
397 * @GST_TAG_IMAGE_TYPE_MEDIUM : Medium (e.g. label side of CD)
398 * @GST_TAG_IMAGE_TYPE_LEAD_ARTIST : Lead artist/lead performer/soloist
399 * @GST_TAG_IMAGE_TYPE_ARTIST : Artist/performer
400 * @GST_TAG_IMAGE_TYPE_CONDUCTOR : Conductor
401 * @GST_TAG_IMAGE_TYPE_BAND_ORCHESTRA : Band/orchestra
402 * @GST_TAG_IMAGE_TYPE_COMPOSER : Composer
403 * @GST_TAG_IMAGE_TYPE_LYRICIST : Lyricist/text writer
404 * @GST_TAG_IMAGE_TYPE_RECORDING_LOCATION : Recording location
405 * @GST_TAG_IMAGE_TYPE_DURING_RECORDING : During recording
406 * @GST_TAG_IMAGE_TYPE_DURING_PERFORMANCE : During performance
407 * @GST_TAG_IMAGE_TYPE_VIDEO_CAPTURE : Movie/video screen capture
408 * @GST_TAG_IMAGE_TYPE_FISH : A fish as funny as the ID3v2 spec
409 * @GST_TAG_IMAGE_TYPE_ILLUSTRATION : Illustration
410 * @GST_TAG_IMAGE_TYPE_BAND_ARTIST_LOGO : Band/artist logotype
411 * @GST_TAG_IMAGE_TYPE_PUBLISHER_STUDIO_LOGO : Publisher/studio logotype
413 * Type of image contained in an image tag (specified as field in
414 * the image buffer's caps structure)
418 /* Note: keep in sync with register_tag_image_type_enum() */
420 GST_TAG_IMAGE_TYPE_NONE = -1,
421 GST_TAG_IMAGE_TYPE_UNDEFINED = 0,
422 GST_TAG_IMAGE_TYPE_FRONT_COVER,
423 GST_TAG_IMAGE_TYPE_BACK_COVER,
424 GST_TAG_IMAGE_TYPE_LEAFLET_PAGE,
425 GST_TAG_IMAGE_TYPE_MEDIUM,
426 GST_TAG_IMAGE_TYPE_LEAD_ARTIST,
427 GST_TAG_IMAGE_TYPE_ARTIST,
428 GST_TAG_IMAGE_TYPE_CONDUCTOR,
429 GST_TAG_IMAGE_TYPE_BAND_ORCHESTRA,
430 GST_TAG_IMAGE_TYPE_COMPOSER,
431 GST_TAG_IMAGE_TYPE_LYRICIST,
432 GST_TAG_IMAGE_TYPE_RECORDING_LOCATION,
433 GST_TAG_IMAGE_TYPE_DURING_RECORDING,
434 GST_TAG_IMAGE_TYPE_DURING_PERFORMANCE,
435 GST_TAG_IMAGE_TYPE_VIDEO_CAPTURE,
436 GST_TAG_IMAGE_TYPE_FISH,
437 GST_TAG_IMAGE_TYPE_ILLUSTRATION,
438 GST_TAG_IMAGE_TYPE_BAND_ARTIST_LOGO,
439 GST_TAG_IMAGE_TYPE_PUBLISHER_STUDIO_LOGO
442 #define GST_TYPE_TAG_IMAGE_TYPE (gst_tag_image_type_get_type ())
443 GType gst_tag_image_type_get_type (void);
446 * GST_TAG_ID3V2_HEADER_SIZE:
448 * ID3V2 header size considered minimum input for some functions such as
449 * gst_tag_list_from_id3v2_tag() and gst_tag_get_id3v2_tag_size() for example.
453 #define GST_TAG_ID3V2_HEADER_SIZE 10
455 /* functions for vorbis comment manipulation */
457 const gchar * gst_tag_from_vorbis_tag (const gchar * vorbis_tag);
458 const gchar * gst_tag_to_vorbis_tag (const gchar * gst_tag);
459 void gst_vorbis_tag_add (GstTagList * list,
461 const gchar * value);
463 GList * gst_tag_to_vorbis_comments (const GstTagList * list,
466 /* functions to convert GstBuffers with vorbiscomment contents to GstTagLists and back */
467 GstTagList * gst_tag_list_from_vorbiscomment_buffer (const GstBuffer * buffer,
468 const guint8 * id_data,
469 const guint id_data_length,
470 gchar ** vendor_string);
471 GstBuffer * gst_tag_list_to_vorbiscomment_buffer (const GstTagList * list,
472 const guint8 * id_data,
473 const guint id_data_length,
474 const gchar * vendor_string);
476 /* functions for ID3 tag manipulation */
478 /* FIXME 0.11: inconsistent API naming: gst_tag_list_new_from_id3v1(), gst_tag_list_from_*_buffer(),
479 * gst_tag_list_from_id3v2_tag(). Also, note gst.tag.list_xyz() namespace vs. gst.tag_list_xyz(),
480 * which is a bit confusing and possibly doesn't map too well */
482 guint gst_tag_id3_genre_count (void);
483 const gchar * gst_tag_id3_genre_get (const guint id);
484 GstTagList * gst_tag_list_new_from_id3v1 (const guint8 * data);
486 const gchar * gst_tag_from_id3_tag (const gchar * id3_tag);
487 const gchar * gst_tag_from_id3_user_tag (const gchar * type,
488 const gchar * id3_user_tag);
489 const gchar * gst_tag_to_id3_tag (const gchar * gst_tag);
491 gboolean gst_tag_list_add_id3_image (GstTagList * tag_list,
492 const guint8 * image_data,
493 guint image_data_len,
494 guint id3_picture_type);
496 GstTagList * gst_tag_list_from_id3v2_tag (GstBuffer * buffer);
498 guint gst_tag_get_id3v2_tag_size (GstBuffer * buffer);
500 /* functions to convert GstBuffers with xmp packets contents to GstTagLists and back */
501 GstTagList * gst_tag_list_from_xmp_buffer (const GstBuffer * buffer);
502 GstBuffer * gst_tag_list_to_xmp_buffer (const GstTagList * list,
504 GstBuffer * gst_tag_list_to_xmp_buffer_full (const GstTagList * list,
505 gboolean read_only, const gchar ** schemas);
506 const gchar** gst_tag_xmp_list_schemas (void);
508 /* functions related to exif */
509 GstBuffer * gst_tag_list_to_exif_buffer (const GstTagList * taglist,
511 guint32 base_offset);
513 GstBuffer * gst_tag_list_to_exif_buffer_with_tiff_header (const GstTagList * taglist);
515 GstTagList * gst_tag_list_from_exif_buffer (const GstBuffer * buffer,
517 guint32 base_offset);
519 GstTagList * gst_tag_list_from_exif_buffer_with_tiff_header (
520 const GstBuffer * buffer);
522 /* other tag-related functions */
524 gboolean gst_tag_parse_extended_comment (const gchar * ext_comment,
528 gboolean fail_if_no_key);
530 gchar * gst_tag_freeform_string_to_utf8 (const gchar * data,
532 const gchar ** env_vars);
534 GstBuffer * gst_tag_image_data_to_image_buffer (const guint8 * image_data,
535 guint image_data_len,
536 GstTagImageType image_type);
538 /* FIXME 0.11: get rid of this awkward register/init function, see tags.c */
539 void gst_tag_register_musicbrainz_tags (void);
542 /* language tag related functions */
544 gchar ** gst_tag_get_language_codes (void);
546 const gchar * gst_tag_get_language_name (const gchar * language_code);
548 const gchar * gst_tag_get_language_code_iso_639_1 (const gchar * lang_code);
550 const gchar * gst_tag_get_language_code_iso_639_2B (const gchar * lang_code);
552 const gchar * gst_tag_get_language_code_iso_639_2T (const gchar * lang_code);
555 * gst_tag_get_language_code:
556 * @lang_code: ISO-639 language code (e.g. "deu" or "ger" or "de")
558 * Convenience macro wrapping gst_tag_get_language_code_iso_639_1().
562 #define gst_tag_get_language_code(lang_code) \
563 gst_tag_get_language_code_iso_639_1(lang_code)
566 /* functions to deal with (mostly) Creative Commons licenses */
569 * GstTagLicenseFlags:
570 * @GST_TAG_LICENSE_PERMITS_REPRODUCTION: making multiple copies
572 * @GST_TAG_LICENSE_PERMITS_DISTRIBUTION: distribution, public display
573 * and public performance are allowed
574 * @GST_TAG_LICENSE_PERMITS_DERIVATIVE_WORKS: distribution of derivative
576 * @GST_TAG_LICENSE_PERMITS_SHARING: commercial derivatives are allowed,
577 * but only non-commercial distribution is allowed
578 * @GST_TAG_LICENSE_REQUIRES_NOTICE: copyright and license notices
579 * must be kept intact
580 * @GST_TAG_LICENSE_REQUIRES_ATTRIBUTION: credit must be given to
581 * copyright holder and/or author
582 * @GST_TAG_LICENSE_REQUIRES_SHARE_ALIKE: derivative works must be
583 * licensed under the same terms or compatible terms as the original work
584 * @GST_TAG_LICENSE_REQUIRES_SOURCE_CODE: source code (the preferred
585 * form for making modifications) must be provided when exercising some
586 * rights granted by the license
587 * @GST_TAG_LICENSE_REQUIRES_COPYLEFT: derivative and combined works
588 * must be licensed under specified terms, similar to those of the original
590 * @GST_TAG_LICENSE_REQUIRES_LESSER_COPYLEFT: derivative works must be
591 * licensed under specified terms, with at least the same conditions as
592 * the original work; combinations with the work may be licensed under
594 * @GST_TAG_LICENSE_PROHIBITS_COMMERCIAL_USE: exercising rights for
595 * commercial purposes is prohibited
596 * @GST_TAG_LICENSE_PROHIBITS_HIGH_INCOME_NATION_USE: use in a
597 * non-developing country is prohibited
598 * @GST_TAG_LICENSE_CREATIVE_COMMONS_LICENSE: this license was created
599 * by the Creative Commons project
600 * @GST_TAG_LICENSE_FREE_SOFTWARE_FOUNDATION_LICENSE: this license was
601 * created by the Free Software Foundation (FSF)
603 * See http://creativecommons.org/ns for more information.
608 GST_TAG_LICENSE_PERMITS_REPRODUCTION = (1 << 0),
609 GST_TAG_LICENSE_PERMITS_DISTRIBUTION = (1 << 1),
610 GST_TAG_LICENSE_PERMITS_DERIVATIVE_WORKS = (1 << 2),
611 GST_TAG_LICENSE_PERMITS_SHARING = (1 << 3),
613 GST_TAG_LICENSE_REQUIRES_NOTICE = (1 << 8),
614 GST_TAG_LICENSE_REQUIRES_ATTRIBUTION = (1 << 9),
615 GST_TAG_LICENSE_REQUIRES_SHARE_ALIKE = (1 << 10),
616 GST_TAG_LICENSE_REQUIRES_SOURCE_CODE = (1 << 11),
617 GST_TAG_LICENSE_REQUIRES_COPYLEFT = (1 << 12),
618 GST_TAG_LICENSE_REQUIRES_LESSER_COPYLEFT = (1 << 13),
620 GST_TAG_LICENSE_PROHIBITS_COMMERCIAL_USE = (1 << 16),
621 GST_TAG_LICENSE_PROHIBITS_HIGH_INCOME_NATION_USE = (1 << 17),
623 GST_TAG_LICENSE_CREATIVE_COMMONS_LICENSE = (1 << 24),
624 GST_TAG_LICENSE_FREE_SOFTWARE_FOUNDATION_LICENSE = (1 << 25)
625 } GstTagLicenseFlags;
627 gchar ** gst_tag_get_licenses (void);
629 GstTagLicenseFlags gst_tag_get_license_flags (const gchar * license_ref);
631 const gchar * gst_tag_get_license_nick (const gchar * license_ref);
633 const gchar * gst_tag_get_license_title (const gchar * license_ref);
635 const gchar * gst_tag_get_license_version (const gchar * license_ref);
637 const gchar * gst_tag_get_license_description (const gchar * license_ref);
639 const gchar * gst_tag_get_license_jurisdiction (const gchar * license_ref);
641 GType gst_tag_license_flags_get_type (void);
645 #endif /* __GST_TAG_TAG_H__ */