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