metadata.texi 2.39 KB
Newer Older
Anton Khirnov's avatar
Anton Khirnov committed
1 2 3
@chapter Metadata
@c man begin METADATA

4
FFmpeg is able to dump metadata from media files into a simple UTF-8-encoded
Anton Khirnov's avatar
Anton Khirnov committed
5 6 7 8 9 10 11 12 13 14
INI-like text file and then load it back using the metadata muxer/demuxer.

The file format is as follows:
@enumerate

@item
A file consists of a header and a number of metadata tags divided into sections,
each on its own line.

@item
15
The header is a @samp{;FFMETADATA} string, followed by a version number (now 1).
Anton Khirnov's avatar
Anton Khirnov committed
16 17

@item
18
Metadata tags are of the form @samp{key=value}
Anton Khirnov's avatar
Anton Khirnov committed
19 20 21 22 23 24 25 26 27 28

@item
Immediately after header follows global metadata

@item
After global metadata there may be sections with per-stream/per-chapter
metadata.

@item
A section starts with the section name in uppercase (i.e. STREAM or CHAPTER) in
29
brackets (@samp{[}, @samp{]}) and ends with next section or end of file.
Anton Khirnov's avatar
Anton Khirnov committed
30 31 32

@item
At the beginning of a chapter section there may be an optional timebase to be
33 34 35
used for start/end values. It must be in form
@samp{TIMEBASE=@var{num}/@var{den}}, where @var{num} and @var{den} are
integers. If the timebase is missing then start/end times are assumed to
Anton Khirnov's avatar
Anton Khirnov committed
36
be in milliseconds.
37

Anton Khirnov's avatar
Anton Khirnov committed
38
Next a chapter section must contain chapter start and end times in form
39 40
@samp{START=@var{num}}, @samp{END=@var{num}}, where @var{num} is a positive
integer.
Anton Khirnov's avatar
Anton Khirnov committed
41 42

@item
43
Empty lines and lines starting with @samp{;} or @samp{#} are ignored.
Anton Khirnov's avatar
Anton Khirnov committed
44 45

@item
46 47
Metadata keys or values containing special characters (@samp{=}, @samp{;},
@samp{#}, @samp{\} and a newline) must be escaped with a backslash @samp{\}.
Anton Khirnov's avatar
Anton Khirnov committed
48 49

@item
50 51 52
Note that whitespace in metadata (e.g. @samp{foo = bar}) is considered to be
a part of the tag (in the example above key is @samp{foo }, value is
@samp{ bar}).
Anton Khirnov's avatar
Anton Khirnov committed
53 54 55 56 57 58 59
@end enumerate

A ffmetadata file might look like this:
@example
;FFMETADATA1
title=bike\\shed
;this is a comment
60
artist=FFmpeg troll team
Anton Khirnov's avatar
Anton Khirnov committed
61 62 63 64 65 66 67 68 69 70 71

[CHAPTER]
TIMEBASE=1/1000
START=0
#chapter ends at 0:01:00
END=60000
title=chapter \#1
[STREAM]
title=multi\
line
@end example
72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87

By using the ffmetadata muxer and demuxer it is possible to extract
metadata from an input file to an ffmetadata file, and then transcode
the file into an output file with the edited ffmetadata file.

Extracting an ffmetadata file with @file{ffmpeg} goes as follows:
@example
ffmpeg -i INPUT -f ffmetadata FFMETADATAFILE
@end example

Reinserting edited metadata information from the FFMETADATAFILE file can
be done as:
@example
ffmpeg -i INPUT -i FFMETADATAFILE -map_metadata 1 -codec copy OUTPUT
@end example

Anton Khirnov's avatar
Anton Khirnov committed
88
@c man end METADATA