diff --git a/include/opus.h b/include/opus.h index 1f85e2db..c242fec0 100644 --- a/include/opus.h +++ b/include/opus.h @@ -200,7 +200,7 @@ OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_encoder_get_size(int channels); * @param [in] application int: Coding mode (@ref OPUS_APPLICATION_VOIP/@ref OPUS_APPLICATION_AUDIO/@ref OPUS_APPLICATION_RESTRICTED_LOWDELAY) * @param [out] error int*: @ref opus_errorcodes * @note Regardless of the sampling rate and number channels selected, the Opus encoder - * can switch to a lower audio audio bandwidth or number of channels if the bitrate + * can switch to a lower audio bandwidth or number of channels if the bitrate * selected is too low. This also means that it is safe to always use 48 kHz stereo input * and let the encoder optimize the encoding. */ @@ -212,7 +212,7 @@ OPUS_EXPORT OPUS_WARN_UNUSED_RESULT OpusEncoder *opus_encoder_create( ); /** Initializes a previously allocated encoder state - * The memory pointed to by st must be the size returned by opus_encoder_get_size(). + * The memory pointed to by st must be at least the size returned by opus_encoder_get_size(). * This is intended for applications which use their own allocator instead of malloc. * @see opus_encoder_create(),opus_encoder_get_size() * To reset a previously initialized state, use the #OPUS_RESET_STATE CTL. @@ -250,10 +250,11 @@ OPUS_EXPORT int opus_encoder_init( * least \a max_data_bytes. * @param [in] max_data_bytes opus_int32: Size of the allocated * memory for the output - * payload. - * This should not be used by - * itself to control the - * bitrate. + * payload. This may be + * used to impose an upper limit on + * the variable bitrate, but should + * not be used as the only bitrate + * control. * @returns The length of the encoded packet (in bytes) on success or a * negative error code (see @ref opus_errorcodes) on failure. */ @@ -289,10 +290,11 @@ OPUS_EXPORT OPUS_WARN_UNUSED_RESULT opus_int32 opus_encode( * least \a max_data_bytes. * @param [in] max_data_bytes opus_int32: Size of the allocated * memory for the output - * payload. - * This should not be used by - * itself to control the - * bitrate. + * payload. This may be + * used to impose an upper limit on + * the variable bitrate, but should + * not be used as the only bitrate + * control. * @returns The length of the encoded packet (in bytes) on success or a * negative error code (see @ref opus_errorcodes) on failure. */ @@ -422,7 +424,7 @@ OPUS_EXPORT OPUS_WARN_UNUSED_RESULT OpusDecoder *opus_decoder_create( ); /** Initializes a previously allocated decoder state. - * The state must be the size returned by opus_decoder_get_size(). + * The state must be at least the size returned by opus_decoder_get_size(). * This is intended for applications which use their own allocator instead of malloc. @see opus_decoder_create,opus_decoder_get_size * To reset a previously initialized state, use the #OPUS_RESET_STATE CTL. * @param [in] st OpusDecoder*: Decoder state. diff --git a/include/opus_multistream.h b/include/opus_multistream.h index be1b44df..f476efa6 100644 --- a/include/opus_multistream.h +++ b/include/opus_multistream.h @@ -68,7 +68,7 @@ extern "C" { * well. * In addition, you may retrieve the encoder or decoder state for an specific * stream via #OPUS_MULTISTREAM_GET_ENCODER_STATE or - * #OPUS_MULTISTREAM_GET_DECODER and apply CTLs to it individually. + * #OPUS_MULTISTREAM_GET_DECODER_STATE and apply CTLs to it individually. */ /**@{*/ @@ -111,8 +111,9 @@ extern "C" { * duration, can be computed without any special negotation. * * The format for multistream Opus packets is defined in the - * Ogg - * encapsulation specification. + * Ogg + * encapsulation specification and is based on the self-delimited Opus + * framing described in Appendix B of RFC 6716. * Normal Opus packets are just a degenerate case of multistream Opus packets, * and can be encoded or decoded with the multistream API by setting * streams to 1 when initializing the encoder or @@ -124,13 +125,25 @@ extern "C" { * The streams are ordered so that all coupled streams appear at the * beginning. * - * A mapping table defines which decoded channel should be used - * for each output channel. The output channels specified by the encoder + * A mapping table defines which decoded channel i + * should be used for each input/output (I/O) channel j. This table is + * typically provided as an unsigned char array. + * Let i = mapping[j] be the index for I/O channel j. + * If i < 2*coupled_streams, then I/O channel j is + * encoded as the left channel of stream (i/2) if i + * is even, or as the right channel of stream (i/2) if + * i is odd. Otherwise, I/O channel j is encoded as + * mono in stream (i - coupled_streams), unless it has the special + * value 255, in which case it is omitted from the encoding entirely (the + * decoder will reproduce it as silence). Each value i must either + * be the special value 255 or be less than streams + coupled_streams. + * + * The output channels specified by the encoder * should use the * Vorbis * channel ordering. A decoder may wish to apply an additional permutation * to the mapping the encoder used to achieve a different output channel - * order. + * order (e.g. for outputing in WAV order). * * Each multistream packet contains an Opus packet for each stream, and all of * the Opus packets in a single multistream packet must have the same @@ -200,12 +213,12 @@ OPUS_EXPORT OPUS_WARN_UNUSED_RESULT opus_int32 opus_multistream_encoder_get_size * 24000, or 48000. * @param channels int: Number of channels in the input signal. * This must be at most 255. - * It may be different from the number of - * channels (streams + + * It may be greater than the number of + * coded channels (streams + * coupled_streams). * @param streams int: The total number of streams to encode from the * input. - * This must be no more than 255. + * This must be no more than the number of channels. * @param coupled_streams int: Number of coupled (2 channel) streams * to encode. * This must be no larger than the total @@ -213,24 +226,13 @@ OPUS_EXPORT OPUS_WARN_UNUSED_RESULT opus_int32 opus_multistream_encoder_get_size * Additionally, The total number of * encoded channels (streams + * coupled_streams) must be no - * more than 255. + * more than the number of input channels. * @param[in] mapping const unsigned char[channels]: Mapping from - * encoded channels to input channels. - * Let i = mapping[j] be the index for input - * channel j. - * If i < 2*coupled_streams, then input - * channel j is encoded as the left channel of - * stream (i/2) if i is even, and - * as the right channel of stream (i/2) if - * i is odd. - * Otherwise, input channel j is encoded as - * mono in stream (i - coupled_streams), - * unless it has the special value 255, in which case it is - * omitted from the encoding entirely (the decoder will - * reproduce it as silence). - * Each value i must either be the special - * value 255 or be less than - * streams + coupled_streams. + * encoded channels to input channels, as described in + * @ref opus_multistream. As an extra constraint, the + * multistream encoder does not allow encoding coupled + * streams for which one channel is unused since this + * is never a good idea. * @param application int: The target encoder application. * This must be one of the following: *
@@ -257,7 +259,7 @@ OPUS_EXPORT OPUS_WARN_UNUSED_RESULT OpusMSEncoder *opus_multistream_encoder_crea ) OPUS_ARG_NONNULL(5); /** Initialize a previously allocated multistream encoder state. - * The memory pointed to by \a st must be the size returned by + * The memory pointed to by \a st must be at least the size returned by * opus_multistream_encoder_get_size(). * This is intended for applications which use their own allocator instead of * malloc. @@ -270,12 +272,12 @@ OPUS_EXPORT OPUS_WARN_UNUSED_RESULT OpusMSEncoder *opus_multistream_encoder_crea * 24000, or 48000. * @param channels int: Number of channels in the input signal. * This must be at most 255. - * It may be different from the number of + * It may be greater than the number of * coded channels (streams + * coupled_streams). * @param streams int: The total number of streams to encode from the * input. - * This must be no more than 255. + * This must be no more than the number of channels. * @param coupled_streams int: Number of coupled (2 channel) streams * to encode. * This must be no larger than the total @@ -283,10 +285,13 @@ OPUS_EXPORT OPUS_WARN_UNUSED_RESULT OpusMSEncoder *opus_multistream_encoder_crea * Additionally, The total number of * encoded channels (streams + * coupled_streams) must be no - * more than 255. + * more than the number of input channels. * @param[in] mapping const unsigned char[channels]: Mapping from - * encoded channels to input channels. - * See opus_multistream_encoder_create() for details. + * encoded channels to input channels, as described in + * @ref opus_multistream. As an extra constraint, the + * multistream encoder does not allow encoding coupled + * streams for which one channel is unused since this + * is never a good idea. * @param application int: The target encoder application. * This must be one of the following: *
@@ -314,7 +319,7 @@ OPUS_EXPORT int opus_multistream_encoder_init( /** Encodes a multistream Opus frame. * @param st OpusMSEncoder*: Multistream encoder state. * @param[in] pcm const opus_int16*: The input signal as interleaved - * samples. + * samples. * This must contain * frame_size*channels * samples. @@ -331,9 +336,11 @@ OPUS_EXPORT int opus_multistream_encoder_init( * This must contain storage for at * least \a max_data_bytes. * @param max_data_bytes opus_int32: Size of the allocated memory for - * the output payload. - * This should not be used by - * itself to control the bitrate. + * the output payload. This may be + * used to impose an upper limit on + * the variable bitrate, but should + * not be used as the only bitrate + * control. * @returns The length of the encoded packet (in bytes) on success or a * negative error code (see @ref opus_errorcodes) on failure. */ @@ -372,9 +379,11 @@ OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_multistream_encode( * This must contain storage for at * least \a max_data_bytes. * @param max_data_bytes opus_int32: Size of the allocated memory for - * the output payload. - * This should not be used by - * itself to control the bitrate. + * the output payload. This may be + * used to impose an upper limit on + * the variable bitrate, but should + * not be used as the only bitrate + * control. * @returns The length of the encoded packet (in bytes) on success or a * negative error code (see @ref opus_errorcodes) on failure. */ @@ -437,7 +446,7 @@ OPUS_EXPORT OPUS_WARN_UNUSED_RESULT opus_int32 opus_multistream_decoder_get_size * @param Fs opus_int32: Sampling rate to decode at (in Hz). * This must be one of 8000, 12000, 16000, * 24000, or 48000. - * @param channels int: Number of channels to decode. + * @param channels int: Number of channels to output. * This must be at most 255. * It may be different from the number of coded * channels (streams + @@ -454,21 +463,8 @@ OPUS_EXPORT OPUS_WARN_UNUSED_RESULT opus_int32 opus_multistream_decoder_get_size * coupled_streams) must be no * more than 255. * @param[in] mapping const unsigned char[channels]: Mapping from - * coded channels to output channels. - * Let i = mapping[j] be the index for output - * channel j. - * If i < 2*coupled_streams, then the output - * for channel j is taken from the left - * channel of stream (i/2) if i - * i is even, and from the right channel of - * stream (i/2) if i is odd. - * Otherwise, the output for channel j is - * taken from stream (i - coupled_streams) - * decoded as mono, unless it has the special value 255, in - * which case silence is used instead. - * Each value i must either be the special - * value 255 or be less than - * streams + coupled_streams. + * coded channels to output channels, as described in + * @ref opus_multistream. * @param[out] error int *: Returns #OPUS_OK on success, or an error * code (see @ref opus_errorcodes) on * failure. @@ -483,7 +479,7 @@ OPUS_EXPORT OPUS_WARN_UNUSED_RESULT OpusMSDecoder *opus_multistream_decoder_crea ) OPUS_ARG_NONNULL(5); /** Intialize a previously allocated decoder state object. - * The memory pointed to by \a st must be the size returned by + * The memory pointed to by \a st must be at least the size returned by * opus_multistream_encoder_get_size(). * This is intended for applications which use their own allocator instead of * malloc. @@ -494,7 +490,7 @@ OPUS_EXPORT OPUS_WARN_UNUSED_RESULT OpusMSDecoder *opus_multistream_decoder_crea * @param Fs opus_int32: Sampling rate to decode at (in Hz). * This must be one of 8000, 12000, 16000, * 24000, or 48000. - * @param channels int: Number of channels to decode. + * @param channels int: Number of channels to output. * This must be at most 255. * It may be different from the number of coded * channels (streams + @@ -511,8 +507,8 @@ OPUS_EXPORT OPUS_WARN_UNUSED_RESULT OpusMSDecoder *opus_multistream_decoder_crea * coupled_streams) must be no * more than 255. * @param[in] mapping const unsigned char[channels]: Mapping from - * coded channels to output channels. - * See opus_multistream_decoder_create() for details. + * coded channels to output channels, as described in + * @ref opus_multistream. * @returns #OPUS_OK on success, or an error code (see @ref opus_errorcodes) * on failure. */