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- build: Building outputs
15- bin: Compilation output
16
17## How to build
18
19The default toolchain used is GCC. Invoke `make` to build the library.
20
21```sh
22$ make -j
23```
24
25Compiled library `liblc3.a` will be found in `bin` directory.
26
27#### Cross compilation
28
29The cc, as, ld and ar can be selected with respective Makefile variables `CC`,
30`AS`, `LD` and `AR`. The `AS` and `LD` selections are optionnal, and fallback
31to `CC` selection when not defined.
32
33The `LIBC` must be set to `bionic` for android cross-compilation. This switch
34prevent link with `pthread` and `rt` libraries, that is included in the
35bionic libc.
36
37Following example build for android, using NDK toolset.
38
39```sh
40$ make -j CC=path_to_android_ndk_prebuilt/toolchain-prefix-clang LIBC=bionic
41```
42
43Compiled library will be found in `bin` directory.
44
45## Tools
46
47Tools can be all compiled, while involking `make` as follows :
48
49```sh
50$ make tools
51```
52
53The standalone encoder `elc3` take a `wave` file as input and encode it
54according given parameter. The LC3 binary file format used is the non
55standard format described by the reference encoder / decoder tools.
56The standalone decoder `dlc3` do the inverse operation.
57
58Refer to `elc3 -h` or `dlc3 -h` for options.
59
60Note that `elc3` output bitstream to standard output when output file is
61omitted. On the other side `dlc3` read from standard input when input output
62file are omitted.
63In such way you can easly test encoding / decoding loop with :
64
65```sh
66$ ./elc3 <in.wav> -b <bitrate> | ./dlc3 > <out.wav>
67```
68
69Adding Linux `aplay` tools, you will be able to instant hear the result :
70
71```sh
72$ ./elc3 <in.wav> -b <bitrate> | ./dlc3 | aplay
73```
74
75## Test
76
77A python implementation of the encoder is provided in `test` diretory.
78The C implementation is unitary validated against this implementation and
79intermediate values given in Appendix C of the specification.
80
81#### Prerequisite
82
83```sh
84# apt install python3 python3-dev python3-pip
85$ pip3 install scipy numpy
86```
87
88#### Running test suite
89
90```sh
91$ make test
92```
93
94## Conformance
95
96The proposed encoder and decoder implementation have been fully tested and
97validated.
98
99For more detail on conformance, refer to [_Bluetooth Conformance
100Documents and scripts_](https://www.bluetooth.com/specifications/specs/low-complexity-communication-codec-1-0/)
101
102## Listening Test
103
104The codec was [_here_](https://hydrogenaud.io/index.php/topic,122575.0.html)
105subjectively evaluated in a blind listening test.
106
107## Meson build system
108
109Meson build system is also available to build and install lc3 codec in Linux
110environment.
111
112```sh
113$ meson build
114$ cd build
115$ ninja
116$ sudo ninja install
117```
118
119
