FFmpeg 9.1
Loading...
Searching...
No Matches
Public Metadata API

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.
    • descriptor – some formats (e.g. ID3v2 COMM and USLT frames) attach a free-form descriptor to a tag to distinguish multiple instances. The full key format is "<tag>-<descriptor>-<lang>", but either component may be absent. When writing, the last dash-separated suffix is interpreted as a language code if it is a valid ISO 639-2/B code; otherwise the entire portion after the first dash is treated as a descriptor. Examples: "comment-eng" (lang only), "comment-MusicMatch_Bio-eng" (descriptor + lang), "comment-foobar" (descriptor only, foobar is not a valid lang code).
    • 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. When a language is required by the format but not specified in the key (e.g. ID3v2 COMM and USLT frames), the default is left to the underlying implementation (ID3v2 defaults to "und").
    • 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.
                ID3v2 COMM frames: bare "comment" has no lang or descriptor;
                "comment-<lang>" for lang only; "comment-<descriptor>-<lang>"
                for both (see descriptor modifier above).
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.
disc_subtitle-- title of a subset, e.g. disc subtitle 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.
lyrics       -- lyrics for the work.
                ID3v2 USLT frames: bare "lyrics" has no lang or descriptor;
                "lyrics-<lang>" for lang only; "lyrics-<descriptor>-<lang>"
                for both (see descriptor modifier above).
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 program
                   represents or that the current stream is part of. On
                   streams it is only set when unambiguous.

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