Public Metadata API

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.