2016-06-12

Adventures in Ffmpeg Meta Data Writing to MP4 Containers

Venturing in the world of adding useful meta data to video files using ffmpeg gets us on really difficult terrain. It sort of feels like we're back in the early days of MP3 audio files. Not much hard documentation and everyone seems to say something else. Fortunately, a dive into ffmpeg's source code allowed me to surface with a simple list of meta data supported for MP4 containers.


Meta What?


More and more media players make good use of meta information embedded inside video files. Only such meta information allows for organizing potentially large video collections. Also, you may get a description or synopsis of what to except before watching.

Of particular note surely is Apple's iTunes software. It more or less is the reference for what meta data can be used at best.

Ffmpeg Supported Meta Information 


It's unfortunate that the current official ffmpeg documentation on supported meta data tags for MP4 containers is neither comprehensive nor completely correct. After a lot of fruitless attempts at getting my meta data correctly attached to my video files, I finally found this place in the source (that is, mov_write_ilst_tag() in movenc.c) where ffmpegs actually lists the meta data keys it writes to MP4 audio/video container files (file ending .mp4, .m4v, as well as some others).

Note: a video file name ending in .mov is considered to be of type MODE_MOV: this mode supports only a subset of the elements listed above. Most other file endings, such as .mp4, will make ffmpeg default to type MODE_MP4. In this mode, ffmpeg supports most iTunes meta data elements. Also, such iTunes meta data ends up in a different meta data branch than meta data for MODE_MOV. Oh, well...
Element ffmpeg Metadata Key Description Internal Tag Name
TitletitleTitle of video. (String)©nam
YeardateThe data of production. (String)

Please note that the ffmpeg documentation unfortunately is completely wrong here; the correct key for this meta data is in fact date but definitely not year. This can also been in the source code: ffmpeg/movenc.c.
©day
CopyrightcopyrightThe copyright of the video. (String)©cpy
ArtistartistThe name of the (video) artist. Please don't use this element for the composer, as there is a dedicated element for it (see below). (String)©ART
Album Artistalbum_artistThe name of the album artist: this may be a guest artist or a featured artist. This can also be left out or the same name as the artist.
(String)
aART
ComposercomposerThe name of the composer.
(String)
©wrt
AlbumalbumThe title or name of the album.
(String)
©alb
DescriptiondescriptionA (content) description of this video. For a synopsis, see below instead. (String)desc
CommentcommentA comment on this video. This will be probably a comment set by an end user but not at time of production. (String)©cmt
SynopsissynopsisA synopsis (or longer description) of this video. (String)ldes
GenregenreThe genre this video belongs to. (String)©gen
GroupinggroupingThe name of a group of videos that somehow belong together. In contrast to the album element, grouping is inside the album level.
(String)
©grp

ShowshowThe name of the TV show.
(String)
tvsh
Episodeepisode_idEither a episode name or episode number for display. Different from display is an optional episode number for sorting, see below.
(String)
tven
Episode for Sortingepisode_sortThe episode number as used for sorting. This field is for sorting only, never for display. It allows numerical sort for episode names that are originally a string. The valid range is 0 to 255, so don't let your mega busta run for too many seasons. (int8)tves
Seasonseason_numberThe season number, which can be in the range of 0 to 255.
(int8)
tvsn
LyricslyricsOptional lyrics for this video.
(String)
©lyr
CompilationcompilationIs this file part of a compilation? Allowed values are: 0 or 1. (int8)cpil