Hi
Rather than continue the RFC thread for this, I decided to submit a
patch that begins the process of documenting metadata keys.
There's quite a lot of keys used in the codebase, and this patch does
not cover all of them. But it should give the general idea. I follow a
similar approach to that used by ffmpeg -codecs to try and keep the
number of columns sane.
One issue I discovered is that pod2man does not seem to support
@multitable very well, and @headitem causes it to fail outright. Not
sure what to do about that. This issue exists with other @multitable in
the documentation. See "man doc/ffmpeg-all.1" and search for "Audio
Codecs"
Anyway, thoughts on this?
/Tomas
From e5909ffbdd2b993aab1574901741eed2953c6600 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Tomas=20H=C3=A4rdin?= <g...@haerdin.se>
Date: Wed, 19 Feb 2025 16:24:16 +0100
Subject: [PATCH] doc/metadata.texi: Start documenting keys
---
doc/metadata.texi | 181 ++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 181 insertions(+)
diff --git a/doc/metadata.texi b/doc/metadata.texi
index e081da7735..4eacdfe59f 100644
--- a/doc/metadata.texi
+++ b/doc/metadata.texi
@@ -86,4 +86,185 @@ be done as:
ffmpeg -i INPUT -i FFMETADATAFILE -map_metadata 1 -codec copy OUTPUT
@end example
+@section Metadata keys
+
+This section contains a non-exhaustive table of metadata keys, where they can appear and within which formats.
+The "Where" column describes where each key in question can reside.
+It is a concatenation of the "flags" listed below:
+
+@table @samp
+@item F
+Format
+@item P
+Program
+@item C
+Chapter
+@item S
+Stream
+@item f
+frame
+@end table
+
+In other words an entry like "FSf" means the key in question can be format-wide (F), apply to a specific stream (S) or to individual audio/video frames (f).
+Letters in parenthesis, such as "(F)", are discouraged methods of passing metadata to muxers.
+See for example @samp{alpha_mode}.
+
+The "Format(s)" column specifies which container format(s) each key can be used with.
+Typically this means the key can be carried from demuxer to muxer.
+In some cases a key might only be supported by the demuxer or by the muxer of a specific format.
+Such cases are not explicitly documented in this list (yet).
+
+@multitable @columnfractions .25 .05 .25 .45
+@c pod2man does not seem to support @headitem
+@item @b{Key} @tab @b{Where} @tab @b{Format(s)} @tab @b{Comment}
+@item absolute_start_time @tab F @tab iff @tab
+@item album @tab F @tab asf au avi lrc mov wav wsd @tab
+@item album_artist @tab F @tab asf flac matroska mov mp3 ogg @tab
+@item alpha_mode @tab (F)S @tab matroska @tab @code{matroskadec} sets @samp{alpha_mode} only on the stream. @code{matroskaenc} accepts @samp{alpha_mode} on either stream or format, preferring to read it from the stream
+@item artist @tab F @tab adf asf au avi bin idf iff libopenmpt lrc mov mp3 nut tiff wsd xbin @tab
+@item author @tab F @tab adf aiff asf bin dss idf libgme lrc mov rm rpl vqf xbin @tab
+@item checksum @tab S @tab argo_cvg @tab Checksum of header, data and footer bytes
+@item coding_history @tab F @tab wav @tab bext
+@item comment @tab FS @tab adf aiff asf avi bin dss flac gif hls idf iff libgme libopenmpt matroska mov mp3 mv nut ogg rm rtp smjpeg sox vqf wav wsd xbin @tab
+@c Keys checked down to just above here
+@item Comment @tab @tab @tab
+@item comment_time @tab @tab @tab
+@item company_name @tab @tab @tab
+@item compatible_brands @tab @tab @tab
+@item composer @tab F @tab asf @tab
+@item copyright @tab F @tab aiff avi @tab
+@item Copyright @tab @tab @tab
+@item creation_time @tab F @tab avi @tab Nikon metadata (avi)
+@item Creator @tab @tab @tab
+@item data_type @tab @tab @tab
+@item date @tab F @tab avi @tab
+@item description @tab F @tab wav @tab bext
+@item disc @tab F @tab asf @tab
+@item duration @tab @tab @tab
+@item enc_key_id @tab @tab @tab
+@item encoded_by @tab F @tab asf avi @tab
+@item encoder @tab F @tab asf avi @tab
+@item encryption @tab @tab @tab
+@item extra info @tab @tab @tab
+@item fileinfo @tab @tab @tab
+@item filename @tab F @tab asf @tab
+@item file_package_name @tab @tab @tab
+@item gamma @tab @tab @tab
+@item genre @tab F @tab asf avi @tab
+@item guid @tab @tab @tab
+@item handler_name @tab @tab @tab
+@item Input Device @tab @tab @tab
+@item isoMode @tab @tab @tab
+@item language @tab F @tab asf avi @tab
+@item lavf.concatdec.duration @tab @tab @tab
+@item lavf.concatdec.start_time @tab @tab @tab
+@item lavfi.asr.text @tab @tab @tab
+@item lavfi.black_end @tab @tab @tab
+@item lavfi.black_start @tab @tab @tab
+@item lavfi.color_quant_ratio @tab @tab @tab
+@item lavfi.cropdetect.limit @tab @tab @tab
+@item lavfi.deflicker.luminance @tab @tab @tab
+@item lavfi.deflicker.new_luminance @tab @tab @tab
+@item lavfi.deflicker.relative_change @tab @tab @tab
+@item lavfi.idet.multiple.bff @tab @tab @tab
+@item lavfi.idet.multiple.current_frame @tab @tab @tab
+@item lavfi.idet.multiple.progressive @tab @tab @tab
+@item lavfi.idet.multiple.tff @tab @tab @tab
+@item lavfi.idet.multiple.undetermined @tab @tab @tab
+@item lavfi.idet.repeated.bottom @tab @tab @tab
+@item lavfi.idet.repeated.current_frame @tab @tab @tab
+@item lavfi.idet.repeated.neither @tab @tab @tab
+@item lavfi.idet.repeated.top @tab @tab @tab
+@item lavfi.idet.single.bff @tab @tab @tab
+@item lavfi.idet.single.current_frame @tab @tab @tab
+@item lavfi.idet.single.progressive @tab @tab @tab
+@item lavfi.idet.single.tff @tab @tab @tab
+@item lavfi.idet.single.undetermined @tab @tab @tab
+@item lavfi.ocr.confidence @tab @tab @tab
+@item lavfi.ocr.text @tab @tab @tab
+@item lavfi.photosensitivity.badness @tab @tab @tab
+@item lavfi.photosensitivity.factor @tab @tab @tab
+@item lavfi.photosensitivity.fixed-badness @tab @tab @tab
+@item lavfi.photosensitivity.frame-badness @tab @tab @tab
+@item lavfi.quirc.count @tab @tab @tab
+@item lavfi.readvitc.found @tab @tab @tab
+@item lavfi.readvitc.tc_str @tab @tab @tab
+@item lavfi.rect.h @tab @tab @tab
+@item lavfi.rect.score @tab @tab @tab
+@item lavfi.rect.w @tab @tab @tab
+@item lavfi.rect.x @tab @tab @tab
+@item lavfi.rect.y @tab @tab @tab
+@item lavfi.scene_score @tab @tab @tab
+@item lavfi.signalstats. @tab @tab @tab
+@item lavfi.signalstats.HUEMED @tab @tab @tab
+@item lavfi.signalstats.SATHIGH @tab @tab @tab
+@item lavfi.signalstats.SATLOW @tab @tab @tab
+@item lavfi.signalstats.SATMAX @tab @tab @tab
+@item lavfi.signalstats.SATMIN @tab @tab @tab
+@item lavfi.signalstats.UBITDEPTH @tab @tab @tab
+@item lavfi.signalstats.UHIGH @tab @tab @tab
+@item lavfi.signalstats.ULOW @tab @tab @tab
+@item lavfi.signalstats.UMAX @tab @tab @tab
+@item lavfi.signalstats.UMIN @tab @tab @tab
+@item lavfi.signalstats.VBITDEPTH @tab @tab @tab
+@item lavfi.signalstats.VHIGH @tab @tab @tab
+@item lavfi.signalstats.VLOW @tab @tab @tab
+@item lavfi.signalstats.VMAX @tab @tab @tab
+@item lavfi.signalstats.VMIN @tab @tab @tab
+@item lavfi.signalstats.YBITDEPTH @tab @tab @tab
+@item lavfi.signalstats.YHIGH @tab @tab @tab
+@item lavfi.signalstats.YLOW @tab @tab @tab
+@item lavfi.signalstats.YMAX @tab @tab @tab
+@item lavfi.signalstats.YMIN @tab @tab @tab
+@item loop @tab S @tab argo_cvg @tab
+@item loop_end @tab @tab @tab
+@item loop_start @tab @tab @tab
+@item major_brand @tab @tab @tab
+@item maker @tab F @tab avi @tab Nikon metadata (avi)
+@item material_package_name @tab @tab @tab
+@item material_track_origin @tab @tab @tab
+@item message @tab @tab @tab
+@item mimetype @tab @tab @tab
+@item minor_version @tab @tab @tab
+@item model @tab F @tab avi @tab Nikon metadata (avi)
+@item name @tab @tab @tab
+@item operational_pattern_ul @tab @tab @tab
+@item origination_date @tab F @tab wav @tab bext
+@item origination_time @tab F @tab wav @tab bext
+@item originator @tab F @tab wav @tab bext
+@item originator_reference @tab F @tab wav @tab bext
+@item playback_time @tab @tab @tab
+@item product @tab F @tab avi @tab
+@item product_name @tab @tab @tab
+@item product_version @tab @tab @tab
+@item publisher @tab F @tab asf @tab
+@item reel_name @tab @tab @tab
+@item ref-frame-config @tab @tab @tab
+@item reverb @tab S @tab argo_cvg @tab
+@item service_name @tab F @tab asf @tab
+@item service_provider @tab F @tab asf @tab
+@item size @tab @tab @tab
+@item software @tab F @tab avi @tab
+@item Source @tab @tab @tab
+@item source_track_origin @tab @tab @tab
+@item start @tab @tab @tab
+@item stereo_mode @tab @tab @tab
+@item subject @tab F @tab avi @tab
+@item time @tab @tab @tab
+@item timecode @tab F @tab avi @tab
+@item time_reference @tab F @tab wav @tab
+@item title @tab FCS @tab aiff wav avi @tab
+@item Title @tab @tab @tab
+@item track @tab F @tab asf avi @tab
+@item track_name @tab @tab @tab
+@item umid @tab F @tab wav @tab bext
+@item variant_bitrate @tab @tab @tab
+@item ve @tab @tab @tab
+@item vendor_id @tab @tab @tab
+@item VIEWPORT @tab @tab @tab
+@item WAVEFORMATEXTENSIBLE_CHANNEL_MASK @tab @tab @tab
+@item writer @tab @tab @tab
+@item xmp @tab @tab @tab
+@end multitable
+
@c man end METADATA
--
2.39.5
_______________________________________________
ffmpeg-devel mailing list
ffmpeg-devel@ffmpeg.org
https://ffmpeg.org/mailman/listinfo/ffmpeg-devel
To unsubscribe, visit link above, or email
ffmpeg-devel-requ...@ffmpeg.org with subject "unsubscribe".
