README.md
1# Low Complexity Communication Codec (LC3)
2
3The LC3 is an efficient low latency audio codec.
4
5[_Low Complexity Communication Codec_](https://www.bluetooth.org/DocMan/handlers/DownloadDoc.ashx?doc_id=502107&vId=542963)
6
7## Overview
8
9The directory layout is as follows :
10- include: Library interface
11- src: Source files
12- tools: Standalone encoder/decoder tools
13- test: Python implentation, used as reference for unit testing
14- fuzz: Roundtrip fuzz testing harness
15- build: Building outputs
16- bin: Compilation output
17
18## How to build
19
20The default toolchain used is GCC. Invoke `make` to build the library.
21
22```sh
23$ make -j
24```
25
26Compiled library `liblc3.a` will be found in `bin` directory.
27
28#### Cross compilation
29
30The cc, as, ld and ar can be selected with respective Makefile variables `CC`,
31`AS`, `LD` and `AR`. The `AS` and `LD` selections are optionnal, and fallback
32to `CC` selection when not defined.
33
34The `LIBC` must be set to `bionic` for android cross-compilation. This switch
35prevent link with `pthread` and `rt` libraries, that is included in the
36bionic libc.
37
38Following example build for android, using NDK toolset.
39
40```sh
41$ make -j CC=path_to_android_ndk_prebuilt/toolchain-prefix-clang LIBC=bionic
42```
43
44Compiled library will be found in `bin` directory.
45
46## Tools
47
48Tools can be all compiled, while involking `make` as follows :
49
50```sh
51$ make tools
52```
53
54The standalone encoder `elc3` take a `wave` file as input and encode it
55according given parameter. The LC3 binary file format used is the non
56standard format described by the reference encoder / decoder tools.
57The standalone decoder `dlc3` do the inverse operation.
58
59Refer to `elc3 -h` or `dlc3 -h` for options.
60
61Note that `elc3` output bitstream to standard output when output file is
62omitted. On the other side `dlc3` read from standard input when input output
63file are omitted.
64In such way you can easly test encoding / decoding loop with :
65
66```sh
67$ ./elc3 <in.wav> -b <bitrate> | ./dlc3 > <out.wav>
68```
69
70Adding Linux `aplay` tools, you will be able to instant hear the result :
71
72```sh
73$ ./elc3 <in.wav> -b <bitrate> | ./dlc3 | aplay
74```
75
76## Test
77
78A python implementation of the encoder is provided in `test` diretory.
79The C implementation is unitary validated against this implementation and
80intermediate values given in Appendix C of the specification.
81
82#### Prerequisite
83
84```sh
85# apt install python3 python3-dev python3-pip
86$ pip3 install scipy numpy
87```
88
89#### Running test suite
90
91```sh
92$ make test
93```
94
95## Fuzzing
96
97Roundtrip fuzz testing harness is available in `fuzz` directory.
98LLVM `clang` and `clang++` compilers are needed to run fuzzing.
99
100The encoder and decoder fuzzers can be run, for 1 million iterations, using
101target respectively `dfuzz` and `efuzz`. The `fuzz` target runs both.
102
103```sh
104$ make efuzz # Run encoder fuzzer for 1M iteration
105$ make dfuzz # Run decoder fuzzer for 1M iteration
106$ make fuzz -j # Run encoder and decoder fuzzers in parallel
107```
108
109## Qualification / Conformance
110
111The implementation is qualified under the [_QDID 194161_](https://launchstudio.bluetooth.com/ListingDetails/160904) as part of Google Fluoride 1.5.
112
113For more detail on conformance, refer to [_Bluetooth Conformance
114Documents and scripts_](https://www.bluetooth.com/specifications/specs/low-complexity-communication-codec-1-0/)
115
116## Listening Test
117
118The codec was [_here_](https://hydrogenaud.io/index.php/topic,122575.0.html)
119subjectively evaluated in a blind listening test.
120
121## Meson build system
122
123Meson build system is also available to build and install lc3 codec in Linux
124environment.
125
126```sh
127$ meson build
128$ cd build
129$ ninja
130$ sudo ninja install
131```
132
133
