opus_multistream.h 33 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660
  1. /* Copyright (c) 2011 Xiph.Org Foundation
  2. Written by Jean-Marc Valin */
  3. /*
  4. Redistribution and use in source and binary forms, with or without
  5. modification, are permitted provided that the following conditions
  6. are met:
  7. - Redistributions of source code must retain the above copyright
  8. notice, this list of conditions and the following disclaimer.
  9. - Redistributions in binary form must reproduce the above copyright
  10. notice, this list of conditions and the following disclaimer in the
  11. documentation and/or other materials provided with the distribution.
  12. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  13. ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  14. LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  15. A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER
  16. OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
  17. EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  18. PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
  19. PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
  20. LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
  21. NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  22. SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  23. */
  24. /**
  25. * @file opus_multistream.h
  26. * @brief Opus reference implementation multistream API
  27. */
  28. #ifndef OPUS_MULTISTREAM_H
  29. #define OPUS_MULTISTREAM_H
  30. #include "opus.h"
  31. #ifdef __cplusplus
  32. extern "C" {
  33. #endif
  34. /** @cond OPUS_INTERNAL_DOC */
  35. /** Macros to trigger compilation errors when the wrong types are provided to a
  36. * CTL. */
  37. /**@{*/
  38. #define __opus_check_encstate_ptr(ptr) ((ptr) + ((ptr) - (OpusEncoder**)(ptr)))
  39. #define __opus_check_decstate_ptr(ptr) ((ptr) + ((ptr) - (OpusDecoder**)(ptr)))
  40. /**@}*/
  41. /** These are the actual encoder and decoder CTL ID numbers.
  42. * They should not be used directly by applications.
  43. * In general, SETs should be even and GETs should be odd.*/
  44. /**@{*/
  45. #define OPUS_MULTISTREAM_GET_ENCODER_STATE_REQUEST 5120
  46. #define OPUS_MULTISTREAM_GET_DECODER_STATE_REQUEST 5122
  47. /**@}*/
  48. /** @endcond */
  49. /** @defgroup opus_multistream_ctls Multistream specific encoder and decoder CTLs
  50. *
  51. * These are convenience macros that are specific to the
  52. * opus_multistream_encoder_ctl() and opus_multistream_decoder_ctl()
  53. * interface.
  54. * The CTLs from @ref opus_genericctls, @ref opus_encoderctls, and
  55. * @ref opus_decoderctls may be applied to a multistream encoder or decoder as
  56. * well.
  57. * In addition, you may retrieve the encoder or decoder state for an specific
  58. * stream via #OPUS_MULTISTREAM_GET_ENCODER_STATE or
  59. * #OPUS_MULTISTREAM_GET_DECODER_STATE and apply CTLs to it individually.
  60. */
  61. /**@{*/
  62. /** Gets the encoder state for an individual stream of a multistream encoder.
  63. * @param[in] x <tt>opus_int32</tt>: The index of the stream whose encoder you
  64. * wish to retrieve.
  65. * This must be non-negative and less than
  66. * the <code>streams</code> parameter used
  67. * to initialize the encoder.
  68. * @param[out] y <tt>OpusEncoder**</tt>: Returns a pointer to the given
  69. * encoder state.
  70. * @retval OPUS_BAD_ARG The index of the requested stream was out of range.
  71. * @hideinitializer
  72. */
  73. #define OPUS_MULTISTREAM_GET_ENCODER_STATE(x,y) OPUS_MULTISTREAM_GET_ENCODER_STATE_REQUEST, __opus_check_int(x), __opus_check_encstate_ptr(y)
  74. /** Gets the decoder state for an individual stream of a multistream decoder.
  75. * @param[in] x <tt>opus_int32</tt>: The index of the stream whose decoder you
  76. * wish to retrieve.
  77. * This must be non-negative and less than
  78. * the <code>streams</code> parameter used
  79. * to initialize the decoder.
  80. * @param[out] y <tt>OpusDecoder**</tt>: Returns a pointer to the given
  81. * decoder state.
  82. * @retval OPUS_BAD_ARG The index of the requested stream was out of range.
  83. * @hideinitializer
  84. */
  85. #define OPUS_MULTISTREAM_GET_DECODER_STATE(x,y) OPUS_MULTISTREAM_GET_DECODER_STATE_REQUEST, __opus_check_int(x), __opus_check_decstate_ptr(y)
  86. /**@}*/
  87. /** @defgroup opus_multistream Opus Multistream API
  88. * @{
  89. *
  90. * The multistream API allows individual Opus streams to be combined into a
  91. * single packet, enabling support for up to 255 channels. Unlike an
  92. * elementary Opus stream, the encoder and decoder must negotiate the channel
  93. * configuration before the decoder can successfully interpret the data in the
  94. * packets produced by the encoder. Some basic information, such as packet
  95. * duration, can be computed without any special negotiation.
  96. *
  97. * The format for multistream Opus packets is defined in the
  98. * <a href="http://tools.ietf.org/html/draft-terriberry-oggopus">Ogg
  99. * encapsulation specification</a> and is based on the self-delimited Opus
  100. * framing described in Appendix B of <a href="http://tools.ietf.org/html/rfc6716">RFC 6716</a>.
  101. * Normal Opus packets are just a degenerate case of multistream Opus packets,
  102. * and can be encoded or decoded with the multistream API by setting
  103. * <code>streams</code> to <code>1</code> when initializing the encoder or
  104. * decoder.
  105. *
  106. * Multistream Opus streams can contain up to 255 elementary Opus streams.
  107. * These may be either "uncoupled" or "coupled", indicating that the decoder
  108. * is configured to decode them to either 1 or 2 channels, respectively.
  109. * The streams are ordered so that all coupled streams appear at the
  110. * beginning.
  111. *
  112. * A <code>mapping</code> table defines which decoded channel <code>i</code>
  113. * should be used for each input/output (I/O) channel <code>j</code>. This table is
  114. * typically provided as an unsigned char array.
  115. * Let <code>i = mapping[j]</code> be the index for I/O channel <code>j</code>.
  116. * If <code>i < 2*coupled_streams</code>, then I/O channel <code>j</code> is
  117. * encoded as the left channel of stream <code>(i/2)</code> if <code>i</code>
  118. * is even, or as the right channel of stream <code>(i/2)</code> if
  119. * <code>i</code> is odd. Otherwise, I/O channel <code>j</code> is encoded as
  120. * mono in stream <code>(i - coupled_streams)</code>, unless it has the special
  121. * value 255, in which case it is omitted from the encoding entirely (the
  122. * decoder will reproduce it as silence). Each value <code>i</code> must either
  123. * be the special value 255 or be less than <code>streams + coupled_streams</code>.
  124. *
  125. * The output channels specified by the encoder
  126. * should use the
  127. * <a href="http://www.xiph.org/vorbis/doc/Vorbis_I_spec.html#x1-800004.3.9">Vorbis
  128. * channel ordering</a>. A decoder may wish to apply an additional permutation
  129. * to the mapping the encoder used to achieve a different output channel
  130. * order (e.g. for outputing in WAV order).
  131. *
  132. * Each multistream packet contains an Opus packet for each stream, and all of
  133. * the Opus packets in a single multistream packet must have the same
  134. * duration. Therefore the duration of a multistream packet can be extracted
  135. * from the TOC sequence of the first stream, which is located at the
  136. * beginning of the packet, just like an elementary Opus stream:
  137. *
  138. * @code
  139. * int nb_samples;
  140. * int nb_frames;
  141. * nb_frames = opus_packet_get_nb_frames(data, len);
  142. * if (nb_frames < 1)
  143. * return nb_frames;
  144. * nb_samples = opus_packet_get_samples_per_frame(data, 48000) * nb_frames;
  145. * @endcode
  146. *
  147. * The general encoding and decoding process proceeds exactly the same as in
  148. * the normal @ref opus_encoder and @ref opus_decoder APIs.
  149. * See their documentation for an overview of how to use the corresponding
  150. * multistream functions.
  151. */
  152. /** Opus multistream encoder state.
  153. * This contains the complete state of a multistream Opus encoder.
  154. * It is position independent and can be freely copied.
  155. * @see opus_multistream_encoder_create
  156. * @see opus_multistream_encoder_init
  157. */
  158. typedef struct OpusMSEncoder OpusMSEncoder;
  159. /** Opus multistream decoder state.
  160. * This contains the complete state of a multistream Opus decoder.
  161. * It is position independent and can be freely copied.
  162. * @see opus_multistream_decoder_create
  163. * @see opus_multistream_decoder_init
  164. */
  165. typedef struct OpusMSDecoder OpusMSDecoder;
  166. /**\name Multistream encoder functions */
  167. /**@{*/
  168. /** Gets the size of an OpusMSEncoder structure.
  169. * @param streams <tt>int</tt>: The total number of streams to encode from the
  170. * input.
  171. * This must be no more than 255.
  172. * @param coupled_streams <tt>int</tt>: Number of coupled (2 channel) streams
  173. * to encode.
  174. * This must be no larger than the total
  175. * number of streams.
  176. * Additionally, The total number of
  177. * encoded channels (<code>streams +
  178. * coupled_streams</code>) must be no
  179. * more than 255.
  180. * @returns The size in bytes on success, or a negative error code
  181. * (see @ref opus_errorcodes) on error.
  182. */
  183. OPUS_EXPORT OPUS_WARN_UNUSED_RESULT opus_int32 opus_multistream_encoder_get_size(
  184. int streams,
  185. int coupled_streams
  186. );
  187. OPUS_EXPORT OPUS_WARN_UNUSED_RESULT opus_int32 opus_multistream_surround_encoder_get_size(
  188. int channels,
  189. int mapping_family
  190. );
  191. /** Allocates and initializes a multistream encoder state.
  192. * Call opus_multistream_encoder_destroy() to release
  193. * this object when finished.
  194. * @param Fs <tt>opus_int32</tt>: Sampling rate of the input signal (in Hz).
  195. * This must be one of 8000, 12000, 16000,
  196. * 24000, or 48000.
  197. * @param channels <tt>int</tt>: Number of channels in the input signal.
  198. * This must be at most 255.
  199. * It may be greater than the number of
  200. * coded channels (<code>streams +
  201. * coupled_streams</code>).
  202. * @param streams <tt>int</tt>: The total number of streams to encode from the
  203. * input.
  204. * This must be no more than the number of channels.
  205. * @param coupled_streams <tt>int</tt>: Number of coupled (2 channel) streams
  206. * to encode.
  207. * This must be no larger than the total
  208. * number of streams.
  209. * Additionally, The total number of
  210. * encoded channels (<code>streams +
  211. * coupled_streams</code>) must be no
  212. * more than the number of input channels.
  213. * @param[in] mapping <code>const unsigned char[channels]</code>: Mapping from
  214. * encoded channels to input channels, as described in
  215. * @ref opus_multistream. As an extra constraint, the
  216. * multistream encoder does not allow encoding coupled
  217. * streams for which one channel is unused since this
  218. * is never a good idea.
  219. * @param application <tt>int</tt>: The target encoder application.
  220. * This must be one of the following:
  221. * <dl>
  222. * <dt>#OPUS_APPLICATION_VOIP</dt>
  223. * <dd>Process signal for improved speech intelligibility.</dd>
  224. * <dt>#OPUS_APPLICATION_AUDIO</dt>
  225. * <dd>Favor faithfulness to the original input.</dd>
  226. * <dt>#OPUS_APPLICATION_RESTRICTED_LOWDELAY</dt>
  227. * <dd>Configure the minimum possible coding delay by disabling certain modes
  228. * of operation.</dd>
  229. * </dl>
  230. * @param[out] error <tt>int *</tt>: Returns #OPUS_OK on success, or an error
  231. * code (see @ref opus_errorcodes) on
  232. * failure.
  233. */
  234. OPUS_EXPORT OPUS_WARN_UNUSED_RESULT OpusMSEncoder *opus_multistream_encoder_create(
  235. opus_int32 Fs,
  236. int channels,
  237. int streams,
  238. int coupled_streams,
  239. const unsigned char *mapping,
  240. int application,
  241. int *error
  242. ) OPUS_ARG_NONNULL(5);
  243. OPUS_EXPORT OPUS_WARN_UNUSED_RESULT OpusMSEncoder *opus_multistream_surround_encoder_create(
  244. opus_int32 Fs,
  245. int channels,
  246. int mapping_family,
  247. int *streams,
  248. int *coupled_streams,
  249. unsigned char *mapping,
  250. int application,
  251. int *error
  252. ) OPUS_ARG_NONNULL(5);
  253. /** Initialize a previously allocated multistream encoder state.
  254. * The memory pointed to by \a st must be at least the size returned by
  255. * opus_multistream_encoder_get_size().
  256. * This is intended for applications which use their own allocator instead of
  257. * malloc.
  258. * To reset a previously initialized state, use the #OPUS_RESET_STATE CTL.
  259. * @see opus_multistream_encoder_create
  260. * @see opus_multistream_encoder_get_size
  261. * @param st <tt>OpusMSEncoder*</tt>: Multistream encoder state to initialize.
  262. * @param Fs <tt>opus_int32</tt>: Sampling rate of the input signal (in Hz).
  263. * This must be one of 8000, 12000, 16000,
  264. * 24000, or 48000.
  265. * @param channels <tt>int</tt>: Number of channels in the input signal.
  266. * This must be at most 255.
  267. * It may be greater than the number of
  268. * coded channels (<code>streams +
  269. * coupled_streams</code>).
  270. * @param streams <tt>int</tt>: The total number of streams to encode from the
  271. * input.
  272. * This must be no more than the number of channels.
  273. * @param coupled_streams <tt>int</tt>: Number of coupled (2 channel) streams
  274. * to encode.
  275. * This must be no larger than the total
  276. * number of streams.
  277. * Additionally, The total number of
  278. * encoded channels (<code>streams +
  279. * coupled_streams</code>) must be no
  280. * more than the number of input channels.
  281. * @param[in] mapping <code>const unsigned char[channels]</code>: Mapping from
  282. * encoded channels to input channels, as described in
  283. * @ref opus_multistream. As an extra constraint, the
  284. * multistream encoder does not allow encoding coupled
  285. * streams for which one channel is unused since this
  286. * is never a good idea.
  287. * @param application <tt>int</tt>: The target encoder application.
  288. * This must be one of the following:
  289. * <dl>
  290. * <dt>#OPUS_APPLICATION_VOIP</dt>
  291. * <dd>Process signal for improved speech intelligibility.</dd>
  292. * <dt>#OPUS_APPLICATION_AUDIO</dt>
  293. * <dd>Favor faithfulness to the original input.</dd>
  294. * <dt>#OPUS_APPLICATION_RESTRICTED_LOWDELAY</dt>
  295. * <dd>Configure the minimum possible coding delay by disabling certain modes
  296. * of operation.</dd>
  297. * </dl>
  298. * @returns #OPUS_OK on success, or an error code (see @ref opus_errorcodes)
  299. * on failure.
  300. */
  301. OPUS_EXPORT int opus_multistream_encoder_init(
  302. OpusMSEncoder *st,
  303. opus_int32 Fs,
  304. int channels,
  305. int streams,
  306. int coupled_streams,
  307. const unsigned char *mapping,
  308. int application
  309. ) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(6);
  310. OPUS_EXPORT int opus_multistream_surround_encoder_init(
  311. OpusMSEncoder *st,
  312. opus_int32 Fs,
  313. int channels,
  314. int mapping_family,
  315. int *streams,
  316. int *coupled_streams,
  317. unsigned char *mapping,
  318. int application
  319. ) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(6);
  320. /** Encodes a multistream Opus frame.
  321. * @param st <tt>OpusMSEncoder*</tt>: Multistream encoder state.
  322. * @param[in] pcm <tt>const opus_int16*</tt>: The input signal as interleaved
  323. * samples.
  324. * This must contain
  325. * <code>frame_size*channels</code>
  326. * samples.
  327. * @param frame_size <tt>int</tt>: Number of samples per channel in the input
  328. * signal.
  329. * This must be an Opus frame size for the
  330. * encoder's sampling rate.
  331. * For example, at 48 kHz the permitted values
  332. * are 120, 240, 480, 960, 1920, and 2880.
  333. * Passing in a duration of less than 10 ms
  334. * (480 samples at 48 kHz) will prevent the
  335. * encoder from using the LPC or hybrid modes.
  336. * @param[out] data <tt>unsigned char*</tt>: Output payload.
  337. * This must contain storage for at
  338. * least \a max_data_bytes.
  339. * @param [in] max_data_bytes <tt>opus_int32</tt>: Size of the allocated
  340. * memory for the output
  341. * payload. This may be
  342. * used to impose an upper limit on
  343. * the instant bitrate, but should
  344. * not be used as the only bitrate
  345. * control. Use #OPUS_SET_BITRATE to
  346. * control the bitrate.
  347. * @returns The length of the encoded packet (in bytes) on success or a
  348. * negative error code (see @ref opus_errorcodes) on failure.
  349. */
  350. OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_multistream_encode(
  351. OpusMSEncoder *st,
  352. const opus_int16 *pcm,
  353. int frame_size,
  354. unsigned char *data,
  355. opus_int32 max_data_bytes
  356. ) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(2) OPUS_ARG_NONNULL(4);
  357. /** Encodes a multistream Opus frame from floating point input.
  358. * @param st <tt>OpusMSEncoder*</tt>: Multistream encoder state.
  359. * @param[in] pcm <tt>const float*</tt>: The input signal as interleaved
  360. * samples with a normal range of
  361. * +/-1.0.
  362. * Samples with a range beyond +/-1.0
  363. * are supported but will be clipped by
  364. * decoders using the integer API and
  365. * should only be used if it is known
  366. * that the far end supports extended
  367. * dynamic range.
  368. * This must contain
  369. * <code>frame_size*channels</code>
  370. * samples.
  371. * @param frame_size <tt>int</tt>: Number of samples per channel in the input
  372. * signal.
  373. * This must be an Opus frame size for the
  374. * encoder's sampling rate.
  375. * For example, at 48 kHz the permitted values
  376. * are 120, 240, 480, 960, 1920, and 2880.
  377. * Passing in a duration of less than 10 ms
  378. * (480 samples at 48 kHz) will prevent the
  379. * encoder from using the LPC or hybrid modes.
  380. * @param[out] data <tt>unsigned char*</tt>: Output payload.
  381. * This must contain storage for at
  382. * least \a max_data_bytes.
  383. * @param [in] max_data_bytes <tt>opus_int32</tt>: Size of the allocated
  384. * memory for the output
  385. * payload. This may be
  386. * used to impose an upper limit on
  387. * the instant bitrate, but should
  388. * not be used as the only bitrate
  389. * control. Use #OPUS_SET_BITRATE to
  390. * control the bitrate.
  391. * @returns The length of the encoded packet (in bytes) on success or a
  392. * negative error code (see @ref opus_errorcodes) on failure.
  393. */
  394. OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_multistream_encode_float(
  395. OpusMSEncoder *st,
  396. const float *pcm,
  397. int frame_size,
  398. unsigned char *data,
  399. opus_int32 max_data_bytes
  400. ) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(2) OPUS_ARG_NONNULL(4);
  401. /** Frees an <code>OpusMSEncoder</code> allocated by
  402. * opus_multistream_encoder_create().
  403. * @param st <tt>OpusMSEncoder*</tt>: Multistream encoder state to be freed.
  404. */
  405. OPUS_EXPORT void opus_multistream_encoder_destroy(OpusMSEncoder *st);
  406. /** Perform a CTL function on a multistream Opus encoder.
  407. *
  408. * Generally the request and subsequent arguments are generated by a
  409. * convenience macro.
  410. * @param st <tt>OpusMSEncoder*</tt>: Multistream encoder state.
  411. * @param request This and all remaining parameters should be replaced by one
  412. * of the convenience macros in @ref opus_genericctls,
  413. * @ref opus_encoderctls, or @ref opus_multistream_ctls.
  414. * @see opus_genericctls
  415. * @see opus_encoderctls
  416. * @see opus_multistream_ctls
  417. */
  418. OPUS_EXPORT int opus_multistream_encoder_ctl(OpusMSEncoder *st, int request, ...) OPUS_ARG_NONNULL(1);
  419. /**@}*/
  420. /**\name Multistream decoder functions */
  421. /**@{*/
  422. /** Gets the size of an <code>OpusMSDecoder</code> structure.
  423. * @param streams <tt>int</tt>: The total number of streams coded in the
  424. * input.
  425. * This must be no more than 255.
  426. * @param coupled_streams <tt>int</tt>: Number streams to decode as coupled
  427. * (2 channel) streams.
  428. * This must be no larger than the total
  429. * number of streams.
  430. * Additionally, The total number of
  431. * coded channels (<code>streams +
  432. * coupled_streams</code>) must be no
  433. * more than 255.
  434. * @returns The size in bytes on success, or a negative error code
  435. * (see @ref opus_errorcodes) on error.
  436. */
  437. OPUS_EXPORT OPUS_WARN_UNUSED_RESULT opus_int32 opus_multistream_decoder_get_size(
  438. int streams,
  439. int coupled_streams
  440. );
  441. /** Allocates and initializes a multistream decoder state.
  442. * Call opus_multistream_decoder_destroy() to release
  443. * this object when finished.
  444. * @param Fs <tt>opus_int32</tt>: Sampling rate to decode at (in Hz).
  445. * This must be one of 8000, 12000, 16000,
  446. * 24000, or 48000.
  447. * @param channels <tt>int</tt>: Number of channels to output.
  448. * This must be at most 255.
  449. * It may be different from the number of coded
  450. * channels (<code>streams +
  451. * coupled_streams</code>).
  452. * @param streams <tt>int</tt>: The total number of streams coded in the
  453. * input.
  454. * This must be no more than 255.
  455. * @param coupled_streams <tt>int</tt>: Number of streams to decode as coupled
  456. * (2 channel) streams.
  457. * This must be no larger than the total
  458. * number of streams.
  459. * Additionally, The total number of
  460. * coded channels (<code>streams +
  461. * coupled_streams</code>) must be no
  462. * more than 255.
  463. * @param[in] mapping <code>const unsigned char[channels]</code>: Mapping from
  464. * coded channels to output channels, as described in
  465. * @ref opus_multistream.
  466. * @param[out] error <tt>int *</tt>: Returns #OPUS_OK on success, or an error
  467. * code (see @ref opus_errorcodes) on
  468. * failure.
  469. */
  470. OPUS_EXPORT OPUS_WARN_UNUSED_RESULT OpusMSDecoder *opus_multistream_decoder_create(
  471. opus_int32 Fs,
  472. int channels,
  473. int streams,
  474. int coupled_streams,
  475. const unsigned char *mapping,
  476. int *error
  477. ) OPUS_ARG_NONNULL(5);
  478. /** Intialize a previously allocated decoder state object.
  479. * The memory pointed to by \a st must be at least the size returned by
  480. * opus_multistream_encoder_get_size().
  481. * This is intended for applications which use their own allocator instead of
  482. * malloc.
  483. * To reset a previously initialized state, use the #OPUS_RESET_STATE CTL.
  484. * @see opus_multistream_decoder_create
  485. * @see opus_multistream_deocder_get_size
  486. * @param st <tt>OpusMSEncoder*</tt>: Multistream encoder state to initialize.
  487. * @param Fs <tt>opus_int32</tt>: Sampling rate to decode at (in Hz).
  488. * This must be one of 8000, 12000, 16000,
  489. * 24000, or 48000.
  490. * @param channels <tt>int</tt>: Number of channels to output.
  491. * This must be at most 255.
  492. * It may be different from the number of coded
  493. * channels (<code>streams +
  494. * coupled_streams</code>).
  495. * @param streams <tt>int</tt>: The total number of streams coded in the
  496. * input.
  497. * This must be no more than 255.
  498. * @param coupled_streams <tt>int</tt>: Number of streams to decode as coupled
  499. * (2 channel) streams.
  500. * This must be no larger than the total
  501. * number of streams.
  502. * Additionally, The total number of
  503. * coded channels (<code>streams +
  504. * coupled_streams</code>) must be no
  505. * more than 255.
  506. * @param[in] mapping <code>const unsigned char[channels]</code>: Mapping from
  507. * coded channels to output channels, as described in
  508. * @ref opus_multistream.
  509. * @returns #OPUS_OK on success, or an error code (see @ref opus_errorcodes)
  510. * on failure.
  511. */
  512. OPUS_EXPORT int opus_multistream_decoder_init(
  513. OpusMSDecoder *st,
  514. opus_int32 Fs,
  515. int channels,
  516. int streams,
  517. int coupled_streams,
  518. const unsigned char *mapping
  519. ) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(6);
  520. /** Decode a multistream Opus packet.
  521. * @param st <tt>OpusMSDecoder*</tt>: Multistream decoder state.
  522. * @param[in] data <tt>const unsigned char*</tt>: Input payload.
  523. * Use a <code>NULL</code>
  524. * pointer to indicate packet
  525. * loss.
  526. * @param len <tt>opus_int32</tt>: Number of bytes in payload.
  527. * @param[out] pcm <tt>opus_int16*</tt>: Output signal, with interleaved
  528. * samples.
  529. * This must contain room for
  530. * <code>frame_size*channels</code>
  531. * samples.
  532. * @param frame_size <tt>int</tt>: The number of samples per channel of
  533. * available space in \a pcm.
  534. * If this is less than the maximum packet duration
  535. * (120 ms; 5760 for 48kHz), this function will not be capable
  536. * of decoding some packets. In the case of PLC (data==NULL)
  537. * or FEC (decode_fec=1), then frame_size needs to be exactly
  538. * the duration of audio that is missing, otherwise the
  539. * decoder will not be in the optimal state to decode the
  540. * next incoming packet. For the PLC and FEC cases, frame_size
  541. * <b>must</b> be a multiple of 2.5 ms.
  542. * @param decode_fec <tt>int</tt>: Flag (0 or 1) to request that any in-band
  543. * forward error correction data be decoded.
  544. * If no such data is available, the frame is
  545. * decoded as if it were lost.
  546. * @returns Number of samples decoded on success or a negative error code
  547. * (see @ref opus_errorcodes) on failure.
  548. */
  549. OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_multistream_decode(
  550. OpusMSDecoder *st,
  551. const unsigned char *data,
  552. opus_int32 len,
  553. opus_int16 *pcm,
  554. int frame_size,
  555. int decode_fec
  556. ) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(4);
  557. /** Decode a multistream Opus packet with floating point output.
  558. * @param st <tt>OpusMSDecoder*</tt>: Multistream decoder state.
  559. * @param[in] data <tt>const unsigned char*</tt>: Input payload.
  560. * Use a <code>NULL</code>
  561. * pointer to indicate packet
  562. * loss.
  563. * @param len <tt>opus_int32</tt>: Number of bytes in payload.
  564. * @param[out] pcm <tt>opus_int16*</tt>: Output signal, with interleaved
  565. * samples.
  566. * This must contain room for
  567. * <code>frame_size*channels</code>
  568. * samples.
  569. * @param frame_size <tt>int</tt>: The number of samples per channel of
  570. * available space in \a pcm.
  571. * If this is less than the maximum packet duration
  572. * (120 ms; 5760 for 48kHz), this function will not be capable
  573. * of decoding some packets. In the case of PLC (data==NULL)
  574. * or FEC (decode_fec=1), then frame_size needs to be exactly
  575. * the duration of audio that is missing, otherwise the
  576. * decoder will not be in the optimal state to decode the
  577. * next incoming packet. For the PLC and FEC cases, frame_size
  578. * <b>must</b> be a multiple of 2.5 ms.
  579. * @param decode_fec <tt>int</tt>: Flag (0 or 1) to request that any in-band
  580. * forward error correction data be decoded.
  581. * If no such data is available, the frame is
  582. * decoded as if it were lost.
  583. * @returns Number of samples decoded on success or a negative error code
  584. * (see @ref opus_errorcodes) on failure.
  585. */
  586. OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_multistream_decode_float(
  587. OpusMSDecoder *st,
  588. const unsigned char *data,
  589. opus_int32 len,
  590. float *pcm,
  591. int frame_size,
  592. int decode_fec
  593. ) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(4);
  594. /** Perform a CTL function on a multistream Opus decoder.
  595. *
  596. * Generally the request and subsequent arguments are generated by a
  597. * convenience macro.
  598. * @param st <tt>OpusMSDecoder*</tt>: Multistream decoder state.
  599. * @param request This and all remaining parameters should be replaced by one
  600. * of the convenience macros in @ref opus_genericctls,
  601. * @ref opus_decoderctls, or @ref opus_multistream_ctls.
  602. * @see opus_genericctls
  603. * @see opus_decoderctls
  604. * @see opus_multistream_ctls
  605. */
  606. OPUS_EXPORT int opus_multistream_decoder_ctl(OpusMSDecoder *st, int request, ...) OPUS_ARG_NONNULL(1);
  607. /** Frees an <code>OpusMSDecoder</code> allocated by
  608. * opus_multistream_decoder_create().
  609. * @param st <tt>OpusMSDecoder</tt>: Multistream decoder state to be freed.
  610. */
  611. OPUS_EXPORT void opus_multistream_decoder_destroy(OpusMSDecoder *st);
  612. /**@}*/
  613. /**@}*/
  614. #ifdef __cplusplus
  615. }
  616. #endif
  617. #endif /* OPUS_MULTISTREAM_H */