Adds OPUS_SET_RESTRICTED_LOWDELAY() encoder ctl
[opus.git] / src / opus_multistream.h
1 /* Copyright (c) 2011 Xiph.Org Foundation
2    Written by Jean-Marc Valin */
3 /*
4    Redistribution and use in source and binary forms, with or without
5    modification, are permitted provided that the following conditions
6    are met:
7
8    - Redistributions of source code must retain the above copyright
9    notice, this list of conditions and the following disclaimer.
10
11    - Redistributions in binary form must reproduce the above copyright
12    notice, this list of conditions and the following disclaimer in the
13    documentation and/or other materials provided with the distribution.
14
15    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
16    ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
17    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
18    A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR
19    CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
20    EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
21    PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
22    PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
23    LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
24    NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
25    SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
26 */
27
28 /**
29  * @file opus_multistream.h
30  * @brief Opus reference implementation multistream API
31  */
32
33 #ifndef OPUS_MULTISTREAM_H
34 #define OPUS_MULTISTREAM_H
35
36 #include "opus.h"
37
38 typedef struct OpusMSEncoder OpusMSEncoder;
39 typedef struct OpusMSDecoder OpusMSDecoder;
40
41 OPUS_EXPORT OpusMSEncoder *opus_multistream_encoder_create(
42       opus_int32 Fs,                     /**< Sampling rate of input signal (Hz) */
43       int channels,               /**< Number of channels (1/2) in input signal */
44       int streams,
45       int coupled_streams,
46       unsigned char *mapping,
47       int application,            /**< Coding mode (OPUS_APPLICATION_VOIP/OPUS_APPLICATION_AUDIO) */
48       int *error                  /**< Error code */
49 );
50
51 OPUS_EXPORT int opus_multistream_encoder_init(
52       OpusMSEncoder *st,          /**< Encoder state */
53       opus_int32 Fs,                     /**< Sampling rate of input signal (Hz) */
54       int channels,               /**< Number of channels (1/2) in input signal */
55       int streams,
56       int coupled_streams,
57       unsigned char *mapping,
58       int application             /**< Coding mode (OPUS_APPLICATION_VOIP/OPUS_APPLICATION_AUDIO) */
59 );
60
61 /** Returns length of the data payload (in bytes) */
62 OPUS_EXPORT int opus_multistream_encode(
63     OpusMSEncoder *st,          /**< Encoder state */
64     const opus_int16 *pcm,      /**< Input signal (interleaved if 2 channels). length is frame_size*channels */
65     int frame_size,             /**< Number of samples per frame of input signal */
66     unsigned char *data,        /**< Output payload (no more than max_data_bytes long) */
67     int max_data_bytes          /**< Allocated memory for payload; don't use for controlling bitrate */
68 );
69
70 /** Returns length of the data payload (in bytes) */
71 OPUS_EXPORT int opus_multistream_encode_float(
72       OpusMSEncoder *st,          /**< Encoder state */
73       const float *pcm,           /**< Input signal (interleaved if 2 channels). length is frame_size*channels */
74       int frame_size,             /**< Number of samples per frame of input signal */
75       unsigned char *data,        /**< Output payload (no more than max_data_bytes long) */
76       int max_data_bytes          /**< Allocated memory for payload; don't use for controlling bitrate */
77   );
78
79 OPUS_EXPORT void opus_multistream_encoder_destroy(OpusMSEncoder *st);
80
81 OPUS_EXPORT int opus_multistream_encoder_ctl(OpusMSEncoder *st, int request, ...);
82
83 OPUS_EXPORT OpusMSDecoder *opus_multistream_decoder_create(
84       opus_int32 Fs,                     /**< Sampling rate of input signal (Hz) */
85       int channels,               /**< Number of channels (1/2) in input signal */
86       int streams,
87       int coupled_streams,
88       unsigned char *mapping,
89       int *error                  /**< Error code */
90 );
91
92 OPUS_EXPORT int opus_multistream_decoder_init(
93       OpusMSDecoder *st,          /**< Encoder state */
94       opus_int32 Fs,                     /**< Sampling rate of input signal (Hz) */
95       int channels,               /**< Number of channels (1/2) in input signal */
96       int streams,
97       int coupled_streams,
98       unsigned char *mapping
99 );
100
101 /** Returns the number of samples decoded or a negative error code */
102 OPUS_EXPORT int opus_multistream_decode(
103     OpusMSDecoder *st,          /**< Decoder state */
104     const unsigned char *data,  /**< Input payload. Use a NULL pointer to indicate packet loss */
105     int len,                    /**< Number of bytes in payload */
106     opus_int16 *pcm,            /**< Output signal (interleaved if 2 channels). length is frame_size*channels */
107     int frame_size,             /**< Number of samples per frame of input signal */
108     int decode_fec              /**< Flag (0/1) to request that any in-band forward error correction data be */
109                                 /**< decoded. If no such data is available the frame is decoded as if it were lost. */
110 );
111
112 /** Returns the number of samples decoded or a negative error code */
113 OPUS_EXPORT int opus_multistream_decode_float(
114     OpusMSDecoder *st,          /**< Decoder state */
115     const unsigned char *data,  /**< Input payload. Use a NULL pointer to indicate packet loss */
116     int len,                    /**< Number of bytes in payload */
117     float *pcm,                 /**< Output signal (interleaved if 2 channels). length is frame_size*channels */
118     int frame_size,             /**< Number of samples per frame of input signal */
119     int decode_fec              /**< Flag (0/1) to request that any in-band forward error correction data be */
120                                 /**< decoded. If no such data is available the frame is decoded as if it were lost. */
121 );
122
123 OPUS_EXPORT int opus_multistream_decoder_ctl(OpusMSDecoder *st, int request, ...);
124
125 OPUS_EXPORT void opus_multistream_decoder_destroy(OpusMSDecoder *st);
126
127 #endif /* OPUS_MULTISTREAM_H */