texinfo
     [file guide.texi not included]

Command-line Tools Guide
************************

Overview
********

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.

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.

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.

     [file mp4file.texi not included]
     [file mp4track.texi not included]
     [file mp4art.texi not included]