ref: 3bcf36789811b9da9e07e1f9b5f3204fda0ec960
parent: ee83c16e7a28c56f33a9523cff3cfb8ba9965cb1
author: Gregory Maxwell <[email protected]>
date: Fri Sep 9 13:11:43 EDT 2011
Documentation updates.
--- a/README
+++ b/README
@@ -20,18 +20,20 @@
Once you have compiled the codec, there will be a test_opus executable in
-the src/ directory.
+the top directory.
-Usage: ./test_opus [-e | -d] <application (0/1)> <sampling rate (Hz)> <channels
-(1/2)> <bits per second> [options] <input> <output>
+Usage: test_opus [-e] <application> <sampling rate (Hz)> <channels (1/2)>
+ <bits per second> [options] <input> <output>
+ test_opus -d <sampling rate (Hz)> <channels (1/2)> [options]
+ <input> <output>
-mode: 0 for VoIP, 1 for audio:
+mode: voip | audio | restricted-lowdelay
options:
-e : only runs the encoder (output the bit-stream)
-d : only runs the decoder (reads the bit-stream as input)
-cbr : enable constant bitrate; default: variable bitrate
--cvbr : enable constrained variable bitrate;
- default: unconstrained
+-cvbr : enable constrained variable bitrate; default:
+-unconstrained
-bandwidth <NB|MB|WB|SWB|FB> : audio bandwidth (from narrowband to fullband);
default: sampling rate
-framesize <2.5|5|10|20|40|60> : frame size in ms; default: 20
@@ -42,4 +44,5 @@
-dtx : enable SILK DTX
-loss <perc> : simulate packet loss, in percent (0-100); default: 0
-input and output are 16-bit PCM files (machine endian)
+input and output are 16-bit PCM files (machine endian) or opus bitstreams
+with simple test_opus propritary framing.
--- a/libcelt/opus_defines.h
+++ b/libcelt/opus_defines.h
@@ -357,13 +357,13 @@
/** Converts an opus error code into a human readable string.
*
* @param[in] error <tt>int</tt>: Error number
- * @retval Error string
+ * @returns Error string
*/
OPUS_EXPORT const char *opus_strerror(int error);
/** Gets the libopus version string.
*
- * @retval Version string
+ * @returns Version string
*/
OPUS_EXPORT const char *opus_get_version_string(void);
/**@}*/
--- a/src/opus.h
+++ b/src/opus.h
@@ -40,17 +40,24 @@
extern "C" {#endif
+/** @defgroup opusencoder Opus Encoder
+ * @{+ */
-
-
-
+/** Opus encoder state.
+ * This contains the complete state of an Opus encoder.
+ * It is position independent and can be freely copied.
+ * @see opus_encoder_create,opus_encoder_init
+ */
typedef struct OpusEncoder OpusEncoder;
-typedef struct OpusDecoder OpusDecoder;
OPUS_EXPORT int opus_encoder_get_size(int channels);
/**
- * There are two coding modes:
+ */
+
+/** Allocates and initializes an encoder state.
+ * There are three coding modes:
* OPUS_APPLICATION_VOIP gives best quality at a given bitrate for voice
* signals. It enhances the input signal by high-pass filtering and
* emphasizing formants and harmonics. Optionally it includes in-band
@@ -61,98 +68,254 @@
* non-voice signals like music. Use this mode for music and mixed
* (music/voice) content, broadcast, and applications requiring less
* than 15 ms of coding delay.
+ * OPUS_APPLICATION_RESTRICTED_LOWDELAY configures low-delay mode that
+ * disables the speech-optimized mode in exchange for slightly reduced delay.
+ * This is useful when the caller knows that the speech-optimized modes will not be needed (use with caution).
+ * @param [in] Fs <tt>opus_int32</tt>: Sampling rate of input signal (Hz)
+ * @param [in] channels <tt>int</tt>: Number of channels (1/2) in input signal
+ * @param [in] application <tt>int</tt>: Coding mode (OPUS_APPLICATION_VOIP/OPUS_APPLICATION_AUDIO/OPUS_APPLICATION_RESTRICTED_LOWDELAY)
+ * @param [out] error <tt>int*</tt>: Error code
*/
-
-/** Returns initialized encoder state */
OPUS_EXPORT OpusEncoder *opus_encoder_create(
- opus_int32 Fs, /**< Sampling rate of input signal (Hz) */
- int channels, /**< Number of channels (1/2) in input signal */
- int application, /**< Coding mode (OPUS_APPLICATION_VOIP/OPUS_APPLICATION_AUDIO) */
- int *error /**< Error code */
+ opus_int32 Fs,
+ int channels,
+ int application,
+ int *error
);
+/** Initializes a previously allocated encoder state
+ * The memory pointed to by st must be 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.
+ * @param [in] st <tt>OpusEncoder*</tt>: Encoder state
+ * @param [in] Fs <tt>opus_int32</tt>: Sampling rate of input signal (Hz)
+ * @param [in] channels <tt>int</tt>: Number of channels (1/2) in input signal
+ * @param [in] application <tt>int</tt>: Coding mode (OPUS_APPLICATION_VOIP/OPUS_APPLICATION_AUDIO/OPUS_APPLICATION_RESTRICTED_LOWDELAY)
+ * @retval OPUS_OK Success.
+ */
OPUS_EXPORT int opus_encoder_init(
- OpusEncoder *st, /**< Encoder state */
- opus_int32 Fs, /**< Sampling rate of input signal (Hz) */
- int channels, /**< Number of channels (1/2) in input signal */
- int application /**< Coding mode (OPUS_APPLICATION_VOIP/OPUS_APPLICATION_AUDIO) */
+ OpusEncoder *st,
+ opus_int32 Fs,
+ int channels,
+ int application
);
-/** Returns length of the data payload (in bytes) */
+/** Encodes an Opus frame.
+ * The passed frame_size must an opus frame size for the encoder's sampling rate.
+ * For example, at 48kHz the permitted values are 120, 240, 480, or 960.
+ * 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>opus_int16*</tt>: Input signal (interleaved if 2 channels). length is frame_size*channels*sizeof(opus_int16)
+ * @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>int</tt>: Allocated memory for payload; don't use for controlling bitrate
+ * @returns length of the data payload (in bytes)
+ */
OPUS_EXPORT int opus_encode(
- OpusEncoder *st, /**< Encoder state */
- const opus_int16 *pcm, /**< Input signal (interleaved if 2 channels). length is frame_size*channels */
- int frame_size, /**< Number of samples per frame of input signal */
- unsigned char *data, /**< Output payload (no more than max_data_bytes long) */
- int max_data_bytes /**< Allocated memory for payload; don't use for controlling bitrate */
+ OpusEncoder *st,
+ const opus_int16 *pcm,
+ int frame_size,
+ unsigned char *data,
+ int max_data_bytes
);
-/** Returns length of the data payload (in bytes) */
+/** Encodes an Opus frame from floating point input.
+ * The passed frame_size must an opus frame size for the encoder's sampling rate.
+ * For example, at 48kHz the permitted values are 120, 240, 480, or 960.
+ * 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] 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>int</tt>: Allocated memory for payload; don't use for controlling bitrate
+ * @returns length of the data payload (in bytes)
+ */
OPUS_EXPORT int opus_encode_float(
- OpusEncoder *st, /**< Encoder state */
- const float *pcm, /**< Input signal (interleaved if 2 channels). length is frame_size*channels 0dbFS range of +/-1.0*/
- int frame_size, /**< Number of samples per frame of input signal */
- unsigned char *data, /**< Output payload (no more than max_data_bytes long) */
- int max_data_bytes /**< Allocated memory for payload; don't use for controlling bitrate */
+ OpusEncoder *st,
+ const float *pcm,
+ int frame_size,
+ unsigned char *data,
+ int max_data_bytes
);
+/** Frees an OpusEncoder allocated by opus_encoder_create.
+ * @param[in] st <tt>OpusEncoder*</tt>: State to be freed.
+ */
OPUS_EXPORT void opus_encoder_destroy(OpusEncoder *st);
+/** Perform a CTL function on an Opus encoder.
+ * @see encoderctls
+ */
OPUS_EXPORT int opus_encoder_ctl(OpusEncoder *st, int request, ...);
+/**@}*/
+/** @defgroup opusdecoder Opus Decoder
+ * @{+ */
+/** Opus decoder state.
+ * This contains the complete state of an Opus decoder.
+ * It is position independent and can be freely copied.
+ * @see opus_decoder_create,opus_decoder_init
+ */
+typedef struct OpusDecoder OpusDecoder;
+/** Gets the size of an OpusDecoder structure.
+ * @param [in] channels <tt>int</tt>: Number of channels
+ * @returns size
+ */
OPUS_EXPORT int opus_decoder_get_size(int channels);
+/** Allocates and initializes a decoder state.
+ * @param [in] Fs <tt>opus_int32</tt>: Sampling rate of input signal (Hz)
+ * @param [in] channels <tt>int</tt>: Number of channels (1/2) in input signal
+ * @param [out] error <tt>int*</tt>: Error code
+ */
OPUS_EXPORT OpusDecoder *opus_decoder_create(
- opus_int32 Fs, /**< Sampling rate of output signal (Hz) */
- int channels, /**< Number of channels (1/2) in output signal */
- int *error /**< Error code*/
+ opus_int32 Fs,
+ int channels,
+ int *error
);
-OPUS_EXPORT int opus_decoder_init(OpusDecoder *st,
- opus_int32 Fs, /**< Sampling rate of output signal (Hz) */
- int channels /**< Number of channels (1/2) in output signal */
+/** Initializes a previously allocated decoder state.
+ * The state must be 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 <tt>OpusDecoder*</tt>: Decoder state.
+ * @param [in] Fs <tt>opus_int32</tt>: Sampling rate of input signal (Hz)
+ * @param [in] channels <tt>int</tt>: Number of channels (1/2) in input signal
+ * @retval OPUS_OK Success.
+ */
+OPUS_EXPORT int opus_decoder_init(
+ OpusDecoder *st,
+ opus_int32 Fs,
+ int channels
);
-/** Returns the number of samples decoded or a negative error code */
+/** Decode an Opus frame
+ * @param [in] st <tt>OpusDecoder*</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,
+ * if less than the maximum frame size (120ms) some frames can not be decoded
+ * @param [in] decode_fec <tt>int</tt>: Flag (0/1) to request that any in-band forward error correction data be
+ * decoded. If no such data is available the frame is decoded as if it were lost.
+ * @returns Number of decoded samples
+ */
OPUS_EXPORT int opus_decode(
- OpusDecoder *st, /**< Decoder state */
- const unsigned char *data, /**< Input payload. Use a NULL pointer to indicate packet loss */
- int len, /**< Number of bytes in payload */
- opus_int16 *pcm, /**< Output signal (interleaved if 2 channels). length is frame_size*channels */
- int frame_size, /**< Number of samples per frame of input signal */
- int decode_fec /**< Flag (0/1) to request that any in-band forward error correction data be */
- /**< decoded. If no such data is available the frame is decoded as if it were lost. */
+ OpusDecoder *st,
+ const unsigned char *data,
+ int len,
+ opus_int16 *pcm,
+ int frame_size,
+ int decode_fec
);
-/** Returns the number of samples decoded or a negative error code */
+/** Decode an opus frame with floating point output
+ * @param [in] st <tt>OpusDecoder*</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,
+ * if less than the maximum frame size (120ms) some frames can not be decoded
+ * @param [in] decode_fec <tt>int</tt>: Flag (0/1) to request that any in-band forward error correction data be
+ * decoded. If no such data is available the frame is decoded as if it were lost.
+ * @returns Number of decoded samples
+ */
OPUS_EXPORT int opus_decode_float(
- OpusDecoder *st, /**< Decoder state */
- const unsigned char *data, /**< Input payload. Use a NULL pointer to indicate packet loss */
- int len, /**< Number of bytes in payload */
- float *pcm, /**< Output signal (interleaved if 2 channels). length is frame_size*channels 0dbFS range of -/+1.0*/
- int frame_size, /**< Number of samples per frame of input signal */
- int decode_fec /**< Flag (0/1) to request that any in-band forward error correction data be */
- /**< decoded. If no such data is available the frame is decoded as if it were lost. */
+ OpusDecoder *st,
+ const unsigned char *data,
+ int len,
+ float *pcm,
+ int frame_size,
+ int decode_fec
);
+/** Perform a CTL function on an Opus decoder.
+ * @see decoderctls
+ */
OPUS_EXPORT int opus_decoder_ctl(OpusDecoder *st, int request, ...);
+/** Frees an OpusDecoder allocated by opus_decoder_create.
+ * @param[in] st <tt>OpusDecoder*</tt>: State to be freed.
+ */
OPUS_EXPORT void opus_decoder_destroy(OpusDecoder *st);
-OPUS_EXPORT int opus_packet_parse(const unsigned char *data, int len,
- unsigned char *out_toc, const unsigned char *frames[48],
- short size[48], int *payload_offset);
+/** Parse an opus packet into one or more frames.
+ * Opus_decode will perform this operation internally so most applications do
+ * not need to use this function.
+ * This function does not copy the frames, the returned pointers are pointers into
+ * the input packet.
+ * @param [in] data <tt>char*</tt>: Opus packet to be parsed
+ * @param [in] len <tt>int</tt>: size of data
+ * @param [out] out_toc <tt>char*</tt>: TOC pointer
+ * @param [out] frames <tt>char*[48]</tt> encapsulated frames
+ * @param [out] size <tt>short[48]</tt> sizes of the encapsulated frames
+ * @param [out] payload_offset <tt>int*</tt>: @todo bloop?
+ * @returns number of frames
+ */
+OPUS_EXPORT int opus_packet_parse(
+ const unsigned char *data,
+ int len,
+ unsigned char *out_toc,
+ const unsigned char *frames[48],
+ short size[48],
+ int *payload_offset
+);
+/** Gets the bandwidth of an Opus packet.
+ * @param [in] data <tt>char*</tt>: Opus packet
+ * @retval OPUS_BANDWIDTH_NARROWBAND Narrowband (4kHz bandpass)
+ * @retval OPUS_BANDWIDTH_MEDIUMBAND Mediumband (6kHz bandpass)
+ * @retval OPUS_BANDWIDTH_WIDEBAND Wideband (8kHz bandpass)
+ * @retval OPUS_BANDWIDTH_SUPERWIDEBAND Superwideband (12kHz bandpass)
+ * @retval OPUS_BANDWIDTH_FULLBAND Fullband (20kHz bandpass)
+ * @retval OPUS_INVALID_PACKET The compressed data passed is corrupted or of an unsupported type
+ */
OPUS_EXPORT int opus_packet_get_bandwidth(const unsigned char *data);
+
+/** Gets the number of samples per frame from an Opus packet.
+ * @param [in] data <tt>char*</tt>: Opus packet
+ * @param [in] Fs <tt>opus_int32</tt>: Sampling rate in Hz
+ * @returns Number of samples per frame
+ * @retval OPUS_INVALID_PACKET The compressed data passed is corrupted or of an unsupported type
+ */
OPUS_EXPORT int opus_packet_get_samples_per_frame(const unsigned char *data, opus_int32 Fs);
+
+/** Gets the number of channels from an Opus packet.
+ * @param [in] data <tt>char*</tt>: Opus packet
+ * @returns Number of channels
+ * @retval OPUS_INVALID_PACKET The compressed data passed is corrupted or of an unsupported type
+ */
OPUS_EXPORT int opus_packet_get_nb_channels(const unsigned char *data);
+
+/** Gets the number of frame in an Opus packet.
+ * @param [in] packet <tt>char*</tt>: Opus packet
+ * @param [in] len <tt>int</tt>: Length of packet
+ * @returns Number of frames
+ * @retval OPUS_INVALID_PACKET The compressed data passed is corrupted or of an unsupported type
+ */
OPUS_EXPORT int opus_packet_get_nb_frames(const unsigned char packet[], int len);
+
+/** Gets the number of samples of an Opus packet.
+ * @param [in] dec <tt>OpusDecoder*</tt>: Decoder state
+ * @param [in] packet <tt>char*</tt>: Opus packet
+ * @param [in] len <tt>int</tt>: Length of packet
+ * @returns Number of samples
+ * @retval OPUS_INVALID_PACKET The compressed data passed is corrupted or of an unsupported type
+ */
OPUS_EXPORT int opus_decoder_get_nb_samples(const OpusDecoder *dec, const unsigned char packet[], int len);
+/**@}*/
+/** @defgroup repacketizer Repacketizer
+ * @{+ */
-/** Repacketizer */
typedef struct OpusRepacketizer OpusRepacketizer;
OPUS_EXPORT int opus_repacketizer_get_size(void);
@@ -170,6 +333,8 @@
OPUS_EXPORT int opus_repacketizer_get_nb_frames(OpusRepacketizer *rp);
OPUS_EXPORT int opus_repacketizer_out(OpusRepacketizer *rp, unsigned char *data, int maxlen);
+
+/**@}*/
#ifdef __cplusplus
}