extra-dependencies/debian/mp4v2/mp4v2-2.0.0~dfsg0/doc/ToolGuide.txt

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

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