opus_custom.h 14 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342
  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.
  96. @brief Mode configuration
  97. */
  98. typedef struct OpusCustomMode OpusCustomMode;
  99. /** Creates a new mode struct. This will be passed to an encoder or
  100. * decoder. The mode MUST NOT BE DESTROYED until the encoders and
  101. * decoders that use it are destroyed as well.
  102. * @param [in] Fs <tt>int</tt>: Sampling rate (8000 to 96000 Hz)
  103. * @param [in] frame_size <tt>int</tt>: Number of samples (per channel) to encode in each
  104. * packet (64 - 1024, prime factorization must contain zero or more 2s, 3s, or 5s and no other primes)
  105. * @param [out] error <tt>int*</tt>: Returned error code (if NULL, no error will be returned)
  106. * @return A newly created mode
  107. */
  108. OPUS_CUSTOM_EXPORT OPUS_WARN_UNUSED_RESULT OpusCustomMode *opus_custom_mode_create(opus_int32 Fs, int frame_size, int *error);
  109. /** Destroys a mode struct. Only call this after all encoders and
  110. * decoders using this mode are destroyed as well.
  111. * @param [in] mode <tt>OpusCustomMode*</tt>: Mode to be freed.
  112. */
  113. OPUS_CUSTOM_EXPORT void opus_custom_mode_destroy(OpusCustomMode *mode);
  114. #if !defined(OPUS_BUILD) || defined(CELT_ENCODER_C)
  115. /* Encoder */
  116. /** Gets the size of an OpusCustomEncoder structure.
  117. * @param [in] mode <tt>OpusCustomMode *</tt>: Mode configuration
  118. * @param [in] channels <tt>int</tt>: Number of channels
  119. * @returns size
  120. */
  121. OPUS_CUSTOM_EXPORT_STATIC OPUS_WARN_UNUSED_RESULT int opus_custom_encoder_get_size(
  122. const OpusCustomMode *mode,
  123. int channels
  124. ) OPUS_ARG_NONNULL(1);
  125. # ifdef CUSTOM_MODES
  126. /** Initializes a previously allocated encoder state
  127. * The memory pointed to by st must be the size returned by opus_custom_encoder_get_size.
  128. * This is intended for applications which use their own allocator instead of malloc.
  129. * @see opus_custom_encoder_create(),opus_custom_encoder_get_size()
  130. * To reset a previously initialized state use the OPUS_RESET_STATE CTL.
  131. * @param [in] st <tt>OpusCustomEncoder*</tt>: Encoder state
  132. * @param [in] mode <tt>OpusCustomMode *</tt>: Contains all the information about the characteristics of
  133. * the stream (must be the same characteristics as used for the
  134. * decoder)
  135. * @param [in] channels <tt>int</tt>: Number of channels
  136. * @return OPUS_OK Success or @ref opus_errorcodes
  137. */
  138. OPUS_CUSTOM_EXPORT int opus_custom_encoder_init(
  139. OpusCustomEncoder *st,
  140. const OpusCustomMode *mode,
  141. int channels
  142. ) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(2);
  143. # endif
  144. #endif
  145. /** Creates a new encoder state. Each stream needs its own encoder
  146. * state (can't be shared across simultaneous streams).
  147. * @param [in] mode <tt>OpusCustomMode*</tt>: Contains all the information about the characteristics of
  148. * the stream (must be the same characteristics as used for the
  149. * decoder)
  150. * @param [in] channels <tt>int</tt>: Number of channels
  151. * @param [out] error <tt>int*</tt>: Returns an error code
  152. * @return Newly created encoder state.
  153. */
  154. OPUS_CUSTOM_EXPORT OPUS_WARN_UNUSED_RESULT OpusCustomEncoder *opus_custom_encoder_create(
  155. const OpusCustomMode *mode,
  156. int channels,
  157. int *error
  158. ) OPUS_ARG_NONNULL(1);
  159. /** Destroys an encoder state.
  160. * @param[in] st <tt>OpusCustomEncoder*</tt>: State to be freed.
  161. */
  162. OPUS_CUSTOM_EXPORT void opus_custom_encoder_destroy(OpusCustomEncoder *st);
  163. /** Encodes a frame of audio.
  164. * @param [in] st <tt>OpusCustomEncoder*</tt>: Encoder state
  165. * @param [in] pcm <tt>float*</tt>: PCM audio in float format, with a normal range of +/-1.0.
  166. * Samples with a range beyond +/-1.0 are supported but will
  167. * be clipped by decoders using the integer API and should
  168. * only be used if it is known that the far end supports
  169. * extended dynamic range. There must be exactly
  170. * frame_size samples per channel.
  171. * @param [in] frame_size <tt>int</tt>: Number of samples per frame of input signal
  172. * @param [out] compressed <tt>char *</tt>: The compressed data is written here. This may not alias pcm and must be at least maxCompressedBytes long.
  173. * @param [in] maxCompressedBytes <tt>int</tt>: Maximum number of bytes to use for compressing the frame
  174. * (can change from one frame to another)
  175. * @return Number of bytes written to "compressed".
  176. * If negative, an error has occurred (see error codes). It is IMPORTANT that
  177. * the length returned be somehow transmitted to the decoder. Otherwise, no
  178. * decoding is possible.
  179. */
  180. OPUS_CUSTOM_EXPORT OPUS_WARN_UNUSED_RESULT int opus_custom_encode_float(
  181. OpusCustomEncoder *st,
  182. const float *pcm,
  183. int frame_size,
  184. unsigned char *compressed,
  185. int maxCompressedBytes
  186. ) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(2) OPUS_ARG_NONNULL(4);
  187. /** Encodes a frame of audio.
  188. * @param [in] st <tt>OpusCustomEncoder*</tt>: Encoder state
  189. * @param [in] pcm <tt>opus_int16*</tt>: PCM audio in signed 16-bit format (native endian).
  190. * There must be exactly frame_size samples per channel.
  191. * @param [in] frame_size <tt>int</tt>: Number of samples per frame of input signal
  192. * @param [out] compressed <tt>char *</tt>: The compressed data is written here. This may not alias pcm and must be at least maxCompressedBytes long.
  193. * @param [in] maxCompressedBytes <tt>int</tt>: Maximum number of bytes to use for compressing the frame
  194. * (can change from one frame to another)
  195. * @return Number of bytes written to "compressed".
  196. * If negative, an error has occurred (see error codes). It is IMPORTANT that
  197. * the length returned be somehow transmitted to the decoder. Otherwise, no
  198. * decoding is possible.
  199. */
  200. OPUS_CUSTOM_EXPORT OPUS_WARN_UNUSED_RESULT int opus_custom_encode(
  201. OpusCustomEncoder *st,
  202. const opus_int16 *pcm,
  203. int frame_size,
  204. unsigned char *compressed,
  205. int maxCompressedBytes
  206. ) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(2) OPUS_ARG_NONNULL(4);
  207. /** Perform a CTL function on an Opus custom encoder.
  208. *
  209. * Generally the request and subsequent arguments are generated
  210. * by a convenience macro.
  211. * @see opus_encoderctls
  212. */
  213. OPUS_CUSTOM_EXPORT int opus_custom_encoder_ctl(OpusCustomEncoder * OPUS_RESTRICT st, int request, ...) OPUS_ARG_NONNULL(1);
  214. #if !defined(OPUS_BUILD) || defined(CELT_DECODER_C)
  215. /* Decoder */
  216. /** Gets the size of an OpusCustomDecoder structure.
  217. * @param [in] mode <tt>OpusCustomMode *</tt>: Mode configuration
  218. * @param [in] channels <tt>int</tt>: Number of channels
  219. * @returns size
  220. */
  221. OPUS_CUSTOM_EXPORT_STATIC OPUS_WARN_UNUSED_RESULT int opus_custom_decoder_get_size(
  222. const OpusCustomMode *mode,
  223. int channels
  224. ) OPUS_ARG_NONNULL(1);
  225. /** Initializes a previously allocated decoder state
  226. * The memory pointed to by st must be the size returned by opus_custom_decoder_get_size.
  227. * This is intended for applications which use their own allocator instead of malloc.
  228. * @see opus_custom_decoder_create(),opus_custom_decoder_get_size()
  229. * To reset a previously initialized state use the OPUS_RESET_STATE CTL.
  230. * @param [in] st <tt>OpusCustomDecoder*</tt>: Decoder state
  231. * @param [in] mode <tt>OpusCustomMode *</tt>: Contains all the information about the characteristics of
  232. * the stream (must be the same characteristics as used for the
  233. * encoder)
  234. * @param [in] channels <tt>int</tt>: Number of channels
  235. * @return OPUS_OK Success or @ref opus_errorcodes
  236. */
  237. OPUS_CUSTOM_EXPORT_STATIC int opus_custom_decoder_init(
  238. OpusCustomDecoder *st,
  239. const OpusCustomMode *mode,
  240. int channels
  241. ) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(2);
  242. #endif
  243. /** Creates a new decoder state. Each stream needs its own decoder state (can't
  244. * be shared across simultaneous streams).
  245. * @param [in] mode <tt>OpusCustomMode</tt>: Contains all the information about the characteristics of the
  246. * stream (must be the same characteristics as used for the encoder)
  247. * @param [in] channels <tt>int</tt>: Number of channels
  248. * @param [out] error <tt>int*</tt>: Returns an error code
  249. * @return Newly created decoder state.
  250. */
  251. OPUS_CUSTOM_EXPORT OPUS_WARN_UNUSED_RESULT OpusCustomDecoder *opus_custom_decoder_create(
  252. const OpusCustomMode *mode,
  253. int channels,
  254. int *error
  255. ) OPUS_ARG_NONNULL(1);
  256. /** Destroys a decoder state.
  257. * @param[in] st <tt>OpusCustomDecoder*</tt>: State to be freed.
  258. */
  259. OPUS_CUSTOM_EXPORT void opus_custom_decoder_destroy(OpusCustomDecoder *st);
  260. /** Decode an opus custom frame with floating point output
  261. * @param [in] st <tt>OpusCustomDecoder*</tt>: Decoder state
  262. * @param [in] data <tt>char*</tt>: Input payload. Use a NULL pointer to indicate packet loss
  263. * @param [in] len <tt>int</tt>: Number of bytes in payload
  264. * @param [out] pcm <tt>float*</tt>: Output signal (interleaved if 2 channels). length
  265. * is frame_size*channels*sizeof(float)
  266. * @param [in] frame_size Number of samples per channel of available space in *pcm.
  267. * @returns Number of decoded samples or @ref opus_errorcodes
  268. */
  269. OPUS_CUSTOM_EXPORT OPUS_WARN_UNUSED_RESULT int opus_custom_decode_float(
  270. OpusCustomDecoder *st,
  271. const unsigned char *data,
  272. int len,
  273. float *pcm,
  274. int frame_size
  275. ) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(4);
  276. /** Decode an opus custom frame
  277. * @param [in] st <tt>OpusCustomDecoder*</tt>: Decoder state
  278. * @param [in] data <tt>char*</tt>: Input payload. Use a NULL pointer to indicate packet loss
  279. * @param [in] len <tt>int</tt>: Number of bytes in payload
  280. * @param [out] pcm <tt>opus_int16*</tt>: Output signal (interleaved if 2 channels). length
  281. * is frame_size*channels*sizeof(opus_int16)
  282. * @param [in] frame_size Number of samples per channel of available space in *pcm.
  283. * @returns Number of decoded samples or @ref opus_errorcodes
  284. */
  285. OPUS_CUSTOM_EXPORT OPUS_WARN_UNUSED_RESULT int opus_custom_decode(
  286. OpusCustomDecoder *st,
  287. const unsigned char *data,
  288. int len,
  289. opus_int16 *pcm,
  290. int frame_size
  291. ) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(4);
  292. /** Perform a CTL function on an Opus custom decoder.
  293. *
  294. * Generally the request and subsequent arguments are generated
  295. * by a convenience macro.
  296. * @see opus_genericctls
  297. */
  298. OPUS_CUSTOM_EXPORT int opus_custom_decoder_ctl(OpusCustomDecoder * OPUS_RESTRICT st, int request, ...) OPUS_ARG_NONNULL(1);
  299. /**@}*/
  300. #ifdef __cplusplus
  301. }
  302. #endif
  303. #endif /* OPUS_CUSTOM_H */