[FFmpeg-devel] [PATCH] doc/metadata.texi: Start documenting keys

[FFmpeg-devel] [PATCH] doc/metadata.texi: Start documenting keys

[Tomas Härdin]

[-- Attachment #1: Type: text/plain, Size: 702 bytes --]

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

[-- Attachment #2: 0001-doc-metadata.texi-Start-documenting-keys.patch --]
[-- Type: text/x-patch, Size: 8355 bytes --]

From e5909ffbdd2b993aab1574901741eed2953c6600 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Tomas=20H=C3=A4rdin?= <git@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


[-- Attachment #3: Type: text/plain, Size: 251 bytes --]

_______________________________________________
ffmpeg-devel mailing list
ffmpeg-devel@ffmpeg.org
https://ffmpeg.org/mailman/listinfo/ffmpeg-devel

To unsubscribe, visit link above, or email
ffmpeg-devel-request@ffmpeg.org with subject "unsubscribe".

Re: [FFmpeg-devel] [PATCH] doc/metadata.texi: Start documenting keys

[Tomas Härdin]

ons 2025-02-19 klockan 16:42 +0100 skrev Tomas Härdin:
> 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?

Ping? Getting this in place hopefully means it gets populated over
time.

/Tomas
_______________________________________________
ffmpeg-devel mailing list
ffmpeg-devel@ffmpeg.org
https://ffmpeg.org/mailman/listinfo/ffmpeg-devel

To unsubscribe, visit link above, or email
ffmpeg-devel-request@ffmpeg.org with subject "unsubscribe".

Re: [FFmpeg-devel] [PATCH] doc/metadata.texi: Start documenting keys

[Andreas Rheinhardt]

Tomas Härdin:
> +@item ref-frame-config @tab @tab @tab
> +@item reverb @tab S @tab argo_cvg @tab

The first is libvp9enc-only, the second argo_cvg only. IMO it is better
to document this at the documentation of the relevant encoder and demuxer.

- Andreas

_______________________________________________
ffmpeg-devel mailing list
ffmpeg-devel@ffmpeg.org
https://ffmpeg.org/mailman/listinfo/ffmpeg-devel

To unsubscribe, visit link above, or email
ffmpeg-devel-request@ffmpeg.org with subject "unsubscribe".

Re: [FFmpeg-devel] [PATCH] doc/metadata.texi: Start documenting keys

[Marvin Scholz]

On 4 Mar 2025, at 12:36, Andreas Rheinhardt wrote:

> Tomas Härdin:
>> +@item ref-frame-config @tab @tab @tab
>> +@item reverb @tab S @tab argo_cvg @tab
>
> The first is libvp9enc-only, the second argo_cvg only. IMO it is better
> to document this at the documentation of the relevant encoder and demuxer.
>

IMHO it is useful to have a centralised list somewhere, to know what 'custom'
metadata to expect from FFmpeg in some cases, without having to check every
possibly relevant components docs.

> - Andreas
>
> _______________________________________________
> ffmpeg-devel mailing list
> ffmpeg-devel@ffmpeg.org
> https://ffmpeg.org/mailman/listinfo/ffmpeg-devel
>
> To unsubscribe, visit link above, or email
> ffmpeg-devel-request@ffmpeg.org with subject "unsubscribe".
_______________________________________________
ffmpeg-devel mailing list
ffmpeg-devel@ffmpeg.org
https://ffmpeg.org/mailman/listinfo/ffmpeg-devel

To unsubscribe, visit link above, or email
ffmpeg-devel-request@ffmpeg.org with subject "unsubscribe".

Re: [FFmpeg-devel] [PATCH] doc/metadata.texi: Start documenting keys

[Tomas Härdin]

tis 2025-03-04 klockan 12:36 +0100 skrev Andreas Rheinhardt:
> Tomas Härdin:
> > +@item ref-frame-config @tab @tab @tab
> > +@item reverb @tab S @tab argo_cvg @tab
> 
> The first is libvp9enc-only, the second argo_cvg only. IMO it is
> better
> to document this at the documentation of the relevant encoder and
> demuxer.

For format-specific metadata maybe. But for metadata supported by
multiple formats, where the user can expect to be able to convert from
one format to the other while keeping the metadata, we'll want a single
place where this is documented, or else users have less chance of
seeing this feature. And then you have a central anyway so you might as
well put all the keys in it rather than having them spread out all over
the docs.

Maybe we could *also* put the keys in the docs for the relevant
formats, filters etc. But then there's a a higher risk of that getting
out of sync with the table.

/Tomas
_______________________________________________
ffmpeg-devel mailing list
ffmpeg-devel@ffmpeg.org
https://ffmpeg.org/mailman/listinfo/ffmpeg-devel

To unsubscribe, visit link above, or email
ffmpeg-devel-request@ffmpeg.org with subject "unsubscribe".