/******************************************************************************
*                        ETSI TS 103 634 V1.1.1                               *
*              Low Complexity Communication Codec Plus (LC3plus)              *
*                        Software Version V1.4.2                              *
* Copyright licence is solely granted through ETSI Intellectual Property      *
* Rights Policy, 3rd April 2019. No patent licence is granted by implication, *
* estoppel or otherwise.                                                      *
******************************************************************************/



Description
-----------
This package contains the fixed-point and floating-point source code of the
LC3plus codec as electronic attachment to ETSI TS 103 634.

The software uses fix-point arithmetic utilizing the ITU-T STL2009 including
the latest updates introduced by 3GPP and/or IEEE 754 floating-point arithmetic.

The following structure outlines the content of this package.

-/src/fixed_point     : fixed-point source files, makefile and Visual Studio
                        solution
-/src/floating_point  : floating-point source files, makefile and Visual Studio
                        solution
-/conformance         : conformance script with example configuration file and
                        Readme
-/testvec             : testvector package with script. Verification that LC3plus
                        build on your system operates as expected by comparing to
                        pre-calculated MD5 hashes
-/tools               : LC3plus helper tools and examples

Please refer to the respective Readme files for more information.

Features:
--------
    - Supported sampling rates: 8 kHz, 16 kHz, 24 kHz, 32 kHz, 44.1 kHz,
                                      48 kHz, 96 kHz
    - Frame duration of 10 ms, 5 ms and 2.5 ms
    - Supported bit rates:
        - frame duration 10 ms:  16 kbps ... 320 kbps per channel
        - frame duration 5 ms:   32 kbps ... 640 kbps per channel
        - frame duration 2.5 ms: 64 kbps ... 1280 kbps per channel
    - High resolution audio mode for 48 kHz and 96 kHz and higher SNR.
    -- Supported bit rates for 48 kHz
        - frame duration 10 ms:  124.8 ... 500 kbps per channel
        - frame duration 5 ms:   148.8 ... 600 kbps per channel
        - frame duration 2.5 ms: 172.8 ... 672 kbps per channel
    -- Supported bit rates for 96 kHz
        - frame duration 10 ms:  149.6 ... 500 kbps per channel
        - frame duration 5 ms:   174.4 ... 600 kbps per channe
        - frame duration 2.5 ms: 198.4 ... 672 kbps per channel

    - Packet loss concealment as defined in ETSI TS 103 634


The fixed-point source code currently has limited support for the
following functions:
    - High resolution mode

The floating-point source code currently has limited support for the
following functions:
    - Packet loss concealment
    - Error protection (LC3plus channel coder)
    - Partial concealment

Changelog:
---------

  Latest non-bitexact changes are encapsulated in defines listed in defines.h
  for review.


    - V1.4.2 2019-07-25 (ETSI TS 103 634 V1.1.1)
        - General
            - Updated copyright header

    - V1.4.1 2019-06-26 (ETSI TS 103 634 V0.1.1)
        - General
            - Added several sanity checks for corrupt bitstreams
            - Fix delay compensation (dc == 2)
            - Changed setup struct size defines to actual maximum values



Building
--------

    Unix platforms:
        - Go to src/fixed_point or src/floating_point folder
        - Call "make"
        - Executable path and name "./LC3plus"

    Windows platforms:
        - Go to src/fixed_point/msvc or src/floating_point/msvc folder
        - Open up solution file LC3plus.sln and build it
        - Standard config executable path and name ".\Win32\Release\LC3plus.exe"
        - The solution is optimized for Visual Studio 2017


The floating-point source code introduces a floating-point data type and
corresponding functions via macros labeled LC3_XYZ. By default they use single
precision floating point format to represent data and perform mathematical
operations. Double precision floating point format can be acitivated by enabling
the define LC3_DOUBLE_PRECISION.

Usage
-----
    The following example commands explain the usage of the LC3plus binary. A
    complete list is available by calling ./LCplus -h.

    To call encoder+decoder at the same time
        ./LC3plus INPUT.wav OUTPUT.wav BITRATE

    To call encoder only
        ./LC3plus -E INPUT.wav OUTPUT.bin BITRATE

    To call decoder only
        ./LC3plus -D INPUT.bin OUTPUT.wav

    To call decoder with frame loss simulations
        ./LC3plus -D -epf patternfile INPUT.bin OUTPUT.wav
        where the patternfile is a binary file containing a sequence of
        16-bit values, non-zero values indicating a frame loss

    The high-resolution mode is only available in the floating-point source code.
    It is mandatory for usage with 96 kHz sampling frequency and can also be used
    with 48 kHz sampling frequency. To enable the high-resolution mode call

        ./LC3plus -hrmode INPUT.wav OUTPUT.wav BITRATE

    To activate error protection mode call

        ./LC3plus -epmode NUM INPUT.wav OUTPUT.wav BITRATE

        where NUM is the error protection mode using the LC3plus channel coder.
        NUM must be in the range of 0 - 4 where:
              - 0 = error protection disabled
              - 1 = minimum error protection, bit error detection only
              - 2 = moderate error protection, e.g. up to 3 bits correctable for
                    a 40 bytes frame
              - 3 = strong error protection, e.g. up to 9 bits correctable for
                    a 40 bytes frame
              - 4 = maximum error protection, e.g. up to 18 bits correctable for
                    a 40 bytes frame
              -NUM can also be a binary switching file holding the values for the
                    current epmode.

    The actual number of correctable bits depends on the bit error distribution
    in a frame where the codes are strongest when bit errors accumulate (e.g.
    burst errors) and weakest when bit errors are uniformly distributed.

    Error protection can be in encoder only mode:
         ./LC3plus -E -epmode NUM INPUT.wav OUTPUT.bin BITRATE

    The decoder needs the information, if error protection is enabled
         ./LC3plus -D -epmode NUM INPUT.bin OUTPUT.wav
         with NUM one of the following: 0 = off, 1 = on. The channel-decoder
         identifies the error protection mode by itself

    The paramter bitrate, bandwidth and epmode also allow the usage of switching
    files instead of a fixed number. If the switching file is shorter than the
    input it is looped from the beginning. The switching files contain data stored
    as little-endian 64-bit values.

    For the bitrate, each value represents a frame's bitrate.
    For the bandwidth, each value represents a frame's cutoff bandwidth in Hz.
    For error protection, each value represents a frame's epmode multiplied with
    100, i.e. epmode = value / 100.
    Switching files can be created with 'gen_rate_profile' available from
    ITU-T G191.

    If error protection is enabled, the compressed LC3plus frame is reduced
    depending on the robustness according to the following table:

    Frame Duration| Min. Bitrate  |  Max. Bitrate
    Channel Mode  | [kbps]        |  [kbps]
    ==============================================
    2.5 ms        |  128          |  960
    Mono          |               |
    ----------------------------------------------
    5 ms          |  64           |  480
    Mono          |               |
    ----------------------------------------------
    10 ms         |  32           |  240
    Mono          |               |
    ----------------------------------------------
    2.5 ms        |  256          |  1920
    Stereo        |               |
    ----------------------------------------------
    5 ms          |  128          |  960
    Stereo        |               |
    ----------------------------------------------
    10 ms         |  64           |  480
    Stereo        |               |

    While the number of bytes per frame is smaller than or equal to 160, left
    and right channel are coded jointly by the LC3plus channel coder. Above this
    threshold, left and right channel are channel encoded separately. The
    cross-over bitrates are given in the table below.

    Frame Duration [ms]|  Max. Bitrate for Joint Channel Coding [kbps]
    ===================================================================
    2.5                |  512
    -------------------------------------------------------------------
    5                  |  256
    -------------------------------------------------------------------
    10                 |  128
    -------------------------------------------------------------------

    The minimum and maximum allowed bitrate per channel depends on the frame duration
    since the minimum and maximum frame data size of 20 bytes ... 400 bytes is kept
    independently of the frame duration. Therefore, the bitrate per channel is
    restricted according to the table below.

    Frame Duration [ms]|  Min. Bitrate [kbps]  |  Max. Bitrate [kbps]
    ===================================================================
    2.5                |  64                   |  1280
    -------------------------------------------------------------------
    5                  |  32                   |  640
    -------------------------------------------------------------------
    10                 |  16                   |  320
    -------------------------------------------------------------------

Binary File Format
-------------------
    Note: The binary file format is intended only for testing purposes. It is
    not standardized and may change in the future.
    The file starts with a config header structure as follows.

    Field         Bytes   Contens
    ------------------------------------------------------------
    file_id       2       file identifier, value 0xcc1c
    header_size   2       total config header size in bytes
    samplingrate  2       sampling frequency / 100
    bitrate       2       bitrate / 100
    channels      2       number of channels
    frame_ms      2       Frame duration in ms * 100
    epmode        2       error protection, 0: off, non-zero: on
    signal_len    4       input signal length in samples

    Note: the floating-point implementation adds an additional field
    hrmode        2       high resolution mode on/off

    All fields are stored in little-endian byte order. The config header could
    be extended in the future so readers should seek to header_size to skip any
    unknown fields.
    The header is immediately followed by a series of coded audio frames, where
    each frame consists of a two-byte frame length information and the current
    coded frame.