MP4v2 2.0-20090110 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.
The default is to try and act on all tracks in a file; but some actions
will require an individual track be specified.

`--track-any'
     act on any track (default).  Specifies the scope of the action to
     operate on all, if applicable, tracks.

`--track-index IDX'
     act on track id INDEX.  Specifies the scope of the action to
     operate on track-index IDX.

`--track-id ID'
     act on track id ID.  Specifies the scope of the action to operate
     on track-id ID.

`--list'
     list all tracks in mp4.  This will produce a brief report of each
     track for each mp4 file.  IDX shows the track-index (0-based).  ID
     shows the track-id.  TYPE shows the track type.  FLAGS shows track
     flags in hex.  Example output:
          IDX    ID  TYPE      FLAGS   #SAMPL  FILE
          ----------------------------------------------------------------------
            0     1  audio     000001  238500  Song.m4a
            0     1  video     000001  239800  Movie1.m4v
            1     2  audio     000003  468100
            2     3  text      00000e  100000
            0     1  video     000001  239800  Movie2.m4v
            1     2  audio     000003  468100
            2     3  text      00000e  100000

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


