Documentation updates.
authorGregory Maxwell <greg@xiph.org>
Fri, 9 Sep 2011 21:11:43 +0000 (17:11 -0400)
committerGregory Maxwell <greg@xiph.org>
Fri, 9 Sep 2011 21:11:43 +0000 (17:11 -0400)
README
libcelt/opus_defines.h
src/opus.h

diff --git a/README b/README
index b271f16..afcbab3 100644 (file)
--- a/README
+++ b/README
@@ -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.
index d27c27b..c72edcc 100644 (file)
@@ -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);
 /**@}*/
index 8c7ec98..7f9f927 100644 (file)
 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