Loading...
Searching...
No Matches
Public Metadata API
libavformat

The metadata API allows libavformat to export metadata tags to a client application when demuxing.

The metadata API allows libavformat to export metadata tags to a client application when demuxing.

Conversely it allows a client application to set metadata when muxing.

Metadata is exported or set as pairs of key/value strings in the 'metadata' fields of the AVFormatContext, AVStream, AVChapter and AVProgram structs using the AVDictionary API. Like all strings in FFmpeg, metadata is assumed to be UTF-8 encoded Unicode. Note that metadata exported by demuxers isn't checked to be valid UTF-8 in most cases.

Important concepts to keep in mind:

- 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 several keys that are literally different but semantically identical. E.g., key=Author5, key=Author6. In this example, all authors must be placed in the same tag.
- 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 and actor Bob, that could have key=alice_and_bobs_childs_email_address.
- Several modifiers can be applied to the tag name. This is done by 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.
  - language – a tag whose value is localized for a particular language is appended with the ISO 639-2/B 3-letter language code. For example: Author-ger=Michael, Author-eng=Mike The original/default language is in the unqualified "Author" tag. A demuxer should set a default if it sets any translated tag.
  - sorting – a modified version of a tag that should be used for sorting will have '-sort' appended. E.g. artist="The Beatles", artist-sort="Beatles, The".
- Some protocols and demuxers support metadata updates. After a successful call to av_read_frame(), AVFormatContext.event_flags or AVStream.event_flags will be updated to indicate if metadata changed. In order to detect metadata changes on a stream, you need to loop through all streams in the AVFormatContext and check their individual event_flags.
- Demuxers attempt to export metadata in a generic format, however tags with no generic equivalents are left as they are stored in the container. Follows a list of generic tag names:

    album        -- name of the set this work belongs to
    album_artist -- main creator of the set/album, if different from artist.
                    e.g. "Various Artists" for compilation albums.
    artist       -- main creator of the work
    comment      -- any additional description of the file.
    composer     -- who composed the work, if different from artist.
    copyright    -- name of copyright holder.
    creation_time-- date when the file was created, preferably in ISO 8601.
    date         -- date when the work was created, preferably in ISO 8601.
    disc         -- number of a subset, e.g. disc in a multi-disc collection.
    encoder      -- name/settings of the software/hardware that produced the file.
    encoded_by   -- person/group who created the file.
    filename     -- original name of the file.
    genre        -- <self-evident>.
    language     -- main language in which the work is performed, preferably
                    in ISO 639-2 format. Multiple languages can be specified by
                    separating them with commas.
    performer    -- artist who performed the work, if different from artist.
                    E.g for "Also sprach Zarathustra", artist would be "Richard
                    Strauss" and performer "London Philharmonic Orchestra".
    publisher    -- name of the label/publisher.
    service_name     -- name of the service in broadcasting (channel name).
    service_provider -- name of the service provider in broadcasting.
    title        -- name of the work.
    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

Look in the examples section for an application example how to use the Metadata API.