1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/media/libopus/include/opus_custom.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,342 @@
1.4 +/* Copyright (c) 2007-2008 CSIRO
1.5 + Copyright (c) 2007-2009 Xiph.Org Foundation
1.6 + Copyright (c) 2008-2012 Gregory Maxwell
1.7 + Written by Jean-Marc Valin and Gregory Maxwell */
1.8 +/*
1.9 + Redistribution and use in source and binary forms, with or without
1.10 + modification, are permitted provided that the following conditions
1.11 + are met:
1.12 +
1.13 + - Redistributions of source code must retain the above copyright
1.14 + notice, this list of conditions and the following disclaimer.
1.15 +
1.16 + - Redistributions in binary form must reproduce the above copyright
1.17 + notice, this list of conditions and the following disclaimer in the
1.18 + documentation and/or other materials provided with the distribution.
1.19 +
1.20 + THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
1.21 + ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
1.22 + LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
1.23 + A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER
1.24 + OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
1.25 + EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
1.26 + PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
1.27 + PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
1.28 + LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
1.29 + NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
1.30 + SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
1.31 +*/
1.32 +
1.33 +/**
1.34 + @file opus_custom.h
1.35 + @brief Opus-Custom reference implementation API
1.36 + */
1.37 +
1.38 +#ifndef OPUS_CUSTOM_H
1.39 +#define OPUS_CUSTOM_H
1.40 +
1.41 +#include "opus_defines.h"
1.42 +
1.43 +#ifdef __cplusplus
1.44 +extern "C" {
1.45 +#endif
1.46 +
1.47 +#ifdef CUSTOM_MODES
1.48 +# define OPUS_CUSTOM_EXPORT OPUS_EXPORT
1.49 +# define OPUS_CUSTOM_EXPORT_STATIC OPUS_EXPORT
1.50 +#else
1.51 +# define OPUS_CUSTOM_EXPORT
1.52 +# ifdef OPUS_BUILD
1.53 +# define OPUS_CUSTOM_EXPORT_STATIC static OPUS_INLINE
1.54 +# else
1.55 +# define OPUS_CUSTOM_EXPORT_STATIC
1.56 +# endif
1.57 +#endif
1.58 +
1.59 +/** @defgroup opus_custom Opus Custom
1.60 + * @{
1.61 + * Opus Custom is an optional part of the Opus specification and
1.62 + * reference implementation which uses a distinct API from the regular
1.63 + * API and supports frame sizes that are not normally supported.\ Use
1.64 + * of Opus Custom is discouraged for all but very special applications
1.65 + * for which a frame size different from 2.5, 5, 10, or 20 ms is needed
1.66 + * (for either complexity or latency reasons) and where interoperability
1.67 + * is less important.
1.68 + *
1.69 + * In addition to the interoperability limitations the use of Opus custom
1.70 + * disables a substantial chunk of the codec and generally lowers the
1.71 + * quality available at a given bitrate. Normally when an application needs
1.72 + * a different frame size from the codec it should buffer to match the
1.73 + * sizes but this adds a small amount of delay which may be important
1.74 + * in some very low latency applications. Some transports (especially
1.75 + * constant rate RF transports) may also work best with frames of
1.76 + * particular durations.
1.77 + *
1.78 + * Libopus only supports custom modes if they are enabled at compile time.
1.79 + *
1.80 + * The Opus Custom API is similar to the regular API but the
1.81 + * @ref opus_encoder_create and @ref opus_decoder_create calls take
1.82 + * an additional mode parameter which is a structure produced by
1.83 + * a call to @ref opus_custom_mode_create. Both the encoder and decoder
1.84 + * must create a mode using the same sample rate (fs) and frame size
1.85 + * (frame size) so these parameters must either be signaled out of band
1.86 + * or fixed in a particular implementation.
1.87 + *
1.88 + * Similar to regular Opus the custom modes support on the fly frame size
1.89 + * switching, but the sizes available depend on the particular frame size in
1.90 + * use. For some initial frame sizes on a single on the fly size is available.
1.91 + */
1.92 +
1.93 +/** Contains the state of an encoder. One encoder state is needed
1.94 + for each stream. It is initialized once at the beginning of the
1.95 + stream. Do *not* re-initialize the state for every frame.
1.96 + @brief Encoder state
1.97 + */
1.98 +typedef struct OpusCustomEncoder OpusCustomEncoder;
1.99 +
1.100 +/** State of the decoder. One decoder state is needed for each stream.
1.101 + It is initialized once at the beginning of the stream. Do *not*
1.102 + re-initialize the state for every frame.
1.103 + @brief Decoder state
1.104 + */
1.105 +typedef struct OpusCustomDecoder OpusCustomDecoder;
1.106 +
1.107 +/** The mode contains all the information necessary to create an
1.108 + encoder. Both the encoder and decoder need to be initialized
1.109 + with exactly the same mode, otherwise the output will be
1.110 + corrupted.
1.111 + @brief Mode configuration
1.112 + */
1.113 +typedef struct OpusCustomMode OpusCustomMode;
1.114 +
1.115 +/** Creates a new mode struct. This will be passed to an encoder or
1.116 + * decoder. The mode MUST NOT BE DESTROYED until the encoders and
1.117 + * decoders that use it are destroyed as well.
1.118 + * @param [in] Fs <tt>int</tt>: Sampling rate (8000 to 96000 Hz)
1.119 + * @param [in] frame_size <tt>int</tt>: Number of samples (per channel) to encode in each
1.120 + * packet (64 - 1024, prime factorization must contain zero or more 2s, 3s, or 5s and no other primes)
1.121 + * @param [out] error <tt>int*</tt>: Returned error code (if NULL, no error will be returned)
1.122 + * @return A newly created mode
1.123 + */
1.124 +OPUS_CUSTOM_EXPORT OPUS_WARN_UNUSED_RESULT OpusCustomMode *opus_custom_mode_create(opus_int32 Fs, int frame_size, int *error);
1.125 +
1.126 +/** Destroys a mode struct. Only call this after all encoders and
1.127 + * decoders using this mode are destroyed as well.
1.128 + * @param [in] mode <tt>OpusCustomMode*</tt>: Mode to be freed.
1.129 + */
1.130 +OPUS_CUSTOM_EXPORT void opus_custom_mode_destroy(OpusCustomMode *mode);
1.131 +
1.132 +
1.133 +#if !defined(OPUS_BUILD) || defined(CELT_ENCODER_C)
1.134 +
1.135 +/* Encoder */
1.136 +/** Gets the size of an OpusCustomEncoder structure.
1.137 + * @param [in] mode <tt>OpusCustomMode *</tt>: Mode configuration
1.138 + * @param [in] channels <tt>int</tt>: Number of channels
1.139 + * @returns size
1.140 + */
1.141 +OPUS_CUSTOM_EXPORT_STATIC OPUS_WARN_UNUSED_RESULT int opus_custom_encoder_get_size(
1.142 + const OpusCustomMode *mode,
1.143 + int channels
1.144 +) OPUS_ARG_NONNULL(1);
1.145 +
1.146 +# ifdef CUSTOM_MODES
1.147 +/** Initializes a previously allocated encoder state
1.148 + * The memory pointed to by st must be the size returned by opus_custom_encoder_get_size.
1.149 + * This is intended for applications which use their own allocator instead of malloc.
1.150 + * @see opus_custom_encoder_create(),opus_custom_encoder_get_size()
1.151 + * To reset a previously initialized state use the OPUS_RESET_STATE CTL.
1.152 + * @param [in] st <tt>OpusCustomEncoder*</tt>: Encoder state
1.153 + * @param [in] mode <tt>OpusCustomMode *</tt>: Contains all the information about the characteristics of
1.154 + * the stream (must be the same characteristics as used for the
1.155 + * decoder)
1.156 + * @param [in] channels <tt>int</tt>: Number of channels
1.157 + * @return OPUS_OK Success or @ref opus_errorcodes
1.158 + */
1.159 +OPUS_CUSTOM_EXPORT int opus_custom_encoder_init(
1.160 + OpusCustomEncoder *st,
1.161 + const OpusCustomMode *mode,
1.162 + int channels
1.163 +) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(2);
1.164 +# endif
1.165 +#endif
1.166 +
1.167 +
1.168 +/** Creates a new encoder state. Each stream needs its own encoder
1.169 + * state (can't be shared across simultaneous streams).
1.170 + * @param [in] mode <tt>OpusCustomMode*</tt>: Contains all the information about the characteristics of
1.171 + * the stream (must be the same characteristics as used for the
1.172 + * decoder)
1.173 + * @param [in] channels <tt>int</tt>: Number of channels
1.174 + * @param [out] error <tt>int*</tt>: Returns an error code
1.175 + * @return Newly created encoder state.
1.176 +*/
1.177 +OPUS_CUSTOM_EXPORT OPUS_WARN_UNUSED_RESULT OpusCustomEncoder *opus_custom_encoder_create(
1.178 + const OpusCustomMode *mode,
1.179 + int channels,
1.180 + int *error
1.181 +) OPUS_ARG_NONNULL(1);
1.182 +
1.183 +
1.184 +/** Destroys a an encoder state.
1.185 + * @param[in] st <tt>OpusCustomEncoder*</tt>: State to be freed.
1.186 + */
1.187 +OPUS_CUSTOM_EXPORT void opus_custom_encoder_destroy(OpusCustomEncoder *st);
1.188 +
1.189 +/** Encodes a frame of audio.
1.190 + * @param [in] st <tt>OpusCustomEncoder*</tt>: Encoder state
1.191 + * @param [in] pcm <tt>float*</tt>: PCM audio in float format, with a normal range of +/-1.0.
1.192 + * Samples with a range beyond +/-1.0 are supported but will
1.193 + * be clipped by decoders using the integer API and should
1.194 + * only be used if it is known that the far end supports
1.195 + * extended dynamic range. There must be exactly
1.196 + * frame_size samples per channel.
1.197 + * @param [in] frame_size <tt>int</tt>: Number of samples per frame of input signal
1.198 + * @param [out] compressed <tt>char *</tt>: The compressed data is written here. This may not alias pcm and must be at least maxCompressedBytes long.
1.199 + * @param [in] maxCompressedBytes <tt>int</tt>: Maximum number of bytes to use for compressing the frame
1.200 + * (can change from one frame to another)
1.201 + * @return Number of bytes written to "compressed".
1.202 + * If negative, an error has occurred (see error codes). It is IMPORTANT that
1.203 + * the length returned be somehow transmitted to the decoder. Otherwise, no
1.204 + * decoding is possible.
1.205 + */
1.206 +OPUS_CUSTOM_EXPORT OPUS_WARN_UNUSED_RESULT int opus_custom_encode_float(
1.207 + OpusCustomEncoder *st,
1.208 + const float *pcm,
1.209 + int frame_size,
1.210 + unsigned char *compressed,
1.211 + int maxCompressedBytes
1.212 +) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(2) OPUS_ARG_NONNULL(4);
1.213 +
1.214 +/** Encodes a frame of audio.
1.215 + * @param [in] st <tt>OpusCustomEncoder*</tt>: Encoder state
1.216 + * @param [in] pcm <tt>opus_int16*</tt>: PCM audio in signed 16-bit format (native endian).
1.217 + * There must be exactly frame_size samples per channel.
1.218 + * @param [in] frame_size <tt>int</tt>: Number of samples per frame of input signal
1.219 + * @param [out] compressed <tt>char *</tt>: The compressed data is written here. This may not alias pcm and must be at least maxCompressedBytes long.
1.220 + * @param [in] maxCompressedBytes <tt>int</tt>: Maximum number of bytes to use for compressing the frame
1.221 + * (can change from one frame to another)
1.222 + * @return Number of bytes written to "compressed".
1.223 + * If negative, an error has occurred (see error codes). It is IMPORTANT that
1.224 + * the length returned be somehow transmitted to the decoder. Otherwise, no
1.225 + * decoding is possible.
1.226 + */
1.227 +OPUS_CUSTOM_EXPORT OPUS_WARN_UNUSED_RESULT int opus_custom_encode(
1.228 + OpusCustomEncoder *st,
1.229 + const opus_int16 *pcm,
1.230 + int frame_size,
1.231 + unsigned char *compressed,
1.232 + int maxCompressedBytes
1.233 +) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(2) OPUS_ARG_NONNULL(4);
1.234 +
1.235 +/** Perform a CTL function on an Opus custom encoder.
1.236 + *
1.237 + * Generally the request and subsequent arguments are generated
1.238 + * by a convenience macro.
1.239 + * @see opus_encoderctls
1.240 + */
1.241 +OPUS_CUSTOM_EXPORT int opus_custom_encoder_ctl(OpusCustomEncoder * OPUS_RESTRICT st, int request, ...) OPUS_ARG_NONNULL(1);
1.242 +
1.243 +
1.244 +#if !defined(OPUS_BUILD) || defined(CELT_DECODER_C)
1.245 +/* Decoder */
1.246 +
1.247 +/** Gets the size of an OpusCustomDecoder structure.
1.248 + * @param [in] mode <tt>OpusCustomMode *</tt>: Mode configuration
1.249 + * @param [in] channels <tt>int</tt>: Number of channels
1.250 + * @returns size
1.251 + */
1.252 +OPUS_CUSTOM_EXPORT_STATIC OPUS_WARN_UNUSED_RESULT int opus_custom_decoder_get_size(
1.253 + const OpusCustomMode *mode,
1.254 + int channels
1.255 +) OPUS_ARG_NONNULL(1);
1.256 +
1.257 +/** Initializes a previously allocated decoder state
1.258 + * The memory pointed to by st must be the size returned by opus_custom_decoder_get_size.
1.259 + * This is intended for applications which use their own allocator instead of malloc.
1.260 + * @see opus_custom_decoder_create(),opus_custom_decoder_get_size()
1.261 + * To reset a previously initialized state use the OPUS_RESET_STATE CTL.
1.262 + * @param [in] st <tt>OpusCustomDecoder*</tt>: Decoder state
1.263 + * @param [in] mode <tt>OpusCustomMode *</tt>: Contains all the information about the characteristics of
1.264 + * the stream (must be the same characteristics as used for the
1.265 + * encoder)
1.266 + * @param [in] channels <tt>int</tt>: Number of channels
1.267 + * @return OPUS_OK Success or @ref opus_errorcodes
1.268 + */
1.269 +OPUS_CUSTOM_EXPORT_STATIC int opus_custom_decoder_init(
1.270 + OpusCustomDecoder *st,
1.271 + const OpusCustomMode *mode,
1.272 + int channels
1.273 +) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(2);
1.274 +
1.275 +#endif
1.276 +
1.277 +
1.278 +/** Creates a new decoder state. Each stream needs its own decoder state (can't
1.279 + * be shared across simultaneous streams).
1.280 + * @param [in] mode <tt>OpusCustomMode</tt>: Contains all the information about the characteristics of the
1.281 + * stream (must be the same characteristics as used for the encoder)
1.282 + * @param [in] channels <tt>int</tt>: Number of channels
1.283 + * @param [out] error <tt>int*</tt>: Returns an error code
1.284 + * @return Newly created decoder state.
1.285 + */
1.286 +OPUS_CUSTOM_EXPORT OPUS_WARN_UNUSED_RESULT OpusCustomDecoder *opus_custom_decoder_create(
1.287 + const OpusCustomMode *mode,
1.288 + int channels,
1.289 + int *error
1.290 +) OPUS_ARG_NONNULL(1);
1.291 +
1.292 +/** Destroys a an decoder state.
1.293 + * @param[in] st <tt>OpusCustomDecoder*</tt>: State to be freed.
1.294 + */
1.295 +OPUS_CUSTOM_EXPORT void opus_custom_decoder_destroy(OpusCustomDecoder *st);
1.296 +
1.297 +/** Decode an opus custom frame with floating point output
1.298 + * @param [in] st <tt>OpusCustomDecoder*</tt>: Decoder state
1.299 + * @param [in] data <tt>char*</tt>: Input payload. Use a NULL pointer to indicate packet loss
1.300 + * @param [in] len <tt>int</tt>: Number of bytes in payload
1.301 + * @param [out] pcm <tt>float*</tt>: Output signal (interleaved if 2 channels). length
1.302 + * is frame_size*channels*sizeof(float)
1.303 + * @param [in] frame_size Number of samples per channel of available space in *pcm.
1.304 + * @returns Number of decoded samples or @ref opus_errorcodes
1.305 + */
1.306 +OPUS_CUSTOM_EXPORT OPUS_WARN_UNUSED_RESULT int opus_custom_decode_float(
1.307 + OpusCustomDecoder *st,
1.308 + const unsigned char *data,
1.309 + int len,
1.310 + float *pcm,
1.311 + int frame_size
1.312 +) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(4);
1.313 +
1.314 +/** Decode an opus custom frame
1.315 + * @param [in] st <tt>OpusCustomDecoder*</tt>: Decoder state
1.316 + * @param [in] data <tt>char*</tt>: Input payload. Use a NULL pointer to indicate packet loss
1.317 + * @param [in] len <tt>int</tt>: Number of bytes in payload
1.318 + * @param [out] pcm <tt>opus_int16*</tt>: Output signal (interleaved if 2 channels). length
1.319 + * is frame_size*channels*sizeof(opus_int16)
1.320 + * @param [in] frame_size Number of samples per channel of available space in *pcm.
1.321 + * @returns Number of decoded samples or @ref opus_errorcodes
1.322 + */
1.323 +OPUS_CUSTOM_EXPORT OPUS_WARN_UNUSED_RESULT int opus_custom_decode(
1.324 + OpusCustomDecoder *st,
1.325 + const unsigned char *data,
1.326 + int len,
1.327 + opus_int16 *pcm,
1.328 + int frame_size
1.329 +) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(4);
1.330 +
1.331 +/** Perform a CTL function on an Opus custom decoder.
1.332 + *
1.333 + * Generally the request and subsequent arguments are generated
1.334 + * by a convenience macro.
1.335 + * @see opus_genericctls
1.336 + */
1.337 +OPUS_CUSTOM_EXPORT int opus_custom_decoder_ctl(OpusCustomDecoder * OPUS_RESTRICT st, int request, ...) OPUS_ARG_NONNULL(1);
1.338 +
1.339 +/**@}*/
1.340 +
1.341 +#ifdef __cplusplus
1.342 +}
1.343 +#endif
1.344 +
1.345 +#endif /* OPUS_CUSTOM_H */
