== OAC audio codec ==

OAC is the Alliance for Open Media's planned successor to Opus. It is
currently a work in progress.

This package implements a shared library for encoding and decoding raw OAC
bitstreams. It also includes a number of test tools used for testing the
correct operation of the library. The bitstreams read/written by these
tools should not be used for OAC file distribution: they include
additional debugging data and cannot support seeking.

== Compiling liboac ==

To build from a distribution tarball, you only need to do the following:

    % ./configure
    % make

To build from the git repository, the following steps are necessary:

0) Set up a development environment:

On an Ubuntu or Debian family Linux distribution:

    % sudo apt-get install git autoconf automake libtool gcc make

On a Fedora/Redhat based Linux:

    % sudo dnf install git autoconf automake libtool gcc make

Or for older Redhat/Centos Linux releases:

    % sudo yum install git autoconf automake libtool gcc make

On Apple macOS, install Xcode and brew.sh, then in the Terminal enter:

    % brew install autoconf automake libtool

1) Clone the repository:

    % git clone https://github.com/AOMediaCodec/oac.git
    % cd oac

2) Compiling the source

    % ./autogen.sh
    % ./configure
    % make

On x86, it's a good idea to use a -march= option that allows the use of AVX2.

3) Install the codec libraries (optional)

    % sudo make install

Once you have compiled the codec, there will be a oac_demo executable
in the top directory.

Usage: oac_demo [-e] <application> <sampling rate (Hz)> <channels (1/2)>
         <bits per second> [options] <input> <output>
       oac_demo -d <sampling rate (Hz)> <channels (1/2)> [options]
         <input> <output>

mode: voip | audio | restricted-lowdelay
options:
  -e                : only runs the encoder (output the bit-stream)
  -d                : only runs the decoder (reads the bit-stream as input)
  -cbr              : enable constant bitrate; default: variable bitrate
  -cvbr             : enable constrained variable bitrate; default:
                      unconstrained
  -bandwidth <NB|MB|WB|SWB|FB>
                    : audio bandwidth (from narrowband to fullband);
                      default: sampling rate
  -framesize <2.5|5|10|20|40|60>
                    : frame size in ms; default: 20
  -max_payload <bytes>
                    : maximum payload size in bytes, default: 1024
  -complexity <comp>
                    : complexity, 0 (lowest) ... 10 (highest); default: 10
  -inbandfec        : enable SILK inband FEC
  -forcemono        : force mono encoding, even for stereo input
  -dtx              : enable SILK DTX
  -loss <perc>      : simulate packet loss, in percent (0-100); default: 0

input and output are little-endian signed 16-bit PCM files or OAC
bitstreams with simple oac_demo custom framing.

== Testing ==

This package includes a collection of automated unit and system tests
which SHOULD be run after compiling the package especially the first
time it is run on a new platform.

To run the integrated tests:

    % make check

== Compiling liboac for Windows and alternative build systems ==

See cmake/README.md or meson/README.md.

== Portability notes ==

This implementation uses floating-point by default but can be compiled to
use only fixed-point arithmetic by setting --enable-fixed-point (if using
autoconf) or by defining the FIXED_POINT macro (if building manually).
The fixed point implementation has somewhat lower audio quality and is
slower on platforms with fast FPUs, it is normally only used in embedded
environments.

The implementation can be compiled with any compiler supporting C89 or later.
While it does not rely on any _undefined behavior_ as defined by C89 or
C99, it relies on common _implementation-defined behavior_ for two's
complement architectures:

o Right shifts of negative values are consistent with two's
  complement arithmetic, so that a>>b is equivalent to
  floor(a/(2^b)),

o For conversion to a signed integer of N bits, the value is reduced
  modulo 2^N to be within range of the type,

o The result of integer division of a negative value is truncated
  towards zero, and

o The compiler provides a 64-bit integer type (a C99 requirement
  which is supported by most C89 compilers).