FAAM Command-Line Manual Page

The reference below is generated automatically from the upstream faam.1 manual page.

NAME

faam - MP4 muxer, demuxer and tag editor for AAC audio and H.264/H.265 video

SYNOPSIS

faam-iinput [-iinput...] -oout.mp4 [options]

faam {info | dump } file

faam demuxfile [options]

faam tagfile [options]

faam chapter {import | export } file [options]

DESCRIPTION

FAAM reads and writes ISO BMFF files: MP4, M4A and M4B. It is a front end to the libfaam library, licensed under the LGPL license. It does not encode or decode audio or video. The subcommands are:

• -i, -o With no subcommand word, mux one or more elementary streams (ADTS AAC, Annex-B H.264 or H.265) into an MP4.
• info Print container, track, tag, gapless and chapter summaries.
• dump Print the MP4 atom tree.
• demux Extract one track's elementary stream.
• tag Edit iTunes metadata tags in place.
• chapter Import or export the chapters of an audiobook.

Text output and success messages go to stdout; errors go to stderr. When a command writes media or a chapter list to stdout, its status messages go to stderr. Use - as an input or output path to read stdin or write stdout. Inputs that need seeking are spooled to a temporary file; AAC mux input is read as a stream. H.264 and H.265 need a build with the muxer-video option (enabled by default); without it muxing video fails with an error. faam writes progressive files by default. When the output is -, it streams fragmented MP4 to stdout in one-second fragments when the build supports fragmented MP4. For stdout muxing, the --faststart option, M4B branding, and gapless delay or padding select progressive output. Progressive stdout is written after muxing finishes. Builds without fragmented MP4 support also use progressive output. Fragmented MP4 files can be read by info, dump and demux in a build with the muxer-fragmented option (enabled by default).

HELP OPTIONS

--help-<group> and --license must be the first argument.

• -h, --help Display a short help text. After a subcommand, display the options of that subcommand.
• -H Display a description of all options.
• --help-commands, --help-mux, --help-inspect, --help-tag, --help-chapter Display the description of one group of options.
• --license Display copyright and license information.

VERBOSITY

-v <verbose> Set verbosity level: -v accepts values from 0 through 2; -v0 is quiet mode and suppresses success confirmation messages; -v1 (default) prints standard status and completion messages; -v2 shows a detailed summary block upon completion. Errors are always written to stderr.

MUX OPTIONS

• -i, --input <file> Elementary stream to mux: ADTS AAC, or Annex-B H.264 or H.265. Repeat for more tracks, up to 8. The path - reads one input track from stdin.
• -o, --output <file> Output MP4 file. Required. The path - writes MP4 to stdout; see the streaming behavior above. An output that exists is refused unless --overwrite is given. An output that is one of the inputs, spelled another way or reached through a link, is refused even with --overwrite. A failed mux removes a partial file; data already written to stdout cannot be recalled.
• --overwrite Overwrite an existing output file.
• --codec:N <codec> Codec of the Nth -i, counting from 0: aac, h264 (or avc) or h265 (or hevc). Without it the codec follows the file extension: .264 / .h264 for H.264, .265 / .hevc for H.265, anything else AAC.
• --brand <name>m4b writes an audiobook brand; m4a is the default. Anything else is an error. Files with a video track use the isom brand regardless.
• --faststart Write the index (moov) before the media data, so the file starts playing while it downloads. This rewrites the whole file when muxing ends and the output is not a valid MP4 until it finishes, so do not use it on flash recorders.
• --width <pixels>, --height <pixels> Size of video tracks, 1 to 65535. Required for video, as the stream is not parsed for it.
• --rotation <degrees> Display rotation of video tracks, clockwise: 0 (the default), 90, 180 or 270. It is written to the track's display matrix; the pictures are not rotated.
• --fps <n[/d]> Frame rate of video tracks, a whole number or a fraction such as 30000/1001. The default is 30.
• --encoder-delay <samples> Leading priming samples of the audio, written as gapless information (an iTunSMPB atom and an edit list). An error without an audio track. The value is in samples at the track's sample rate, which for HE-AAC is the core rate, half the output rate. The encoder reports it: see EXAMPLES.
• --padding-delay <samples> Trailing padding samples of the audio, written as gapless information. The length of the program is derived from the frames muxed minus the delay and the padding, so without this option the padding is not trimmed.
• --sbr-signaling <mode> ADTS cannot say whether SBR or PS follow, so the caller does. none (the default) leaves it to the decoder, compatible writes backward-compatible signaling, explicit hierarchical signaling, ps and ps-explicit the same for HE-AAC v2, which needs a mono core. Anything else is an error.
• --language <code3>, --lang <code3> ISO 639-2/T language code of the audio tracks, for example eng or ger. It must be three letters, in either case; the default is und.
• --creation-time <value> Creation and modification time of the file. auto uses the modification time of the first input, now the current time, and a number is a Unix time in seconds that fits 32 bits; larger or negative values are refused. Without the option the SOURCE_DATE_EPOCH environment variable is used when set, otherwise the time is left unset (0). An invalid value gives a warning and 0.

Every option listed under TAG OPTIONS except --remove and --clear also applies when muxing.

ADTS input:

• The AAC object type, sample rate and channel configuration are read from the first ADTS header, which must be valid and must follow an optional ID3v2 tag.
• Each frame is muxed as one 1024-sample unit, so a stream whose frames hold more than one raw data block (number_of_raw_data_blocks above 0) is an error.
• A channel configuration of 0 means the layout is in a program config element, which the first frame must open with; the AudioSpecificConfig is built from it. Eight-channel streams from faac are signaled this way.
• Bytes that are not a frame header are skipped, and so are frames whose profile, rate or channels differ from the first header's, as they are most likely false syncs.
• The ps modes need a mono core.

Video input:

• One picture is muxed per sample in stream order. The avcC or hvcC is built from the parameter sets in the stream, which must hold them.
• B-frames are not supported: no composition time offsets are written, so reordered pictures would play out of order.
• --width and --height are required.

INSPECT AND EXTRACT OPTIONS

info and dump take only the file name. info prints, in this order and omitting sections the file does not have:

Container: ISO BMFF (major brand M4A)
Tracks Count: 1

Track #1 (ID 1):
  Type: Audio
  Codec: AAC
  Timescale: 44100
  Sample Rate: 44100 Hz
  Channels: 2
  AAC Object Type: 2 (AAC-LC)
  SBR Present: No
  PS Present: No
  Total Frames: 131

Metadata Tags:
  Title: Song
  Track: 3/12

Gapless Audio Metadata:
  Encoder Delay: 1024 samples
  Trailing Padding: 820 samples

Chapters / Bookmarks (2 entries):
  Chapter #1: start=0 ms, title="Intro"
  Chapter #2: start=90500 ms, title="Part 2"

A track whose codec is not AAC, H.264 or H.265 is listed as Generic. dump lists the top-level boxes and what is inside moov.

demux accepts:

• -o, --output <file> Output file, output.raw by default. The path - writes the extracted stream to stdout. A name containing .aac or .adts gets ADTS headers, built from the track's AudioSpecificConfig, on AAC frames, with a layout held in a program config element written into the first frame and every 32nd after it; video is written as Annex-B. An output that exists is refused unless --overwrite is given; an output that is the input is always refused. A failed run removes a partial file; data already written to stdout cannot be recalled.
• --format <raw|adts> Choose raw AAC or ADTS output explicitly. By default, output names containing .aac or .adts select ADTS; other names, including -, select raw AAC. ADTS output requires an AAC audio track.
• -t, --track <id> Track ID to extract, the first track by default.
• --export-asc <file> Also write the track's codec configuration (AudioSpecificConfig, avcC or hvcC).
• --overwrite Overwrite an existing output or --export-asc file.

TAG OPTIONS

faam tag rewrites the tags of file in place. Existing tags are kept unless removed, so only the given fields change; All untouched metadata atoms, including unknown tags and every cover image, are preserved byte-for-byte in original relative order. Files using QuickTime keys metadata (mdta handler) are refused without modification. A file that cannot be read as an MP4 is refused and left untouched. The edit is not crash-safe: work on a copy of a file that matters. Text is converted to UTF-8. All options except --remove and --clear also work when muxing.

• --title, --artist, --album, --albumartist, --composer <text> Set the field.
• --titlesort, --artistsort, --albumsort, --albumartistsort, --composersort <text> Set the sort name of the field.
• --year, --comment <text> Set the field.
• --lyrics <text>, --lyrics-file <file> Set plain embedded lyrics in the standard ©lyr atom. File input must be UTF-8, with an optional UTF-8 BOM, and contain no NUL bytes. Line breaks and surrounding whitespace are preserved. An empty file writes empty lyrics; use --remove lyrics to delete the tag. Repeated lyrics options use the last value. No timing synchronization is implied.
• --grouping, --copyright, --description, --long-description, --work, --movement <text> Set the corresponding native text atom.
• --bpm, --movement-number, --movement-total <number> Set a two-byte integer from 0 to 65535.
• --show-work-movement Enable display of classical work and movement names.
• --genre <value> An ID3v1 genre number (0 to 191) or name is stored as the text genre, and a numeric genre already in the file is removed. Names ignore case, spacing and punctuation, so hip hop finds Hip-Hop; any other value is stored as typed. Anything else is stored as free text without the numeric atom.
• --compilation Mark the file as part of a compilation.
• --track <n[/total]>, --disc <n[/total]> Set the track or disc number.
• --cover-art <file> Cover image, GIF, JPEG, PNG or BMP, up to 32 MiB. The format is detected from the file contents; a BMP needs valid file and DIB headers.
• --tag <name=value> Custom tag; the name and the value are separated by the first = or ,. Both must be non-empty. Repeat for more.
• --remove <field> Remove a field before the other options apply. The fields are title, titlesort, artist, artistsort, album, albumsort, albumartist, albumartistsort, composer, composersort, year, comment, genre, compilation, track, disc, cover-art, lyrics, grouping, copyright, description, long-description, work, movement, bpm, movement-number, movement-total, show-work-movement, encoder, genre-code and custom (all freeform tags except iTunSMPB). Repeatable, up to 32 times. An unknown field is an error.
• --clear Remove every existing tag and preserved atom before the other options apply.

CHAPTER OPTIONS

• import <file> Replace the chapters of file with those of the --chapters file. The tags are kept.
• export <file> Write the chapters of file to the -o file; the path - reads the MP4 from stdin. A file without chapters is an error.
• --chapters <file> Chapter list to import; the path - reads the list from stdin.
• -o, --output <file> Chapter list to write; the path - writes it to stdout. An output that exists is refused unless --overwrite is given; the input file is always refused.
• --overwrite Overwrite an existing chapter list on export.

A chapter list has one line per chapter, a time, a tab and a title, as in 00:01:30.500<TAB>Chapter 2. The time is HH:MM:SS.mmm with one to three fractional digits, so .5 is 500 ms. At most 255 chapters are read, a list without chapters is an error, and titles are cut at 255 bytes. Chapters are stored as a Nero chpl atom. Apple players do not read these chapters, and QuickTime chapter tracks are not written.

EXAMPLES

Gapless playback needs the encoder's priming and padding, which the encoder reports; ADTS does not carry them. The .m4a that faac (1) writes records them, and faam info shows them as Encoder Delay and Trailing Padding. For AAC-LC from faac the delay is 1024 samples. For HE-AAC v1 it is 1040: faac reports 2080 at the output rate, and the file counts samples at the core rate, which is half. The padding depends on the length of the input.

Mux an AAC-LC ADTS stream from faac into an M4A with gapless information:

faam -i song.aac -o song.m4a --encoder-delay 1024 --padding-delay 820

Mux an HE-AAC v1 ADTS stream from faac, announcing SBR:

faam -i song.aac -o song.m4a --sbr-signaling compatible --encoder-delay 1040 --padding-delay 1418

Mux an audiobook:

faam -i book.aac -o book.m4b --brand m4b --title Book --language eng

Mux H.264 video and AAC audio:

faam -i clip.264 -i sound.aac -o clip.mp4 --width 1280 --height 720 --fps 30000/1001

Show what a file contains:

faam info song.m4a

Extract the audio as an ADTS stream:

faam demux song.m4a -o song.aac

Set tags and cover art:

faam tag song.m4a --title Song --artist Artist --track 3/12 --cover-art cover.jpg

Add lyrics from a UTF-8 file:

faam tag song.m4a --lyrics-file lyrics.txt

Replace all tags:

faam tag song.m4a --clear --title Song

Copy chapters from one audiobook to another:

faam chapter export a.m4b -o chapters.txt
faam chapter import b.m4b --chapters chapters.txt

EXIT STATUS

0 on success and 1 on a usage or option error, an invalid option value, an unreadable input, an uncreatable output, an output that exists without --overwrite, an output that is also an input, an invalid chapter list, a file that tag cannot read, or a library error.

ENVIRONMENT

• SOURCE_DATE_EPOCH Creation time of muxed files when --creation-time is not given.

SEE ALSO

faac (1), faad (1), faar (1)

faac (1) is the AAC encoder. It is built and installed unless the encoder build option is disabled.

faad (1) is the AAC decoder. It is built and installed unless the decoder build option is disabled.

AUTHORS

Developed and maintained by Nils Schimmelmann.