Adds OPUS_SET_RESTRICTED_LOWDELAY() encoder ctl
[opus.git] / src / opus.h
index 4ffe444..8c7ec98 100644 (file)
@@ -1,5 +1,5 @@
-/* Copyright (c) 2010 Xiph.Org Foundation
-   Written by Jean-Marc Valin */
+/* Copyright (c) 2010-2011 Xiph.Org Foundation, Skype Limited
+   Written by Jean-Marc Valin and Koen Vos */
 /*
    Redistribution and use in source and binary forms, with or without
    modification, are permitted provided that the following conditions
    SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
 
+/**
+ * @file opus.h
+ * @brief Opus reference implementation API
+ */
+
 #ifndef OPUS_H
 #define OPUS_H
 
 #include "opus_types.h"
+#include "opus_defines.h"
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
-#if defined(__GNUC__) && defined(OPUS_BUILD)
-#define OPUS_EXPORT __attribute__ ((visibility ("default")))
-#elif defined(WIN32)
-#define OPUS_EXPORT __declspec(dllexport)
-#else
-#define OPUS_EXPORT
-#endif
 
-#define __check_int(x) (((void)((x) == (int)0)), (int)(x))
-#define __check_int_ptr(ptr) ((ptr) + ((ptr) - (int*)(ptr)))
-
-/* Error codes */
-/** No error */
-#define OPUS_OK                0
-/** An (or more) invalid argument (e.g. out of range) */
-#define OPUS_BAD_ARG          -1
-/** The mode struct passed is invalid */
-#define OPUS_BUFFER_TOO_SMALL -2
-/** An internal error was detected */
-#define OPUS_INTERNAL_ERROR   -3
-/** The data passed (e.g. compressed data to decoder) is corrupted */
-#define OPUS_CORRUPTED_DATA   -4
-/** Invalid/unsupported request number */
-#define OPUS_UNIMPLEMENTED    -5
-/** An encoder or decoder structure is invalid or already freed */
-#define OPUS_INVALID_STATE    -6
-/** Memory allocation has failed */
-#define OPUS_ALLOC_FAIL       -7
-
-#define OPUS_BITRATE_AUTO       -1
-
-#define OPUS_APPLICATION_VOIP        2000
-#define OPUS_APPLICATION_AUDIO       2001
-
-#define OPUS_SIGNAL_AUTO             3000
-#define OPUS_SIGNAL_VOICE            3001
-#define OPUS_SIGNAL_MUSIC            3002
-
-#define MODE_SILK_ONLY          1000
-#define MODE_HYBRID             1001
-#define MODE_CELT_ONLY          1002
-
-#define OPUS_BANDWIDTH_AUTO          1100
-#define OPUS_BANDWIDTH_NARROWBAND    1101
-#define OPUS_BANDWIDTH_MEDIUMBAND    1102
-#define OPUS_BANDWIDTH_WIDEBAND      1103
-#define OPUS_BANDWIDTH_SUPERWIDEBAND 1104
-#define OPUS_BANDWIDTH_FULLBAND      1105
-
-
-
-#define OPUS_SET_MODE_REQUEST 0
-#define OPUS_SET_MODE(x) OPUS_SET_MODE_REQUEST, __check_int(x)
-#define OPUS_GET_MODE_REQUEST 1
-#define OPUS_GET_MODE(x) OPUS_GET_MODE_REQUEST, __check_int_ptr(x)
-
-#define OPUS_SET_BITRATE_REQUEST 2
-#define OPUS_SET_BITRATE(x) OPUS_SET_BITRATE_REQUEST, __check_int(x)
-#define OPUS_GET_BITRATE_REQUEST 3
-#define OPUS_GET_BITRATE(x) OPUS_GET_BITRATE_REQUEST, __check_int_ptr(x)
-
-#define OPUS_SET_VBR_FLAG_REQUEST 6
-#define OPUS_SET_VBR_FLAG(x) OPUS_SET_VBR_FLAG_REQUEST, __check_int(x)
-#define OPUS_GET_VBR_FLAG_REQUEST 7
-#define OPUS_GET_VBR_FLAG(x) OPUS_GET_VBR_FLAG_REQUEST, __check_int_ptr(x)
-
-#define OPUS_SET_BANDWIDTH_REQUEST 8
-#define OPUS_SET_BANDWIDTH(x) OPUS_SET_BANDWIDTH_REQUEST, __check_int(x)
-#define OPUS_GET_BANDWIDTH_REQUEST 9
-#define OPUS_GET_BANDWIDTH(x) OPUS_GET_BANDWIDTH_REQUEST, __check_int_ptr(x)
-
-#define OPUS_SET_COMPLEXITY_REQUEST 10
-#define OPUS_SET_COMPLEXITY(x) OPUS_SET_COMPLEXITY_REQUEST, __check_int(x)
-#define OPUS_GET_COMPLEXITY_REQUEST 11
-#define OPUS_GET_COMPLEXITY(x) OPUS_GET_COMPLEXITY_REQUEST, __check_int_ptr(x)
-
-#define OPUS_SET_INBAND_FEC_FLAG_REQUEST 12
-#define OPUS_SET_INBAND_FEC_FLAG(x) OPUS_SET_INBAND_FEC_FLAG_REQUEST, __check_int(x)
-#define OPUS_GET_INBAND_FEC_FLAG_REQUEST 13
-#define OPUS_GET_INBAND_FEC_FLAG(x) OPUS_GET_INBAND_FEC_FLAG_REQUEST, __check_int_ptr(x)
-
-#define OPUS_SET_PACKET_LOSS_PERC_REQUEST 14
-#define OPUS_SET_PACKET_LOSS_PERC(x) OPUS_SET_PACKET_LOSS_PERC_REQUEST, __check_int(x)
-#define OPUS_GET_PACKET_LOSS_PERC_REQUEST 15
-#define OPUS_GET_PACKET_LOSS_PERC(x) OPUS_GET_PACKET_LOSS_PERC_REQUEST, __check_int_ptr(x)
-
-#define OPUS_SET_DTX_FLAG_REQUEST 16
-#define OPUS_SET_DTX_FLAG(x) OPUS_SET_DTX_FLAG_REQUEST, __check_int(x)
-#define OPUS_GET_DTX_FLAG_REQUEST 17
-#define OPUS_GET_DTX_FLAG(x) OPUS_GET_DTX_FLAG_REQUEST, __check_int_ptr(x)
-
-#define OPUS_SET_VOICE_RATIO_REQUEST 18
-#define OPUS_SET_VOICE_RATIO(x) OPUS_SET_VOICE_RATIO_REQUEST, __check_int(x)
-#define OPUS_GET_VOICE_RATIO_REQUEST 19
-#define OPUS_GET_VOICE_RATIO(x) OPUS_GET_VOICE_RATIO_REQUEST, __check_int_ptr(x)
-
-#define OPUS_SET_VBR_CONSTRAINT_REQUEST 20
-#define OPUS_SET_VBR_CONSTRAINT(x) OPUS_SET_VBR_CONSTRAINT_REQUEST, __check_int(x)
-#define OPUS_GET_VBR_CONSTRAINT_REQUEST 21
-#define OPUS_GET_VBR_CONSTRAINT(x) OPUS_GET_VBR_CONSTRAINT_REQUEST, __check_int_ptr(x)
-
-#define OPUS_SET_FORCE_MONO_REQUEST 22
-#define OPUS_SET_FORCE_MONO(x) OPUS_SET_FORCE_MONO_REQUEST, __check_int(x)
-#define OPUS_GET_FORCE_MONO_REQUEST 23
-#define OPUS_GET_FORCE_MONO(x) OPUS_GET_FORCE_MONO_REQUEST, __check_int_ptr(x)
-
-#define OPUS_SET_SIGNAL_REQUEST 24
-#define OPUS_SET_SIGNAL(x) OPUS_SET_SIGNAL_REQUEST, __check_int(x)
-#define OPUS_GET_SIGNAL_REQUEST 25
-#define OPUS_GET_SIGNAL(x) OPUS_GET_SIGNAL_REQUEST, __check_int_ptr(x)
-
-#define OPUS_GET_LOOKAHEAD_REQUEST 27
-#define OPUS_GET_LOOKAHEAD(x) OPUS_GET_LOOKAHEAD_REQUEST, __check_int_ptr(x)
+
+
 
 typedef struct OpusEncoder OpusEncoder;
 typedef struct OpusDecoder OpusDecoder;
 
-/*
+OPUS_EXPORT int opus_encoder_get_size(int channels);
+
+/**
  * There are two 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
@@ -165,52 +63,78 @@ typedef struct OpusDecoder OpusDecoder;
  *    than 15 ms of coding delay.
  */
 
-/* Returns initialized encoder state */
+/** Returns initialized encoder state */
 OPUS_EXPORT OpusEncoder *opus_encoder_create(
-    int 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) */
+    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_EXPORT OpusEncoder *opus_encoder_init(
-    OpusEncoder *st,            /* Encoder state */
-    int 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) */
+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) */
 );
 
-/* Returns length of the data payload (in bytes) */
+/** 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,            /**< 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 */
+);
+
+/** 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 */
 );
 
 OPUS_EXPORT void opus_encoder_destroy(OpusEncoder *st);
 
 OPUS_EXPORT int opus_encoder_ctl(OpusEncoder *st, int request, ...);
 
+
+
+OPUS_EXPORT int opus_decoder_get_size(int channels);
+
 OPUS_EXPORT OpusDecoder *opus_decoder_create(
-    int Fs,                     /* Sampling rate of output signal (Hz) */
-    int channels                /* Number of channels (1/2) in output signal */
+    opus_int32 Fs,              /**< Sampling rate of output signal (Hz) */
+    int channels,               /**< Number of channels (1/2) in output signal */
+    int *error                  /**< Error code*/
 );
 
-OPUS_EXPORT OpusDecoder *opus_decoder_init(OpusDecoder *st,
-    int Fs,                     /* Sampling rate of output signal (Hz) */
-    int channels                /* Number of channels (1/2) in output signal */
+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 */
 );
 
-/* Returns the number of samples decoded or a negative error code */
+/** Returns the number of samples decoded or a negative error code */
 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,            /**< 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. */
+);
+
+/** Returns the number of samples decoded or a negative error code */
+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. */
 );
 
 OPUS_EXPORT int opus_decoder_ctl(OpusDecoder *st, int request, ...);
@@ -222,22 +146,13 @@ OPUS_EXPORT int opus_packet_parse(const unsigned char *data, int len,
       short size[48], int *payload_offset);
 
 OPUS_EXPORT int opus_packet_get_bandwidth(const unsigned char *data);
-OPUS_EXPORT int opus_packet_get_samples_per_frame(const unsigned char *data, int Fs);
+OPUS_EXPORT int opus_packet_get_samples_per_frame(const unsigned char *data, opus_int32 Fs);
 OPUS_EXPORT int opus_packet_get_nb_channels(const unsigned char *data);
 OPUS_EXPORT int opus_packet_get_nb_frames(const unsigned char packet[], int len);
 OPUS_EXPORT int opus_decoder_get_nb_samples(const OpusDecoder *dec, const unsigned char packet[], int len);
 
-OPUS_EXPORT const char *opus_strerror(int error);
-
-OPUS_EXPORT const char *opus_get_version_string(void);
-
-/* For testing purposes: the encoder and decoder state should
-   always be identical after coding a payload */
-OPUS_EXPORT int opus_encoder_get_final_range(OpusEncoder *st);
-OPUS_EXPORT int opus_decoder_get_final_range(OpusDecoder *st);
-
 
-/* Repacketizer */
+/** Repacketizer */
 typedef struct OpusRepacketizer OpusRepacketizer;
 
 OPUS_EXPORT int opus_repacketizer_get_size(void);