MP4v2 2.0.0 Command-line Tools Guide ************************************ Table of Contents ***************** 1 Overview 2 Introduction 3 Common Options 4 mp4file 5 mp4track 6 mp4art 1 Overview ********** MP4v2 bundles several command-line tools which, in general, allow some basic manipulation of mp4 files which have been created by other means. They are not meant to be a complete solution to management of mp4 file structure. The following is a brief summary of the tools available and the functionality offered. Other tools may be packaged with the distribution but are not yet stable enough to even document. User beware. `mp4file' Operates on the entire file with actions such as list (summary information), optimization and ASCII dumps. `mp4track' Operates on individual tracks with actions such as colr-box and pasp-box manipulation. `mp4art' Operates on iTunes Metadata Cover-art Boxes with actions such as list, add, replace, remove and extraction of Cover-art images. 2 Introduction ************** The tools are invoked by their command-name, followed by one or more options, actions, parameters for actions, and finally one or more files on which the tool will operate. Options are specified in one of two ways; in short or long syntax. A short-syntax option is prefixed with exactly one dash while a long-syntax option is prefixed with exactly two dashes. Depending on the option, it may or may not expect an argument. Specifying an option which expects an argument usually follows either of the following patterns: toolname --something value ... toolname --something=value ... The rest of this guide will use the equals sign method. 3 Common Options **************** Many of the tools share a common set of options which. These common options usually have identically behaving short or long syntax. In some cases short-syntax differs from long-syntax in that it may not require an argument. This style is used sparingly and only when truly convenient. Even though it is common practice in many unix-style tools to permit optional arguments, the tools used in this project will tend to avoid that because it can create a great deal of confusion. The following is a list of common options available: `-y, --dryrun' do not actually create or modify any files. In situations where the command will create new or modify existing files, specifying this option will cause the tool to do as much as possible stopping short of performing any actual writes. This is useful to guard against user mistakes or unexpected behavior. `-k, --keepgoing' continue batch processing even after errors. When actions involve multiple files or operations, the default behavior is to stop and exit on the first error encountered. Specify this option if it is desirable to record the error but continue processing. `-o, --overwrite' overwrite existing files when creating. In situations where a new file will be created, the default behavior is to not overwrite a file if it already exists. Use this option to allow overwriting. `-f, --force' force overwrite even if file is read-only. If overwriting is enabled, file permissions may prevent writes. Specify this option to try and overwrite the file anyways. This usually involves deleting the file, then creating a new one. `-q, --quiet' equivalent to -verbose 0. Default behavior is to print a low amount of informative information, usually one line of text per action/file. Specify this option to omit normal messages. Errors will still be reported. `-d, --debug NUM' increase debug or long-option to set NUM. File I/O with mp4 file structures have special debug options available to users interested in all the fine details. Default is level 1 . The short-syntax is accumulative and takes no argument, while long-syntax takes an argument. For exmaple, the following are equivalent and would set level 3: `-dd' or `-d -d' or `--debug=3'. The following levels are available: 0. supressed 1. add warnings and errors (default) 2. add table details 3. add implicits 4. everything `-v, --verbose NUM' increase verbosity or long-option to set NUM. Tool activity by default will generally print one informative message per action/file. Specify this option to change the default behavior. The short-syntax is accumulative and takes no argument, while long-syntax takes an argument. 0. warnings and errors 1. normal informative messages (default) 2. more informative messages 3. everything `-h, --help' print brief help or long-option for extended help. The short-syntax will produce brief help. Specify the long-option for more extensive help. `--version' print version information and exit. Extended version information used for SCM purposes is not listed in help, but is available by specifying `--verionx'. 4 mp4file ********* `--list' list (summary information). This will produce brief report when summarizing each mp4 file. BRAND shows the file's main brand identifier. COMPAT shows additional brands for which the file purports to be comaptible with. SIZING displays if the file has 64-bit extensions of any kind, otherwise 32-bit. Example output: BRAND COMPAT SIZING FILE ---------------------------------------------------------------------- M4A M4A,isom,mp42 32-bit Song.m4a mp42 isom,mp42 32-bit Movie1.m4v mp42 isom,mp42 32-bit Movie2.m4v `--optimize' optimize mp4 structure. This will rewrite the entire mp4 file which, if needed, will clean up any unused (free) sections, and re-order the atoms in a manner somewhat consistent with the best-practices described in the ISO base media file specification. `--dump' dump mp4 structure in human-readable format. An ASCII dump of mp4 atoms is printed to stdout. This action is heavily influenced by `--debug' option. Example, list some files: mp4file --list *.mp4 *.m4a *.m4v Example, dump a file with more than usual debugging information: mp4file -dd --dump movie.m4v 5 mp4track ********** This tool is used to manage various aspects of individual tracks in an mp4 file. Some of the actions are mp4 (generic) while others may support standards based on mp4 files such as `.m4a' or `.m4v' files. Each action has an appropriate scope upon which it acts. See individual actions for details. The following parameters are used to set scopes for actions: `--track-any' act on any/all tracks. `--track-index IDX' act on a single track specified by index value. A track index is 0-based and counts upwards for each track available. `--track-id ID' act on a single track specified by id value. A track id is a unique value assigned to each track and never changes. The list action will produce a brief report of each track for each mp4 file. Many (but not all) of the values shown may be modified by actions documented later in this article. This will produce a brief report of each track for each mp4 file. `--list' list all tracks in mp4. Example output: track[0] id=1 type = video enabled = true inMovie = false inPreview = false layer = 0 alternateGroup = 0 volume = 0.0000 width = 850.96295166 height = 360.00000000 language = UNDEFINED(0) handlerName = userDataName = The following group of actions are used to modify the values shown by -list action. The modification of these values should be done with great care on any files, and as always you are cautioned to backup your media files before modification. `--enabled BOOL' set trak.tkhd.flags (enabled bit). When true indicates the track is enabled. `--inmovie BOOL' set trak.tkhd.flags (inMovie bit). When true indicates the track is used in the movie. `--inpreview BOOL' set trak.tkhd.flags (inPreview bit). When true indicates the track is used in the movie's preview. `--layer NUM' set trak.tkhd.layer. Specifies the front-to-back ordering of video tracks; tracks with lower numbers are closer to the viewer. 0 is the normal value, and -1 would be in front of track 0, and so on. `--altgroup NUM' set trak.tkhd.alternate_group. An integer that specifies a group or collection of tracks. If this field is 0 there is no information on possible relations to other tracks. If this field is not 0, it should be the same for tracks that contain alternate data for one another and different for tracks belonging to different such groups. Only one track within an alternate group should be played or streamed at any one time, and must be distinguishable from other tracks in the group via attributes such as bitrate, codec, language, packet size etc. A group may have only one member. `--volume FLOAT' set trak.tkhd.volume. Specifies the track's relative audio volume. Full volume is 1.0 and is the normal value. `--width FLOAT' set trak.tkhd.width. Specifies the track's visual presentation width. By default this is the same as the pixel width of the images. All images in the sequence are scaled to this size before any overall transformation by the matrix. `--height FLOAT' set trak.tkhd.height. Specifies the track's visual presentation height. By default this is the same as the pixel width of the images. All images in the sequence are scaled to this size before any overall transformation by the matrix. `--language CODE' set trak.mdia.mdhd.language. Specifies the ISO-639-2/T langauge code of the track. For example, `eng' for English, `fra' for French. `--hdlrname STR' set trak.mdia.hdlr.name. Specifies a human-readable track type (for debugging and inspection purposes). `--udtaname STR' set trak.udta.name.value. Specifies an arbitrary track-name. This value is optional (may be absent). `--udtaname-remove' remove trak.udta.name atom. This action will remove the optional atom. The colr related actions manage Color Parameter boxes which are used by QuickTime to map numerical values of pixels in a file to a common representation of color for video tracks. They may or may not be suitable for other Apple media players. Community feedback on compatibility is welcome. `--colr-list' list all colr-boxes in mp4. `--colr-add' add colr-box to a video track. An individual track must be specified. `--colr-set' set colr-box parms. An individual track must be specified. `--colr-remove' remove colr-box from track. By default all colr-boxes will be removed unless an individual track is specified. `--colr-parms CSV' where CSV is IDX1,IDX2,IDX3 . Specify the exact parameters of an NCLC Color Parameter box as specified in the QuickTime specification. IDX1 correlates to the 16-bit primaries index. IDX2 correlates to the 16-bit transferFunction index. IDX3 correlates to the 16-bit matrixIndex index. Effects actions -colr-add, -colr-set. `--colr-parm-hd' equivalent to -colr-parms=1,1,1 . This is a convenience setting generally suitable for HD content. Effects actions -colr-add, -colr-set. `--colr-parm-sd' equivalent to -colr-parms=6,1,6 . This is a convenience setting generally suitable for SD content. Effects actions -colr-add, -colr-set. Example, add a colr-box tuned for HD content: mp4track --track-id=1 --colr-add --colr-parm-hd mymovie.m4v Example, add a colr-box with arbitrary index parameters: mp4track --track-id=1 --colr-add --colr-parms=2,3,4 mymovie.m4v The pasp related actions manage Picture Aspect Ratio boxes which are used by QuickTime to specify height-to-width ratio of pixels for video tracks. They may or may not be suitable for other Apple media players. Community feedback on compatibility is welcome. `--pasp-list' list all pasp-boxes in mp4. `--pasp-add' add pasp-box to a video track. An individual track must be specified. `--pasp-set' set pasp-box parms. An individual track must be specified. `--pasp-remove' remove pasp-box from track By default all pasp-boxes will be removed unless an individual track is specified. `--pasp-parms CSV' where CSV is hSPACING,vSPACING. Specify the exact parameters of Picture Aspect Ratio box as specified in the QuickTime specification. Effects actions -pasp-add, -pasp-set. Example, add a pasp-box with default (1,1) parameters for square pixels: mp4track --track-id=1 --pasp-add --pasp-parms=1,1 mymovie.m4v Example, add a pasp-box for 16:9 digital 525 (NTSC): mp4track --track-id=1 --pasp-add --pasp-parms=40,33 mymovie.m4v Example, add a pasp-box for 16:9 digital 625 (PAL): mp4track --track-id=1 --pasp-add --pasp-parms=118,81 mymovie.m4v 6 mp4art ******** This tool is used to manage iTunes Metadata Cover-art which is typically used to embed an image to a song file. For example, the songs in an album collection might all contain an image of the album cover art. This data is usually found in `.m4a', `.m4v' and `.mov' files. `--art-any' act on all covr-boxes (default). Specifies the scope of the action to operate on all, if applicable, covr-boxes. `--art-index IDX' act on covr-box index IDX. Specifies the scope of the action to operate on single covr-box INDEX. `--list' list all covr-boxes. IDX BYTES CRC32 TYPE FILE ---------------------------------------------------------------------- 0 173613 710a3ec9 JPEG 01 Life In Technicolor.m4a 0 173613 710a3ec9 JPEG 02 Cemeteries Of London.m4a 0 173613 710a3ec9 JPEG 03 Lost!.m4a 0 173613 710a3ec9 JPEG 04 42.m4a 0 173613 710a3ec9 JPEG 05 Lovers In Japan _ Reign Of Love.m4a 0 173613 710a3ec9 JPEG 06 Yes.m4a 0 173613 710a3ec9 JPEG 07 Viva La Vida.m4a 0 173613 710a3ec9 JPEG 08 Violet Hill.m4a 0 173613 710a3ec9 JPEG 09 Strawberry Swing.m4a 0 173613 710a3ec9 JPEG 10 Death And All His Friends.m4a `--add IMG' add covr-box from IMG file. `--replace IMG' replace covr-box with IMG file. `--remove' remove covr-box. `--extract' extract covr-box. This will extract all covr-box data to image files in the format of `BASENAME.art[INDEX].TYPE' . Example, add PNG image file: mp4art --add ACDC.png mysong.m4a Example, extract image files from file: mp4art --extract mysong.m4a