X-Git-Url: http://git.ieval.ro/?p=fdkaac.git;a=blobdiff_plain;f=README;h=f11010d46c313389f797d728f4d11bff27562bcc;hp=76ebcd15cdac75c9061dc15f628f3ab4f4635791;hb=374ae78b970a9249d047f0958472114b16523e23;hpb=afe73f4916c2dc676ab101c3d2625ac2880d38d1 diff --git a/README b/README index 76ebcd1..f11010d 100644 --- a/README +++ b/README @@ -1,115 +1,323 @@ -========================================================================== -fdkaac - command line frontend encoder for libfdk-aac -========================================================================== - -Prerequisites -------------- -You need libfdk-aac. -On Posix environment, you will also need GNU gettext (for iconv.m4) and -GNU autoconf/automake. - -How to build on Posix environment ---------------------------------- -First, you need to build libfdk-aac and install on your system. -Once you have done it, the following will do the task. -(MinGW build can be done the same way, and doesn't require gettext/iconv) - -$ autoreconf -i -$ ./configure && make && make install - -How to build on MSVC --------------------- -First you have to extract libfdk-aac source here, so that directory tree will -look like the following: -+- fdk-aac ---+-documentation -| +-libAACdec -| +-libAACenc -| : -+- m4 -+- missings -+- MSVC -+- src - -MSVC solution for Visual Studio 2010 is under MSVC directory. - -Available input format ----------------------- -WAV (or RF64), upto 32bit int / 64bit float format is supported. -However, since FDK AAC encoder is implemented based on fixed point integer, -encoder itself treats 16bit input only. -Therefore, when feeding non-integer input, be careful so that input doesn't -exceed 0dBFS to avoid hard clips. -You might also want to apply dither/noise shape beforehand when your input -has higher resolution. - -Note that fdkaac doesn't automatically resample for you -when input samplerate is not supported by AAC spec. - -Tagging Options ---------------- -Generic tagging options like --tag, --tag-from-file, --long-tag allows you -to set arbitrary tags. -Available tags and their fcc (four char code) for --tag and --tag-from-file -can be found at http://code.google.com/p/mp4v2/wiki/iTunesMetadata - -For tags such as Artist where first char of fcc is copyright sign, -you can skip first char and just say like --tag="ART:Foo Bar" or ---tag-from-file=lyr:/path/to/your/lyrics.txt - -Currently, --tag-from-file just stores file contents into m4a without any -character encoding / line terminater conversion. -Therefore, only use UTF-8 (without BOM) when setting text tags by this option. - -On the other hand, --tag / --long-tag (and other command line arguments) are -converted from locale character encoding to UTF-8 on Posix environment. -On Windows, command line arguments are always treated as Unicode. - -Tagging using JSON ------------------- -With --tag-from-json, fdkaac can read JSON file and set tags from it. -By default, tags are assumed to be in the root object(dictionary) like this: - -{ - "title": "No Expectations", - "artist": "The Rolling Stones", - "album": "Beggars Banquet", - "track": 2 -} - -In this case, you can simply specify the filename like: ---tag-from-json=/path/to/json - -If the object containing tags is placed somewhere else, you can optionally -specify the path of the object with dotted notation. - -{ - "format" : { - "filename" : "Middle Curse.flac", - "nb_streams" : 1, - "format_name" : "flac", - "format_long_name" : "raw FLAC", - "start_time" : "N/A", - "duration" : "216.146667", - "size" : "11851007.000000", - "bit_rate" : "438628.000000", - "tags" : { - "ALBUM" : "Scary World Theory", - "ARTIST" : "Lali Puna", - "DATE" : "2001", - "DISCID" : "9208CC0A", - "TITLE" : "Middle Curse", - "TRACKTOTAL" : "10", - "track" : "2" - } - } -} - -In this example, tags are placed under the object "format.tags". -("format" is a child of the root, and "tags" is a child of the "format"). -In this case, you can say: ---tag-from-json=/path/to/json?format.tags - -For your information, ffprobe of ffmpeg project (or avprobe of libav) can -output media information/metadata in json format like this. - -Note that not all tags can be read/written this way. +% FDKAAC(1) +% nu774 +% November, 2013 + +NAME +==== + +fdkaac - command line frontend for libfdk-aac encoder + +SYNOPSIS +======== + +**fdkaac** [OPTIONS] [FILE] + +DESCRIPTION +=========== + +**fdkaac** reads linear PCM audio in either WAV, raw PCM, or CAF format, +and encodes it into either M4A / AAC file. + +If the input file is "-", data is read from stdin. Likewise, if the +output file is "-", data is written to stdout if one of streamable AAC +transport formats are selected by **-f**. + +When CAF input and M4A output is used, tags in CAF file are copied into +the resulting M4A. + +OPTIONS +======= + +-h, --help +: Show command help + +-o \ +: Output filename. + +-p, --profile \ +: Target profile (MPEG4 audio object type, AOT) + + 2 + : MPEG-4 AAC LC (default) + + 5 + : MPEG-4 HE-AAC (SBR) + + 29 + : MPEG-4 HE-AAC v2 (SBR+PS) + + 23 + : MPEG-4 AAC LD + + 39 + : MPEG-4 AAC ELD + +-b, --bitrate \ +: Target bitrate (for CBR) + +-m, --bitrate-mode \ +: Bitrate configuration mode. Available VBR quality value depends on + other parameters such as profile, sample rate, or number of + channels. + + 0 + : CBR (default) + + 1-5 + : VBR (higher value -\> higher bitrate) + +-w, --bandwidth \ +: Frequency bandwidth (lowpass cut-off frequency) in Hz. Available on + AAC LC only. + +-a, --afterburner \ +: Configure afterburner mode. When enabled, quality is increased at + the expense of additional computational workload. + + 0 + : Off + + 1 + : On (default) + +-L, --lowdelay-sbr \ +: Configure SBR activity on AAC ELD. + + -1 + : Use ELD SBR auto configuration + + 0 + : Disable SBR on ELD (default) + + 1 + : Enable SBR on ELD + +-s, --sbr-ratio \ +: Controls activation of downsampled SBR. + + 0 + : Use lib default (default) + + 1 + : Use downsampled SBR (default for ELD+SBR) + + 2 + : Use dual-rate SBR (default for HE-AAC) + + Dual-rate SBR is what is normally used for HE-AAC, where AAC is + encoded at half the sample rate of SBR, hence "dual rate". On the + other hand, downsampled SBR uses same sample rate for both of AAC + and SBR (single rate), therefore downsampled SBR typically consumes + more bitrate. + + Downsampled SBR is newly introduced feature in FDK encoder library + version 3.4.12. When libfdk-aac in the system doesn't support this, + dual-rate SBR will be used. When available, dual-rate SBR is the + default for HE-AAC and downsampled SBR is the default for ELD+SBR. + + Note that downsampled HE-AAC is not so common as dual-rate one. When + downsampled HE-AAC is selected, **fdkaac** is forced to choose + explicit hierarchical SBR signaling, which (at least) iTunes doesn't + accept. + +-f, --transport-format \ +: Transport format. Tagging and gapless playback is only available on + M4A. Streaming to stdout is only available on others. + + 0 + : M4A (default) + + 1 + : ADIF + + 2 + : ADTS + + 6 + : LATM MCP=1 + + 7 + : LATM MCP=0 + + 10 + : LOAS/LATM (LATM within LOAS) + +-C, --adts-crc-check +: Add CRC protection on ADTS header. + +-h, --header-period \ +: StreamMuxConfig/PCE repetition period in the transport layer. + +-G, --gapless-mode \ +: Method to declare amount of encoder delay (and padding) in M4A + container. These values are mandatory for proper gapless playback on + player side. + + 0 + : iTunSMPB (default) + + 1 + : ISO standard (edts and sgpd) + + 2 + : Both + +--include-sbr-delay +: When specified, count SBR decoder delay in encoder delay. + + This is not iTunes compatible and will lead to gapless playback + issue on LC only decoder, but this is the default behavior of FDK + library. + + Whether counting SBR decoder delay in encoder delay or not result in + incompatibility in gapless playback. You should pick which one will + work for your favorite player. + + However, it's better not to choose SBR at all if you want gapless + playback. LC doesn't have such issues. + +-I, --ignorelength +: Ignore length field of data chunk in input WAV file. + +-S, --silent +: Don't print progress messages. + +--moov-before-mdat +: Place moov box before mdat box in M4A container. This option might + be important for some hardware players, that are known to refuse + moov box placed after mdat box. + +-R, --raw +: Regard input as raw PCM. + +--raw-channels \ +: Specify number of channels of raw input (default: 2) + +--raw-rate \ +: Specify sample rate of raw input (default: 44100) + +--raw-format \ +: Specify sample format of raw input (default: "S16L"). **Spec** is as + the following (case insensitive): + + 1st char -- type of sample + : **S** (igned) | **U** (nsigned) | **F** (loat) + + 2nd part (in digits) + : bits per channel + + Last char -- endianness (can be omitted) + : **L** (ittle, default) | **B** (ig) + +--title \ +: Set title tag. + +--artist \ +: Set artist tag. + +--album \ +: Set album tag. + +--genre \ +: Set genre tag. + +--date \ +: Set date tag. + +--composer \ +: Set composer tag. + +--grouping \ +: Set grouping tag. + +--comment \ +: Set comment tag. + +--album-artist \ +: Set album artist tag. + +--track \ +: Set track tag, with or without number of total tracks. + +--disk \ +: Set disk tag, with or without number of total discs. + +--tempo \ +: Set tempo (BPM) tag. + +--tag \:\ +: Set iTunes predefined tag with explicit fourcc key and value. See + [https://code.google.com/p/mp4v2/wiki/iTunesMetadata](https://code.google.com/p/mp4v2/wiki/iTunesMetadata) + for known predefined keys. You can omit first char of **fcc** when + it is the copyright sign. + +--tag-from-file \:\ +: Same as --tag, but set content of file as tag value. + +--long-tag \:\ +: Set arbitrary tag as iTunes custom metadata. Stored in + com.apple.iTunes field. + +--tag-from-json \ +: Read tags from JSON. By default, tags are assumed to be direct + children of the root object in JSON. Optionally you can specify + arbitrary dot notation to locate the object containing tags. + + +EXAMPLES +======== + +Encode WAV file into a M4A file. MPEG4 AAC LC, VBR quality 3: + + fdkaac -m3 foo.wav + +Encode WAV file into a M4A file. MPEG4 HE-AAC, bitrate 64kbps: + + fdkaac -p5 -b64 foo.wav + +Piping from **ffmpeg** (you need version supporting CAF output): + + ffmpeg -i foo.flac -f caf - | fdkaac -b128 - -o foo.m4a + +Import tags via json: + + ffprobe -v 0 -of json -show_format foo.flac >foo.json + + flac -dc foo.flac | \ + fdkaac - -ox.m4a -m2 --import-tag-from-json=foo.json?format.tags + +NOTES +===== + +Upto 32bit integer or 64bit floating point format is supported as input. +However, FDK library is implemented based on fixed point math and only +supports 16bit integer PCM. Therefore, be wary of clipping. You might +want to dither/noise shape beforehand when your input has higher +resolution. + +Following channel layouts are supported by the encoder. + +1ch +: C + +2ch +: L R + +3ch +: C L R + +4ch +: C L R Cs + +5ch +: C L R Ls Rs + +5.1ch +: C L R Ls Rs LFE + +7.1ch (front) +: C Lc Rc L R Ls Rs LFE + +7.1ch (rear) +: C L R Ls Rs Rls Rrs LFE +