48
48
struct AVFormatContext;
52
* Public Metadata API.
52
* @defgroup metadata_api Public Metadata API
53
54
* The metadata API allows libavformat to export metadata tags to a client
54
55
* application using a sequence of key/value pairs. Like all strings in Libav,
55
56
* metadata must be stored as UTF-8 encoded Unicode. Note that metadata
56
57
* exported by demuxers isn't checked to be valid UTF-8 in most cases.
57
58
* Important concepts to keep in mind:
58
* 1. Keys are unique; there can never be 2 tags with the same key. This is
59
* - Keys are unique; there can never be 2 tags with the same key. This is
59
60
* also meant semantically, i.e., a demuxer should not knowingly produce
60
61
* several keys that are literally different but semantically identical.
61
62
* E.g., key=Author5, key=Author6. In this example, all authors must be
62
63
* placed in the same tag.
63
* 2. Metadata is flat, not hierarchical; there are no subtags. If you
64
* - Metadata is flat, not hierarchical; there are no subtags. If you
64
65
* want to store, e.g., the email address of the child of producer Alice
65
66
* and actor Bob, that could have key=alice_and_bobs_childs_email_address.
66
* 3. Several modifiers can be applied to the tag name. This is done by
67
* - Several modifiers can be applied to the tag name. This is done by
67
68
* appending a dash character ('-') and the modifier name in the order
68
69
* they appear in the list below -- e.g. foo-eng-sort, not foo-sort-eng.
69
* a) language -- a tag whose value is localized for a particular language
70
* - language -- a tag whose value is localized for a particular language
70
71
* is appended with the ISO 639-2/B 3-letter language code.
71
72
* For example: Author-ger=Michael, Author-eng=Mike
72
73
* The original/default language is in the unqualified "Author" tag.
73
74
* A demuxer should set a default if it sets any translated tag.
74
* b) sorting -- a modified version of a tag that should be used for
75
* - sorting -- a modified version of a tag that should be used for
75
76
* sorting will have '-sort' appended. E.g. artist="The Beatles",
76
77
* artist-sort="Beatles, The".
78
* 4. Demuxers attempt to export metadata in a generic format, however tags
79
* - Demuxers attempt to export metadata in a generic format, however tags
79
80
* with no generic equivalents are left as they are stored in the container.
80
81
* Follows a list of generic tag names:
82
* album -- name of the set this work belongs to
83
* album_artist -- main creator of the set/album, if different from artist.
84
* e.g. "Various Artists" for compilation albums.
85
* artist -- main creator of the work
86
* comment -- any additional description of the file.
87
* composer -- who composed the work, if different from artist.
88
* copyright -- name of copyright holder.
89
* creation_time-- date when the file was created, preferably in ISO 8601.
90
* date -- date when the work was created, preferably in ISO 8601.
91
* disc -- number of a subset, e.g. disc in a multi-disc collection.
92
* encoder -- name/settings of the software/hardware that produced the file.
93
* encoded_by -- person/group who created the file.
94
* filename -- original name of the file.
95
* genre -- <self-evident>.
96
* language -- main language in which the work is performed, preferably
97
* in ISO 639-2 format. Multiple languages can be specified by
98
* separating them with commas.
99
* performer -- artist who performed the work, if different from artist.
100
* E.g for "Also sprach Zarathustra", artist would be "Richard
101
* Strauss" and performer "London Philharmonic Orchestra".
102
* publisher -- name of the label/publisher.
103
* service_name -- name of the service in broadcasting (channel name).
104
* service_provider -- name of the service provider in broadcasting.
105
* title -- name of the work.
106
* track -- number of this work in the set, can be in form current/total.
107
* variant_bitrate -- the total bitrate of the bitrate variant that the current stream is part of
84
album -- name of the set this work belongs to
85
album_artist -- main creator of the set/album, if different from artist.
86
e.g. "Various Artists" for compilation albums.
87
artist -- main creator of the work
88
comment -- any additional description of the file.
89
composer -- who composed the work, if different from artist.
90
copyright -- name of copyright holder.
91
creation_time-- date when the file was created, preferably in ISO 8601.
92
date -- date when the work was created, preferably in ISO 8601.
93
disc -- number of a subset, e.g. disc in a multi-disc collection.
94
encoder -- name/settings of the software/hardware that produced the file.
95
encoded_by -- person/group who created the file.
96
filename -- original name of the file.
97
genre -- <self-evident>.
98
language -- main language in which the work is performed, preferably
99
in ISO 639-2 format. Multiple languages can be specified by
100
separating them with commas.
101
performer -- artist who performed the work, if different from artist.
102
E.g for "Also sprach Zarathustra", artist would be "Richard
103
Strauss" and performer "London Philharmonic Orchestra".
104
publisher -- name of the label/publisher.
105
service_name -- name of the service in broadcasting (channel name).
106
service_provider -- name of the service provider in broadcasting.
107
title -- name of the work.
108
track -- number of this work in the set, can be in form current/total.
109
variant_bitrate -- the total bitrate of the bitrate variant that the current stream is part of
112
* Look in the examples section for an application example how to use the Metadata API.
110
117
#if FF_API_OLD_METADATA2