Debian Codegraph @

src/include/syn123.h

raw
1 /*
2 syn123: some audio signal synthesis and format conversion
3
4 copyright 2017-2023 by the mpg123 project,
5 free software under the terms of the LGPL 2.1
6 see COPYING and AUTHORS files in distribution or http://mpg123.org
7
8 initially written by Thomas Orgis
9
10 Consider defining SYN123_PORTABLE_API to limit the definitions to
11 a safer subset without some problematic features (mainly off_t usage).
12 */
13
14 #ifndef SYN123_H
15 #define SYN123_H
16
17 /** \file syn123.h The header file for the libsyn123 library. */
18
19 /* Common audio encoding specification. */
20 #include "fmt123.h"
21
22 /** A macro to check at compile time which set of API functions to expect.
23 * This must be incremented at least each time a new symbol is added
24 * to the header.
25 */
26 #define SYN123_API_VERSION 2
27 /** library patch level at client build time */
28 #define SYN123_PATCHLEVEL 3
29
30 #ifndef MPG123_EXPORT
31 /** Defines needed for MS Visual Studio(tm) DLL builds.
32 * Every public function must be prefixed with MPG123_EXPORT. When building
33 * the DLL ensure to define BUILD_MPG123_DLL. This makes the function accessible
34 * for clients and includes it in the import library which is created together
35 * with the DLL. When consuming the DLL ensure to define LINK_MPG123_DLL which
36 * imports the functions from the DLL.
37 */
38 #ifdef BUILD_MPG123_DLL
39 /* The dll exports. */
40 #define MPG123_EXPORT __declspec(dllexport)
41 #else
42 #ifdef LINK_MPG123_DLL
43 /* The exe imports. */
44 #define MPG123_EXPORT __declspec(dllimport)
45 #else
46 /* Nothing on normal/UNIX builds */
47 #define MPG123_EXPORT
48 #endif
49 #endif
50 #endif
51
52 /** Support the restrict keyword for handed-in pointers. Defined to
53 'restrict' if available.
54 */
55 #ifndef MPG123_RESTRICT
56 #if defined(__STDC_VERSION__) && __STDC_VERSION__ >= 199901L
57 #define MPG123_RESTRICT restrict
58 #else
59 #define MPG123_RESTRICT
60 #endif
61 #endif
62
63 // for off_t and ssize_t
64 #ifndef SYN123_PORTABLE_API
65 #include <sys/types.h>
66 #endif
67
68 #include <stddef.h>
69 #include <stdint.h>
70
71 #ifdef __cplusplus
72 extern "C" {
73 #endif
74
75 /** \defgroup syn123_api syn123 library API
76 * I wanted to create some test signals in different encodings for testing
77 * libout123. Also, they shall serve to verify the decoding of libmpg123
78 * in automated testing. Then, the awful drop-sample resampling inside the
79 * latter needed replacement. As digital filtering is part of the resampler
80 * dance, a chain of those can also be configured and applied. I hope I can
81 * avoid adding yet more functionality. It's a little utility library to
82 * accompany libmpg123 and libout123, OK?
83 *
84 * This is what libsyn123 offers:
85 *
86 * - signal generation (mix of differing wave shapes, noise, a simulated
87 * Geiger counter for fun)
88 * - format conversion and channel mixing and amplification, with hard and
89 * soft clipping, also optional dithering
90 * - near-zero-latency good-enough quite-fast resampling
91 * - applying digital filters with user-provided coefficients
92 *
93 * The usage model for signal generation is this:
94 *
95 * 1. Create handle with desired output format.
96 * 2. Set up synthesis mode with parameters.
97 * 3. Repeatedly extract buffers with PCM samples.
98 *
99 * If your hardware is slow on floating point operations, you may benefit
100 * from the period buffer in the handle that only needs actual computation
101 * once in the setup function. The frequencies of a wave mix may be fudged
102 * a bit to make for a configured period size.
103 *
104 * The usage model for resampling is this:
105 *
106 * 1. Create handle with any format or re-use a signal generation handle.
107 * 2. Set up resampling (rate ratio, channels, dirty mode).
108 * 3. Use predictor functions to work out matching sizes of input and
109 * output buffers.
110 * 4. Call the resampler on chunks of input, immediately producing matching
111 * chunks of output.
112 *
113 * The resampler works on 32 bit float, exclusively. This is what is required
114 * and appropriate for the provided quality.
115 *
116 * The usage model for filtering is this:
117 *
118 * 1. Create or re-use a handle.
119 * 2. Set up the filter chain for single or double precision floating point.
120 * 3. Apply the filter to chunks of input in succession.
121 *
122 * Computations are generally done in floating point, either 32 bit or 64
123 * bit (single or double precision). The functions for encoding conversion,
124 * (de-)interleaving, and interleaved mixing can work without a handle and
125 * only use the buffers you hand in. Some support using a syn123 handle to
126 * provide the temporary buffers for encoding conversion on the fly to apply
127 * flotating-point processing to integer encodings.
128 *
129 * Only the functions that are able to return a success code do check
130 * arguments for obvious trouble like NULL pointers. You are supposed to
131 * act responsibly when calling.
132 *
133 * The size of buffers is either counted in bytes or samples, which,
134 * depending on the context, refer to individual PCM samples or to what is
135 * more strictly called a frame (one sample for each channel counted
136 * together).
137 @{
138 */
139
140 /** Opaque structure for the libsyn123 handle.
141 *
142 * Simple context-free API functions do not need a handle, while
143 * others require it. Those that require it want it as first argument.
144 * Functions taking a handle as last argument after others make optional
145 * use of it (if non-NULL) to enable advanced functionality like
146 * on-the-fly encoding conversion that needs temporary storage.
147 */
148 struct syn123_struct;
149 /** Typedef shortcut as preferrend name for the handle type. */
150 typedef struct syn123_struct syn123_handle;
151
152 /** Get version of the mpg123 distribution this library build came with.
153 * (optional means non-NULL)
154 * \param major optional address to store major version number
155 * \param minor optional address to store minor version number
156 * \param patch optional address to store patchlevel version number
157 * \return full version string (like "1.2.3-beta4 (experimental)")
158 */
159 MPG123_EXPORT
160 const char *syn123_distversion(unsigned int *major, unsigned int *minor, unsigned int *patch);
161
162 /** Get API version of library build.
163 * \param patch optional address to store patchlevel
164 * \return API version of library
165 */
166 MPG123_EXPORT
167 unsigned int syn123_libversion(unsigned int *patch);
168
169 /** Functions that return an integer success code either return
170 * SYN123_OK if everything went fine, or one of the other detailed
171 * error codes.
172 */
173 enum syn123_error
174 {
175 SYN123_OK = 0 /**< no error */
176 , SYN123_BAD_HANDLE /**< bad handle given (NULL) */
177 , SYN123_BAD_FMT /**< bad format (rate/channels) */
178 , SYN123_BAD_ENC /**< bad encoding given */
179 , SYN123_BAD_CONV /**< unsupported conversion */
180 , SYN123_BAD_SIZE /**< buffer size bad (too small) */
181 , SYN123_BAD_BUF /**< bad buffer pointer (NULL) */
182 , SYN123_BAD_CHOP /**< byte buffer not cut at sample boundaries */
183 , SYN123_DOOM /**< Disaster, Out Of Memory. */
184 , SYN123_WEIRD /**< An internal error that should never occur. */
185 , SYN123_BAD_FREQ /**< Invalid wave frequency given. */
186 , SYN123_BAD_SWEEP /**< Invalid sweep curve given. */
187 , SYN123_OVERFLOW /**< Some fatal (integer) overflow that prevents proper operation. */
188 , SYN123_NO_DATA /**< Not enough data to do something. */
189 , SYN123_BAD_DATA /**< Data present, but not usable. */
190 };
191
192 /** Give a short phrase explaining an error code.
193 * \param errcode the code returned by an API function
194 * \return error phrase
195 */
196 const char* syn123_strerror(int errcode);
197
198 /** Create new handle with specified output format.
199 * \param rate sampling rate
200 * \param channels channel count (duplicated mono channels)
201 * \param encoding sample encoding (see enum mpg123_enc_enum)
202 * \param maxbuf maximum buffer size in bytes to allow for caching periodic
203 * signals. When this is given, it is attempted to fit any configured signal
204 * into this buffer in the hope it will work being played periodically. Maybe
205 * there will be tricks with non-periodic signals.
206 * A buffer size of zero turns off buffering and signals are always generated
207 * during extraction.
208 * \param err address to store error code, non-NULL if you care
209 * \return Pointer to allocated handle structure or NULL on error.
210 */
211 MPG123_EXPORT
212 syn123_handle* syn123_new( long rate, int channels, int encoding
213 , size_t maxbuf, int *err );
214
215 /** Delete a handle.
216 * \param sh the handle to delete
217 */
218 MPG123_EXPORT
219 void syn123_del(syn123_handle *sh);
220
221 /** Enable/disable dithering for conversions.
222 *
223 * The default is no dither for conversions to integer encodings. You can
224 * enable dithering after handle creation, or disable it, as you wish.
225 * Enabling the dither resets the random number generator seed to the provided
226 * value or an internal default if the provided value is zero. The dither noise
227 * is unfiltered with triangular distribution (TPDF), as a sensible common
228 * choice. No further filtering of questionable benefit.
229 *
230 * \param sh handle to work on
231 * \param dither Disable (0) or enable (1, actually nonzero) dithering.
232 * Positive values > 1 may trigger differing dither modes in future, but not
233 * now.
234 * \param seed optional address to read the initial seed value from (if non-zero)
235 * and to write the current value to
236 */
237 MPG123_EXPORT
238 int syn123_dither(syn123_handle *sh, int dither, unsigned long *seed);
239
240 /** Extract desired amount of data from the generator.
241 * \param sh handle
242 * \param dst destination buffer
243 * \param dst_bytes number of bytes to extract
244 * \return actual number of extracted bytes
245 * (might differ if dst_bytes is no multiple of the PCM frame size)
246 */
247 MPG123_EXPORT
248 size_t syn123_read(syn123_handle *sh, void *dst, size_t dst_bytes);
249
250 /** Wave types */
251 enum syn123_wave_id
252 {
253 SYN123_WAVE_INVALID = -1 /**< invalid wave pattern */
254 , SYN123_WAVE_FLAT = 0 /**< flat line, silence */
255 , SYN123_WAVE_SINE /**< sinusodial wave*/
256 , SYN123_WAVE_SQUARE /**< square wave */
257 , SYN123_WAVE_TRIANGLE /**< triangle wave */
258 , SYN123_WAVE_SAWTOOTH /**< sawtooth wave */
259 , SYN123_WAVE_GAUSS /**< Gaussian bell shape */
260 , SYN123_WAVE_PULSE /**< pulse shape, x^2 exp(-A x^2)/S */
261 , SYN123_WAVE_SHOT /**< shot (sharper pulse), x^2 exp(-A x)/S
262 * (different values for A and S) */
263 , SYN123_WAVE_LIMIT /**< valid IDs below that. A newer release of
264 * the library might support more. */
265 };
266
267 /** Setup periodic wave generator.
268 * This sets up a series of oscillators with differing wave shapes.
269 * They are multiplied/scaled with each other instead of mixed
270 * in a sum of signals. It's more fun this way to generate interesting
271 * sounds. If you want to mix differing streams with differing volumes,
272 * channel balance and phase shifts, just create multiple single-channel
273 * generators with a convenient format (float encoding comes to mind)
274 * and mix to your heart's desire. You can then still use this library
275 * to get your channel buffers interleaved and converted to something
276 * your output device likes.
277 *
278 * You can ensure strict periodicity without possible shifts in phases
279 * due to floating point rounding errors with the buffered variant.
280 * That may adjust your chosen frequencies to be able to keep the limit
281 * on buffer size, but the resulting data is then strictly periodic
282 * without any further computations that may introduce timing errors.
283 * Apart from possibly saving computing time via the precomputed table,
284 * this is the reason to pre-mix multiple waves into a common buffer at
285 * all.
286 *
287 * The adjustments of the wave frequencies also include limiting them
288 * between some minimal value and the Nyquist frequency. Without the
289 * buffer, you can happily choose waves that are not resolved at all
290 * by the sampling rate and get the nasty results. Things get nasty
291 * inside the buffer, too, when you approach the Nyquist limit, but that
292 * is life (and mathematics).
293 *
294 * The default wave is a 440 Hz sine without phase offset. If any setting
295 * is missing, the default is taken from that.
296 *
297 * \param sh handle
298 * \param count number of waves (if zero, one default wave is configured)
299 * \param id array of wave IDs (enum syn123_wave_id), may be NULL
300 * \param freq array of wave frequencies, may be NULL
301 * Your provided frequencies are overwritten with the actual
302 * values if the periodic buffer is chosen.
303 * \param phase array of wave phases, may be NULL
304 * \param backwards array of true (non-zero) or false (zero), indicating
305 whether the wave is being inverted in time, may be NULL
306 * \param period address to store the size of the period buffer
307 * in samples (zero if not using the buffer), ignored if NULL
308 * \return success code
309 */
310 MPG123_EXPORT
311 int syn123_setup_waves( syn123_handle* sh, size_t count
312 , int *id, double *freq, double *phase, int* backwards
313 , size_t *period );
314
315 /** Query current wave generator setup and state.
316 *
317 * This lets you extract the setup of the wave generator and
318 * the current phases to be able to re-create it and continue
319 * seamlessly, or maybe intentionally in some tweaked form with
320 * slight phase or frequency shifts.
321 *
322 * You only need to set target pointers to non-NULL where you
323 * want the corresponding values extracted. You need to have
324 * the storage prepared for the correct wave count. A common
325 * mode of usage might be to make a first call to only query
326 * the count, allocate storage, then a do a second call for the
327 * wave data.
328 *
329 * \param sh handle
330 * \param count address to store number of waves
331 * \param id storage for array of wave IDs
332 * \param freq storage for array of wave frequencies
333 * \param phase storage for array of wave phases
334 * \param backwards storage for array of true (non-zero) or false (zero),
335 * indicating whether the wave is being inverted in time
336 * \param period address to store the size of the period buffer
337 * in samples (zero if not using the buffer)
338 * \return success code
339 */
340 MPG123_EXPORT
341 int syn123_query_waves( syn123_handle* sh, size_t *count
342 , int *id, double *freq, double *phase, int* backwards
343 , size_t *period );
344
345 /** Return the name of the indicated wave pattern.
346 * \param id The numerical ID of the wave pattern
347 * (out of enum syn123_wave_id).
348 * \return The name string, guaranteed to be non-NULL.
349 * Invalid codes yield the string "???".
350 */
351 MPG123_EXPORT
352 const char* syn123_wave_name(int id);
353
354 /** Return the wave pattern id given a name string.
355 * \param name The name string.
356 * \return The numerical id (out of enum syn123_wave_id).
357 *
358 */
359 MPG123_EXPORT
360 int syn123_wave_id(const char *name);
361
362 /** Types of frequency sweeps.
363 * There are no functions mapping those to/from strings,
364 * as this list is supposed to be fixed and small.
365 * There are only so many types of sweeps that make sense.
366 */
367 enum syn123_sweep_id
368 {
369 SYN123_SWEEP_LIN = 0 /**< linear frequency change */
370 , SYN123_SWEEP_QUAD /**< quadratic frequency change */
371 , SYN123_SWEEP_EXP /**< exponential (octave per time unit) */
372 , SYN123_SWEEP_LIMIT /**< valid IDs less than that */
373 };
374
375 /** Frequency sweep generator.
376 * This generates a sweep from one frequency to another with one
377 * of the available wave shapes over a given time.
378 * While you can just extract your single sweep by exactly reading
379 * the requestet duration, the generator is set up to run the sweep
380 * a bit longer until the beginning phase is reached again
381 * (one sample before that, of course). That way, reasonably smooth
382 * periodic playback from the buffer is possible without that nasty jump.
383 * Still, a large freqency difference will result in an audible pop,
384 * but at least that is not whole spectrum due to a phase jump.
385 * \param sh handle
386 * \param wave_id wave ID (enum syn123_wave_id)
387 * \param f1 pointer to beginning frequency in Hz (>= 1e-4, please,
388 * a value <= 0 being replaced by the standard frequency and stored for you)
389 * \param f2 ending frequency in Hz (>= 1e-4, please,
390 * in case of exponential sweep: f2-f1 >= 1e-4, too,
391 * a value <= 0 being replaced by the standard frequency and stored for you)
392 * \param sweep_id choice of sweep curve (enum syn123_sweep_id)
393 * \param smooth enable the periodic smoothing, if sensible
394 * (extending signal beyond the sweep to avoid phase jumps, a continuing
395 * starting at given start phase, not the returned endphase)
396 * \param duration duration of sweep in samples (> 1, please)
397 * This theoretically should be an off_t relating to the size of a
398 * file you produce, but off_t in API headers causes headaches.
399 * A 32 bit size_t still gives you over 24 hours of sweeping with 44100 kHz
400 * rate. On top of that, you can use the returned endphase to chop
401 * your monster sweep into pieces.
402 * \param phase initial phase of the sweep
403 * \param backwards invert the waveform in time if true
404 * \param endphase address to store the normal phase that would
405 * smoothly continue the signal without the period correction
406 * (You can create a following sweep that continues smoothly to a new
407 * target frequency by handing in this endphase as initial phase. Combine
408 * that with phases of constant tone and you could simulate a Theremin
409 * player by approximating the reaction to hand movements via sweeps.)
410 * \param period address to store the periodic sample count, usually
411 * being a bit bigger than the duration for getting the phase
412 * back down; does not imply use of the internal period buffer
413 * \param buffer_period address to store the period count only if the
414 * period buffer is actually in use
415 */
416 MPG123_EXPORT
417 int syn123_setup_sweep( syn123_handle* sh
418 , int wave_id, double phase, int backwards
419 , int sweep_id, double *f1, double *f2, int smooth, size_t duration
420 , double *endphase, size_t *period, size_t *buffer_period );
421
422 /** Set up pink noise generator.
423 * This employs the Gardner/McCartney method to the approximate
424 * the real thing. The number of rows in the tree pattern is tunable.
425 * The result is pink noise with around 2.5 dB/octave. Do not expect
426 * more than 32 bits of randomness (or anything;-).
427 * \param sh handle
428 * \param rows rows for the generator algorithm
429 * It maxes out at 30 rows. Below 1 chooses a default.
430 * \param seed a 32 bit seed value for the pseudo-random number generator
431 * \param period optional address to store the size of the enforced period
432 * (zero for endlessly freshly generated signal)
433 * \return success code
434 */
435 MPG123_EXPORT
436 int syn123_setup_pink( syn123_handle *sh, int rows, unsigned long seed
437 , size_t *period );
438
439 /** Set up white noise generator.
440 * A simple white noise source using some cheap pseudo RNG. Do not
441 * expect more than 32 bits of randomness (or anything;-).
442 * \param sh handle
443 * \param seed a 32 bit seed value for the pseudo-random number generator
444 * \param period optional address to store the size of the
445 * enforced period (zero for endlessly freshly generated signal)
446 */
447 MPG123_EXPORT
448 int syn123_setup_white(syn123_handle *sh, unsigned long seed, size_t *period);
449
450 /** Set up Geiger counter simulator.
451 * This models a speaker that is triggered by the pulses from
452 * the Geiger-Mueller counter. That creepy ticking sound.
453 * \param sh handle
454 * \param activity average events per second
455 * \param seed a 32 bit seed value for the pseudo-random number generator
456 * \param period optional address to store the size of the enforced period
457 * (zero for endlessly freshly generated signal)
458 * \return success code
459 */
460 MPG123_EXPORT
461 int syn123_setup_geiger( syn123_handle *sh, double activity
462 , unsigned long seed, size_t *period );
463
464 /** Set up silence.
465 * This goes back to the vanilla state.
466 * \return success code
467 */
468 MPG123_EXPORT
469 int syn123_setup_silence(syn123_handle *sh);
470
471 /** Convert between supported encodings.
472 * The buffers must not overlap.
473 * Note that syn123 converts -1.0 to -127 for 8 bit signed (and analogous for
474 * other encodings), but still clips asymmetrically at -128 as that is the
475 * range of the type. If you do explicit clipping using syn123_clip(),
476 * the resulting range will be symmetrical inside [-1.0:1.0] and hence
477 * only down to -127 for 8 bit signed encoding.
478 * The conversions only work directly either from anything to double/float or
479 * from double/float to anything. This process is wrapped in the routine if
480 * a handle is provided, using the fixed mixing buffer in that. Clipping
481 * is only handled for floating point to integer conversions. Also, NaN
482 * is set to zero on conversion and counted as clipped.
483 * The ulaw and alaw conversions use Sun's reference implementation of the
484 * G711 standard (differing from libmpg123's big lookup table).
485 *
486 * \param dst destination buffer
487 * \param dst_enc destination encoding (enum mpg123_enc_enum)
488 * \param dst_size size of destination buffer in bytes
489 * \param src source buffer
490 * \param src_enc source encoding
491 * \param src_bytes source buffer size in bytes
492 * \param dst_bytes optional address to store the written byte count to
493 * \param clipped optional address to store number of clipped samples to
494 * \param sh an optional syn123_handle which enables arbitrary encoding
495 * conversions by utilizing the contained buffer as intermediate storage,
496 * can be NULL, disabling any conversion not involving floating point
497 * input or output
498 * \return success code
499 */
500 MPG123_EXPORT
501 int syn123_conv( void * MPG123_RESTRICT dst, int dst_enc, size_t dst_size
502 , void * MPG123_RESTRICT src, int src_enc, size_t src_bytes
503 , size_t *dst_bytes, size_t *clipped, syn123_handle * sh );
504
505 /** The range of decibel values handled by syn123 goes from
506 * -SYN123_DB_LIMIT to +SYN123_DB_LIMIT
507 * This value ensures that a resulting linear volume can still
508 * be expressed using single-precision float.
509 * The resulting amplitude from -500 dB is still small enough
510 * to drive a 32 bit integer sample value orders of magnitude below
511 * 1, so it is effectively a zero. Note that physical volume controls
512 * typically give a range as small as 60 dB. You might want to present
513 * a tighter range to the user than +/- 500 dB!
514 */
515 #define SYN123_DB_LIMIT 500
516
517 /** Convert decibels to linear volume (amplitude factor).
518 * This just returns pow(10, db/20) in the supported range.
519 * The dB value is limited according to SYN123_DB_LIMIT, with
520 * NaN being put at the lower end of the range. Better silent
521 * than insanely loud.
522 * \param db relative volume in dB
523 * \return linear volume factor
524 */
525 MPG123_EXPORT double syn123_db2lin(double db);
526
527 /** Convert linear volume (amplitude factor) to decibels.
528 * This just returns 20*log10(volume) in the supported range.
529 * The returned value is limited according to SYN123_DB_LIMIT, with
530 * NaN being put at the lower end of the range. Better silent
531 * than insanely loud.
532 * \param volume linear volume factor
533 * \return relative volume in dB
534 */
535 MPG123_EXPORT double syn123_lin2db(double volume);
536
537 /** Amplify given buffer.
538 * This multiplies all samples by the given floating point value
539 * (possibly converting to/from floating point on the fly, if a
540 * handle with the included working buffer is given).
541 * Also an offset correction is provided.
542 *
543 * \param buf the buffer to work on
544 * \param encoding the sample encoding
545 * \param samples number of samples
546 * \param volume linear volume factor (use syn123_db2lin() for
547 * applying a change in dB)
548 * \param offset offset to add to the sample values before
549 * multiplication
550 * \param clipped optional address to store number of clipped samples to
551 * \param sh optional handle to enable work on non-float
552 * encodings
553 * \return success code (e.g. bad encoding without handle)
554 */
555 MPG123_EXPORT
556 int syn123_amp( void* buf, int encoding, size_t samples
557 , double volume, double offset, size_t *clipped, syn123_handle *sh );
558
559 /** Clip samples in buffer to default range.
560 * This only does anything with floating point encoding, but you can always
561 * call it without damage as a no-op on other encodings. After this, the
562 * samples are guaranteed to be in the range [-1,+1]. NaNs are mapped
563 * to zero (and counted as clipped), so they will still sound bad.
564 * If you want to hard clip to a smaller range, use syn123_soft_clip() with
565 * a width of zero.
566 * \param buf buffer to work on
567 * \param encoding sample encoding
568 * \param samples total number of samples
569 * \return number of clipped samples
570 */
571 MPG123_EXPORT
572 size_t syn123_clip(void *buf, int encoding, size_t samples);
573
574 /** Soft clipping / cheap limiting.
575 * This limits the samples above the threshold of limit-width with a
576 * smooth curve, dampening the high-frequency content of the clipping.
577 * This is no proper frequency filter, but just an independent function on
578 * each sample value, also ignorant of the channel count. This can
579 * directly work on float encodings and does nothing on others unless
580 * a handle is provided for on-line conversion.
581 * \param buf buffer to work on
582 * \param encoding sample encoding
583 * \param samples total number of samples
584 * \param limit the limit to clip to (normally 1 for full scale)
585 * \param width smoothing range
586 * \param sh optional handle to work on non-float encodings
587 * \return number of clipped samples
588 */
589 MPG123_EXPORT
590 size_t syn123_soft_clip( void *buf, int encoding, size_t samples
591 , double limit, double width, syn123_handle *sh );
592
593 /** Interleave given number of channels into one stream.
594 * A rather trivial functionality, here for completeness. As the
595 * algorithm is agnostic to what is actually stored as a "sample",
596 * the parameter types are so generic that you could use these
597 * functions to arrange huge structs (hence samplesize as size_t)
598 * or whatever. If that makes sense is up to you.
599 * The buffers shall not overlap!
600 * \param dst destination buffer
601 * \param src source buffer array (one per channel)
602 * \param channels channel count
603 * \param samplesize size of one sample
604 * \param samplecount count of samples per channel
605 */
606 MPG123_EXPORT
607 void syn123_interleave( void * MPG123_RESTRICT dst, void** MPG123_RESTRICT src
608 , int channels, size_t samplesize, size_t samplecount );
609
610 /** Deinterleave given number of channels out of one stream.
611 * A rather trivial functionality, here for completeness. As the
612 * algorithm is agnostic to what is actually stored as a "sample",
613 * the parameter types are so generic that you could use these
614 * functions to arrange huge structs (hence samplesize as size_t)
615 * or whatever. If that makes sense is up to you.
616 * The buffers must not overlap!
617 * \param dst destination buffer array (one per channel)
618 * \param src source buffer
619 * \param channels channel count
620 * \param samplesize size of one sample (see MPG123_SAMPLESIZE)
621 * \param samplecount count of samples per channel
622 */
623 MPG123_EXPORT
624 void syn123_deinterleave( void ** MPG123_RESTRICT dst, void * MPG123_RESTRICT src
625 , int channels, size_t samplesize, size_t samplecount );
626
627 /** Simply copies mono samples into an interleaved stream.
628 * This might be implemented by a call to syn123_interleave(), it might
629 * be optimized to something different. You could have fun measuring that.
630 * \param dst destination buffer
631 * \param src source buffer
632 * \param channels channel count
633 * \param samplesize size of one sample (see MPG123_SAMPLESIZE)
634 * \param samplecount count of samples per channel
635 */
636 MPG123_EXPORT
637 void syn123_mono2many( void * MPG123_RESTRICT dst, void * MPG123_RESTRICT src
638 , int channels, size_t samplesize, size_t samplecount );
639
640 /** A little helper/reminder on how interleaved format works:
641 * Produce the offset of the given sample for the given channel.
642 */
643 #define SYN123_IOFF(sample, channel, channels) ((sample)*(channels)+(channel))
644
645 /** Specify floating point encoding to use for preserving precision in
646 * intermediate computations for given source and destination encoding.
647 * This should return either MPG123_ENC_FLOAT_32 or MPG123_ENC_FLOAT_64,
648 * unless an uncertain future adds things like 16 bit fp ...
649 * This is what syn123_conv() and syn123_mix() will use internally if
650 * intermediate conversion is necessary.
651 * Note that 64 bit floating point material will be mixed in 32 bit if the
652 * destination encoding does not need more precision.
653 * \param src_enc source/input encoding
654 * \param dst_enc destination/output encoding
655 * \return encoding value, zero if none can be chosen (invalid parameters)
656 */
657 MPG123_EXPORT
658 int syn123_mixenc(int src_enc, int dst_enc);
659
660 /** Mix n input channels on top of m output channels.
661 * This takes an interleaved input stream and mixes its channels
662 * into the output stream given a channel matrix (m,n) where
663 * each of the m rows contains the n volume factors (weights)
664 * to apply when summing the samples from the n input channels.
665 * Sample values are added to what is already present unless
666 * initial silence is explicitly requested.
667 * This works directly with identical floating point encodings. It
668 * may have some optimization to work faster with mono or stereo on
669 * either side and slower generic code for arbitrary channel counts.
670 * You can use syn123_conv() to convert from/to input/output encodings
671 * or provide a syn123_handle to do it on the fly.
672 * There are no optimizations for special cases of mixing factors, so
673 * you should always be able to predict the number of floating point
674 * operations being executed.
675 * For fun, you could give the same problem to a BLAS implementation
676 * of your choice and compare the performance;-)
677 * \param dst destination buffer
678 * \param dst_enc output sample encoding, must be MPG123_ENC_FLOAT_32 or
679 * MPG123_ENC_FLOAT_64 unless a syn123_handle is provided
680 * \param dst_channels destination channel count (m)
681 * \param src source buffer
682 * \param src_enc input sample encoding, must be MPG123_ENC_FLOAT_32 or
683 * MPG123_ENC_FLOAT_64 unless a syn123_handle is provided
684 * \param src_channels source channel count (n)
685 * \param mixmatrix mixing factors ((m,n) matrix), same encoding as
686 * the audio data
687 * \param samples count of samples (PCM frames) to work on
688 * \param silence Set to non-zero value to intialize the output
689 * to a silent signal before adding the input.
690 * \param clipped optional address to store number of clipped samples to
691 * (in case of mixing to an integer encoding)
692 * \param sh an optional syn123_handle which enables work on non-float
693 * encodings by utilizing the contained buffer as intermediate storage,
694 * converting to/from float transparently; Note that this may limit
695 * the amount of channels depending on the fixed internal buffer space.
696 * As long as you have up to 128 channels, you should not worry.
697 * \return success code (e.g. bad encoding, channel counts ...)
698 */
699 MPG123_EXPORT
700 int syn123_mix( void * MPG123_RESTRICT dst, int dst_enc, int dst_channels
701 , void * MPG123_RESTRICT src, int src_enc, int src_channels
702 , const double * mixmatrix
703 , size_t samples, int silence, size_t *clipped, syn123_handle *sh );
704
705 /** Set up a generic digital filter.
706 *
707 * This takes a filter order N and coefficient set to prepare
708 * the internal state of a digital filter defined by the transfer
709 * function
710 * \f[
711 *
712 * H(z) = \frac
713 * {b_0 + b_1 z^{-1} + ... + b_N z^{-N}}
714 * {1 + a_1 z^{-1} + ... + a_N z^{-N}}
715 * \f]
716 * It is your task to come up with fun values for the coefficients
717 * b_n and a_n to implement various FIR and IIR filters.
718 *
719 * Since it is easy to do and useful, this configures not only a single
720 * filter but a chain of them. If you do configure a chain, the choice
721 * of mixenc and channels must match. No conversion between filters.
722 *
723 * \param sh mandatory handle
724 * \param append if true, append a filter to the chain, fresh chain otherwise
725 * \param order filter order N (filter length minus one)
726 * \param b nominator coefficients, starting with b_0 (order+1 elements)
727 * \param a denominator coefficients, starting with a_0=1 (order+1 elements).
728 * It is an error to provide a sequence that does not start with 1.
729 * For a non-recursive (FIR) filter, you can set all following
730 * values from a_1 on to zero or choose to provide a NULL pointer.
731 * \param mixenc either MPG123_ENC_FLOAT_32 or MPG123_ENC_FLOAT_64 for
732 * computation in single or double precision, can be zero to refer to
733 * the value demanded by an already present filter
734 * \param channels number of channels in the audio signal, can be zero
735 * to refer to the value demanded by an already present filter
736 * \param init_firstval If non-zero, initialize the filter history with
737 * a constant stream of the first encountered sample instead of zero.
738 * \return success code
739 */
740 MPG123_EXPORT
741 int syn123_setup_filter( syn123_handle *sh
742 , int append, unsigned int order, double *b, double *a
743 , int mixenc, int channels, int init_firstval );
744
745 /** init_firstval is the effective setting (extreme coefficients may remove the distinction) */
746
747 MPG123_EXPORT
748 int syn123_query_filter( syn123_handle *sh, size_t position
749 , size_t *count, unsigned int *order, double *b, double *a
750 , int *mixenc, int *channels, int *init_firstval );
751
752 /** drop the n last filters */
753 MPG123_EXPORT
754 void syn123_drop_filter(syn123_handle *sh, size_t count);
755
756 /** Apply a prepared digital filter.
757 *
758 * This applies the filter prepared by syn123_setup_filter to yur
759 * provided buffer in single or double precision float.
760 * Handing in a non-float encoding is an error. You are supposed
761 * to convert and clip before/after applying the filters.
762 *
763 * If you got no filters configured, this always succeeds and
764 * does nothing.
765 *
766 * \param sh handle
767 * \param buf audio data to work on (channel count matching what
768 * was given to mpg123_setup_filter())
769 * \param encoding audio encoding
770 * \param samples count of samples (PCM frames) in the buffer
771 * \return success code
772 */
773 MPG123_EXPORT
774 int syn123_filter( syn123_handle *sh
775 , void* buf, int encoding, size_t samples );
776
777 /** Set up the resampler.
778 *
779 * This works independently of the signal generators. You can combine
780 * syn123_setup_resample() with syn123_setup_geiger(), for example.
781 *
782 * People can get worked up a lot about differing algorithms for resampling,
783 * while many folks can actually bear the simple drop/repeat method and most
784 * probably do not bother about the distortions from linear resampling.
785 * A testament to this is that in the 18 years of me maintaining mpg123, I
786 * got bugged about the missing dithering and on subtle bias in shuffling
787 * a playlist, but people seem to insist on using the NtoM resampoler inside
788 * libmpg123, despite me warning about its horrible consequences for audio
789 * quality. It is a plain drop-sample implementation. The only good things to
790 * say about it is that it is cheap and is embedded with the sample-accurate
791 * decoder so that you do not have to worry about offsets in terms of input
792 * and output samples.
793 *
794 * Anyhow, this is my take on a reasonably good and efficient resampler that is
795 * neither the best-sounding, nor the fastest in terms of CPU time, but gets
796 * by without significant latency. It needs far less computation than usual
797 * high-quality windowed-sinc resampling (libsamplerate), but cannot beat
798 * libsoxr with its FFT-based approach. The less stringent dirty mode (using
799 * only a 72 dB lowpass filter, in practice still close to CD-DA quality)
800 * comes quite close, though.
801 *
802 * The selling point is that it produces output samples as soon as you start
803 * feeding, without any buffering of future samples to fill a window for the
804 * FIR filter or the Fourier transform. It employs IIR filters for low-passing,
805 * possibly in multiple stages for decimation, and optimized interpolation
806 * formulas using up to 6 points. These formulas, based on research by
807 * Olli Niemitalo using using Differential Evolution, are what enables a
808 * dynamic range of 108 dB, well above 16 bit CD-DA quality. Simple
809 * cubic splines after low-passing distort up to around -40 dB in my tests.
810 *
811 * There is some effective signal delay well below 10 samples. The impulse
812 * response is about 3 samples late, so this is well inside the realm of
813 * (nonlinear) phase shift. The phase distortion looks bad on paper but does
814 * not matter much in the intended domain of application: the final change in
815 * sampling rate before playback on audio hardware, the last filter that is
816 * applied before the sound hits the speakers (or all the other filters
817 * implemented in your audio harware, that you can choose to be ignorant
818 * about). Use better resamplers for mixing in the studio. Use better
819 * resamplers for converting files on disk. For live playback, consider this
820 * one because it is good enough, fast enough, cheap enough.
821 *
822 * Note that if you call this function repeatedly, the internal history
823 * is only cleared if you change anything besides the sampling rates. If
824 * only the rates change, the state of the resampler is kept to enable
825 * you to continue on prior data. This means you can vary the resampling
826 * ratio during operation, somewhat smoothly depending on your buffer size.
827 *
828 * Also note that even on identical input and output rates, the resampler
829 * will apply the full filtering as for any ratio close to that, including
830 * oversampling. No special shortcuts.
831 *
832 * A returned error guarantees that the internal resampler setup has
833 * been cleared (frees a little bit of memory). You can provide zero
834 * inrate, outrate, and channel count at the same time to that effect
835 * without an error message being produced (but still SYN123_BAD_FMT
836 * being returned).
837 *
838 * \param sh mandatory handle
839 * \param inrate input sample rate (nominator of ratio)
840 * \param outrate output sample rate (denominator of ratio)
841 * \param channels number of interleaved channels
842 * \param dirty Enable (!= 0) the dirty mode for even more 'good enough'
843 * resampling with less computing time. Offers -72 dB low pass attentuation,
844 * worst-case distortion around that, too, and 85% worst-case bandwidth.
845 * With this set to zero, the normal mode is used, offering at least 108 dB
846 * dynamic range and worst-case bandwidth above 84%.
847 * \param smooth Enable (!=0) extra code smoothing the resampler response to
848 * on-the-fly changes of sampling rate ratio. This involves keeping
849 * some per-stage history to bootstrap additional decimation filters and the
850 * changed final lowpass/interpolation.
851 * \return success code
852 */
853 MPG123_EXPORT
854 int syn123_setup_resample( syn123_handle *sh, long inrate, long outrate
855 , int channels, int dirty, int smooth );
856
857 /** Return the maximum allowed value for sample rates given to the resampler.
858 *
859 * Not every possible value of the underlying data type is a valid sample
860 * rate for the resampler. It needs some headroom for computations. This
861 * function returns the maximal rate you can specify. For 32-bit long, this
862 * will be above 1e9, for 64-bit long above 4e18. The minimum is 1, of course.
863 * So, with 32 bit, you can speed up/down by a factor of one million if you
864 * want to keep 0.1% precision in the rates.
865 *
866 * \return upper sample rate limit
867 */
868 MPG123_EXPORT
869 long syn123_resample_maxrate(void);
870
871 /** Give upper limit for output sample count from the resampler.
872 *
873 * Since there is some rounding involved, the exact number of output samples
874 * from the resampler, being given a certain amount of input samples, can
875 * vary (one more or less than expected). This function is here to give you
876 * a safe output buffer size given a certain input buffer size. If you intend
877 * to vary the output rate for a fixed input rate, you may compute the output
878 * buffer size for the largest intended output rate and use that throughout.
879 * The same applies to the input sample count.
880 * A return value of zero indicates an error (zero, negative, or too large
881 * rate given) unless the given input sample count is also zero.
882 * The resampler only produces output when given new input.
883 * \param inrate input sample rate
884 * \param outrate output sample rate
885 * \param ins input sample count for one buffer
886 * \return number of maximum output samples for one buffer, or zero
887 * if no sensible value exists
888 */
889 MPG123_EXPORT
890 size_t syn123_resample_count(long inrate, long outrate, size_t ins);
891
892 /** Return the amount of input samples needed to recreate resample filter state.
893 *
894 * This returns a number of input samples that should fill the internal
895 * filter states good enough for output being close to that produced from
896 * the full input since the beginning. Since recursive filters are employed,
897 * there is no exact number that recreates a state apart from the full sequence
898 * that created it the first time. This number here shall be more than the
899 * non-recursive history, but not by a huge factor. For extreme cases, this
900 * value may be saturated at SIZE_MAX and thus smaller than what is demanded
901 * by the above definition. It is assumed that you define a maximal practical
902 * size of history to consider for your application, anyway.
903 *
904 * \param inrate input sample rate
905 * \param outrate output sample rate
906 * \param dirty switch for dirty resampling mode (see syn123_setup_resample())
907 * \return number of input samples to fill history, zero on error
908 */
909 MPG123_EXPORT
910 size_t syn123_resample_history(long inrate, long outrate, int dirty);
911
912 /** Compute the minimal input sample count needed for given output sample count.
913 *
914 * The reverse of syn123_resample_count(), in a way. This gives you the
915 * minimum amount of input samples to guarantee at least the desired amount
916 * of output samples. Once you got that, ensure to call syn123_resample_count()
917 * to get a safe buffer size for that amount of input and prepare accordingly.
918 * With this approach, you can ensure that you get your realtime output device
919 * buffer filled with each loop run fetching a bit of input, at the expense
920 * of handling some additional buffering for the returned sample counts above
921 * the minimum.
922 *
923 * \param input_rate input sample rate
924 * \param output_rate output sample rate
925 * \param outs desired minimal output sample count for one input buffer
926 * \return number of minimal input samples in one buffer, or zero if no
927 * sensible value exists (invalid input parameters, or zero outs)
928 */
929 MPG123_EXPORT
930 size_t syn123_resample_incount(long input_rate, long output_rate, size_t outs);
931
932 /** Compute the input sample count needed for close to given output sample
933 * count, but never more.
934 *
935 * Call this to get a safe fixed count of input samples to make best use
936 * of a preallocated output buffer, filling it as much as safely possible.
937 * This can also be achieved by calling syn123_resample_incount() and reducing
938 * the value until syn123_resample_count() fits into your buffer.
939 *
940 * \param input_rate input sample rate
941 * \param output_rate output sample rate
942 * \param outs desired output sample count for one input buffer
943 * \return number of input samples in one buffer, or zero if no
944 * sensible value exists (invalid input parameters, or zero outs)
945 */
946 MPG123_EXPORT
947 size_t syn123_resample_fillcount(long input_rate, long output_rate, size_t outs);
948
949
950 /** Compute the maximum number of input samples for a resampling buffer.
951 *
952 * Upsampling means that you will get more output samples than input samples.
953 * This larger number still needs to fit into the data type for sample
954 * counts. So please don't feed more than the value returned here.
955 *
956 * \param input_rate input sample rate
957 * \param output_rate output sample rate
958 * \return maximum safe input sample count
959 */
960 MPG123_EXPORT
961 size_t syn123_resample_maxincount(long input_rate, long output_rate);
962
963 /** Give exact output sample count for feeding given input now.
964 *
965 * This gives you the exact number of samples you will get returned
966 * when feeding the resampler the given additional input samples now,
967 * given the current resampler state contained in the handle.
968 *
969 * On error, zero is returned and the error code is set to a nonzero
970 * syn123 error code.
971 *
972 * \param sh syn123 handle
973 * \param ins input sample count
974 * \param err location to store error code
975 * \return output sample count
976 */
977 MPG123_EXPORT
978 size_t syn123_resample_out(syn123_handle *sh, size_t ins, int *err);
979
980 /** Give minimum input sample count needed now for given output.
981 *
982 * This give you the minimal number of input samples needed right
983 * now to yield at least the specified amount of output samples.
984 * Since one input sample can result in several output sampels in one
985 * go, you have to check using syn123_resample_out() how many
986 * output samples to really expect.
987 *
988 * On error, zero is returned and the error code is set to a nonzero
989 * syn123 error code.
990 *
991 * \param sh syn123 handle
992 * \param outs output sample count
993 * \param err location to store error code
994 * \return minimal input sample count
995 */
996 MPG123_EXPORT
997 size_t syn123_resample_in(syn123_handle *sh, size_t outs, int *err);
998
999 /** Give exact output sample count for total input sample count.
1000 *
1001 * Use this to determine the total length of your output stream
1002 * given the length of the input stream. The computation is exact.
1003 * But: It is only valid for a constant sampling rate ratio. If you
1004 * play with that during runtime, you need to figure out your output
1005 * offset yourself.
1006 *
1007 * \param inrate input sample rate
1008 * \param outrate output sample rate
1009 * \param ins input sample count for the whole stream
1010 * \return number of output samples or -1 if the computation fails
1011 * (bad/too large sampling rates, integer overflow)
1012 */
1013 MPG123_EXPORT
1014 int64_t syn123_resample_total64(long inrate, long outrate, int64_t ins);
1015
1016 /** Give minimum input sample count for total output sample count.
1017 *
1018 * You need to feed at least that amount of input samples to get
1019 * the desired amount of output samples from the resampler. Depending
1020 * on the resampling ratio, you may in fact get more than the desired
1021 * amount (one input sample being worth multiple output samples during
1022 * upsampling) so make sure to call syn123_resample_total() to get
1023 * the exact number of samples you need to prepare for.
1024 * Again, the output offset is only meaninful for a constant sampling
1025 * rate ratio.
1026 *
1027 * \param inrate input sample rate
1028 * \param outrate output sample rate
1029 * \param outs output sample count for the whole stream
1030 * \return number of input samples or -1 if the computation fails
1031 * (bad/too large sampling rates, integer overflow)
1032 */
1033 MPG123_EXPORT
1034 int64_t syn123_resample_intotal64(long inrate, long outrate, int64_t outs);
1035
1036 /** Resample input buffer to output buffer.
1037 *
1038 * This executes the resampling configured by syn123_setup_resample(). The
1039 * input and output encoding is fixed at single-precision float
1040 * (MPG123_ENC_FLOAT_32) and multiple channels are interleaved. There
1041 * is no implicit conversion of other encodings since the fixed internal
1042 * buffers for that may not fit your chosen extreme resampling ratios. Also,
1043 * dealing with double precision does not make sense with the mathematical
1044 * limitations of the employed filters.
1045 *
1046 * You are responsible for having your buffers prepared with the correct sizes.
1047 * Use syn123_resample_count() to ensure that you are prepared for the correct
1048 * number of output samples given your input sample count.
1049 *
1050 * Also, ensuring a minimal number of input samples using
1051 * syn123_resample_incount() helps to identify an error situation where zero
1052 * samples are returned (which would be valid for low input sample count).
1053 * The only error apart from handing in an invalid/unprepared handle is
1054 * a too large number of input samples. Check syn123_resample_maxincount().
1055 *
1056 * \param sh handle with prepared resampling method
1057 * If this is NULL or if the resampler has not been initialized before, the
1058 * function returns zero instead of crashing randomly.
1059 * \param dst destination buffer
1060 * \param src source buffer
1061 * \param samples input samples (PCM frames) in source buffer
1062 * \return number of output samples (PCM frames)
1063 */
1064 MPG123_EXPORT
1065 size_t syn123_resample( syn123_handle *sh,
1066 float * MPG123_RESTRICT dst, float * MPG123_RESTRICT src, size_t samples );
1067
1068 /** Swap byte order between little/big endian.
1069 * \param buf buffer to work on
1070 * \param samplesize size of one sample (see MPG123_SAMPLESIZE)
1071 * \param samplecount count of samples
1072 */
1073 MPG123_EXPORT
1074 void syn123_swap_bytes(void* buf, size_t samplesize, size_t samplecount);
1075
1076 /* Wrappers over the above to convert to/from syn123's native byte order
1077 from/to little or big endian. */
1078
1079 /** Convert from host order to little endian.
1080 * \param buf buffer to work on
1081 * \param samplesize size of one sample (see MPG123_SAMPLESIZE)
1082 * \param samplecount count of samples
1083 */
1084 MPG123_EXPORT
1085 void syn123_host2le(void *buf, size_t samplesize, size_t samplecount);
1086
1087 /** Convert from host order to big endian.
1088 * \param buf buffer to work on
1089 * \param samplesize size of one sample (see MPG123_SAMPLESIZE)
1090 * \param samplecount count of samples
1091 */
1092 MPG123_EXPORT
1093 void syn123_host2be(void *buf, size_t samplesize, size_t samplecount);
1094
1095 /** Convert from little endian to host order.
1096 * \param buf buffer to work on
1097 * \param samplesize size of one sample (see MPG123_SAMPLESIZE)
1098 * \param samplecount count of samples
1099 */
1100 MPG123_EXPORT
1101 void syn123_le2host(void *buf, size_t samplesize, size_t samplecount);
1102
1103 /** Convert from big endian to host order.
1104 * \param buf buffer to work on
1105 * \param samplesize size of one sample (see MPG123_SAMPLESIZE)
1106 * \param samplecount count of samples
1107 */
1108 MPG123_EXPORT
1109 void syn123_be2host(void *buf, size_t samplesize, size_t samplecount);
1110
1111 // You are invited to defined SYN123_PORTABLE_API to avoid seeing shape-shifting off_t
1112 // anywhere, also to avoid using non-standard types like ssize_t.
1113 #if !defined(SYN123_PORTABLE_API) && !defined(SYN123_NO_LARGEFUNC)
1114
1115 /** A little hack to help MSVC not having ssize_t, duplicated in internal header. */
1116 #ifdef _MSC_VER
1117 #include <stddef.h>
1118 typedef ptrdiff_t syn123_ssize_t;
1119 #else
1120 typedef ssize_t syn123_ssize_t;
1121 #endif
1122
1123 /** Give exact output sample count for feeding given input now.
1124 *
1125 * Old variant of syn123_resample_out() that (ab)uses ssize_t.
1126 *
1127 * \deprecated Use syn123_resample_out() instead.
1128 * The return of errors (integer overflow in
1129 * calculation)is broken, as both the error codes and the valid results
1130 * are positive integers. I screwed up.
1131 *
1132 * \param sh syn123 handle
1133 * \param ins input sample count
1134 * \return output sample count or error code, hard to distinguish
1135 */
1136 MPG123_EXPORT
1137 syn123_ssize_t syn123_resample_expect(syn123_handle *sh, size_t ins);
1138
1139 /** Give minimum input sample count needed now for given output.
1140 *
1141 * Old variant of syn123_resample_in() that (ab)uses ssize_t.
1142 *
1143 * \deprecated Use syn123_resample_in() instead.
1144 * The return of errors (integer overflow in
1145 * calculation)is broken, as both the error codes and the valid results
1146 * are positive integers. I screwed up.
1147 *
1148 * \param sh syn123 handle
1149 * \param outs output sample count
1150 * \return minimal input sample count or error code, hard to distinguish
1151 */
1152 MPG123_EXPORT
1153 syn123_ssize_t syn123_resample_inexpect(syn123_handle *sh, size_t outs);
1154
1155 /* Lightweight large file hackery to enable worry-reduced use of off_t.
1156 Depending on the size of off_t in your client build, the corresponding
1157 library function needs to be chosen. */
1158
1159 #if defined(_FILE_OFFSET_BITS) && !defined(MPG123_NO_LARGENAME)
1160 # if _FILE_OFFSET_BITS+0 == 32
1161 # define syn123_resample_total syn123_resample_total_32
1162 # define syn123_resample_intotal syn123_resample_intotal_32
1163 # elif _FILE_OFFSET_BITS+0 == 64
1164 # define syn123_resample_total syn123_resample_total_64
1165 # define syn123_resample_intotal syn123_resample_intotal_64
1166 # else
1167 # error "Unpredicted _FILE_OFFSET_BITS value."
1168 # endif
1169 #endif
1170
1171 /** Give exact output sample count for total input sample count.
1172 *
1173 * This is syn123_resample_total64() with shape-shifting off_t,
1174 * possibly renamed by macro. For type safety, use the former.
1175 *
1176 * \deprecated Use syn123_resample_total64() instead.
1177 *
1178 * \param inrate input sample rate
1179 * \param outrate output sample rate
1180 * \param ins input sample count for the whole stream
1181 * \return number of output samples or -1 if the computation fails
1182 * (bad/too large sampling rates, integer overflow)
1183 */
1184 MPG123_EXPORT
1185 off_t syn123_resample_total(long inrate, long outrate, off_t ins);
1186
1187 /** Give minimum input sample count for total output sample count.
1188 *
1189 * This is syn123_resample_intotal64() with shape-shifting off_t,
1190 * possibly renamed by macro. For type safety, use the former.
1191 *
1192 * \deprecated Use syn123_resample_intotal64() instead.
1193 *
1194 * \param inrate input sample rate
1195 * \param outrate output sample rate
1196 * \param outs output sample count for the whole stream
1197 * \return number of input samples or -1 if the computation fails
1198 * (bad/too large sampling rates, integer overflow)
1199 */
1200 MPG123_EXPORT
1201 off_t syn123_resample_intotal(long inrate, long outrate, off_t outs);
1202
1203 #endif
1204
1205 /** @} */
1206
1207 #ifdef __cplusplus
1208 }
1209 #endif
1210
1211 #endif