ref: 1f65ce89b03a1d9c9bae9fa3ed0109b3bde21a60
parent: 2967d4e220ffe5805c833252861ad2a9c3f7d113
author: Gregory Maxwell <[email protected]>
date: Sun Jun 10 17:15:02 EDT 2012
Correct documentation in opus_custom.h.
--- a/doc/Doxyfile.in
+++ b/doc/Doxyfile.in
@@ -613,7 +613,8 @@
INPUT = @top_srcdir@/include/opus.h \
@top_srcdir@/include/opus_types.h \
@top_srcdir@/include/opus_defines.h \
- @top_srcdir@/include/opus_multistream.h
+ @top_srcdir@/include/opus_multistream.h \
+ @top_srcdir@/include/opus_custom.h
# This tag can be used to specify the character encoding of the source files
# that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is
@@ -1454,7 +1455,7 @@
# undefined via #undef or recursively expanded use the := operator
# instead of the = operator.
-PREDEFINED = OPUS_EXPORT= OPUS_WARN_UNUSED_RESULT= OPUS_ARG_NONNULL(_x)=
+PREDEFINED = OPUS_EXPORT= OPUS_CUSTOM_EXPORT= OPUS_CUSTOM_EXPORT_STATIC= OPUS_WARN_UNUSED_RESULT= OPUS_ARG_NONNULL(_x)=
# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then
# this tag can be used to specify a list of macro names that should be expanded.
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -3,7 +3,8 @@
DOCINPUTS = $(top_srcdir)/include/opus.h \
$(top_srcdir)/include/opus_multistream.h \
$(top_srcdir)/include/opus_defines.h \
- $(top_srcdir)/include/opus_types.h
+ $(top_srcdir)/include/opus_types.h \
+ $(top_srcdir)/include/opus_custom.h
EXTRA_DIST = Doxyfile.in
--- a/include/opus.h
+++ b/include/opus.h
@@ -67,6 +67,7 @@
* @li @ref opus_decoder
* @li @ref opus_repacketizer
* @li @ref opus_libinfo
+ * @li @ref opus_custom
*/
/** @defgroup opus_encoder Opus Encoder
@@ -243,7 +244,12 @@
* Passing in a duration of less than 10ms (480 samples at 48kHz) will
* prevent the encoder from using the LPC or hybrid modes.
* @param [in] st <tt>OpusEncoder*</tt>: Encoder state
- * @param [in] pcm <tt>float*</tt>: Input signal (interleaved if 2 channels). length is frame_size*channels*sizeof(float)
+ * @param [in] pcm <tt>float*</tt>: Input in float format (interleaved if 2 channels), with a normal range of +/-1.0.
+ * Samples with a range beyond +/-1.0 are supported but will
+ * be clipped by decoders using the integer API and should
+ * only be used if it is known that the far end supports
+ * extended dynamic range.
+ * length is frame_size*channels*sizeof(float)
* @param [in] frame_size <tt>int</tt>: Number of samples per frame of input signal
* @param [out] data <tt>char*</tt>: Output payload (at least max_data_bytes long)
* @param [in] max_data_bytes <tt>opus_int32</tt>: Allocated memory for payload; don't use for controlling bitrate
--- a/include/opus_custom.h
+++ b/include/opus_custom.h
@@ -1,12 +1,7 @@
/* Copyright (c) 2007-2008 CSIRO
Copyright (c) 2007-2009 Xiph.Org Foundation
- Copyright (c) 2008 Gregory Maxwell
+ Copyright (c) 2008-2012 Gregory Maxwell
Written by Jean-Marc Valin and Gregory Maxwell */
-/**
- @file celt.h
- @brief Contains all the functions for encoding and decoding audio
- */
-
/*
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
@@ -32,10 +27,14 @@
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
+/**
+ @file opus_custom.h
+ @brief Opus-Custom reference implementation API
+ */
+
#ifndef OPUS_CUSTOM_H
#define OPUS_CUSTOM_H
-
#include "opus_defines.h"
#ifdef __cplusplus
@@ -54,157 +53,274 @@
#endif
#endif
+/** @defgroup opus_custom Opus Custom
+ * @{+ * Opus Custom is an optional part of the Opus specification and
+ * reference implementation which uses a distinct API from the regular
+ * API and supports frame sizes that are not normally supported.\ Use
+ * of Opus Custom is discouraged for all but very special applications
+ * for which a frame size different from 2.5, 5, 10, or 20 ms is needed
+ * (for either complexity or latency reasons) and where interoperability
+ * is less important.
+ *
+ * In addition to the interoperability limitations the use of Opus custom
+ * disables a substantial chunk of the codec and generally lowers the
+ * quality available at a given bitrate. Normally when an application needs
+ * a different frame size from the codec it should buffer to match the
+ * sizes but this adds a small amount of delay which may be important
+ * in some very low latency applications. Some transports (especially
+ * constant rate RF transports) may also work best with frames of
+ * particular durations.
+ *
+ * Libopus only supports custom modes if they are enabled at compile time.
+ *
+ * The Opus Custom API is similar to the regular API but the
+ * @ref opus_encoder_create and @ref opus_decoder_create calls take
+ * an additional mode parameter which is a structure produced by
+ * a call to @ref opus_custom_mode_create. Both the encoder and decoder
+ * must create a mode using the same sample rate (fs) and frame size
+ * (frame size) so these parameters must either be signaled out of band
+ * or fixed in a particular implementation.
+ *
+ * Similar to regular Opus the custom modes support on the fly frame size
+ * switching, but the sizes available depend on the particular frame size in
+ * use. For some initial frame sizes on a single on the fly size is available.
+ */
+
/** Contains the state of an encoder. One encoder state is needed
- for each stream. It is initialised once at the beginning of the
- stream. Do *not* re-initialise the state for every frame.
+ for each stream. It is initialized once at the beginning of the
+ stream. Do *not* re-initialize the state for every frame.
@brief Encoder state
*/
typedef struct OpusCustomEncoder OpusCustomEncoder;
/** State of the decoder. One decoder state is needed for each stream.
- It is initialised once at the beginning of the stream. Do *not*
- re-initialise the state for every frame */
+ It is initialized once at the beginning of the stream. Do *not*
+ re-initialize the state for every frame.
+ @brief Decoder state
+ */
typedef struct OpusCustomDecoder OpusCustomDecoder;
/** The mode contains all the information necessary to create an
- encoder. Both the encoder and decoder need to be initialised
- with exactly the same mode, otherwise the quality will be very
- bad */
+ encoder. Both the encoder and decoder need to be initialized
+ with exactly the same mode, otherwise the output will be
+ corrupted.
+ @brief Mode configuration
+ */
typedef struct OpusCustomMode OpusCustomMode;
/** Creates a new mode struct. This will be passed to an encoder or
- decoder. The mode MUST NOT BE DESTROYED until the encoders and
- decoders that use it are destroyed as well.
- @param Fs Sampling rate (32000 to 96000 Hz)
- @param frame_size Number of samples (per channel) to encode in each
- packet (even values; 64 - 512)
- @param error Returned error code (if NULL, no error will be returned)
- @return A newly created mode
-*/
+ * decoder. The mode MUST NOT BE DESTROYED until the encoders and
+ * decoders that use it are destroyed as well.
+ * @param [in] Fs <tt>int</tt>: Sampling rate (8000 to 96000 Hz)
+ * @param [in] frame_size <tt>int</tt>: Number of samples (per channel) to encode in each
+ * packet (64 - 1024, prime factorization must contain zero or more 2s, 3s, or 5s and no other primes)
+ * @param [out] error <tt>int*</tt>: Returned error code (if NULL, no error will be returned)
+ * @return A newly created mode
+ */
OPUS_CUSTOM_EXPORT OPUS_WARN_UNUSED_RESULT OpusCustomMode *opus_custom_mode_create(opus_int32 Fs, int frame_size, int *error);
/** Destroys a mode struct. Only call this after all encoders and
- decoders using this mode are destroyed as well.
- @param mode Mode to be destroyed
-*/
+ * decoders using this mode are destroyed as well.
+ * @param [in] mode <tt>OpusCustomMode*</tt>: Mode to be freed.
+ */
OPUS_CUSTOM_EXPORT void opus_custom_mode_destroy(OpusCustomMode *mode);
/* Encoder */
+/** Gets the size of an OpusCustomEncoder structure.
+ * @param [in] mode <tt>OpusCustomMode *</tt>: Mode configuration
+ * @param [in] channels <tt>int</tt>: Number of channels
+ * @returns size
+ */
+OPUS_CUSTOM_EXPORT_STATIC OPUS_WARN_UNUSED_RESULT int opus_custom_encoder_get_size(
+ const OpusCustomMode *mode,
+ int channels
+) OPUS_ARG_NONNULL(1);
-OPUS_CUSTOM_EXPORT_STATIC OPUS_WARN_UNUSED_RESULT int opus_custom_encoder_get_size(const OpusCustomMode *mode, int channels);
-
/** Creates a new encoder state. Each stream needs its own encoder
- state (can't be shared across simultaneous streams).
- @param mode Contains all the information about the characteristics of
- * the stream (must be the same characteristics as used for the
- * decoder)
- @param channels Number of channels
- @param error Returns an error code
- @return Newly created encoder state.
+ * state (can't be shared across simultaneous streams).
+ * @param [in] mode <tt>OpusCustomMode*</tt>: Contains all the information about the characteristics of
+ * the stream (must be the same characteristics as used for the
+ * decoder)
+ * @param [in] channels <tt>int</tt>: Number of channels
+ * @param [out] error <tt>int*</tt>: Returns an error code
+ * @return Newly created encoder state.
*/
-OPUS_CUSTOM_EXPORT OPUS_WARN_UNUSED_RESULT OpusCustomEncoder *opus_custom_encoder_create(const OpusCustomMode *mode, int channels, int *error);
+OPUS_CUSTOM_EXPORT OPUS_WARN_UNUSED_RESULT OpusCustomEncoder *opus_custom_encoder_create(
+ const OpusCustomMode *mode,
+ int channels,
+ int *error
+) OPUS_ARG_NONNULL(1);
-OPUS_CUSTOM_EXPORT_STATIC int opus_custom_encoder_init(OpusCustomEncoder *st, const OpusCustomMode *mode, int channels);
+/** Initializes a previously allocated encoder state
+ * The memory pointed to by st must be the size returned by opus_custom_encoder_get_size.
+ * This is intended for applications which use their own allocator instead of malloc.
+ * @see opus_custom_encoder_create(),opus_custom_encoder_get_size()
+ * To reset a previously initialized state use the OPUS_RESET_STATE CTL.
+ * @param [in] st <tt>OpusCustomEncoder*</tt>: Encoder state
+ * @param [in] mode <tt>OpusCustomMode *</tt>: Contains all the information about the characteristics of
+ * the stream (must be the same characteristics as used for the
+ * decoder)
+ * @param [in] channels <tt>int</tt>: Number of channels
+ * @return OPUS_OK Success or @ref opus_errorcodes
+ */
+OPUS_CUSTOM_EXPORT_STATIC int opus_custom_encoder_init(
+ OpusCustomEncoder *st,
+ const OpusCustomMode *mode,
+ int channels
+) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(2);
/** Destroys a an encoder state.
- @param st Encoder state to be destroyed
- */
+ * @param[in] st <tt>OpusCustomEncoder*</tt>: State to be freed.
+ */
OPUS_CUSTOM_EXPORT void opus_custom_encoder_destroy(OpusCustomEncoder *st);
/** Encodes a frame of audio.
- @param st Encoder state
- @param pcm PCM audio in float format, with a normal range of +/-1.0.
- * Samples with a range beyond +/-1.0 are supported but will
- * be clipped by decoders using the integer API and should
- * only be used if it is known that the far end supports
- * extended dynmaic range. There must be exactly
- * frame_size samples per channel.
- @param compressed The compressed data is written here. This may not alias pcm or
- * optional_synthesis.
- @param nbCompressedBytes Maximum number of bytes to use for compressing the frame
- * (can change from one frame to another)
- @return Number of bytes written to "compressed". Will be the same as
- * "nbCompressedBytes" unless the stream is VBR and will never be larger.
- * If negative, an error has occurred (see error codes). It is IMPORTANT that
- * the length returned be somehow transmitted to the decoder. Otherwise, no
- * decoding is possible.
-*/
-OPUS_CUSTOM_EXPORT OPUS_WARN_UNUSED_RESULT int opus_custom_encode_float(OpusCustomEncoder *st, const float *pcm, int frame_size, unsigned char *compressed, int maxCompressedBytes);
+ * @param [in] st <tt>OpusCustomEncoder*</tt>: Encoder state
+ * @param [in] pcm <tt>float*</tt>: PCM audio in float format, with a normal range of +/-1.0.
+ * Samples with a range beyond +/-1.0 are supported but will
+ * be clipped by decoders using the integer API and should
+ * only be used if it is known that the far end supports
+ * extended dynamic range. There must be exactly
+ * frame_size samples per channel.
+ * @param [in] frame_size <tt>int</tt>: Number of samples per frame of input signal
+ * @param [out] compressed <tt>char *</tt>: The compressed data is written here. This may not alias pcm and must be at least maxCompressedBytes long.
+ * @param [in] maxCompressedBytes <tt>int</tt>: Maximum number of bytes to use for compressing the frame
+ * (can change from one frame to another)
+ * @return Number of bytes written to "compressed".
+ * If negative, an error has occurred (see error codes). It is IMPORTANT that
+ * the length returned be somehow transmitted to the decoder. Otherwise, no
+ * decoding is possible.
+ */
+OPUS_CUSTOM_EXPORT OPUS_WARN_UNUSED_RESULT int opus_custom_encode_float(
+ OpusCustomEncoder *st,
+ const float *pcm,
+ int frame_size,
+ unsigned char *compressed,
+ int maxCompressedBytes
+) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(2) OPUS_ARG_NONNULL(4);
/** Encodes a frame of audio.
- @param st Encoder state
- @param pcm PCM audio in signed 16-bit format (native endian). There must be
- * exactly frame_size samples per channel.
- @param compressed The compressed data is written here. This may not alias pcm or
- * optional_synthesis.
- @param nbCompressedBytes Maximum number of bytes to use for compressing the frame
- * (can change from one frame to another)
- @return Number of bytes written to "compressed". Will be the same as
- * "nbCompressedBytes" unless the stream is VBR and will never be larger.
- * If negative, an error has occurred (see error codes). It is IMPORTANT that
- * the length returned be somehow transmitted to the decoder. Otherwise, no
- * decoding is possible.
+ * @param [in] st <tt>OpusCustomEncoder*</tt>: Encoder state
+ * @param [in] pcm <tt>opus_int16*</tt>: PCM audio in signed 16-bit format (native endian).
+ * There must be exactly frame_size samples per channel.
+ * @param [in] frame_size <tt>int</tt>: Number of samples per frame of input signal
+ * @param [out] compressed <tt>char *</tt>: The compressed data is written here. This may not alias pcm and must be at least maxCompressedBytes long.
+ * @param [in] maxCompressedBytes <tt>int</tt>: Maximum number of bytes to use for compressing the frame
+ * (can change from one frame to another)
+ * @return Number of bytes written to "compressed".
+ * If negative, an error has occurred (see error codes). It is IMPORTANT that
+ * the length returned be somehow transmitted to the decoder. Otherwise, no
+ * decoding is possible.
*/
-OPUS_CUSTOM_EXPORT OPUS_WARN_UNUSED_RESULT int opus_custom_encode(OpusCustomEncoder *st, const opus_int16 *pcm, int frame_size, unsigned char *compressed, int maxCompressedBytes);
+OPUS_CUSTOM_EXPORT OPUS_WARN_UNUSED_RESULT int opus_custom_encode(
+ OpusCustomEncoder *st,
+ const opus_int16 *pcm,
+ int frame_size,
+ unsigned char *compressed,
+ int maxCompressedBytes
+) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(2) OPUS_ARG_NONNULL(4);
-/** Query and set encoder parameters
- @param st Encoder state
- @param request Parameter to change or query
- @param value Pointer to a 32-bit int value
- @return Error code
-*/
-OPUS_CUSTOM_EXPORT int opus_custom_encoder_ctl(OpusCustomEncoder * restrict st, int request, ...);
+/** Perform a CTL function on an Opus custom encoder.
+ *
+ * Generally the request and subsequent arguments are generated
+ * by a convenience macro.
+ * @see opus_encoderctls
+ */
+OPUS_CUSTOM_EXPORT int opus_custom_encoder_ctl(OpusCustomEncoder * restrict st, int request, ...) OPUS_ARG_NONNULL(1);
/* Decoder */
-OPUS_CUSTOM_EXPORT_STATIC OPUS_WARN_UNUSED_RESULT int opus_custom_decoder_get_size(const OpusCustomMode *mode, int channels);
+/** Gets the size of an OpusCustomDecoder structure.
+ * @param [in] mode <tt>OpusCustomMode *</tt>: Mode configuration
+ * @param [in] channels <tt>int</tt>: Number of channels
+ * @returns size
+ */
+OPUS_CUSTOM_EXPORT_STATIC OPUS_WARN_UNUSED_RESULT int opus_custom_decoder_get_size(
+ const OpusCustomMode *mode,
+ int channels
+) OPUS_ARG_NONNULL(1);
/** Creates a new decoder state. Each stream needs its own decoder state (can't
- be shared across simultaneous streams).
- @param mode Contains all the information about the characteristics of the
- stream (must be the same characteristics as used for the encoder)
- @param channels Number of channels
- @param error Returns an error code
- @return Newly created decoder state.
- */
-OPUS_CUSTOM_EXPORT OPUS_WARN_UNUSED_RESULT OpusCustomDecoder *opus_custom_decoder_create(const OpusCustomMode *mode, int channels, int *error);
+ * be shared across simultaneous streams).
+ * @param [in] mode <tt>OpusCustomMode</tt>: Contains all the information about the characteristics of the
+ * stream (must be the same characteristics as used for the encoder)
+ * @param [in] channels <tt>int</tt>: Number of channels
+ * @param [out] error <tt>int*</tt>: Returns an error code
+ * @return Newly created decoder state.
+ */
+OPUS_CUSTOM_EXPORT OPUS_WARN_UNUSED_RESULT OpusCustomDecoder *opus_custom_decoder_create(
+ const OpusCustomMode *mode,
+ int channels,
+ int *error
+) OPUS_ARG_NONNULL(1);
-OPUS_CUSTOM_EXPORT_STATIC int opus_custom_decoder_init(OpusCustomDecoder *st, const OpusCustomMode *mode, int channels);
+/** Initializes a previously allocated decoder state
+ * The memory pointed to by st must be the size returned by opus_custom_decoder_get_size.
+ * This is intended for applications which use their own allocator instead of malloc.
+ * @see opus_custom_decoder_create(),opus_custom_decoder_get_size()
+ * To reset a previously initialized state use the OPUS_RESET_STATE CTL.
+ * @param [in] st <tt>OpusCustomDecoder*</tt>: Decoder state
+ * @param [in] mode <tt>OpusCustomMode *</tt>: Contains all the information about the characteristics of
+ * the stream (must be the same characteristics as used for the
+ * encoder)
+ * @param [in] channels <tt>int</tt>: Number of channels
+ * @return OPUS_OK Success or @ref opus_errorcodes
+ */
+OPUS_CUSTOM_EXPORT_STATIC int opus_custom_decoder_init(
+ OpusCustomDecoder *st,
+ const OpusCustomMode *mode,
+ int channels
+) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(2);
-/** Destroys a a decoder state.
- @param st Decoder state to be destroyed
- */
+/** Destroys a an decoder state.
+ * @param[in] st <tt>OpusCustomDecoder*</tt>: State to be freed.
+ */
OPUS_CUSTOM_EXPORT void opus_custom_decoder_destroy(OpusCustomDecoder *st);
-/** Decodes a frame of audio.
- @param st Decoder state
- @param data Compressed data produced by an encoder
- @param len Number of bytes to read from "data". This MUST be exactly the number
- of bytes returned by the encoder. Using a larger value WILL NOT WORK.
- @param pcm One frame (frame_size samples per channel) of decoded PCM will be
- returned here in float format.
- @return Error code.
- */
-OPUS_CUSTOM_EXPORT OPUS_WARN_UNUSED_RESULT int opus_custom_decode_float(OpusCustomDecoder *st, const unsigned char *data, int len, float *pcm, int frame_size);
+/** Decode an opus custom frame with floating point output
+ * @param [in] st <tt>OpusCustomDecoder*</tt>: Decoder state
+ * @param [in] data <tt>char*</tt>: Input payload. Use a NULL pointer to indicate packet loss
+ * @param [in] len <tt>int</tt>: Number of bytes in payload
+ * @param [out] pcm <tt>float*</tt>: Output signal (interleaved if 2 channels). length
+ * is frame_size*channels*sizeof(float)
+ * @param [in] frame_size Number of samples per channel of available space in *pcm.
+ * @returns Number of decoded samples or @ref opus_errorcodes
+ */
+OPUS_CUSTOM_EXPORT OPUS_WARN_UNUSED_RESULT int opus_custom_decode_float(
+ OpusCustomDecoder *st,
+ const unsigned char *data,
+ int len,
+ float *pcm,
+ int frame_size
+) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(4);
-/** Decodes a frame of audio.
- @param st Decoder state
- @param data Compressed data produced by an encoder
- @param len Number of bytes to read from "data". This MUST be exactly the number
- of bytes returned by the encoder. Using a larger value WILL NOT WORK.
- @param pcm One frame (frame_size samples per channel) of decoded PCM will be
- returned here in 16-bit PCM format (native endian).
- @return Error code.
- */
-OPUS_CUSTOM_EXPORT OPUS_WARN_UNUSED_RESULT int opus_custom_decode(OpusCustomDecoder *st, const unsigned char *data, int len, opus_int16 *pcm, int frame_size);
+/** Decode an opus custom frame
+ * @param [in] st <tt>OpusCustomDecoder*</tt>: Decoder state
+ * @param [in] data <tt>char*</tt>: Input payload. Use a NULL pointer to indicate packet loss
+ * @param [in] len <tt>int</tt>: Number of bytes in payload
+ * @param [out] pcm <tt>opus_int16*</tt>: Output signal (interleaved if 2 channels). length
+ * is frame_size*channels*sizeof(opus_int16)
+ * @param [in] frame_size Number of samples per channel of available space in *pcm.
+ * @returns Number of decoded samples or @ref opus_errorcodes
+ */
+OPUS_CUSTOM_EXPORT OPUS_WARN_UNUSED_RESULT int opus_custom_decode(
+ OpusCustomDecoder *st,
+ const unsigned char *data,
+ int len,
+ opus_int16 *pcm,
+ int frame_size
+) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(4);
-/** Query and set decoder parameters
- @param st Decoder state
- @param request Parameter to change or query
- @param value Pointer to a 32-bit int value
- @return Error code
- */
-OPUS_CUSTOM_EXPORT int opus_custom_decoder_ctl(OpusCustomDecoder * restrict st, int request, ...);
+/** Perform a CTL function on an Opus custom decoder.
+ *
+ * Generally the request and subsequent arguments are generated
+ * by a convenience macro.
+ * @see opus_genericctls
+ */
+OPUS_CUSTOM_EXPORT int opus_custom_decoder_ctl(OpusCustomDecoder * restrict st, int request, ...) OPUS_ARG_NONNULL(1);
+
+/**@}*/
#ifdef __cplusplus
}