-
Notifications
You must be signed in to change notification settings - Fork 1
/
Readme.txt
375 lines (305 loc) · 16 KB
/
Readme.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
/******************************************************************************
* ETSI TS 103 634 V1.5.1 *
* Low Complexity Communication Codec Plus (LC3plus) *
* Software Version V1.7.4ETSI *
* 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.
-/conformance : conformance script with example configuration file and
Readme
-/fec_control_unit : example fec control unit script and Readme
-/src/fixed_point : fixed-point source files, makefile and Visual Studio
solution
-/src/floating_point : floating-point source files, makefile and Visual Studio
solution
-/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
- Multichannel support by multi-mono coding
- Support of audio sample depth: 16 bits and 24 bits
- Frame duration of 10 ms, 7.5 ms, 5 ms and 2.5 ms
- Supported bit rates as outlined in Table 5.1 and Table 5.2 of TS 103 634
- Packet loss concealment as defined in ETSI TS 103 634
Changelog
---------
Latest non-bitexact changes are encapsulated in defines listed in defines.h
for review.
- V1.7.4ETSI 2024-05-01 (ETSI TS 103 634 V1.5.1)
- General
- Accepted defines CR8, CR9, CR10 and CR11
- V1.7.3ETSI 2024-04-01 (ETSI TS 103 634 V1.4.5)
- General
- Implemented CR1 on ETSI TS 103 634 V1.4.4 (changes marked with CR11)
- V1.7.2ETSI 2024-03-13 (ETSI TS 103 634 V1.4.4)
- General
- Implemented CR1 on ETSI TS 103 634 V1.4.3 (changes marked with CR10)
- V1.7.1ETSI 2024-02-09 (ETSI TS 103 634 V1.4.4)
- General
- Implemented CR1 on ETSI TS 103 634 V1.4.2 (changes marked with CR9)
- V1.7.0ETSI 2023-09-15 (ETSI TS 103 634 V1.4.2)
- General
- Implemented CR1, CR2 and CR3 on ETSI TS 103 634 V1.4.1 (changes marked with CR8)
- V1.6.9ETSI 2023-03-01 (ETSI TS 103 634 V1.4.1)
- General
- Updated source headers to version V1.4.1
- V1.6.8ETSI 2023-01-20 (ETSI TS 103 634 V1.3.4)
- General
- Accepted defines CR6 and CR7
- V1.6.7ETSI 2022-11-18 (ETSI TS 103 634 V1.3.3)
- General
- Updated software version and ETSI TS version
- Implemented CR1 on TS 103 634 V1.3.2 (changes marked with defines CR7)
- V1.6.6ETSI 2022-06-22 (ETSI TS 103 634 V1.3.2)
- General
- Updated software version and ETSI TS version
- Implemented CR1 on TS 103 634 V1.3.1 (changes marked with defines CR6)
- V1.6.4ETSI 2021-10-01 (ETSI TS 103 634 V1.3.1)
- General
- Updated software version and ETSI TS version
- V1.6.3ETSI 2021-08-01 (ETSI TS 103 634 V1.2.5)
- General
- Implemented CR1 on TS 103 634 V1.2.4 (changes marked with defines CR6)
- Accepted CR1 to CR5
- V1.6.2ETSI 2021-06-23 (ETSI TS 103 634 V1.2.4)
- General
- Implemented CR1 on TS 103 634 V1.2.3 (changes marked with defines CR5)
- Major Features
- Added high resolution audio support and improved precision coding for regular modes
in fixed-point code (wrapped in the define ENABLE_HR_MODE)
- Added support for fallback bitrates for the high resolution mode
for critical conditions
- V1.6.0ETSI 2021-05-25 (ETSI TS 103 634 V1.2.3)
- General
- Implemented CR1 on TS 103 634 V1.2.2 (changes marked with defines CR4)
- V1.4.12ETSI 2021-03-03 (ETSI TS 103 634 V1.2.2)
- General
- Implemented CR1 on TS 103 634 V1.2.1 (changes marked with defines CR3)
- Major Features
- Added concealment and forward error protection for floating point code
- Limited bit rate to 320 kbps for regular modes
- V1.4.10ETSI 2020-07-23 (ETSI TS 103 634 V1.2.1)
- General
- Accepted CR2 defines
- V1.4.9E 2020-03-23 (ETSI TS 103 634 V1.1.3)
- General
- Fix PLC fade-out for frame lengths < 10ms, implemented
under define CR2_B_NONBE_PLC3_ENHANCEMENTS
- Channel Coder
- added epok_flags according to CR2_G, implemented
under define CR2_G_EPOK_FLAGS
- fixed incorrect value of error_report for
certain cases with bfi=1 according to CR2_J, implemented
under define CR2_J_NONBE_ERROR_REPORT_FIX
- V1.4.6E 2020-01-22 (ETSI TS 103 634 V1.1.2)
- General
- Renamed NONBE defines according to corresponding change in CR
- V1.4.5E 2020-01-10 (ETSI TS 103 634 V1.1.2)
- General
- Added Channel Coder Converter
- Several Packet Loss Concealment simplifications
- Aligned LTPF normcorr window
- 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. They use single
precision floating point format to represent data and perform mathematical
operations.
Usage
-----
The following example commands explain the usage of the LC3plus binary. A
complete list is available by calling ./LC3plus -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 specify output bits per sample
./LC3plus -bps NUM INPUT.wav OUTPUT.wav BITRATE
where NUM is either 16 (default) or 24.
To specify bitrate switching file instead of fixed bitrate
./LC3plus -swf FILE INPUT.wav OUTPUT.wav BITRATE
where FILE is a binary file containing the bitrate as a
sequence of 64-bit values.
To specify delay compensation
./LC3plus -dc DC INPUT.wav OUTPUT.wav BITRATE
where DC is 0, 1 (default) or 2 meaning that:
0: Don't use delay compensation
1: Compensate delay in decoder (default)
2: Split delay equally in encoder and decoder
To disable frame counter (quiet mode)
./LC3plus -q INPUT.wav OUTPUT.wav BITRATE
To activate verbose mode (print switching commands)
./LC3plus -v INPUT.wav OUTPUT.wav BITRATE
To use the G192 bitstream format
./LC3plus -E -formatG192 INPUT.wav OUTPUT.g192 BITRATE
Note that an additional file OUTPUT.cfg will be created containing
the decoder information. To specify the configuration file,
the flag -cfgG192 FILE can be used where FILE is the path to the
configuration file.
Note that the same flags (-formatG192 and -cfgG192) shall be used for decoding,
if the G192 format was chosen for encoding.
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
To write error detection pattern (from arithmetic decoder) into a 16-bit binary file
./LC3plus -D -edf patternfile INPUT.bin OUTPUT.wav
where the patternfile is a binary file containing a sequence of
16-bit values, non-zero values indicating a detected frame loss
The high-resolution mode 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 parameter 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
-------------------------------------------------------------------
The software package also includes a Channel Coder Converter (CCC) which converts unprotected
and protected LC3plus payloads within each other.
Building:
On Unix:
- make ccConvert
On Windows:
- Go to src/fixed_point/msvc_ccc
- Open up solution file ccConvert.sln and build it
- Standard config executable path and name ".\Win32\Release\ccConvert.exe"
Usage:
The CCC can be used as follows:
Pack mode (convert to protected): ./ccConvert -pack gross_bytes ep_mode in.lc3 out.lc3
Unpack mode (convert to unprotected): ./ccConvert -unpack in.lc3 out.lc3
where gross_bytes is the gross number of bytes available and ep_mode the error protection
mode which is one of 0,1,2,3,4.
For G.192 format, the filename extension should be ".g192".
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 Content
------------------------------------------------------------------
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 2 input signal length in samples
signal_len_red 2 signal_len >> 16
hrmode 2 high resolution mode, 0: off, 1: on
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.
For multichannel audio, the coded audio frames for each channel are concatenated and the
length refers to the sum of the frame lengths.