You could access this page securely.

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
28 #define SYN123_PATCHLEVEL 3
29 
30 #ifndef MPG123_EXPORT
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 
160 const char *syn123_distversion(unsigned int *major, unsigned int *minor, unsigned int *patch);
161 
167 unsigned int syn123_libversion(unsigned int *patch);
168 
174 {
175  SYN123_OK = 0
190 };
191 
196 const char* syn123_strerror(int errcode);
197 
212 syn123_handle* syn123_new( long rate, int channels, int encoding
213 , size_t maxbuf, int *err );
214 
220 
238 int syn123_dither(syn123_handle *sh, int dither, unsigned long *seed);
239 
248 size_t syn123_read(syn123_handle *sh, void *dst, size_t dst_bytes);
249 
252 {
253  SYN123_WAVE_INVALID = -1
265 };
266 
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 
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 
352 const char* syn123_wave_name(int id);
353 
360 int syn123_wave_id(const char *name);
361 
368 {
369  SYN123_SWEEP_LIN = 0
373 };
374 
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 
436 int syn123_setup_pink( syn123_handle *sh, int rows, unsigned long seed
437 , size_t *period );
438 
448 int syn123_setup_white(syn123_handle *sh, unsigned long seed, size_t *period);
449 
461 int syn123_setup_geiger( syn123_handle *sh, double activity
462 , unsigned long seed, size_t *period );
463 
470 
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 
556 int syn123_amp( void* buf, int encoding, size_t samples
557 , double volume, double offset, size_t *clipped, syn123_handle *sh );
558 
572 size_t syn123_clip(void *buf, int encoding, size_t samples);
573 
590 size_t syn123_soft_clip( void *buf, int encoding, size_t samples
591 , double limit, double width, syn123_handle *sh );
592 
608 , int channels, size_t samplesize, size_t samplecount );
609 
625 , int channels, size_t samplesize, size_t samplecount );
626 
638 , int channels, size_t samplesize, size_t samplecount );
639 
643 #define SYN123_IOFF(sample, channel, channels) ((sample)*(channels)+(channel))
644 
658 int syn123_mixenc(int src_enc, int dst_enc);
659 
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 
742 , int append, unsigned int order, double *b, double *a
743 , int mixenc, int channels, int init_firstval );
744 
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 
754 void syn123_drop_filter(syn123_handle *sh, size_t count);
755 
775 , void* buf, int encoding, size_t samples );
776 
854 int syn123_setup_resample( syn123_handle *sh, long inrate, long outrate
855 , int channels, int dirty, int smooth );
856 
870 
890 size_t syn123_resample_count(long inrate, long outrate, size_t ins);
891 
910 size_t syn123_resample_history(long inrate, long outrate, int dirty);
911 
930 size_t syn123_resample_incount(long input_rate, long output_rate, size_t outs);
931 
947 size_t syn123_resample_fillcount(long input_rate, long output_rate, size_t outs);
948 
949 
961 size_t syn123_resample_maxincount(long input_rate, long output_rate);
962 
978 size_t syn123_resample_out(syn123_handle *sh, size_t ins, int *err);
979 
997 size_t syn123_resample_in(syn123_handle *sh, size_t outs, int *err);
998 
1014 int64_t syn123_resample_total64(long inrate, long outrate, int64_t ins);
1015 
1034 int64_t syn123_resample_intotal64(long inrate, long outrate, int64_t outs);
1035 
1066  float * MPG123_RESTRICT dst, float * MPG123_RESTRICT src, size_t samples );
1067 
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 
1085 void syn123_host2le(void *buf, size_t samplesize, size_t samplecount);
1086 
1093 void syn123_host2be(void *buf, size_t samplesize, size_t samplecount);
1094 
1101 void syn123_le2host(void *buf, size_t samplesize, size_t samplecount);
1102 
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 
1137 syn123_ssize_t syn123_resample_expect(syn123_handle *sh, size_t ins);
1138 
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 
1185 off_t syn123_resample_total(long inrate, long outrate, off_t ins);
1186 
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
MPG123_EXPORT const char * syn123_wave_name(int id)
MPG123_EXPORT int syn123_query_waves(syn123_handle *sh, size_t *count, int *id, double *freq, double *phase, int *backwards, size_t *period)
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)
MPG123_EXPORT size_t syn123_read(syn123_handle *sh, void *dst, size_t dst_bytes)
MPG123_EXPORT int syn123_setup_waves(syn123_handle *sh, size_t count, int *id, double *freq, double *phase, int *backwards, size_t *period)
MPG123_EXPORT size_t syn123_resample_fillcount(long input_rate, long output_rate, size_t outs)
MPG123_EXPORT size_t syn123_resample_count(long inrate, long outrate, size_t ins)
MPG123_EXPORT double syn123_db2lin(double db)
MPG123_EXPORT int syn123_setup_pink(syn123_handle *sh, int rows, unsigned long seed, size_t *period)
MPG123_EXPORT void syn123_be2host(void *buf, size_t samplesize, size_t samplecount)
MPG123_EXPORT size_t syn123_resample_out(syn123_handle *sh, size_t ins, int *err)
MPG123_EXPORT int syn123_setup_silence(syn123_handle *sh)
MPG123_EXPORT void syn123_host2be(void *buf, size_t samplesize, size_t samplecount)
MPG123_EXPORT long syn123_resample_maxrate(void)
struct syn123_struct syn123_handle
Definition: syn123.h:150
const char * syn123_strerror(int errcode)
MPG123_EXPORT size_t syn123_clip(void *buf, int encoding, size_t samples)
MPG123_EXPORT int syn123_setup_resample(syn123_handle *sh, long inrate, long outrate, int channels, int dirty, int smooth)
MPG123_EXPORT const char * syn123_distversion(unsigned int *major, unsigned int *minor, unsigned int *patch)
MPG123_EXPORT syn123_handle * syn123_new(long rate, int channels, int encoding, size_t maxbuf, int *err)
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)
MPG123_EXPORT void syn123_interleave(void *MPG123_RESTRICT dst, void **MPG123_RESTRICT src, int channels, size_t samplesize, size_t samplecount)
MPG123_EXPORT unsigned int syn123_libversion(unsigned int *patch)
MPG123_EXPORT size_t syn123_resample_in(syn123_handle *sh, size_t outs, int *err)
MPG123_EXPORT void syn123_del(syn123_handle *sh)
MPG123_EXPORT size_t syn123_soft_clip(void *buf, int encoding, size_t samples, double limit, double width, syn123_handle *sh)
MPG123_EXPORT double syn123_lin2db(double volume)
syn123_error
Definition: syn123.h:174
MPG123_EXPORT syn123_ssize_t syn123_resample_inexpect(syn123_handle *sh, size_t outs)
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)
MPG123_EXPORT void syn123_swap_bytes(void *buf, size_t samplesize, size_t samplecount)
MPG123_EXPORT int64_t syn123_resample_total64(long inrate, long outrate, int64_t ins)
MPG123_EXPORT size_t syn123_resample(syn123_handle *sh, float *MPG123_RESTRICT dst, float *MPG123_RESTRICT src, size_t samples)
MPG123_EXPORT int syn123_setup_geiger(syn123_handle *sh, double activity, unsigned long seed, size_t *period)
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)
MPG123_EXPORT void syn123_le2host(void *buf, size_t samplesize, size_t samplecount)
MPG123_EXPORT int syn123_mixenc(int src_enc, int dst_enc)
MPG123_EXPORT size_t syn123_resample_history(long inrate, long outrate, int dirty)
MPG123_EXPORT void syn123_drop_filter(syn123_handle *sh, size_t count)
MPG123_EXPORT void syn123_mono2many(void *MPG123_RESTRICT dst, void *MPG123_RESTRICT src, int channels, size_t samplesize, size_t samplecount)
MPG123_EXPORT void syn123_deinterleave(void **MPG123_RESTRICT dst, void *MPG123_RESTRICT src, int channels, size_t samplesize, size_t samplecount)
MPG123_EXPORT size_t syn123_resample_incount(long input_rate, long output_rate, size_t outs)
MPG123_EXPORT int syn123_dither(syn123_handle *sh, int dither, unsigned long *seed)
MPG123_EXPORT syn123_ssize_t syn123_resample_expect(syn123_handle *sh, size_t ins)
syn123_sweep_id
Definition: syn123.h:368
MPG123_EXPORT int syn123_setup_white(syn123_handle *sh, unsigned long seed, size_t *period)
syn123_wave_id
Definition: syn123.h:252
MPG123_EXPORT int syn123_filter(syn123_handle *sh, void *buf, int encoding, size_t samples)
MPG123_EXPORT void syn123_host2le(void *buf, size_t samplesize, size_t samplecount)
MPG123_EXPORT size_t syn123_resample_maxincount(long input_rate, long output_rate)
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)
MPG123_EXPORT int syn123_amp(void *buf, int encoding, size_t samples, double volume, double offset, size_t *clipped, syn123_handle *sh)
MPG123_EXPORT off_t syn123_resample_intotal(long inrate, long outrate, off_t outs)
MPG123_EXPORT off_t syn123_resample_total(long inrate, long outrate, off_t ins)
MPG123_EXPORT int64_t syn123_resample_intotal64(long inrate, long outrate, int64_t outs)
@ SYN123_BAD_ENC
Definition: syn123.h:178
@ SYN123_WEIRD
Definition: syn123.h:184
@ SYN123_OVERFLOW
Definition: syn123.h:187
@ SYN123_BAD_CONV
Definition: syn123.h:179
@ SYN123_BAD_DATA
Definition: syn123.h:189
@ SYN123_BAD_SWEEP
Definition: syn123.h:186
@ SYN123_OK
Definition: syn123.h:175
@ SYN123_BAD_FMT
Definition: syn123.h:177
@ SYN123_BAD_FREQ
Definition: syn123.h:185
@ SYN123_BAD_CHOP
Definition: syn123.h:182
@ SYN123_BAD_SIZE
Definition: syn123.h:180
@ SYN123_NO_DATA
Definition: syn123.h:188
@ SYN123_BAD_HANDLE
Definition: syn123.h:176
@ SYN123_BAD_BUF
Definition: syn123.h:181
@ SYN123_DOOM
Definition: syn123.h:183
@ SYN123_SWEEP_LIMIT
Definition: syn123.h:372
@ SYN123_SWEEP_EXP
Definition: syn123.h:371
@ SYN123_SWEEP_QUAD
Definition: syn123.h:370
@ SYN123_SWEEP_LIN
Definition: syn123.h:369
@ SYN123_WAVE_LIMIT
Definition: syn123.h:263
@ SYN123_WAVE_PULSE
Definition: syn123.h:260
@ SYN123_WAVE_TRIANGLE
Definition: syn123.h:257
@ SYN123_WAVE_GAUSS
Definition: syn123.h:259
@ SYN123_WAVE_SAWTOOTH
Definition: syn123.h:258
@ SYN123_WAVE_SQUARE
Definition: syn123.h:256
@ SYN123_WAVE_INVALID
Definition: syn123.h:253
@ SYN123_WAVE_SINE
Definition: syn123.h:255
@ SYN123_WAVE_SHOT
Definition: syn123.h:261
@ SYN123_WAVE_FLAT
Definition: syn123.h:254
#define MPG123_EXPORT
Definition: syn123.h:47
#define MPG123_RESTRICT
Definition: syn123.h:59
Hopefully valid HTML! Valid CSS!