git.sesse.net Git - ffmpeg/blob - doc/metadata.texi

   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 nanoseconds.
  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