2
0

opus_custom.h 14 KB

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