1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/media/libopus/include/opus_multistream.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,660 @@
1.4 +/* Copyright (c) 2011 Xiph.Org Foundation
1.5 + Written by Jean-Marc Valin */
1.6 +/*
1.7 + Redistribution and use in source and binary forms, with or without
1.8 + modification, are permitted provided that the following conditions
1.9 + are met:
1.10 +
1.11 + - Redistributions of source code must retain the above copyright
1.12 + notice, this list of conditions and the following disclaimer.
1.13 +
1.14 + - Redistributions in binary form must reproduce the above copyright
1.15 + notice, this list of conditions and the following disclaimer in the
1.16 + documentation and/or other materials provided with the distribution.
1.17 +
1.18 + THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
1.19 + ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
1.20 + LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
1.21 + A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER
1.22 + OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
1.23 + EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
1.24 + PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
1.25 + PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
1.26 + LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
1.27 + NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
1.28 + SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
1.29 +*/
1.30 +
1.31 +/**
1.32 + * @file opus_multistream.h
1.33 + * @brief Opus reference implementation multistream API
1.34 + */
1.35 +
1.36 +#ifndef OPUS_MULTISTREAM_H
1.37 +#define OPUS_MULTISTREAM_H
1.38 +
1.39 +#include "opus.h"
1.40 +
1.41 +#ifdef __cplusplus
1.42 +extern "C" {
1.43 +#endif
1.44 +
1.45 +/** @cond OPUS_INTERNAL_DOC */
1.46 +
1.47 +/** Macros to trigger compilation errors when the wrong types are provided to a
1.48 + * CTL. */
1.49 +/**@{*/
1.50 +#define __opus_check_encstate_ptr(ptr) ((ptr) + ((ptr) - (OpusEncoder**)(ptr)))
1.51 +#define __opus_check_decstate_ptr(ptr) ((ptr) + ((ptr) - (OpusDecoder**)(ptr)))
1.52 +/**@}*/
1.53 +
1.54 +/** These are the actual encoder and decoder CTL ID numbers.
1.55 + * They should not be used directly by applications.
1.56 + * In general, SETs should be even and GETs should be odd.*/
1.57 +/**@{*/
1.58 +#define OPUS_MULTISTREAM_GET_ENCODER_STATE_REQUEST 5120
1.59 +#define OPUS_MULTISTREAM_GET_DECODER_STATE_REQUEST 5122
1.60 +/**@}*/
1.61 +
1.62 +/** @endcond */
1.63 +
1.64 +/** @defgroup opus_multistream_ctls Multistream specific encoder and decoder CTLs
1.65 + *
1.66 + * These are convenience macros that are specific to the
1.67 + * opus_multistream_encoder_ctl() and opus_multistream_decoder_ctl()
1.68 + * interface.
1.69 + * The CTLs from @ref opus_genericctls, @ref opus_encoderctls, and
1.70 + * @ref opus_decoderctls may be applied to a multistream encoder or decoder as
1.71 + * well.
1.72 + * In addition, you may retrieve the encoder or decoder state for an specific
1.73 + * stream via #OPUS_MULTISTREAM_GET_ENCODER_STATE or
1.74 + * #OPUS_MULTISTREAM_GET_DECODER_STATE and apply CTLs to it individually.
1.75 + */
1.76 +/**@{*/
1.77 +
1.78 +/** Gets the encoder state for an individual stream of a multistream encoder.
1.79 + * @param[in] x <tt>opus_int32</tt>: The index of the stream whose encoder you
1.80 + * wish to retrieve.
1.81 + * This must be non-negative and less than
1.82 + * the <code>streams</code> parameter used
1.83 + * to initialize the encoder.
1.84 + * @param[out] y <tt>OpusEncoder**</tt>: Returns a pointer to the given
1.85 + * encoder state.
1.86 + * @retval OPUS_BAD_ARG The index of the requested stream was out of range.
1.87 + * @hideinitializer
1.88 + */
1.89 +#define OPUS_MULTISTREAM_GET_ENCODER_STATE(x,y) OPUS_MULTISTREAM_GET_ENCODER_STATE_REQUEST, __opus_check_int(x), __opus_check_encstate_ptr(y)
1.90 +
1.91 +/** Gets the decoder state for an individual stream of a multistream decoder.
1.92 + * @param[in] x <tt>opus_int32</tt>: The index of the stream whose decoder you
1.93 + * wish to retrieve.
1.94 + * This must be non-negative and less than
1.95 + * the <code>streams</code> parameter used
1.96 + * to initialize the decoder.
1.97 + * @param[out] y <tt>OpusDecoder**</tt>: Returns a pointer to the given
1.98 + * decoder state.
1.99 + * @retval OPUS_BAD_ARG The index of the requested stream was out of range.
1.100 + * @hideinitializer
1.101 + */
1.102 +#define OPUS_MULTISTREAM_GET_DECODER_STATE(x,y) OPUS_MULTISTREAM_GET_DECODER_STATE_REQUEST, __opus_check_int(x), __opus_check_decstate_ptr(y)
1.103 +
1.104 +/**@}*/
1.105 +
1.106 +/** @defgroup opus_multistream Opus Multistream API
1.107 + * @{
1.108 + *
1.109 + * The multistream API allows individual Opus streams to be combined into a
1.110 + * single packet, enabling support for up to 255 channels. Unlike an
1.111 + * elementary Opus stream, the encoder and decoder must negotiate the channel
1.112 + * configuration before the decoder can successfully interpret the data in the
1.113 + * packets produced by the encoder. Some basic information, such as packet
1.114 + * duration, can be computed without any special negotiation.
1.115 + *
1.116 + * The format for multistream Opus packets is defined in the
1.117 + * <a href="http://tools.ietf.org/html/draft-terriberry-oggopus">Ogg
1.118 + * encapsulation specification</a> and is based on the self-delimited Opus
1.119 + * framing described in Appendix B of <a href="http://tools.ietf.org/html/rfc6716">RFC 6716</a>.
1.120 + * Normal Opus packets are just a degenerate case of multistream Opus packets,
1.121 + * and can be encoded or decoded with the multistream API by setting
1.122 + * <code>streams</code> to <code>1</code> when initializing the encoder or
1.123 + * decoder.
1.124 + *
1.125 + * Multistream Opus streams can contain up to 255 elementary Opus streams.
1.126 + * These may be either "uncoupled" or "coupled", indicating that the decoder
1.127 + * is configured to decode them to either 1 or 2 channels, respectively.
1.128 + * The streams are ordered so that all coupled streams appear at the
1.129 + * beginning.
1.130 + *
1.131 + * A <code>mapping</code> table defines which decoded channel <code>i</code>
1.132 + * should be used for each input/output (I/O) channel <code>j</code>. This table is
1.133 + * typically provided as an unsigned char array.
1.134 + * Let <code>i = mapping[j]</code> be the index for I/O channel <code>j</code>.
1.135 + * If <code>i < 2*coupled_streams</code>, then I/O channel <code>j</code> is
1.136 + * encoded as the left channel of stream <code>(i/2)</code> if <code>i</code>
1.137 + * is even, or as the right channel of stream <code>(i/2)</code> if
1.138 + * <code>i</code> is odd. Otherwise, I/O channel <code>j</code> is encoded as
1.139 + * mono in stream <code>(i - coupled_streams)</code>, unless it has the special
1.140 + * value 255, in which case it is omitted from the encoding entirely (the
1.141 + * decoder will reproduce it as silence). Each value <code>i</code> must either
1.142 + * be the special value 255 or be less than <code>streams + coupled_streams</code>.
1.143 + *
1.144 + * The output channels specified by the encoder
1.145 + * should use the
1.146 + * <a href="http://www.xiph.org/vorbis/doc/Vorbis_I_spec.html#x1-800004.3.9">Vorbis
1.147 + * channel ordering</a>. A decoder may wish to apply an additional permutation
1.148 + * to the mapping the encoder used to achieve a different output channel
1.149 + * order (e.g. for outputing in WAV order).
1.150 + *
1.151 + * Each multistream packet contains an Opus packet for each stream, and all of
1.152 + * the Opus packets in a single multistream packet must have the same
1.153 + * duration. Therefore the duration of a multistream packet can be extracted
1.154 + * from the TOC sequence of the first stream, which is located at the
1.155 + * beginning of the packet, just like an elementary Opus stream:
1.156 + *
1.157 + * @code
1.158 + * int nb_samples;
1.159 + * int nb_frames;
1.160 + * nb_frames = opus_packet_get_nb_frames(data, len);
1.161 + * if (nb_frames < 1)
1.162 + * return nb_frames;
1.163 + * nb_samples = opus_packet_get_samples_per_frame(data, 48000) * nb_frames;
1.164 + * @endcode
1.165 + *
1.166 + * The general encoding and decoding process proceeds exactly the same as in
1.167 + * the normal @ref opus_encoder and @ref opus_decoder APIs.
1.168 + * See their documentation for an overview of how to use the corresponding
1.169 + * multistream functions.
1.170 + */
1.171 +
1.172 +/** Opus multistream encoder state.
1.173 + * This contains the complete state of a multistream Opus encoder.
1.174 + * It is position independent and can be freely copied.
1.175 + * @see opus_multistream_encoder_create
1.176 + * @see opus_multistream_encoder_init
1.177 + */
1.178 +typedef struct OpusMSEncoder OpusMSEncoder;
1.179 +
1.180 +/** Opus multistream decoder state.
1.181 + * This contains the complete state of a multistream Opus decoder.
1.182 + * It is position independent and can be freely copied.
1.183 + * @see opus_multistream_decoder_create
1.184 + * @see opus_multistream_decoder_init
1.185 + */
1.186 +typedef struct OpusMSDecoder OpusMSDecoder;
1.187 +
1.188 +/**\name Multistream encoder functions */
1.189 +/**@{*/
1.190 +
1.191 +/** Gets the size of an OpusMSEncoder structure.
1.192 + * @param streams <tt>int</tt>: The total number of streams to encode from the
1.193 + * input.
1.194 + * This must be no more than 255.
1.195 + * @param coupled_streams <tt>int</tt>: Number of coupled (2 channel) streams
1.196 + * to encode.
1.197 + * This must be no larger than the total
1.198 + * number of streams.
1.199 + * Additionally, The total number of
1.200 + * encoded channels (<code>streams +
1.201 + * coupled_streams</code>) must be no
1.202 + * more than 255.
1.203 + * @returns The size in bytes on success, or a negative error code
1.204 + * (see @ref opus_errorcodes) on error.
1.205 + */
1.206 +OPUS_EXPORT OPUS_WARN_UNUSED_RESULT opus_int32 opus_multistream_encoder_get_size(
1.207 + int streams,
1.208 + int coupled_streams
1.209 +);
1.210 +
1.211 +OPUS_EXPORT OPUS_WARN_UNUSED_RESULT opus_int32 opus_multistream_surround_encoder_get_size(
1.212 + int channels,
1.213 + int mapping_family
1.214 +);
1.215 +
1.216 +
1.217 +/** Allocates and initializes a multistream encoder state.
1.218 + * Call opus_multistream_encoder_destroy() to release
1.219 + * this object when finished.
1.220 + * @param Fs <tt>opus_int32</tt>: Sampling rate of the input signal (in Hz).
1.221 + * This must be one of 8000, 12000, 16000,
1.222 + * 24000, or 48000.
1.223 + * @param channels <tt>int</tt>: Number of channels in the input signal.
1.224 + * This must be at most 255.
1.225 + * It may be greater than the number of
1.226 + * coded channels (<code>streams +
1.227 + * coupled_streams</code>).
1.228 + * @param streams <tt>int</tt>: The total number of streams to encode from the
1.229 + * input.
1.230 + * This must be no more than the number of channels.
1.231 + * @param coupled_streams <tt>int</tt>: Number of coupled (2 channel) streams
1.232 + * to encode.
1.233 + * This must be no larger than the total
1.234 + * number of streams.
1.235 + * Additionally, The total number of
1.236 + * encoded channels (<code>streams +
1.237 + * coupled_streams</code>) must be no
1.238 + * more than the number of input channels.
1.239 + * @param[in] mapping <code>const unsigned char[channels]</code>: Mapping from
1.240 + * encoded channels to input channels, as described in
1.241 + * @ref opus_multistream. As an extra constraint, the
1.242 + * multistream encoder does not allow encoding coupled
1.243 + * streams for which one channel is unused since this
1.244 + * is never a good idea.
1.245 + * @param application <tt>int</tt>: The target encoder application.
1.246 + * This must be one of the following:
1.247 + * <dl>
1.248 + * <dt>#OPUS_APPLICATION_VOIP</dt>
1.249 + * <dd>Process signal for improved speech intelligibility.</dd>
1.250 + * <dt>#OPUS_APPLICATION_AUDIO</dt>
1.251 + * <dd>Favor faithfulness to the original input.</dd>
1.252 + * <dt>#OPUS_APPLICATION_RESTRICTED_LOWDELAY</dt>
1.253 + * <dd>Configure the minimum possible coding delay by disabling certain modes
1.254 + * of operation.</dd>
1.255 + * </dl>
1.256 + * @param[out] error <tt>int *</tt>: Returns #OPUS_OK on success, or an error
1.257 + * code (see @ref opus_errorcodes) on
1.258 + * failure.
1.259 + */
1.260 +OPUS_EXPORT OPUS_WARN_UNUSED_RESULT OpusMSEncoder *opus_multistream_encoder_create(
1.261 + opus_int32 Fs,
1.262 + int channels,
1.263 + int streams,
1.264 + int coupled_streams,
1.265 + const unsigned char *mapping,
1.266 + int application,
1.267 + int *error
1.268 +) OPUS_ARG_NONNULL(5);
1.269 +
1.270 +OPUS_EXPORT OPUS_WARN_UNUSED_RESULT OpusMSEncoder *opus_multistream_surround_encoder_create(
1.271 + opus_int32 Fs,
1.272 + int channels,
1.273 + int mapping_family,
1.274 + int *streams,
1.275 + int *coupled_streams,
1.276 + unsigned char *mapping,
1.277 + int application,
1.278 + int *error
1.279 +) OPUS_ARG_NONNULL(5);
1.280 +
1.281 +/** Initialize a previously allocated multistream encoder state.
1.282 + * The memory pointed to by \a st must be at least the size returned by
1.283 + * opus_multistream_encoder_get_size().
1.284 + * This is intended for applications which use their own allocator instead of
1.285 + * malloc.
1.286 + * To reset a previously initialized state, use the #OPUS_RESET_STATE CTL.
1.287 + * @see opus_multistream_encoder_create
1.288 + * @see opus_multistream_encoder_get_size
1.289 + * @param st <tt>OpusMSEncoder*</tt>: Multistream encoder state to initialize.
1.290 + * @param Fs <tt>opus_int32</tt>: Sampling rate of the input signal (in Hz).
1.291 + * This must be one of 8000, 12000, 16000,
1.292 + * 24000, or 48000.
1.293 + * @param channels <tt>int</tt>: Number of channels in the input signal.
1.294 + * This must be at most 255.
1.295 + * It may be greater than the number of
1.296 + * coded channels (<code>streams +
1.297 + * coupled_streams</code>).
1.298 + * @param streams <tt>int</tt>: The total number of streams to encode from the
1.299 + * input.
1.300 + * This must be no more than the number of channels.
1.301 + * @param coupled_streams <tt>int</tt>: Number of coupled (2 channel) streams
1.302 + * to encode.
1.303 + * This must be no larger than the total
1.304 + * number of streams.
1.305 + * Additionally, The total number of
1.306 + * encoded channels (<code>streams +
1.307 + * coupled_streams</code>) must be no
1.308 + * more than the number of input channels.
1.309 + * @param[in] mapping <code>const unsigned char[channels]</code>: Mapping from
1.310 + * encoded channels to input channels, as described in
1.311 + * @ref opus_multistream. As an extra constraint, the
1.312 + * multistream encoder does not allow encoding coupled
1.313 + * streams for which one channel is unused since this
1.314 + * is never a good idea.
1.315 + * @param application <tt>int</tt>: The target encoder application.
1.316 + * This must be one of the following:
1.317 + * <dl>
1.318 + * <dt>#OPUS_APPLICATION_VOIP</dt>
1.319 + * <dd>Process signal for improved speech intelligibility.</dd>
1.320 + * <dt>#OPUS_APPLICATION_AUDIO</dt>
1.321 + * <dd>Favor faithfulness to the original input.</dd>
1.322 + * <dt>#OPUS_APPLICATION_RESTRICTED_LOWDELAY</dt>
1.323 + * <dd>Configure the minimum possible coding delay by disabling certain modes
1.324 + * of operation.</dd>
1.325 + * </dl>
1.326 + * @returns #OPUS_OK on success, or an error code (see @ref opus_errorcodes)
1.327 + * on failure.
1.328 + */
1.329 +OPUS_EXPORT int opus_multistream_encoder_init(
1.330 + OpusMSEncoder *st,
1.331 + opus_int32 Fs,
1.332 + int channels,
1.333 + int streams,
1.334 + int coupled_streams,
1.335 + const unsigned char *mapping,
1.336 + int application
1.337 +) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(6);
1.338 +
1.339 +OPUS_EXPORT int opus_multistream_surround_encoder_init(
1.340 + OpusMSEncoder *st,
1.341 + opus_int32 Fs,
1.342 + int channels,
1.343 + int mapping_family,
1.344 + int *streams,
1.345 + int *coupled_streams,
1.346 + unsigned char *mapping,
1.347 + int application
1.348 +) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(6);
1.349 +
1.350 +/** Encodes a multistream Opus frame.
1.351 + * @param st <tt>OpusMSEncoder*</tt>: Multistream encoder state.
1.352 + * @param[in] pcm <tt>const opus_int16*</tt>: The input signal as interleaved
1.353 + * samples.
1.354 + * This must contain
1.355 + * <code>frame_size*channels</code>
1.356 + * samples.
1.357 + * @param frame_size <tt>int</tt>: Number of samples per channel in the input
1.358 + * signal.
1.359 + * This must be an Opus frame size for the
1.360 + * encoder's sampling rate.
1.361 + * For example, at 48 kHz the permitted values
1.362 + * are 120, 240, 480, 960, 1920, and 2880.
1.363 + * Passing in a duration of less than 10 ms
1.364 + * (480 samples at 48 kHz) will prevent the
1.365 + * encoder from using the LPC or hybrid modes.
1.366 + * @param[out] data <tt>unsigned char*</tt>: Output payload.
1.367 + * This must contain storage for at
1.368 + * least \a max_data_bytes.
1.369 + * @param [in] max_data_bytes <tt>opus_int32</tt>: Size of the allocated
1.370 + * memory for the output
1.371 + * payload. This may be
1.372 + * used to impose an upper limit on
1.373 + * the instant bitrate, but should
1.374 + * not be used as the only bitrate
1.375 + * control. Use #OPUS_SET_BITRATE to
1.376 + * control the bitrate.
1.377 + * @returns The length of the encoded packet (in bytes) on success or a
1.378 + * negative error code (see @ref opus_errorcodes) on failure.
1.379 + */
1.380 +OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_multistream_encode(
1.381 + OpusMSEncoder *st,
1.382 + const opus_int16 *pcm,
1.383 + int frame_size,
1.384 + unsigned char *data,
1.385 + opus_int32 max_data_bytes
1.386 +) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(2) OPUS_ARG_NONNULL(4);
1.387 +
1.388 +/** Encodes a multistream Opus frame from floating point input.
1.389 + * @param st <tt>OpusMSEncoder*</tt>: Multistream encoder state.
1.390 + * @param[in] pcm <tt>const float*</tt>: The input signal as interleaved
1.391 + * samples with a normal range of
1.392 + * +/-1.0.
1.393 + * Samples with a range beyond +/-1.0
1.394 + * are supported but will be clipped by
1.395 + * decoders using the integer API and
1.396 + * should only be used if it is known
1.397 + * that the far end supports extended
1.398 + * dynamic range.
1.399 + * This must contain
1.400 + * <code>frame_size*channels</code>
1.401 + * samples.
1.402 + * @param frame_size <tt>int</tt>: Number of samples per channel in the input
1.403 + * signal.
1.404 + * This must be an Opus frame size for the
1.405 + * encoder's sampling rate.
1.406 + * For example, at 48 kHz the permitted values
1.407 + * are 120, 240, 480, 960, 1920, and 2880.
1.408 + * Passing in a duration of less than 10 ms
1.409 + * (480 samples at 48 kHz) will prevent the
1.410 + * encoder from using the LPC or hybrid modes.
1.411 + * @param[out] data <tt>unsigned char*</tt>: Output payload.
1.412 + * This must contain storage for at
1.413 + * least \a max_data_bytes.
1.414 + * @param [in] max_data_bytes <tt>opus_int32</tt>: Size of the allocated
1.415 + * memory for the output
1.416 + * payload. This may be
1.417 + * used to impose an upper limit on
1.418 + * the instant bitrate, but should
1.419 + * not be used as the only bitrate
1.420 + * control. Use #OPUS_SET_BITRATE to
1.421 + * control the bitrate.
1.422 + * @returns The length of the encoded packet (in bytes) on success or a
1.423 + * negative error code (see @ref opus_errorcodes) on failure.
1.424 + */
1.425 +OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_multistream_encode_float(
1.426 + OpusMSEncoder *st,
1.427 + const float *pcm,
1.428 + int frame_size,
1.429 + unsigned char *data,
1.430 + opus_int32 max_data_bytes
1.431 +) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(2) OPUS_ARG_NONNULL(4);
1.432 +
1.433 +/** Frees an <code>OpusMSEncoder</code> allocated by
1.434 + * opus_multistream_encoder_create().
1.435 + * @param st <tt>OpusMSEncoder*</tt>: Multistream encoder state to be freed.
1.436 + */
1.437 +OPUS_EXPORT void opus_multistream_encoder_destroy(OpusMSEncoder *st);
1.438 +
1.439 +/** Perform a CTL function on a multistream Opus encoder.
1.440 + *
1.441 + * Generally the request and subsequent arguments are generated by a
1.442 + * convenience macro.
1.443 + * @param st <tt>OpusMSEncoder*</tt>: Multistream encoder state.
1.444 + * @param request This and all remaining parameters should be replaced by one
1.445 + * of the convenience macros in @ref opus_genericctls,
1.446 + * @ref opus_encoderctls, or @ref opus_multistream_ctls.
1.447 + * @see opus_genericctls
1.448 + * @see opus_encoderctls
1.449 + * @see opus_multistream_ctls
1.450 + */
1.451 +OPUS_EXPORT int opus_multistream_encoder_ctl(OpusMSEncoder *st, int request, ...) OPUS_ARG_NONNULL(1);
1.452 +
1.453 +/**@}*/
1.454 +
1.455 +/**\name Multistream decoder functions */
1.456 +/**@{*/
1.457 +
1.458 +/** Gets the size of an <code>OpusMSDecoder</code> structure.
1.459 + * @param streams <tt>int</tt>: The total number of streams coded in the
1.460 + * input.
1.461 + * This must be no more than 255.
1.462 + * @param coupled_streams <tt>int</tt>: Number streams to decode as coupled
1.463 + * (2 channel) streams.
1.464 + * This must be no larger than the total
1.465 + * number of streams.
1.466 + * Additionally, The total number of
1.467 + * coded channels (<code>streams +
1.468 + * coupled_streams</code>) must be no
1.469 + * more than 255.
1.470 + * @returns The size in bytes on success, or a negative error code
1.471 + * (see @ref opus_errorcodes) on error.
1.472 + */
1.473 +OPUS_EXPORT OPUS_WARN_UNUSED_RESULT opus_int32 opus_multistream_decoder_get_size(
1.474 + int streams,
1.475 + int coupled_streams
1.476 +);
1.477 +
1.478 +/** Allocates and initializes a multistream decoder state.
1.479 + * Call opus_multistream_decoder_destroy() to release
1.480 + * this object when finished.
1.481 + * @param Fs <tt>opus_int32</tt>: Sampling rate to decode at (in Hz).
1.482 + * This must be one of 8000, 12000, 16000,
1.483 + * 24000, or 48000.
1.484 + * @param channels <tt>int</tt>: Number of channels to output.
1.485 + * This must be at most 255.
1.486 + * It may be different from the number of coded
1.487 + * channels (<code>streams +
1.488 + * coupled_streams</code>).
1.489 + * @param streams <tt>int</tt>: The total number of streams coded in the
1.490 + * input.
1.491 + * This must be no more than 255.
1.492 + * @param coupled_streams <tt>int</tt>: Number of streams to decode as coupled
1.493 + * (2 channel) streams.
1.494 + * This must be no larger than the total
1.495 + * number of streams.
1.496 + * Additionally, The total number of
1.497 + * coded channels (<code>streams +
1.498 + * coupled_streams</code>) must be no
1.499 + * more than 255.
1.500 + * @param[in] mapping <code>const unsigned char[channels]</code>: Mapping from
1.501 + * coded channels to output channels, as described in
1.502 + * @ref opus_multistream.
1.503 + * @param[out] error <tt>int *</tt>: Returns #OPUS_OK on success, or an error
1.504 + * code (see @ref opus_errorcodes) on
1.505 + * failure.
1.506 + */
1.507 +OPUS_EXPORT OPUS_WARN_UNUSED_RESULT OpusMSDecoder *opus_multistream_decoder_create(
1.508 + opus_int32 Fs,
1.509 + int channels,
1.510 + int streams,
1.511 + int coupled_streams,
1.512 + const unsigned char *mapping,
1.513 + int *error
1.514 +) OPUS_ARG_NONNULL(5);
1.515 +
1.516 +/** Intialize a previously allocated decoder state object.
1.517 + * The memory pointed to by \a st must be at least the size returned by
1.518 + * opus_multistream_encoder_get_size().
1.519 + * This is intended for applications which use their own allocator instead of
1.520 + * malloc.
1.521 + * To reset a previously initialized state, use the #OPUS_RESET_STATE CTL.
1.522 + * @see opus_multistream_decoder_create
1.523 + * @see opus_multistream_deocder_get_size
1.524 + * @param st <tt>OpusMSEncoder*</tt>: Multistream encoder state to initialize.
1.525 + * @param Fs <tt>opus_int32</tt>: Sampling rate to decode at (in Hz).
1.526 + * This must be one of 8000, 12000, 16000,
1.527 + * 24000, or 48000.
1.528 + * @param channels <tt>int</tt>: Number of channels to output.
1.529 + * This must be at most 255.
1.530 + * It may be different from the number of coded
1.531 + * channels (<code>streams +
1.532 + * coupled_streams</code>).
1.533 + * @param streams <tt>int</tt>: The total number of streams coded in the
1.534 + * input.
1.535 + * This must be no more than 255.
1.536 + * @param coupled_streams <tt>int</tt>: Number of streams to decode as coupled
1.537 + * (2 channel) streams.
1.538 + * This must be no larger than the total
1.539 + * number of streams.
1.540 + * Additionally, The total number of
1.541 + * coded channels (<code>streams +
1.542 + * coupled_streams</code>) must be no
1.543 + * more than 255.
1.544 + * @param[in] mapping <code>const unsigned char[channels]</code>: Mapping from
1.545 + * coded channels to output channels, as described in
1.546 + * @ref opus_multistream.
1.547 + * @returns #OPUS_OK on success, or an error code (see @ref opus_errorcodes)
1.548 + * on failure.
1.549 + */
1.550 +OPUS_EXPORT int opus_multistream_decoder_init(
1.551 + OpusMSDecoder *st,
1.552 + opus_int32 Fs,
1.553 + int channels,
1.554 + int streams,
1.555 + int coupled_streams,
1.556 + const unsigned char *mapping
1.557 +) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(6);
1.558 +
1.559 +/** Decode a multistream Opus packet.
1.560 + * @param st <tt>OpusMSDecoder*</tt>: Multistream decoder state.
1.561 + * @param[in] data <tt>const unsigned char*</tt>: Input payload.
1.562 + * Use a <code>NULL</code>
1.563 + * pointer to indicate packet
1.564 + * loss.
1.565 + * @param len <tt>opus_int32</tt>: Number of bytes in payload.
1.566 + * @param[out] pcm <tt>opus_int16*</tt>: Output signal, with interleaved
1.567 + * samples.
1.568 + * This must contain room for
1.569 + * <code>frame_size*channels</code>
1.570 + * samples.
1.571 + * @param frame_size <tt>int</tt>: The number of samples per channel of
1.572 + * available space in \a pcm.
1.573 + * If this is less than the maximum packet duration
1.574 + * (120 ms; 5760 for 48kHz), this function will not be capable
1.575 + * of decoding some packets. In the case of PLC (data==NULL)
1.576 + * or FEC (decode_fec=1), then frame_size needs to be exactly
1.577 + * the duration of audio that is missing, otherwise the
1.578 + * decoder will not be in the optimal state to decode the
1.579 + * next incoming packet. For the PLC and FEC cases, frame_size
1.580 + * <b>must</b> be a multiple of 2.5 ms.
1.581 + * @param decode_fec <tt>int</tt>: Flag (0 or 1) to request that any in-band
1.582 + * forward error correction data be decoded.
1.583 + * If no such data is available, the frame is
1.584 + * decoded as if it were lost.
1.585 + * @returns Number of samples decoded on success or a negative error code
1.586 + * (see @ref opus_errorcodes) on failure.
1.587 + */
1.588 +OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_multistream_decode(
1.589 + OpusMSDecoder *st,
1.590 + const unsigned char *data,
1.591 + opus_int32 len,
1.592 + opus_int16 *pcm,
1.593 + int frame_size,
1.594 + int decode_fec
1.595 +) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(4);
1.596 +
1.597 +/** Decode a multistream Opus packet with floating point output.
1.598 + * @param st <tt>OpusMSDecoder*</tt>: Multistream decoder state.
1.599 + * @param[in] data <tt>const unsigned char*</tt>: Input payload.
1.600 + * Use a <code>NULL</code>
1.601 + * pointer to indicate packet
1.602 + * loss.
1.603 + * @param len <tt>opus_int32</tt>: Number of bytes in payload.
1.604 + * @param[out] pcm <tt>opus_int16*</tt>: Output signal, with interleaved
1.605 + * samples.
1.606 + * This must contain room for
1.607 + * <code>frame_size*channels</code>
1.608 + * samples.
1.609 + * @param frame_size <tt>int</tt>: The number of samples per channel of
1.610 + * available space in \a pcm.
1.611 + * If this is less than the maximum packet duration
1.612 + * (120 ms; 5760 for 48kHz), this function will not be capable
1.613 + * of decoding some packets. In the case of PLC (data==NULL)
1.614 + * or FEC (decode_fec=1), then frame_size needs to be exactly
1.615 + * the duration of audio that is missing, otherwise the
1.616 + * decoder will not be in the optimal state to decode the
1.617 + * next incoming packet. For the PLC and FEC cases, frame_size
1.618 + * <b>must</b> be a multiple of 2.5 ms.
1.619 + * @param decode_fec <tt>int</tt>: Flag (0 or 1) to request that any in-band
1.620 + * forward error correction data be decoded.
1.621 + * If no such data is available, the frame is
1.622 + * decoded as if it were lost.
1.623 + * @returns Number of samples decoded on success or a negative error code
1.624 + * (see @ref opus_errorcodes) on failure.
1.625 + */
1.626 +OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_multistream_decode_float(
1.627 + OpusMSDecoder *st,
1.628 + const unsigned char *data,
1.629 + opus_int32 len,
1.630 + float *pcm,
1.631 + int frame_size,
1.632 + int decode_fec
1.633 +) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(4);
1.634 +
1.635 +/** Perform a CTL function on a multistream Opus decoder.
1.636 + *
1.637 + * Generally the request and subsequent arguments are generated by a
1.638 + * convenience macro.
1.639 + * @param st <tt>OpusMSDecoder*</tt>: Multistream decoder state.
1.640 + * @param request This and all remaining parameters should be replaced by one
1.641 + * of the convenience macros in @ref opus_genericctls,
1.642 + * @ref opus_decoderctls, or @ref opus_multistream_ctls.
1.643 + * @see opus_genericctls
1.644 + * @see opus_decoderctls
1.645 + * @see opus_multistream_ctls
1.646 + */
1.647 +OPUS_EXPORT int opus_multistream_decoder_ctl(OpusMSDecoder *st, int request, ...) OPUS_ARG_NONNULL(1);
1.648 +
1.649 +/** Frees an <code>OpusMSDecoder</code> allocated by
1.650 + * opus_multistream_decoder_create().
1.651 + * @param st <tt>OpusMSDecoder</tt>: Multistream decoder state to be freed.
1.652 + */
1.653 +OPUS_EXPORT void opus_multistream_decoder_destroy(OpusMSDecoder *st);
1.654 +
1.655 +/**@}*/
1.656 +
1.657 +/**@}*/
1.658 +
1.659 +#ifdef __cplusplus
1.660 +}
1.661 +#endif
1.662 +
1.663 +#endif /* OPUS_MULTISTREAM_H */
