# API documentation for libmpg123, libout123, and libsyn123

Note: This API doc is automatically generated from the current development version that you can get via Subversion or as a daily snapshot from http://mpg123.org/snapshot. There may be differences (additions) compared to the latest stable release. See NEWS.libmpg123, NEWS.libout123, NEWS.libsyn123, and the overall NEWS file on libmpg123 versions and important changes between them.
Let me emphasize that the policy for the lib*123 family is to always stay backwards compatible -- only additions are planned (and it's not yet planned to change the plans;-).
syn123.h
Go to the documentation of this file.
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
19 /* Common audio encoding specification. */
20 #include "fmt123.h"
21
26 #define SYN123_API_VERSION 2
27
28 #define SYN123_PATCHLEVEL 3
29
30 #ifndef MPG123_EXPORT
31
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
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
148 struct syn123_struct;
150 typedef struct syn123_struct syn123_handle;
151
159 MPG123_EXPORT
160 const char *syn123_distversion(unsigned int *major, unsigned int *minor, unsigned int *patch);
161
166 MPG123_EXPORT
167 unsigned int syn123_libversion(unsigned int *patch);
168
173 enum syn123_error
174 {
175 SYN123_OK = 0
176 , SYN123_BAD_HANDLE
177 , SYN123_BAD_FMT
178 , SYN123_BAD_ENC
179 , SYN123_BAD_CONV
180 , SYN123_BAD_SIZE
181 , SYN123_BAD_BUF
182 , SYN123_BAD_CHOP
183 , SYN123_DOOM
184 , SYN123_WEIRD
185 , SYN123_BAD_FREQ
186 , SYN123_BAD_SWEEP
187 , SYN123_OVERFLOW
188 , SYN123_NO_DATA
189 , SYN123_BAD_DATA
190 };
191
196 const char* syn123_strerror(int errcode);
197
211 MPG123_EXPORT
212 syn123_handle* syn123_new( long rate, int channels, int encoding
213 , size_t maxbuf, int *err );
214
218 MPG123_EXPORT
219 void syn123_del(syn123_handle *sh);
220
237 MPG123_EXPORT
238 int syn123_dither(syn123_handle *sh, int dither, unsigned long *seed);
239
247 MPG123_EXPORT
248 size_t syn123_read(syn123_handle *sh, void *dst, size_t dst_bytes);
249
251 enum syn123_wave_id
252 {
253 SYN123_WAVE_INVALID = -1
254 , SYN123_WAVE_FLAT = 0
255 , SYN123_WAVE_SINE
256 , SYN123_WAVE_SQUARE
257 , SYN123_WAVE_TRIANGLE
258 , SYN123_WAVE_SAWTOOTH
259 , SYN123_WAVE_GAUSS
260 , SYN123_WAVE_PULSE
261 , SYN123_WAVE_SHOT
263 , SYN123_WAVE_LIMIT
265 };
266
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
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
351 MPG123_EXPORT
352 const char* syn123_wave_name(int id);
353
359 MPG123_EXPORT
360 int syn123_wave_id(const char *name);
361
367 enum syn123_sweep_id
368 {
369 SYN123_SWEEP_LIN = 0
370 , SYN123_SWEEP_QUAD
371 , SYN123_SWEEP_EXP
372 , SYN123_SWEEP_LIMIT
373 };
374
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
435 MPG123_EXPORT
436 int syn123_setup_pink( syn123_handle *sh, int rows, unsigned long seed
437 , size_t *period );
438
447 MPG123_EXPORT
448 int syn123_setup_white(syn123_handle *sh, unsigned long seed, size_t *period);
449
460 MPG123_EXPORT
461 int syn123_setup_geiger( syn123_handle *sh, double activity
462 , unsigned long seed, size_t *period );
463
468 MPG123_EXPORT
469 int syn123_setup_silence(syn123_handle *sh);
470
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
515 #define SYN123_DB_LIMIT 500
516
525 MPG123_EXPORT double syn123_db2lin(double db);
526
535 MPG123_EXPORT double syn123_lin2db(double volume);
536
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
571 MPG123_EXPORT
572 size_t syn123_clip(void *buf, int encoding, size_t samples);
573
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
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
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
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
643 #define SYN123_IOFF(sample, channel, channels) ((sample)*(channels)+(channel))
644
657 MPG123_EXPORT
658 int syn123_mixenc(int src_enc, int dst_enc);
659
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
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
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
753 MPG123_EXPORT
754 void syn123_drop_filter(syn123_handle *sh, size_t count);
755
773 MPG123_EXPORT
774 int syn123_filter( syn123_handle *sh
775 , void* buf, int encoding, size_t samples );
776
853 MPG123_EXPORT
854 int syn123_setup_resample( syn123_handle *sh, long inrate, long outrate
855 , int channels, int dirty, int smooth );
856
868 MPG123_EXPORT
869 long syn123_resample_maxrate(void);
870
889 MPG123_EXPORT
890 size_t syn123_resample_count(long inrate, long outrate, size_t ins);
891
909 MPG123_EXPORT
910 size_t syn123_resample_history(long inrate, long outrate, int dirty);
911
929 MPG123_EXPORT
930 size_t syn123_resample_incount(long input_rate, long output_rate, size_t outs);
931
946 MPG123_EXPORT
947 size_t syn123_resample_fillcount(long input_rate, long output_rate, size_t outs);
948
949
960 MPG123_EXPORT
961 size_t syn123_resample_maxincount(long input_rate, long output_rate);
962
977 MPG123_EXPORT
978 size_t syn123_resample_out(syn123_handle *sh, size_t ins, int *err);
979
996 MPG123_EXPORT
997 size_t syn123_resample_in(syn123_handle *sh, size_t outs, int *err);
998
1013 MPG123_EXPORT
1014 int64_t syn123_resample_total64(long inrate, long outrate, int64_t ins);
1015
1033 MPG123_EXPORT
1034 int64_t syn123_resample_intotal64(long inrate, long outrate, int64_t outs);
1035
1064 MPG123_EXPORT
1065 size_t syn123_resample( syn123_handle *sh,
1066 float * MPG123_RESTRICT dst, float * MPG123_RESTRICT src, size_t samples );
1067
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
1084 MPG123_EXPORT
1085 void syn123_host2le(void *buf, size_t samplesize, size_t samplecount);
1086
1092 MPG123_EXPORT
1093 void syn123_host2be(void *buf, size_t samplesize, size_t samplecount);
1094
1100 MPG123_EXPORT
1101 void syn123_le2host(void *buf, size_t samplesize, size_t samplecount);
1102
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
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
1136 MPG123_EXPORT
1137 syn123_ssize_t syn123_resample_expect(syn123_handle *sh, size_t ins);
1138
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
1184 MPG123_EXPORT
1185 off_t syn123_resample_total(long inrate, long outrate, off_t ins);
1186
1200 MPG123_EXPORT
1201 off_t syn123_resample_intotal(long inrate, long outrate, off_t outs);
1202
1203 #endif
1204
1207 #ifdef __cplusplus
1208 }
1209 #endif
1210
1211 #endif
syn123_resample_intotal
MPG123_EXPORT off_t syn123_resample_intotal(long inrate, long outrate, off_t outs)
syn123_query_waves
MPG123_EXPORT int syn123_query_waves(syn123_handle *sh, size_t *count, int *id, double *freq, double *phase, int *backwards, size_t *period)
syn123_host2le
MPG123_EXPORT void syn123_host2le(void *buf, size_t samplesize, size_t samplecount)
SYN123_BAD_SWEEP
@ SYN123_BAD_SWEEP
Definition: syn123.h:186
fmt123.h
syn123_dither
MPG123_EXPORT int syn123_dither(syn123_handle *sh, int dither, unsigned long *seed)
SYN123_SWEEP_QUAD
@ SYN123_SWEEP_QUAD
Definition: syn123.h:370
SYN123_WAVE_LIMIT
@ SYN123_WAVE_LIMIT
Definition: syn123.h:263
syn123_wave_id
syn123_wave_id
Definition: syn123.h:251
syn123_soft_clip
MPG123_EXPORT size_t syn123_soft_clip(void *buf, int encoding, size_t samples, double limit, double width, syn123_handle *sh)
SYN123_BAD_FREQ
@ SYN123_BAD_FREQ
Definition: syn123.h:185
SYN123_BAD_ENC
@ SYN123_BAD_ENC
Definition: syn123.h:178
syn123_ssize_t
ssize_t syn123_ssize_t
Definition: syn123.h:1120
syn123_resample_maxincount
MPG123_EXPORT size_t syn123_resample_maxincount(long input_rate, long output_rate)
syn123_mix
MPG123_EXPORT int syn123_mix(void *MPG123_RESTRICT dst, int dst_enc, int dst_channels, void *MPG123_RESTRICT src, int src_enc, int src_channels, const double *mixmatrix, size_t samples, int silence, size_t *clipped, syn123_handle *sh)
syn123_setup_waves
MPG123_EXPORT int syn123_setup_waves(syn123_handle *sh, size_t count, int *id, double *freq, double *phase, int *backwards, size_t *period)
SYN123_WAVE_SINE
@ SYN123_WAVE_SINE
Definition: syn123.h:255
syn123_clip
MPG123_EXPORT size_t syn123_clip(void *buf, int encoding, size_t samples)
syn123_del
MPG123_EXPORT void syn123_del(syn123_handle *sh)
syn123_interleave
MPG123_EXPORT void syn123_interleave(void *MPG123_RESTRICT dst, void **MPG123_RESTRICT src, int channels, size_t samplesize, size_t samplecount)
syn123_setup_pink
MPG123_EXPORT int syn123_setup_pink(syn123_handle *sh, int rows, unsigned long seed, size_t *period)
syn123_resample
MPG123_EXPORT size_t syn123_resample(syn123_handle *sh, float *MPG123_RESTRICT dst, float *MPG123_RESTRICT src, size_t samples)
syn123_filter
MPG123_EXPORT int syn123_filter(syn123_handle *sh, void *buf, int encoding, size_t samples)
syn123_resample_intotal64
MPG123_EXPORT int64_t syn123_resample_intotal64(long inrate, long outrate, int64_t outs)
syn123_setup_geiger
MPG123_EXPORT int syn123_setup_geiger(syn123_handle *sh, double activity, unsigned long seed, size_t *period)
syn123_resample_history
MPG123_EXPORT size_t syn123_resample_history(long inrate, long outrate, int dirty)
SYN123_BAD_HANDLE
@ SYN123_BAD_HANDLE
Definition: syn123.h:176
syn123_resample_fillcount
MPG123_EXPORT size_t syn123_resample_fillcount(long input_rate, long output_rate, size_t outs)
SYN123_BAD_FMT
@ SYN123_BAD_FMT
Definition: syn123.h:177
syn123_resample_maxrate
MPG123_EXPORT long syn123_resample_maxrate(void)
SYN123_OK
@ SYN123_OK
Definition: syn123.h:175
syn123_mixenc
MPG123_EXPORT int syn123_mixenc(int src_enc, int dst_enc)
syn123_le2host
MPG123_EXPORT void syn123_le2host(void *buf, size_t samplesize, size_t samplecount)
SYN123_WAVE_SHOT
@ SYN123_WAVE_SHOT
Definition: syn123.h:261
SYN123_BAD_DATA
@ SYN123_BAD_DATA
Definition: syn123.h:189
syn123_wave_name
const MPG123_EXPORT char * syn123_wave_name(int id)
SYN123_SWEEP_LIMIT
@ SYN123_SWEEP_LIMIT
Definition: syn123.h:372
syn123_error
syn123_error
Definition: syn123.h:173
syn123_db2lin
MPG123_EXPORT double syn123_db2lin(double db)
syn123_lin2db
MPG123_EXPORT double syn123_lin2db(double volume)
syn123_resample_inexpect
MPG123_EXPORT syn123_ssize_t syn123_resample_inexpect(syn123_handle *sh, size_t outs)
syn123_query_filter
MPG123_EXPORT int syn123_query_filter(syn123_handle *sh, size_t position, size_t *count, unsigned int *order, double *b, double *a, int *mixenc, int *channels, int *init_firstval)
SYN123_WAVE_GAUSS
@ SYN123_WAVE_GAUSS
Definition: syn123.h:259
SYN123_WAVE_PULSE
@ SYN123_WAVE_PULSE
Definition: syn123.h:260
syn123_host2be
MPG123_EXPORT void syn123_host2be(void *buf, size_t samplesize, size_t samplecount)
syn123_new
MPG123_EXPORT syn123_handle * syn123_new(long rate, int channels, int encoding, size_t maxbuf, int *err)
SYN123_BAD_SIZE
@ SYN123_BAD_SIZE
Definition: syn123.h:180
syn123_sweep_id
syn123_sweep_id
Definition: syn123.h:367
syn123_resample_total
MPG123_EXPORT off_t syn123_resample_total(long inrate, long outrate, off_t ins)
SYN123_SWEEP_EXP
@ SYN123_SWEEP_EXP
Definition: syn123.h:371
SYN123_WAVE_INVALID
@ SYN123_WAVE_INVALID
Definition: syn123.h:253
syn123_be2host
MPG123_EXPORT void syn123_be2host(void *buf, size_t samplesize, size_t samplecount)
SYN123_WAVE_FLAT
@ SYN123_WAVE_FLAT
Definition: syn123.h:254
syn123_resample_in
MPG123_EXPORT size_t syn123_resample_in(syn123_handle *sh, size_t outs, int *err)
syn123_resample_out
MPG123_EXPORT size_t syn123_resample_out(syn123_handle *sh, size_t ins, int *err)
syn123_resample_count
MPG123_EXPORT size_t syn123_resample_count(long inrate, long outrate, size_t ins)
syn123_resample_total64
MPG123_EXPORT int64_t syn123_resample_total64(long inrate, long outrate, int64_t ins)
syn123_strerror
const char * syn123_strerror(int errcode)
syn123_setup_resample
MPG123_EXPORT int syn123_setup_resample(syn123_handle *sh, long inrate, long outrate, int channels, int dirty, int smooth)
syn123_distversion
const MPG123_EXPORT char * syn123_distversion(unsigned int *major, unsigned int *minor, unsigned int *patch)
syn123_setup_sweep
MPG123_EXPORT int syn123_setup_sweep(syn123_handle *sh, int wave_id, double phase, int backwards, int sweep_id, double *f1, double *f2, int smooth, size_t duration, double *endphase, size_t *period, size_t *buffer_period)
syn123_setup_filter
MPG123_EXPORT int syn123_setup_filter(syn123_handle *sh, int append, unsigned int order, double *b, double *a, int mixenc, int channels, int init_firstval)
syn123_handle
struct syn123_struct syn123_handle
Definition: syn123.h:150
syn123_swap_bytes
MPG123_EXPORT void syn123_swap_bytes(void *buf, size_t samplesize, size_t samplecount)
SYN123_WAVE_SAWTOOTH
@ SYN123_WAVE_SAWTOOTH
Definition: syn123.h:258
syn123_libversion
MPG123_EXPORT unsigned int syn123_libversion(unsigned int *patch)
SYN123_WAVE_TRIANGLE
@ SYN123_WAVE_TRIANGLE
Definition: syn123.h:257
SYN123_DOOM
@ SYN123_DOOM
Definition: syn123.h:183
SYN123_BAD_CHOP
@ SYN123_BAD_CHOP
Definition: syn123.h:182
SYN123_BAD_CONV
@ SYN123_BAD_CONV
Definition: syn123.h:179
syn123_resample_expect
MPG123_EXPORT syn123_ssize_t syn123_resample_expect(syn123_handle *sh, size_t ins)
syn123_setup_silence
MPG123_EXPORT int syn123_setup_silence(syn123_handle *sh)
syn123_deinterleave
MPG123_EXPORT void syn123_deinterleave(void **MPG123_RESTRICT dst, void *MPG123_RESTRICT src, int channels, size_t samplesize, size_t samplecount)
MPG123_EXPORT
#define MPG123_EXPORT
Definition: syn123.h:47
syn123_mono2many
MPG123_EXPORT void syn123_mono2many(void *MPG123_RESTRICT dst, void *MPG123_RESTRICT src, int channels, size_t samplesize, size_t samplecount)
SYN123_OVERFLOW
@ SYN123_OVERFLOW
Definition: syn123.h:187
syn123_resample_incount
MPG123_EXPORT size_t syn123_resample_incount(long input_rate, long output_rate, size_t outs)
SYN123_BAD_BUF
@ SYN123_BAD_BUF
Definition: syn123.h:181
SYN123_NO_DATA
@ SYN123_NO_DATA
Definition: syn123.h:188
syn123_drop_filter
MPG123_EXPORT void syn123_drop_filter(syn123_handle *sh, size_t count)
syn123_conv
MPG123_EXPORT int syn123_conv(void *MPG123_RESTRICT dst, int dst_enc, size_t dst_size, void *MPG123_RESTRICT src, int src_enc, size_t src_bytes, size_t *dst_bytes, size_t *clipped, syn123_handle *sh)
SYN123_SWEEP_LIN
@ SYN123_SWEEP_LIN
Definition: syn123.h:369
syn123_read
MPG123_EXPORT size_t syn123_read(syn123_handle *sh, void *dst, size_t dst_bytes)
SYN123_WAVE_SQUARE
@ SYN123_WAVE_SQUARE
Definition: syn123.h:256
MPG123_RESTRICT
#define MPG123_RESTRICT
Definition: syn123.h:59
syn123_amp
MPG123_EXPORT int syn123_amp(void *buf, int encoding, size_t samples, double volume, double offset, size_t *clipped, syn123_handle *sh)
SYN123_WEIRD
@ SYN123_WEIRD
Definition: syn123.h:184
syn123_setup_white
MPG123_EXPORT int syn123_setup_white(syn123_handle *sh, unsigned long seed, size_t *period)