diff options
Diffstat (limited to 'lib/rbcodec/codecs/libopus/opus_custom.h')
-rw-r--r-- | lib/rbcodec/codecs/libopus/opus_custom.h | 329 |
1 files changed, 329 insertions, 0 deletions
diff --git a/lib/rbcodec/codecs/libopus/opus_custom.h b/lib/rbcodec/codecs/libopus/opus_custom.h new file mode 100644 index 0000000000..e7861d6f0a --- /dev/null +++ b/lib/rbcodec/codecs/libopus/opus_custom.h | |||
@@ -0,0 +1,329 @@ | |||
1 | /* Copyright (c) 2007-2008 CSIRO | ||
2 | Copyright (c) 2007-2009 Xiph.Org Foundation | ||
3 | Copyright (c) 2008-2012 Gregory Maxwell | ||
4 | Written by Jean-Marc Valin and Gregory Maxwell */ | ||
5 | /* | ||
6 | Redistribution and use in source and binary forms, with or without | ||
7 | modification, are permitted provided that the following conditions | ||
8 | are met: | ||
9 | |||
10 | - Redistributions of source code must retain the above copyright | ||
11 | notice, this list of conditions and the following disclaimer. | ||
12 | |||
13 | - Redistributions in binary form must reproduce the above copyright | ||
14 | notice, this list of conditions and the following disclaimer in the | ||
15 | documentation and/or other materials provided with the distribution. | ||
16 | |||
17 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS | ||
18 | ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT | ||
19 | LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR | ||
20 | A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER | ||
21 | OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, | ||
22 | EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, | ||
23 | PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR | ||
24 | PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF | ||
25 | LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING | ||
26 | NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS | ||
27 | SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. | ||
28 | */ | ||
29 | |||
30 | /** | ||
31 | @file opus_custom.h | ||
32 | @brief Opus-Custom reference implementation API | ||
33 | */ | ||
34 | |||
35 | #ifndef OPUS_CUSTOM_H | ||
36 | #define OPUS_CUSTOM_H | ||
37 | |||
38 | #include "opus_defines.h" | ||
39 | |||
40 | #ifdef __cplusplus | ||
41 | extern "C" { | ||
42 | #endif | ||
43 | |||
44 | #ifdef CUSTOM_MODES | ||
45 | #define OPUS_CUSTOM_EXPORT OPUS_EXPORT | ||
46 | #define OPUS_CUSTOM_EXPORT_STATIC OPUS_EXPORT | ||
47 | #else | ||
48 | #define OPUS_CUSTOM_EXPORT | ||
49 | #ifdef CELT_C | ||
50 | #define OPUS_CUSTOM_EXPORT_STATIC static inline | ||
51 | #else | ||
52 | #define OPUS_CUSTOM_EXPORT_STATIC | ||
53 | #endif | ||
54 | #endif | ||
55 | |||
56 | /** @defgroup opus_custom Opus Custom | ||
57 | * @{ | ||
58 | * Opus Custom is an optional part of the Opus specification and | ||
59 | * reference implementation which uses a distinct API from the regular | ||
60 | * API and supports frame sizes that are not normally supported.\ Use | ||
61 | * of Opus Custom is discouraged for all but very special applications | ||
62 | * for which a frame size different from 2.5, 5, 10, or 20 ms is needed | ||
63 | * (for either complexity or latency reasons) and where interoperability | ||
64 | * is less important. | ||
65 | * | ||
66 | * In addition to the interoperability limitations the use of Opus custom | ||
67 | * disables a substantial chunk of the codec and generally lowers the | ||
68 | * quality available at a given bitrate. Normally when an application needs | ||
69 | * a different frame size from the codec it should buffer to match the | ||
70 | * sizes but this adds a small amount of delay which may be important | ||
71 | * in some very low latency applications. Some transports (especially | ||
72 | * constant rate RF transports) may also work best with frames of | ||
73 | * particular durations. | ||
74 | * | ||
75 | * Libopus only supports custom modes if they are enabled at compile time. | ||
76 | * | ||
77 | * The Opus Custom API is similar to the regular API but the | ||
78 | * @ref opus_encoder_create and @ref opus_decoder_create calls take | ||
79 | * an additional mode parameter which is a structure produced by | ||
80 | * a call to @ref opus_custom_mode_create. Both the encoder and decoder | ||
81 | * must create a mode using the same sample rate (fs) and frame size | ||
82 | * (frame size) so these parameters must either be signaled out of band | ||
83 | * or fixed in a particular implementation. | ||
84 | * | ||
85 | * Similar to regular Opus the custom modes support on the fly frame size | ||
86 | * switching, but the sizes available depend on the particular frame size in | ||
87 | * use. For some initial frame sizes on a single on the fly size is available. | ||
88 | */ | ||
89 | |||
90 | /** Contains the state of an encoder. One encoder state is needed | ||
91 | for each stream. It is initialized once at the beginning of the | ||
92 | stream. Do *not* re-initialize the state for every frame. | ||
93 | @brief Encoder state | ||
94 | */ | ||
95 | typedef struct OpusCustomEncoder OpusCustomEncoder; | ||
96 | |||
97 | /** State of the decoder. One decoder state is needed for each stream. | ||
98 | It is initialized once at the beginning of the stream. Do *not* | ||
99 | re-initialize the state for every frame. | ||
100 | @brief Decoder state | ||
101 | */ | ||
102 | typedef struct OpusCustomDecoder OpusCustomDecoder; | ||
103 | |||
104 | /** The mode contains all the information necessary to create an | ||
105 | encoder. Both the encoder and decoder need to be initialized | ||
106 | with exactly the same mode, otherwise the output will be | ||
107 | corrupted. | ||
108 | @brief Mode configuration | ||
109 | */ | ||
110 | typedef struct OpusCustomMode OpusCustomMode; | ||
111 | |||
112 | /** Creates a new mode struct. This will be passed to an encoder or | ||
113 | * decoder. The mode MUST NOT BE DESTROYED until the encoders and | ||
114 | * decoders that use it are destroyed as well. | ||
115 | * @param [in] Fs <tt>int</tt>: Sampling rate (8000 to 96000 Hz) | ||
116 | * @param [in] frame_size <tt>int</tt>: Number of samples (per channel) to encode in each | ||
117 | * packet (64 - 1024, prime factorization must contain zero or more 2s, 3s, or 5s and no other primes) | ||
118 | * @param [out] error <tt>int*</tt>: Returned error code (if NULL, no error will be returned) | ||
119 | * @return A newly created mode | ||
120 | */ | ||
121 | OPUS_CUSTOM_EXPORT OPUS_WARN_UNUSED_RESULT OpusCustomMode *opus_custom_mode_create(opus_int32 Fs, int frame_size, int *error); | ||
122 | |||
123 | /** Destroys a mode struct. Only call this after all encoders and | ||
124 | * decoders using this mode are destroyed as well. | ||
125 | * @param [in] mode <tt>OpusCustomMode*</tt>: Mode to be freed. | ||
126 | */ | ||
127 | OPUS_CUSTOM_EXPORT void opus_custom_mode_destroy(OpusCustomMode *mode); | ||
128 | |||
129 | /* Encoder */ | ||
130 | /** Gets the size of an OpusCustomEncoder structure. | ||
131 | * @param [in] mode <tt>OpusCustomMode *</tt>: Mode configuration | ||
132 | * @param [in] channels <tt>int</tt>: Number of channels | ||
133 | * @returns size | ||
134 | */ | ||
135 | OPUS_CUSTOM_EXPORT_STATIC OPUS_WARN_UNUSED_RESULT int opus_custom_encoder_get_size( | ||
136 | const OpusCustomMode *mode, | ||
137 | int channels | ||
138 | ) OPUS_ARG_NONNULL(1); | ||
139 | |||
140 | /** Creates a new encoder state. Each stream needs its own encoder | ||
141 | * state (can't be shared across simultaneous streams). | ||
142 | * @param [in] mode <tt>OpusCustomMode*</tt>: Contains all the information about the characteristics of | ||
143 | * the stream (must be the same characteristics as used for the | ||
144 | * decoder) | ||
145 | * @param [in] channels <tt>int</tt>: Number of channels | ||
146 | * @param [out] error <tt>int*</tt>: Returns an error code | ||
147 | * @return Newly created encoder state. | ||
148 | */ | ||
149 | OPUS_CUSTOM_EXPORT OPUS_WARN_UNUSED_RESULT OpusCustomEncoder *opus_custom_encoder_create( | ||
150 | const OpusCustomMode *mode, | ||
151 | int channels, | ||
152 | int *error | ||
153 | ) OPUS_ARG_NONNULL(1); | ||
154 | |||
155 | /** Initializes a previously allocated encoder state | ||
156 | * The memory pointed to by st must be the size returned by opus_custom_encoder_get_size. | ||
157 | * This is intended for applications which use their own allocator instead of malloc. | ||
158 | * @see opus_custom_encoder_create(),opus_custom_encoder_get_size() | ||
159 | * To reset a previously initialized state use the OPUS_RESET_STATE CTL. | ||
160 | * @param [in] st <tt>OpusCustomEncoder*</tt>: Encoder state | ||
161 | * @param [in] mode <tt>OpusCustomMode *</tt>: Contains all the information about the characteristics of | ||
162 | * the stream (must be the same characteristics as used for the | ||
163 | * decoder) | ||
164 | * @param [in] channels <tt>int</tt>: Number of channels | ||
165 | * @return OPUS_OK Success or @ref opus_errorcodes | ||
166 | */ | ||
167 | OPUS_CUSTOM_EXPORT_STATIC int opus_custom_encoder_init( | ||
168 | OpusCustomEncoder *st, | ||
169 | const OpusCustomMode *mode, | ||
170 | int channels | ||
171 | ) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(2); | ||
172 | |||
173 | /** Destroys a an encoder state. | ||
174 | * @param[in] st <tt>OpusCustomEncoder*</tt>: State to be freed. | ||
175 | */ | ||
176 | OPUS_CUSTOM_EXPORT void opus_custom_encoder_destroy(OpusCustomEncoder *st); | ||
177 | |||
178 | /** Encodes a frame of audio. | ||
179 | * @param [in] st <tt>OpusCustomEncoder*</tt>: Encoder state | ||
180 | * @param [in] pcm <tt>float*</tt>: PCM audio in float format, with a normal range of +/-1.0. | ||
181 | * Samples with a range beyond +/-1.0 are supported but will | ||
182 | * be clipped by decoders using the integer API and should | ||
183 | * only be used if it is known that the far end supports | ||
184 | * extended dynamic range. There must be exactly | ||
185 | * frame_size samples per channel. | ||
186 | * @param [in] frame_size <tt>int</tt>: Number of samples per frame of input signal | ||
187 | * @param [out] compressed <tt>char *</tt>: The compressed data is written here. This may not alias pcm and must be at least maxCompressedBytes long. | ||
188 | * @param [in] maxCompressedBytes <tt>int</tt>: Maximum number of bytes to use for compressing the frame | ||
189 | * (can change from one frame to another) | ||
190 | * @return Number of bytes written to "compressed". | ||
191 | * If negative, an error has occurred (see error codes). It is IMPORTANT that | ||
192 | * the length returned be somehow transmitted to the decoder. Otherwise, no | ||
193 | * decoding is possible. | ||
194 | */ | ||
195 | OPUS_CUSTOM_EXPORT OPUS_WARN_UNUSED_RESULT int opus_custom_encode_float( | ||
196 | OpusCustomEncoder *st, | ||
197 | const float *pcm, | ||
198 | int frame_size, | ||
199 | unsigned char *compressed, | ||
200 | int maxCompressedBytes | ||
201 | ) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(2) OPUS_ARG_NONNULL(4); | ||
202 | |||
203 | /** Encodes a frame of audio. | ||
204 | * @param [in] st <tt>OpusCustomEncoder*</tt>: Encoder state | ||
205 | * @param [in] pcm <tt>opus_int16*</tt>: PCM audio in signed 16-bit format (native endian). | ||
206 | * There must be exactly frame_size samples per channel. | ||
207 | * @param [in] frame_size <tt>int</tt>: Number of samples per frame of input signal | ||
208 | * @param [out] compressed <tt>char *</tt>: The compressed data is written here. This may not alias pcm and must be at least maxCompressedBytes long. | ||
209 | * @param [in] maxCompressedBytes <tt>int</tt>: Maximum number of bytes to use for compressing the frame | ||
210 | * (can change from one frame to another) | ||
211 | * @return Number of bytes written to "compressed". | ||
212 | * If negative, an error has occurred (see error codes). It is IMPORTANT that | ||
213 | * the length returned be somehow transmitted to the decoder. Otherwise, no | ||
214 | * decoding is possible. | ||
215 | */ | ||
216 | OPUS_CUSTOM_EXPORT OPUS_WARN_UNUSED_RESULT int opus_custom_encode( | ||
217 | OpusCustomEncoder *st, | ||
218 | const opus_int16 *pcm, | ||
219 | int frame_size, | ||
220 | unsigned char *compressed, | ||
221 | int maxCompressedBytes | ||
222 | ) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(2) OPUS_ARG_NONNULL(4); | ||
223 | |||
224 | /** Perform a CTL function on an Opus custom encoder. | ||
225 | * | ||
226 | * Generally the request and subsequent arguments are generated | ||
227 | * by a convenience macro. | ||
228 | * @see opus_encoderctls | ||
229 | */ | ||
230 | OPUS_CUSTOM_EXPORT int opus_custom_encoder_ctl(OpusCustomEncoder * OPUS_RESTRICT st, int request, ...) OPUS_ARG_NONNULL(1); | ||
231 | |||
232 | /* Decoder */ | ||
233 | |||
234 | /** Gets the size of an OpusCustomDecoder structure. | ||
235 | * @param [in] mode <tt>OpusCustomMode *</tt>: Mode configuration | ||
236 | * @param [in] channels <tt>int</tt>: Number of channels | ||
237 | * @returns size | ||
238 | */ | ||
239 | OPUS_CUSTOM_EXPORT_STATIC OPUS_WARN_UNUSED_RESULT int opus_custom_decoder_get_size( | ||
240 | const OpusCustomMode *mode, | ||
241 | int channels | ||
242 | ) OPUS_ARG_NONNULL(1); | ||
243 | |||
244 | /** Creates a new decoder state. Each stream needs its own decoder state (can't | ||
245 | * be shared across simultaneous streams). | ||
246 | * @param [in] mode <tt>OpusCustomMode</tt>: Contains all the information about the characteristics of the | ||
247 | * stream (must be the same characteristics as used for the encoder) | ||
248 | * @param [in] channels <tt>int</tt>: Number of channels | ||
249 | * @param [out] error <tt>int*</tt>: Returns an error code | ||
250 | * @return Newly created decoder state. | ||
251 | */ | ||
252 | OPUS_CUSTOM_EXPORT OPUS_WARN_UNUSED_RESULT OpusCustomDecoder *opus_custom_decoder_create( | ||
253 | const OpusCustomMode *mode, | ||
254 | int channels, | ||
255 | int *error | ||
256 | ) OPUS_ARG_NONNULL(1); | ||
257 | |||
258 | /** Initializes a previously allocated decoder state | ||
259 | * The memory pointed to by st must be the size returned by opus_custom_decoder_get_size. | ||
260 | * This is intended for applications which use their own allocator instead of malloc. | ||
261 | * @see opus_custom_decoder_create(),opus_custom_decoder_get_size() | ||
262 | * To reset a previously initialized state use the OPUS_RESET_STATE CTL. | ||
263 | * @param [in] st <tt>OpusCustomDecoder*</tt>: Decoder state | ||
264 | * @param [in] mode <tt>OpusCustomMode *</tt>: Contains all the information about the characteristics of | ||
265 | * the stream (must be the same characteristics as used for the | ||
266 | * encoder) | ||
267 | * @param [in] channels <tt>int</tt>: Number of channels | ||
268 | * @return OPUS_OK Success or @ref opus_errorcodes | ||
269 | */ | ||
270 | OPUS_CUSTOM_EXPORT_STATIC int opus_custom_decoder_init( | ||
271 | OpusCustomDecoder *st, | ||
272 | const OpusCustomMode *mode, | ||
273 | int channels | ||
274 | ) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(2); | ||
275 | |||
276 | /** Destroys a an decoder state. | ||
277 | * @param[in] st <tt>OpusCustomDecoder*</tt>: State to be freed. | ||
278 | */ | ||
279 | OPUS_CUSTOM_EXPORT void opus_custom_decoder_destroy(OpusCustomDecoder *st); | ||
280 | |||
281 | /** Decode an opus custom frame with floating point output | ||
282 | * @param [in] st <tt>OpusCustomDecoder*</tt>: Decoder state | ||
283 | * @param [in] data <tt>char*</tt>: Input payload. Use a NULL pointer to indicate packet loss | ||
284 | * @param [in] len <tt>int</tt>: Number of bytes in payload | ||
285 | * @param [out] pcm <tt>float*</tt>: Output signal (interleaved if 2 channels). length | ||
286 | * is frame_size*channels*sizeof(float) | ||
287 | * @param [in] frame_size Number of samples per channel of available space in *pcm. | ||
288 | * @returns Number of decoded samples or @ref opus_errorcodes | ||
289 | */ | ||
290 | OPUS_CUSTOM_EXPORT OPUS_WARN_UNUSED_RESULT int opus_custom_decode_float( | ||
291 | OpusCustomDecoder *st, | ||
292 | const unsigned char *data, | ||
293 | int len, | ||
294 | float *pcm, | ||
295 | int frame_size | ||
296 | ) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(4); | ||
297 | |||
298 | /** Decode an opus custom frame | ||
299 | * @param [in] st <tt>OpusCustomDecoder*</tt>: Decoder state | ||
300 | * @param [in] data <tt>char*</tt>: Input payload. Use a NULL pointer to indicate packet loss | ||
301 | * @param [in] len <tt>int</tt>: Number of bytes in payload | ||
302 | * @param [out] pcm <tt>opus_int16*</tt>: Output signal (interleaved if 2 channels). length | ||
303 | * is frame_size*channels*sizeof(opus_int16) | ||
304 | * @param [in] frame_size Number of samples per channel of available space in *pcm. | ||
305 | * @returns Number of decoded samples or @ref opus_errorcodes | ||
306 | */ | ||
307 | OPUS_CUSTOM_EXPORT OPUS_WARN_UNUSED_RESULT int opus_custom_decode( | ||
308 | OpusCustomDecoder *st, | ||
309 | const unsigned char *data, | ||
310 | int len, | ||
311 | opus_int16 *pcm, | ||
312 | int frame_size | ||
313 | ) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(4); | ||
314 | |||
315 | /** Perform a CTL function on an Opus custom decoder. | ||
316 | * | ||
317 | * Generally the request and subsequent arguments are generated | ||
318 | * by a convenience macro. | ||
319 | * @see opus_genericctls | ||
320 | */ | ||
321 | OPUS_CUSTOM_EXPORT int opus_custom_decoder_ctl(OpusCustomDecoder * OPUS_RESTRICT st, int request, ...) OPUS_ARG_NONNULL(1); | ||
322 | |||
323 | /**@}*/ | ||
324 | |||
325 | #ifdef __cplusplus | ||
326 | } | ||
327 | #endif | ||
328 | |||
329 | #endif /* OPUS_CUSTOM_H */ | ||