generic-library/ffmpeg
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

avformat: doxify the Metadata API

Browse Source 
convert the comment that documents the metadata API to use
the doxygen markup
This commit is contained in:
Reinhard Tartler 2011-07-01 20:49:14 +02:00
parent 4f731c4429
commit 1a53a438dc
1 changed files with 39 additions and 34 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

73
libavformat/avformat.h
View File

@ -48,63 +48,68 @@ const char *avformat_license(void);
struct AVFormatContext; struct AVFormatContext;
/* /**
* Public Metadata API. * @defgroup metadata_api Public Metadata API
* @{
* The metadata API allows libavformat to export metadata tags to a client * The metadata API allows libavformat to export metadata tags to a client
* application using a sequence of key/value pairs. Like all strings in Libav, * application using a sequence of key/value pairs. Like all strings in Libav,
* metadata must be stored as UTF-8 encoded Unicode. Note that metadata * metadata must be stored as UTF-8 encoded Unicode. Note that metadata
* exported by demuxers isn't checked to be valid UTF-8 in most cases. * exported by demuxers isn't checked to be valid UTF-8 in most cases.
* Important concepts to keep in mind: * Important concepts to keep in mind:
* 1. Keys are unique; there can never be 2 tags with the same key. This is * - Keys are unique; there can never be 2 tags with the same key. This is
* also meant semantically, i.e., a demuxer should not knowingly produce * also meant semantically, i.e., a demuxer should not knowingly produce
* several keys that are literally different but semantically identical. * several keys that are literally different but semantically identical.
* E.g., key=Author5, key=Author6. In this example, all authors must be * E.g., key=Author5, key=Author6. In this example, all authors must be
* placed in the same tag. * placed in the same tag.
* 2. Metadata is flat, not hierarchical; there are no subtags. If you * - Metadata is flat, not hierarchical; there are no subtags. If you
* want to store, e.g., the email address of the child of producer Alice * want to store, e.g., the email address of the child of producer Alice
* and actor Bob, that could have key=alice_and_bobs_childs_email_address. * and actor Bob, that could have key=alice_and_bobs_childs_email_address.
* 3. Several modifiers can be applied to the tag name. This is done by * - Several modifiers can be applied to the tag name. This is done by
* appending a dash character ('-') and the modifier name in the order * appending a dash character ('-') and the modifier name in the order
* they appear in the list below -- e.g. foo-eng-sort, not foo-sort-eng. * they appear in the list below -- e.g. foo-eng-sort, not foo-sort-eng.
* a) language -- a tag whose value is localized for a particular language * - language -- a tag whose value is localized for a particular language
* is appended with the ISO 639-2/B 3-letter language code. * is appended with the ISO 639-2/B 3-letter language code.
* For example: Author-ger=Michael, Author-eng=Mike * For example: Author-ger=Michael, Author-eng=Mike
* The original/default language is in the unqualified "Author" tag. * The original/default language is in the unqualified "Author" tag.
* A demuxer should set a default if it sets any translated tag. * A demuxer should set a default if it sets any translated tag.
* b) sorting -- a modified version of a tag that should be used for * - sorting -- a modified version of a tag that should be used for
* sorting will have '-sort' appended. E.g. artist="The Beatles", * sorting will have '-sort' appended. E.g. artist="The Beatles",
* artist-sort="Beatles, The". * artist-sort="Beatles, The".
* *
* 4. Demuxers attempt to export metadata in a generic format, however tags * - Demuxers attempt to export metadata in a generic format, however tags
* with no generic equivalents are left as they are stored in the container. * with no generic equivalents are left as they are stored in the container.
* Follows a list of generic tag names: * Follows a list of generic tag names:
* *
* album -- name of the set this work belongs to @verbatim
* album_artist -- main creator of the set/album, if different from artist. album -- name of the set this work belongs to
* e.g. "Various Artists" for compilation albums. album_artist -- main creator of the set/album, if different from artist.
* artist -- main creator of the work e.g. "Various Artists" for compilation albums.
* comment -- any additional description of the file. artist -- main creator of the work
* composer -- who composed the work, if different from artist. comment -- any additional description of the file.
* copyright -- name of copyright holder. composer -- who composed the work, if different from artist.
* creation_time-- date when the file was created, preferably in ISO 8601. copyright -- name of copyright holder.
* date -- date when the work was created, preferably in ISO 8601. creation_time-- date when the file was created, preferably in ISO 8601.
* disc -- number of a subset, e.g. disc in a multi-disc collection. date -- date when the work was created, preferably in ISO 8601.
* encoder -- name/settings of the software/hardware that produced the file. disc -- number of a subset, e.g. disc in a multi-disc collection.
* encoded_by -- person/group who created the file. encoder -- name/settings of the software/hardware that produced the file.
* filename -- original name of the file. encoded_by -- person/group who created the file.
* genre -- <self-evident>. filename -- original name of the file.
* language -- main language in which the work is performed, preferably genre -- <self-evident>.
* in ISO 639-2 format. Multiple languages can be specified by language -- main language in which the work is performed, preferably
* separating them with commas. in ISO 639-2 format. Multiple languages can be specified by
* performer -- artist who performed the work, if different from artist. separating them with commas.
* E.g for "Also sprach Zarathustra", artist would be "Richard performer -- artist who performed the work, if different from artist.
* Strauss" and performer "London Philharmonic Orchestra". E.g for "Also sprach Zarathustra", artist would be "Richard
* publisher -- name of the label/publisher. Strauss" and performer "London Philharmonic Orchestra".
* service_name -- name of the service in broadcasting (channel name). publisher -- name of the label/publisher.
* service_provider -- name of the service provider in broadcasting. service_name -- name of the service in broadcasting (channel name).
* title -- name of the work. service_provider -- name of the service provider in broadcasting.
* track -- number of this work in the set, can be in form current/total. title -- name of the work.
* variant_bitrate -- the total bitrate of the bitrate variant that the current stream is part of track -- number of this work in the set, can be in form current/total.
variant_bitrate -- the total bitrate of the bitrate variant that the current stream is part of
@endverbatim
*
* @}
*/ */
#if FF_API_OLD_METADATA2 #if FF_API_OLD_METADATA2