refactor pcm io routines

[fdkaac.git] / README

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