include/opus_custom.h

   1 /* Copyright (c) 2007-2008 CSIRO
   2    Copyright (c) 2007-2009 Xiph.Org Foundation
   3    Copyright (c) 2008 Gregory Maxwell
   4    Written by Jean-Marc Valin and Gregory Maxwell */
   5 /**
   6   @file celt.h
   7   @brief Contains all the functions for encoding and decoding audio
   8  */
   9
  10 /*
  11    Redistribution and use in source and binary forms, with or without
  12    modification, are permitted provided that the following conditions
  13    are met:
  14
  15    - Redistributions of source code must retain the above copyright
  16    notice, this list of conditions and the following disclaimer.
  17
  18    - Redistributions in binary form must reproduce the above copyright
  19    notice, this list of conditions and the following disclaimer in the
  20    documentation and/or other materials provided with the distribution.
  21
  22    - Neither the name of Internet Society, IETF or IETF Trust, nor the
  23    names of specific contributors, may be used to endorse or promote
  24    products derived from this software without specific prior written
  25    permission.
  26
  27    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  28    ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  29    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  30    A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER
  31    OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
  32    EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  33    PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
  34    PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
  35    LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
  36    NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  37    SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  38 */
  39
  40 #ifndef OPUS_CUSTOM_H
  41 #define OPUS_CUSTOM_H
  42
  43
  44 #include "opus_defines.h"
  45
  46 #ifdef __cplusplus
  47 extern "C" {
  48 #endif
  49
  50 #ifdef CUSTOM_MODES
  51 #define OPUS_CUSTOM_EXPORT OPUS_EXPORT
  52 #define OPUS_CUSTOM_EXPORT_STATIC OPUS_EXPORT
  53 #else
  54 #define OPUS_CUSTOM_EXPORT
  55 #ifdef CELT_C
  56 #define OPUS_CUSTOM_EXPORT_STATIC static inline
  57 #else
  58 #define OPUS_CUSTOM_EXPORT_STATIC
  59 #endif
  60 #endif
  61
  62 /** Contains the state of an encoder. One encoder state is needed
  63     for each stream. It is initialised once at the beginning of the
  64     stream. Do *not* re-initialise the state for every frame.
  65    @brief Encoder state
  66  */
  67 typedef struct OpusCustomEncoder OpusCustomEncoder;
  68
  69 /** State of the decoder. One decoder state is needed for each stream.
  70     It is initialised once at the beginning of the stream. Do *not*
  71     re-initialise the state for every frame */
  72 typedef struct OpusCustomDecoder OpusCustomDecoder;
  73
  74 /** The mode contains all the information necessary to create an
  75     encoder. Both the encoder and decoder need to be initialised
  76     with exactly the same mode, otherwise the quality will be very
  77     bad */
  78 typedef struct OpusCustomMode OpusCustomMode;
  79
  80 /** Creates a new mode struct. This will be passed to an encoder or
  81     decoder. The mode MUST NOT BE DESTROYED until the encoders and
  82     decoders that use it are destroyed as well.
  83  @param Fs Sampling rate (32000 to 96000 Hz)
  84  @param frame_size Number of samples (per channel) to encode in each
  85                    packet (even values; 64 - 512)
  86  @param error Returned error code (if NULL, no error will be returned)
  87  @return A newly created mode
  88 */
  89 OPUS_CUSTOM_EXPORT OpusCustomMode *opus_custom_mode_create(opus_int32 Fs, int frame_size, int *error);
  90
  91 /** Destroys a mode struct. Only call this after all encoders and
  92     decoders using this mode are destroyed as well.
  93  @param mode Mode to be destroyed
  94 */
  95 OPUS_CUSTOM_EXPORT void opus_custom_mode_destroy(OpusCustomMode *mode);
  96
  97 /* Encoder */
  98
  99 OPUS_CUSTOM_EXPORT_STATIC int opus_custom_encoder_get_size(const OpusCustomMode *mode, int channels);
 100
 101 /** Creates a new encoder state. Each stream needs its own encoder
 102     state (can't be shared across simultaneous streams).
 103  @param mode Contains all the information about the characteristics of
 104  *  the stream (must be the same characteristics as used for the
 105  *  decoder)
 106  @param channels Number of channels
 107  @param error Returns an error code
 108  @return Newly created encoder state.
 109 */
 110 OPUS_CUSTOM_EXPORT OpusCustomEncoder *opus_custom_encoder_create(const OpusCustomMode *mode, int channels, int *error);
 111
 112 OPUS_CUSTOM_EXPORT_STATIC int opus_custom_encoder_init(OpusCustomEncoder *st, const OpusCustomMode *mode, int channels);
 113
 114 /** Destroys a an encoder state.
 115  @param st Encoder state to be destroyed
 116  */
 117 OPUS_CUSTOM_EXPORT void opus_custom_encoder_destroy(OpusCustomEncoder *st);
 118
 119 /** Encodes a frame of audio.
 120  @param st Encoder state
 121  @param pcm PCM audio in float format, with a normal range of +/-1.0.
 122  *          Samples with a range beyond +/-1.0 are supported but will
 123  *          be clipped by decoders using the integer API and should
 124  *          only be used if it is known that the far end supports
 125  *          extended dynmaic range. There must be exactly
 126  *          frame_size samples per channel.
 127  @param compressed The compressed data is written here. This may not alias pcm or
 128  *                 optional_synthesis.
 129  @param nbCompressedBytes Maximum number of bytes to use for compressing the frame
 130  *          (can change from one frame to another)
 131  @return Number of bytes written to "compressed". Will be the same as
 132  *       "nbCompressedBytes" unless the stream is VBR and will never be larger.
 133  *       If negative, an error has occurred (see error codes). It is IMPORTANT that
 134  *       the length returned be somehow transmitted to the decoder. Otherwise, no
 135  *       decoding is possible.
 136 */
 137 OPUS_CUSTOM_EXPORT int opus_custom_encode_float(OpusCustomEncoder *st, const float *pcm, int frame_size, unsigned char *compressed, int maxCompressedBytes);
 138
 139 /** Encodes a frame of audio.
 140  @param st Encoder state
 141  @param pcm PCM audio in signed 16-bit format (native endian). There must be
 142  *          exactly frame_size samples per channel.
 143  @param compressed The compressed data is written here. This may not alias pcm or
 144  *                         optional_synthesis.
 145  @param nbCompressedBytes Maximum number of bytes to use for compressing the frame
 146  *                        (can change from one frame to another)
 147  @return Number of bytes written to "compressed". Will be the same as
 148  *       "nbCompressedBytes" unless the stream is VBR and will never be larger.
 149  *       If negative, an error has occurred (see error codes). It is IMPORTANT that
 150  *       the length returned be somehow transmitted to the decoder. Otherwise, no
 151  *       decoding is possible.
 152  */
 153 OPUS_CUSTOM_EXPORT int opus_custom_encode(OpusCustomEncoder *st, const opus_int16 *pcm, int frame_size, unsigned char *compressed, int maxCompressedBytes);
 154
 155 /** Query and set encoder parameters
 156  @param st Encoder state
 157  @param request Parameter to change or query
 158  @param value Pointer to a 32-bit int value
 159  @return Error code
 160 */
 161 OPUS_CUSTOM_EXPORT int opus_custom_encoder_ctl(OpusCustomEncoder * restrict st, int request, ...);
 162
 163 /* Decoder */
 164
 165 OPUS_CUSTOM_EXPORT_STATIC int opus_custom_decoder_get_size(const OpusCustomMode *mode, int channels);
 166
 167 /** Creates a new decoder state. Each stream needs its own decoder state (can't
 168     be shared across simultaneous streams).
 169  @param mode Contains all the information about the characteristics of the
 170              stream (must be the same characteristics as used for the encoder)
 171  @param channels Number of channels
 172  @param error Returns an error code
 173  @return Newly created decoder state.
 174  */
 175 OPUS_CUSTOM_EXPORT OpusCustomDecoder *opus_custom_decoder_create(const OpusCustomMode *mode, int channels, int *error);
 176
 177 OPUS_CUSTOM_EXPORT_STATIC int opus_custom_decoder_init(OpusCustomDecoder *st, const OpusCustomMode *mode, int channels);
 178
 179 /** Destroys a a decoder state.
 180  @param st Decoder state to be destroyed
 181  */
 182 OPUS_CUSTOM_EXPORT void opus_custom_decoder_destroy(OpusCustomDecoder *st);
 183
 184 /** Decodes a frame of audio.
 185  @param st Decoder state
 186  @param data Compressed data produced by an encoder
 187  @param len Number of bytes to read from "data". This MUST be exactly the number
 188             of bytes returned by the encoder. Using a larger value WILL NOT WORK.
 189  @param pcm One frame (frame_size samples per channel) of decoded PCM will be
 190             returned here in float format.
 191  @return Error code.
 192    */
 193 OPUS_CUSTOM_EXPORT int opus_custom_decode_float(OpusCustomDecoder *st, const unsigned char *data, int len, float *pcm, int frame_size);
 194
 195 /** Decodes a frame of audio.
 196  @param st Decoder state
 197  @param data Compressed data produced by an encoder
 198  @param len Number of bytes to read from "data". This MUST be exactly the number
 199             of bytes returned by the encoder. Using a larger value WILL NOT WORK.
 200  @param pcm One frame (frame_size samples per channel) of decoded PCM will be
 201             returned here in 16-bit PCM format (native endian).
 202  @return Error code.
 203  */
 204 OPUS_CUSTOM_EXPORT int opus_custom_decode(OpusCustomDecoder *st, const unsigned char *data, int len, opus_int16 *pcm, int frame_size);
 205
 206 /** Query and set decoder parameters
 207    @param st Decoder state
 208    @param request Parameter to change or query
 209    @param value Pointer to a 32-bit int value
 210    @return Error code
 211  */
 212 OPUS_CUSTOM_EXPORT int opus_custom_decoder_ctl(OpusCustomDecoder * restrict st, int request, ...);
 213
 214 #ifdef __cplusplus
 215 }
 216 #endif
 217
 218 #endif /* OPUS_CUSTOM_H */