| 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 |