[deb_ffmpeg.git] / ffmpeg / doc / metadata.texi

@chapter Metadata
@c man begin METADATA

FFmpeg is able to dump metadata from media files into a simple UTF-8-encoded
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
The header is a ';FFMETADATA' string, followed by a version number (now 1).

@item
Metadata tags are of the form 'key=value'

@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
brackets ('[', ']') and ends with next section or end of file.

@item
At the beginning of a chapter section there may be an optional timebase to be
used for start/end values. It must be in form 'TIMEBASE=num/den', where num and
den are integers. If the timebase is missing then start/end times are assumed to
be in milliseconds.
Next a chapter section must contain chapter start and end times in form
'START=num', 'END=num', where num is a positive integer.

@item
Empty lines and lines starting with ';' or '#' are ignored.

@item
Metadata keys or values containing special characters ('=', ';', '#', '\' and a
newline) must be escaped with a backslash '\'.

@item
Note that whitespace in metadata (e.g. foo = bar) is considered to be a part of
the tag (in the example above key is 'foo ', value is ' bar').
@end enumerate

A ffmetadata file might look like this:
@example
;FFMETADATA1
title=bike\\shed
;this is a comment
artist=FFmpeg troll team

[CHAPTER]
TIMEBASE=1/1000
START=0
#chapter ends at 0:01:00
END=60000
title=chapter \#1
[STREAM]
title=multi\
line
@end example

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

@c man end METADATA
Commit	Line	Data
2ba45a60 DM	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 ';FFMETADATA' string, followed by a version number (now 1).
	16
	17	@item
	18	Metadata tags are of the form '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 ('[', ']') 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 'TIMEBASE=num/den', where num and
	34	den are integers. If the timebase is missing then start/end times are assumed to
	35	be in milliseconds.
	36	Next a chapter section must contain chapter start and end times in form
	37	'START=num', 'END=num', where num is a positive integer.
	38
	39	@item
	40	Empty lines and lines starting with ';' or '#' are ignored.
	41
	42	@item
	43	Metadata keys or values containing special characters ('=', ';', '#', '\' and a
	44	newline) must be escaped with a backslash '\'.
	45
	46	@item
	47	Note that whitespace in metadata (e.g. foo = bar) is considered to be a part of
	48	the tag (in the example above key is 'foo ', value is ' bar').
	49	@end enumerate
	50
	51	A ffmetadata file might look like this:
	52	@example
	53	;FFMETADATA1
	54	title=bike\\shed
	55	;this is a comment
	56	artist=FFmpeg troll team
	57
	58	[CHAPTER]
	59	TIMEBASE=1/1000
	60	START=0
	61	#chapter ends at 0:01:00
	62	END=60000
	63	title=chapter \#1
	64	[STREAM]
65	title=multi\
66	line
67	@end example
68
69	By using the ffmetadata muxer and demuxer it is possible to extract
70	metadata from an input file to an ffmetadata file, and then transcode
71	the file into an output file with the edited ffmetadata file.
72
73	Extracting an ffmetadata file with @file{ffmpeg} goes as follows:
74	@example
75	ffmpeg -i INPUT -f ffmetadata FFMETADATAFILE
76	@end example
77
78	Reinserting edited metadata information from the FFMETADATAFILE file can
79	be done as:
80	@example
81	ffmpeg -i INPUT -i FFMETADATAFILE -map_metadata 1 -codec copy OUTPUT
82	@end example
83
84	@c man end METADATA