fork/rust-sdks

git clone https://git.julia.blue/fork/rust-sdks

Théo Monnomsoxr-sys (#438)2e4d385

livekit/livekit-ffi@0.13.0
13.7 KiB344 linesraw
1/* SoX Resampler Library      Copyright (c) 2007-18 robs@users.sourceforge.net
2 *
3 * This library is free software; you can redistribute it and/or modify it
4 * under the terms of the GNU Lesser General Public License as published by
5 * the Free Software Foundation; either version 2.1 of the License, or (at
6 * your option) any later version.
7 *
8 * This library is distributed in the hope that it will be useful, but
9 * WITHOUT ANY WARRANTY; without even the implied warranty of
10 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser
11 * General Public License for more details.
12 *
13 * You should have received a copy of the GNU Lesser General Public License
14 * along with this library; if not, write to the Free Software Foundation,
15 * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
16 */
17
18
19
20/* -------------------------------- Gubbins --------------------------------- */
21
22#if !defined soxr_included
23#define soxr_included
24
25
26#if defined __cplusplus
27  #include <cstddef>
28  extern "C" {
29#else
30  #include <stddef.h>
31#endif
32
33#if defined SOXR_DLL
34  #if defined soxr_EXPORTS
35    #define SOXR __declspec(dllexport)
36  #else
37    #define SOXR __declspec(dllimport)
38  #endif
39#elif defined SOXR_VISIBILITY && defined __GNUC__ && (__GNUC__ > 4 || __GNUC__ == 4 && __GNUC_MINOR__ >= 1)
40  #define SOXR __attribute__ ((visibility("default")))
41#else
42  #define SOXR
43#endif
44
45typedef struct soxr_io_spec soxr_io_spec_t;
46typedef struct soxr_quality_spec soxr_quality_spec_t;
47typedef struct soxr_runtime_spec soxr_runtime_spec_t;
48
49
50
51/* ---------------------------- API conventions --------------------------------
52
53Buffer lengths (and occupancies) are expressed as the number of contained
54samples per channel.
55
56Parameter names for buffer lengths have the suffix `len'.
57
58A single-character `i' or 'o' is often used in names to give context as
59input or output (e.g. ilen, olen).                                            */
60
61
62
63/* --------------------------- Version management --------------------------- */
64
65/* E.g. #if SOXR_THIS_VERSION >= SOXR_VERSION(0,1,1) ...                      */
66
67#define SOXR_VERSION(x,y,z)     (((x)<<16)|((y)<<8)|(z))
68#define SOXR_THIS_VERSION       SOXR_VERSION(0,1,3)
69#define SOXR_THIS_VERSION_STR               "0.1.3"
70
71
72
73/* --------------------------- Type declarations ---------------------------- */
74
75typedef struct soxr * soxr_t;          /* A resampler for 1 or more channels. */
76typedef char const * soxr_error_t;                /* 0:no-error; non-0:error. */
77
78typedef void       * soxr_buf_t;  /* 1 buffer of channel-interleaved samples. */
79typedef void const * soxr_cbuf_t;                        /* Ditto; read-only. */
80
81typedef soxr_buf_t const  * soxr_bufs_t;/* Or, a separate buffer for each ch. */
82typedef soxr_cbuf_t const * soxr_cbufs_t;                /* Ditto; read-only. */
83
84typedef void const * soxr_in_t;      /* Either a soxr_cbuf_t or soxr_cbufs_t,
85                                        depending on itype in soxr_io_spec_t. */
86typedef void       * soxr_out_t;     /* Either a soxr_buf_t or soxr_bufs_t,
87                                        depending on otype in soxr_io_spec_t. */
88
89
90
91/* --------------------------- API main functions --------------------------- */
92
93SOXR char const * soxr_version(void);  /* Query library version: "libsoxr-x.y.z" */
94
95#define soxr_strerror(e)               /* Soxr counterpart to strerror. */     \
96    ((e)?(e):"no error")
97
98
99/* Create a stream resampler: */
100
101SOXR soxr_t soxr_create(
102    double      input_rate,      /* Input sample-rate. */
103    double      output_rate,     /* Output sample-rate. */
104    unsigned    num_channels,    /* Number of channels to be used. */
105        /* All following arguments are optional (may be set to NULL). */
106    soxr_error_t *,              /* To report any error during creation. */
107    soxr_io_spec_t const *,      /* To specify non-default I/O formats. */
108    soxr_quality_spec_t const *, /* To specify non-default resampling quality.*/
109    soxr_runtime_spec_t const *);/* To specify non-default runtime resources.
110
111    Default io_spec      is per soxr_io_spec(SOXR_FLOAT32_I, SOXR_FLOAT32_I)
112    Default quality_spec is per soxr_quality_spec(SOXR_HQ, 0)
113    Default runtime_spec is per soxr_runtime_spec(1)                          */
114
115
116
117/* If not using an app-supplied input function, after creating a stream
118 * resampler, repeatedly call: */
119
120SOXR soxr_error_t soxr_process(
121    soxr_t      resampler,      /* As returned by soxr_create. */
122                            /* Input (to be resampled): */
123    soxr_in_t   in,             /* Input buffer(s); may be NULL (see below). */
124    size_t      ilen,           /* Input buf. length (samples per channel). */
125    size_t      * idone,        /* To return actual # samples used (<= ilen). */
126                            /* Output (resampled): */
127    soxr_out_t  out,            /* Output buffer(s).*/
128    size_t      olen,           /* Output buf. length (samples per channel). */
129    size_t      * odone);       /* To return actual # samples out (<= olen).
130
131    Note that no special meaning is associated with ilen or olen equal to
132    zero.  End-of-input (i.e. no data is available nor shall be available)
133    may be indicated by seting `in' to NULL.                                  */
134
135
136
137/* If using an app-supplied input function, it must look and behave like this:*/
138
139typedef size_t /* data_len */
140  (* soxr_input_fn_t)(         /* Supply data to be resampled. */
141    void * input_fn_state,     /* As given to soxr_set_input_fn (below). */
142    soxr_in_t * data,          /* Returned data; see below. N.B. ptr to ptr(s)*/
143    size_t requested_len);     /* Samples per channel, >= returned data_len.
144
145  data_len  *data     Indicates    Meaning
146   ------- -------   ------------  -------------------------
147     !=0     !=0       Success     *data contains data to be
148                                   input to the resampler.
149      0    !=0 (or   End-of-input  No data is available nor
150           not set)                shall be available.
151      0       0        Failure     An error occurred whilst trying to
152                                   source data to be input to the resampler.  */
153
154/* and be registered with a previously created stream resampler using: */
155
156SOXR soxr_error_t soxr_set_input_fn(/* Set (or reset) an input function.*/
157    soxr_t resampler,            /* As returned by soxr_create. */
158    soxr_input_fn_t,             /* Function to supply data to be resampled.*/
159    void * input_fn_state,       /* If needed by the input function. */
160    size_t max_ilen);            /* Maximum value for input fn. requested_len.*/
161
162/* then repeatedly call: */
163
164SOXR size_t /*odone*/ soxr_output(/* Resample and output a block of data.*/
165    soxr_t resampler,            /* As returned by soxr_create. */
166    soxr_out_t data,             /* App-supplied buffer(s) for resampled data.*/
167    size_t olen);                /* Amount of data to output; >= odone. */
168
169
170
171/* Common stream resampler operations: */
172
173SOXR soxr_error_t soxr_error(soxr_t);   /* Query error status. */
174SOXR size_t   * soxr_num_clips(soxr_t); /* Query int. clip counter (for R/W). */
175SOXR double     soxr_delay(soxr_t);  /* Query current delay in output samples.*/
176SOXR char const * soxr_engine(soxr_t);  /* Query resampling engine name. */
177
178SOXR soxr_error_t soxr_clear(soxr_t); /* Ready for fresh signal, same config. */
179SOXR void         soxr_delete(soxr_t);  /* Free resources. */
180
181
182
183/* `Short-cut', single call to resample a (probably short) signal held entirely
184 * in memory.  See soxr_create and soxr_process above for parameter details.
185 * Note that unlike soxr_create however, the default quality spec. for
186 * soxr_oneshot is per soxr_quality_spec(SOXR_LQ, 0). */
187
188SOXR soxr_error_t soxr_oneshot(
189    double         input_rate,
190    double         output_rate,
191    unsigned       num_channels,
192    soxr_in_t    in , size_t ilen, size_t * idone,
193    soxr_out_t   out, size_t olen, size_t * odone,
194    soxr_io_spec_t const *,
195    soxr_quality_spec_t const *,
196    soxr_runtime_spec_t const *);
197
198
199
200/* For variable-rate resampling. See example # 5 for how to create a
201 * variable-rate resampler and how to use this function. */
202
203SOXR soxr_error_t soxr_set_io_ratio(soxr_t, double io_ratio, size_t slew_len);
204
205
206
207/* -------------------------- API type definitions -------------------------- */
208
209typedef enum {          /* Datatypes supported for I/O to/from the resampler: */
210  /* Internal; do not use: */
211  SOXR_FLOAT32, SOXR_FLOAT64, SOXR_INT32, SOXR_INT16, SOXR_SPLIT = 4,
212
213  /* Use for interleaved channels: */
214  SOXR_FLOAT32_I = SOXR_FLOAT32, SOXR_FLOAT64_I, SOXR_INT32_I, SOXR_INT16_I,
215
216  /* Use for split channels: */
217  SOXR_FLOAT32_S = SOXR_SPLIT  , SOXR_FLOAT64_S, SOXR_INT32_S, SOXR_INT16_S
218
219} soxr_datatype_t;
220
221#define soxr_datatype_size(x)  /* Returns `sizeof' a soxr_datatype_t sample. */\
222  ((unsigned char *)"\4\10\4\2")[(x)&3]
223
224
225
226struct soxr_io_spec {                                            /* Typically */
227  soxr_datatype_t itype;     /* Input datatype.                SOXR_FLOAT32_I */
228  soxr_datatype_t otype;     /* Output datatype.               SOXR_FLOAT32_I */
229  double scale;              /* Linear gain to apply during resampling.  1    */
230  void * e;                  /* Reserved for internal use                0    */
231  unsigned long flags;       /* Per the following #defines.              0    */
232};
233
234#define SOXR_TPDF              0     /* Applicable only if otype is INT16. */
235#define SOXR_NO_DITHER         8u    /* Disable the above. */
236
237
238
239struct soxr_quality_spec {                                       /* Typically */
240  double precision;         /* Conversion precision (in bits).           20   */
241  double phase_response;    /* 0=minimum, ... 50=linear, ... 100=maximum 50   */
242  double passband_end;      /* 0dB pt. bandwidth to preserve; nyquist=1  0.913*/
243  double stopband_begin;    /* Aliasing/imaging control; > passband_end   1   */
244  void * e;                 /* Reserved for internal use.                 0   */
245  unsigned long flags;      /* Per the following #defines.                0   */
246};
247
248#define SOXR_ROLLOFF_SMALL     0u    /* <= 0.01 dB */
249#define SOXR_ROLLOFF_MEDIUM    1u    /* <= 0.35 dB */
250#define SOXR_ROLLOFF_NONE      2u    /* For Chebyshev bandwidth. */
251
252#define SOXR_HI_PREC_CLOCK     8u  /* Increase `irrational' ratio accuracy. */
253#define SOXR_DOUBLE_PRECISION 16u  /* Use D.P. calcs even if precision <= 20. */
254#define SOXR_VR               32u  /* Variable-rate resampling. */
255
256
257
258struct soxr_runtime_spec {                                       /* Typically */
259  unsigned log2_min_dft_size;   /* For DFT efficiency. [8,15]           10    */
260  unsigned log2_large_dft_size; /* For DFT efficiency. [8,20]           17    */
261  unsigned coef_size_kbytes;    /* For SOXR_COEF_INTERP_AUTO (below).   400   */
262  unsigned num_threads;         /* 0: per OMP_NUM_THREADS; 1: 1 thread.  1    */
263  void * e;                     /* Reserved for internal use.            0    */
264  unsigned long flags;          /* Per the following #defines.           0    */
265};
266                                   /* For `irrational' ratios only: */
267#define SOXR_COEF_INTERP_AUTO  0u    /* Auto select coef. interpolation. */
268#define SOXR_COEF_INTERP_LOW   2u    /* Man. select: less CPU, more memory. */
269#define SOXR_COEF_INTERP_HIGH  3u    /* Man. select: more CPU, less memory. */
270
271
272
273/* -------------------------- API type constructors ------------------------- */
274
275/* These functions allow setting of the most commonly-used structure
276 * parameters, with other parameters being given default values.  The default
277 * values may then be overridden, directly in the structure, if needed.  */
278
279SOXR soxr_quality_spec_t soxr_quality_spec(
280    unsigned long recipe,       /* Per the #defines immediately below. */
281    unsigned long flags);       /* As soxr_quality_spec_t.flags. */
282
283                                  /* The 5 standard qualities found in SoX: */
284#define SOXR_QQ                 0   /* 'Quick' cubic interpolation. */
285#define SOXR_LQ                 1   /* 'Low' 16-bit with larger rolloff. */
286#define SOXR_MQ                 2   /* 'Medium' 16-bit with medium rolloff. */
287#define SOXR_HQ                 SOXR_20_BITQ /* 'High quality'. */
288#define SOXR_VHQ                SOXR_28_BITQ /* 'Very high quality'. */
289
290#define SOXR_16_BITQ            3
291#define SOXR_20_BITQ            4
292#define SOXR_24_BITQ            5
293#define SOXR_28_BITQ            6
294#define SOXR_32_BITQ            7
295                                /* Reserved for internal use (to be removed): */
296#define SOXR_LSR0Q              8     /* 'Best sinc'. */
297#define SOXR_LSR1Q              9     /* 'Medium sinc'. */
298#define SOXR_LSR2Q              10    /* 'Fast sinc'. */
299
300#define SOXR_LINEAR_PHASE       0x00
301#define SOXR_INTERMEDIATE_PHASE 0x10
302#define SOXR_MINIMUM_PHASE      0x30
303
304#define SOXR_STEEP_FILTER       0x40
305
306
307
308SOXR soxr_runtime_spec_t soxr_runtime_spec(
309    unsigned num_threads);
310
311
312
313SOXR soxr_io_spec_t soxr_io_spec(
314    soxr_datatype_t itype,
315    soxr_datatype_t otype);
316
317
318
319/* --------------------------- Advanced use only ---------------------------- */
320
321/* For new designs, the following functions/usage will probably not be needed.
322 * They might be useful when adding soxr into an existing design where values
323 * for the resampling-rate and/or number-of-channels parameters to soxr_create
324 * are not available when that function will be called.  In such cases, the
325 * relevant soxr_create parameter(s) can be given as 0, then one or both of the
326 * following (as appropriate) later invoked (but prior to calling soxr_process
327 * or soxr_output):
328 *
329 * soxr_set_error(soxr, soxr_set_io_ratio(soxr, io_ratio, 0));
330 * soxr_set_error(soxr, soxr_set_num_channels(soxr, num_channels));
331 */
332
333SOXR soxr_error_t soxr_set_error(soxr_t, soxr_error_t);
334SOXR soxr_error_t soxr_set_num_channels(soxr_t, unsigned);
335
336
337
338#undef SOXR
339
340#if defined __cplusplus
341}
342#endif
343
344#endif