diff options
| -rw-r--r-- | README | 17 | ||||
| -rw-r--r-- | libcelt/opus_defines.h | 4 | ||||
| -rw-r--r-- | src/opus.h | 273 |
3 files changed, 231 insertions, 63 deletions
@@ -20,18 +20,20 @@ To build from the git repository, the following steps are necessary: 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 @@ options: -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. diff --git a/libcelt/opus_defines.h b/libcelt/opus_defines.h index d27c27ba..c72edcc3 100644 --- a/libcelt/opus_defines.h +++ b/libcelt/opus_defines.h @@ -357,13 +357,13 @@ extern "C" { /** 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); /**@}*/ @@ -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 @@ OPUS_EXPORT int opus_encoder_get_size(int channels); * 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); @@ -171,6 +334,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 } #endif |