path: root/doc/metadata.texi (plain)
blob: bddcc99470d2a17fd1950688ce57bb2f37ccd65e

1	@chapter Metadata
2	@c man begin METADATA
3
4	FFmpeg is able to dump metadata from media files into a simple UTF-8-encoded
5	INI-like text file and then load it back using the metadata muxer/demuxer.
6
7	The file format is as follows:
8	@enumerate
9
10	@item
11	A file consists of a header and a number of metadata tags divided into sections,
12	each on its own line.
13
14	@item
15	The header is a @samp{;FFMETADATA} string, followed by a version number (now 1).
16
17	@item
18	Metadata tags are of the form @samp{key=value}
19
20	@item
21	Immediately after header follows global metadata
22
23	@item
24	After global metadata there may be sections with per-stream/per-chapter
25	metadata.
26
27	@item
28	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.
30
31	@item
32	At the beginning of a chapter section there may be an optional timebase to be
33	used for start/end values. It must be in form
34	@samp{TIMEBASE=@var{num}/@var{den}}, where @var{num} and @var{den} are
35	integers. If the timebase is missing then start/end times are assumed to
36	be in milliseconds.
37
38	Next a chapter section must contain chapter start and end times in form
39	@samp{START=@var{num}}, @samp{END=@var{num}}, where @var{num} is a positive
40	integer.
41
42	@item
43	Empty lines and lines starting with @samp{;} or @samp{#} are ignored.
44
45	@item
46	Metadata keys or values containing special characters (@samp{=}, @samp{;},
47	@samp{#}, @samp{\} and a newline) must be escaped with a backslash @samp{\}.
48
49	@item
50	Note that whitespace in metadata (e.g. @samp{foo = bar}) is considered to be
51	a part of the tag (in the example above key is @samp{foo }, value is
52	@samp{ bar}).
53	@end enumerate
54
55	A ffmetadata file might look like this:
56	@example
57	;FFMETADATA1
58	title=bike\\shed
59	;this is a comment
60	artist=FFmpeg troll team
61
62	[CHAPTER]
63	TIMEBASE=1/1000
64	START=0
65	#chapter ends at 0:01:00
66	END=60000
67	title=chapter \#1
68	[STREAM]
69	title=multi\
70	line
71	@end example
72
73	By using the ffmetadata muxer and demuxer it is possible to extract
74	metadata from an input file to an ffmetadata file, and then transcode
75	the file into an output file with the edited ffmetadata file.
76
77	Extracting an ffmetadata file with @file{ffmpeg} goes as follows:
78	@example
79	ffmpeg -i INPUT -f ffmetadata FFMETADATAFILE
80	@end example
81
82	Reinserting edited metadata information from the FFMETADATAFILE file can
83	be done as:
84	@example
85	ffmpeg -i INPUT -i FFMETADATAFILE -map_metadata 1 -codec copy OUTPUT
86	@end example
87
88	@c man end METADATA
89