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 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;-).
mpg123.h File Reference
#include "fmt123.h"
#include <stddef.h>
#include <stdint.h>
#include <sys/types.h>
Include dependency graph for mpg123.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.


struct  mpg123_frameinfo
struct  mpg123_frameinfo2
struct  mpg123_moreinfo
struct  mpg123_string
struct  mpg123_text
struct  mpg123_picture
struct  mpg123_id3v2
struct  mpg123_id3v1


#define MPG123_API_VERSION   48
#define MPG123_PATCHLEVEL   2
#define MPG123_EXPORT
#define MPG123_ID3   0x3
#define MPG123_NEW_ID3   0x1
#define MPG123_ICY   0xc
#define MPG123_NEW_ICY   0x4


typedef ssize_t mpg123_ssize_t
typedef struct mpg123_handle_struct mpg123_handle
typedef struct mpg123_pars_struct mpg123_pars


enum  mpg123_parms {
  MPG123_VERBOSE = 0 , MPG123_FLAGS ,
enum  mpg123_param_flags {
  MPG123_FORCE_MONO = 0x7 , MPG123_MONO_LEFT = 0x1 ,
  MPG123_MONO_RIGHT = 0x2 , MPG123_MONO_MIX = 0x4 ,
  MPG123_FORCE_STEREO = 0x8 , MPG123_FORCE_8BIT = 0x10 ,
  MPG123_QUIET = 0x20 , MPG123_GAPLESS = 0x40 ,
  MPG123_NO_RESYNC = 0x80 , MPG123_SEEKBUFFER = 0x100 ,
  MPG123_FUZZY = 0x200 , MPG123_FORCE_FLOAT = 0x400 ,
  MPG123_PLAIN_ID3TEXT = 0x800 , MPG123_IGNORE_STREAMLENGTH = 0x1000 ,
  MPG123_SKIP_ID3V2 = 0x2000 , MPG123_IGNORE_INFOFRAME = 0x4000 ,
  MPG123_AUTO_RESAMPLE = 0x8000 , MPG123_PICTURE = 0x10000 ,
  MPG123_NO_PEEK_END = 0x20000 , MPG123_FORCE_SEEKABLE = 0x40000 ,
  MPG123_STORE_RAW_ID3 = 0x80000 , MPG123_FORCE_ENDIAN = 0x100000 ,
  MPG123_BIG_ENDIAN = 0x200000 , MPG123_NO_READAHEAD = 0x400000 ,
  MPG123_FLOAT_FALLBACK = 0x800000 , MPG123_NO_FRANKENSTEIN = 0x1000000
enum  mpg123_param_rva {
  MPG123_RVA_OFF = 0 , MPG123_RVA_MIX = 1 ,
enum  mpg123_feature_set {
enum  mpg123_errors {
  MPG123_DONE =-12 , MPG123_NEW_FORMAT =-11 ,
  MPG123_NEED_MORE =-10 , MPG123_ERR =-1 ,
enum  mpg123_channelcount { MPG123_MONO = 1 , MPG123_STEREO = 2 }
enum  mpg123_channels {
  MPG123_LEFT =0x1 , MPG123_RIGHT =0x2 ,
  MPG123_LR =0x3
enum  mpg123_vbr {
  MPG123_CBR =0 , MPG123_VBR ,
enum  mpg123_version {
  MPG123_1_0 =0 , MPG123_2_0 ,
enum  mpg123_mode {
  MPG123_M_STEREO =0 , MPG123_M_JOINT ,
enum  mpg123_flags {
  MPG123_CRC =0x1 , MPG123_COPYRIGHT =0x2 ,
  MPG123_PRIVATE =0x4 , MPG123_ORIGINAL =0x8
enum  mpg123_state {
enum  mpg123_text_encoding {
  mpg123_text_unknown = 0 , mpg123_text_utf8 = 1 ,
  mpg123_text_latin1 = 2 , mpg123_text_icy = 3 ,
  mpg123_text_cp1252 = 4 , mpg123_text_utf16 = 5 ,
  mpg123_text_utf16bom = 6 , mpg123_text_utf16be = 7 ,
  mpg123_text_max = 7
enum  mpg123_id3_enc {
  mpg123_id3_latin1 = 0 , mpg123_id3_utf16bom = 1 ,
  mpg123_id3_utf16be = 2 , mpg123_id3_utf8 = 3 ,
  mpg123_id3_enc_max = 3
enum  mpg123_id3_pic_type {
  mpg123_id3_pic_other = 0 , mpg123_id3_pic_icon = 1 ,
  mpg123_id3_pic_other_icon = 2 , mpg123_id3_pic_front_cover = 3 ,
  mpg123_id3_pic_back_cover = 4 , mpg123_id3_pic_leaflet = 5 ,
  mpg123_id3_pic_media = 6 , mpg123_id3_pic_lead = 7 ,
  mpg123_id3_pic_artist = 8 , mpg123_id3_pic_conductor = 9 ,
  mpg123_id3_pic_orchestra = 10 , mpg123_id3_pic_composer = 11 ,
  mpg123_id3_pic_lyricist = 12 , mpg123_id3_pic_location = 13 ,
  mpg123_id3_pic_recording = 14 , mpg123_id3_pic_performance = 15 ,
  mpg123_id3_pic_video = 16 , mpg123_id3_pic_fish = 17 ,
  mpg123_id3_pic_illustration = 18 , mpg123_id3_pic_artist_logo = 19 ,
  mpg123_id3_pic_publisher_logo = 20


const char * mpg123_distversion (unsigned int *major, unsigned int *minor, unsigned int *patch)
unsigned int mpg123_libversion (unsigned int *patch)
MPG123_EXPORT int mpg123_init (void)
MPG123_EXPORT void mpg123_exit (void)
MPG123_EXPORT mpg123_handlempg123_new (const char *decoder, int *error)
MPG123_EXPORT void mpg123_delete (mpg123_handle *mh)
MPG123_EXPORT void mpg123_free (void *ptr)
MPG123_EXPORT int mpg123_param (mpg123_handle *mh, enum mpg123_parms type, long value, double fvalue)
MPG123_EXPORT int mpg123_param2 (mpg123_handle *mh, int type, long value, double fvalue)
MPG123_EXPORT int mpg123_getparam (mpg123_handle *mh, enum mpg123_parms type, long *value, double *fvalue)
MPG123_EXPORT int mpg123_getparam2 (mpg123_handle *mh, int type, long *value, double *fvalue)
MPG123_EXPORT int mpg123_feature (const enum mpg123_feature_set key)
MPG123_EXPORT int mpg123_feature2 (int key)
MPG123_EXPORT const char * mpg123_plain_strerror (int errcode)
MPG123_EXPORT const char * mpg123_strerror (mpg123_handle *mh)
MPG123_EXPORT int mpg123_errcode (mpg123_handle *mh)
MPG123_EXPORT const char ** mpg123_decoders (void)
MPG123_EXPORT const char ** mpg123_supported_decoders (void)
MPG123_EXPORT int mpg123_decoder (mpg123_handle *mh, const char *decoder_name)
MPG123_EXPORT const char * mpg123_current_decoder (mpg123_handle *mh)
MPG123_EXPORT void mpg123_rates (const long **list, size_t *number)
MPG123_EXPORT void mpg123_encodings (const int **list, size_t *number)
MPG123_EXPORT int mpg123_encsize (int encoding)
MPG123_EXPORT int mpg123_format_none (mpg123_handle *mh)
MPG123_EXPORT int mpg123_format_all (mpg123_handle *mh)
MPG123_EXPORT int mpg123_format (mpg123_handle *mh, long rate, int channels, int encodings)
MPG123_EXPORT int mpg123_format2 (mpg123_handle *mh, long rate, int channels, int encodings)
MPG123_EXPORT int mpg123_format_support (mpg123_handle *mh, long rate, int encoding)
MPG123_EXPORT int mpg123_getformat (mpg123_handle *mh, long *rate, int *channels, int *encoding)
MPG123_EXPORT int mpg123_getformat2 (mpg123_handle *mh, long *rate, int *channels, int *encoding, int clear_flag)
MPG123_EXPORT int mpg123_open_fixed (mpg123_handle *mh, const char *path, int channels, int encoding)
MPG123_EXPORT int mpg123_open (mpg123_handle *mh, const char *path)
MPG123_EXPORT int mpg123_open_fd (mpg123_handle *mh, int fd)
MPG123_EXPORT int mpg123_open_handle (mpg123_handle *mh, void *iohandle)
MPG123_EXPORT int mpg123_open_feed (mpg123_handle *mh)
MPG123_EXPORT int mpg123_close (mpg123_handle *mh)
MPG123_EXPORT int mpg123_read (mpg123_handle *mh, void *outmemory, size_t outmemsize, size_t *done)
MPG123_EXPORT int mpg123_feed (mpg123_handle *mh, const unsigned char *in, size_t size)
MPG123_EXPORT int mpg123_decode (mpg123_handle *mh, const unsigned char *inmemory, size_t inmemsize, void *outmemory, size_t outmemsize, size_t *done)
MPG123_EXPORT int mpg123_decode_frame (mpg123_handle *mh, off_t *num, unsigned char **audio, size_t *bytes)
MPG123_EXPORT int mpg123_framebyframe_decode (mpg123_handle *mh, off_t *num, unsigned char **audio, size_t *bytes)
MPG123_EXPORT int mpg123_decode_frame64 (mpg123_handle *mh, int64_t *num, unsigned char **audio, size_t *bytes)
MPG123_EXPORT int mpg123_framebyframe_decode64 (mpg123_handle *mh, int64_t *num, unsigned char **audio, size_t *bytes)
MPG123_EXPORT int mpg123_framebyframe_next (mpg123_handle *mh)
MPG123_EXPORT int mpg123_framedata (mpg123_handle *mh, unsigned long *header, unsigned char **bodydata, size_t *bodybytes)
MPG123_EXPORT off_t mpg123_framepos (mpg123_handle *mh)
MPG123_EXPORT int64_t mpg123_framepos64 (mpg123_handle *mh)
MPG123_EXPORT off_t mpg123_tell (mpg123_handle *mh)
MPG123_EXPORT int64_t mpg123_tell64 (mpg123_handle *mh)
MPG123_EXPORT off_t mpg123_tellframe (mpg123_handle *mh)
MPG123_EXPORT int64_t mpg123_tellframe64 (mpg123_handle *mh)
MPG123_EXPORT off_t mpg123_tell_stream (mpg123_handle *mh)
MPG123_EXPORT int64_t mpg123_tell_stream64 (mpg123_handle *mh)
MPG123_EXPORT off_t mpg123_seek (mpg123_handle *mh, off_t sampleoff, int whence)
MPG123_EXPORT int64_t mpg123_seek64 (mpg123_handle *mh, int64_t sampleoff, int whence)
MPG123_EXPORT off_t mpg123_feedseek (mpg123_handle *mh, off_t sampleoff, int whence, off_t *input_offset)
MPG123_EXPORT int64_t mpg123_feedseek64 (mpg123_handle *mh, int64_t sampleoff, int whence, int64_t *input_offset)
MPG123_EXPORT off_t mpg123_seek_frame (mpg123_handle *mh, off_t frameoff, int whence)
MPG123_EXPORT int64_t mpg123_seek_frame64 (mpg123_handle *mh, int64_t frameoff, int whence)
MPG123_EXPORT off_t mpg123_timeframe (mpg123_handle *mh, double sec)
MPG123_EXPORT int mpg123_index (mpg123_handle *mh, off_t **offsets, off_t *step, size_t *fill)
MPG123_EXPORT int64_t mpg123_timeframe64 (mpg123_handle *mh, double sec)
MPG123_EXPORT int mpg123_index64 (mpg123_handle *mh, int64_t **offsets, int64_t *step, size_t *fill)
MPG123_EXPORT int mpg123_set_index (mpg123_handle *mh, off_t *offsets, off_t step, size_t fill)
MPG123_EXPORT int mpg123_set_index64 (mpg123_handle *mh, int64_t *offsets, int64_t step, size_t fill)
MPG123_EXPORT int mpg123_position (mpg123_handle *mh, off_t INT123_frame_offset, off_t buffered_bytes, off_t *current_frame, off_t *frames_left, double *current_seconds, double *seconds_left)
MPG123_EXPORT int mpg123_eq (mpg123_handle *mh, enum mpg123_channels channel, int band, double val)
MPG123_EXPORT int mpg123_eq2 (mpg123_handle *mh, int channel, int band, double val)
MPG123_EXPORT int mpg123_eq_bands (mpg123_handle *mh, int channel, int a, int b, double factor)
MPG123_EXPORT int mpg123_eq_change (mpg123_handle *mh, int channel, int a, int b, double db)
MPG123_EXPORT double mpg123_geteq (mpg123_handle *mh, enum mpg123_channels channel, int band)
MPG123_EXPORT double mpg123_geteq2 (mpg123_handle *mh, int channel, int band)
MPG123_EXPORT int mpg123_reset_eq (mpg123_handle *mh)
MPG123_EXPORT int mpg123_volume (mpg123_handle *mh, double vol)
MPG123_EXPORT int mpg123_volume_change (mpg123_handle *mh, double change)
MPG123_EXPORT int mpg123_volume_change_db (mpg123_handle *mh, double db)
MPG123_EXPORT int mpg123_getvolume (mpg123_handle *mh, double *base, double *really, double *rva_db)
MPG123_EXPORT int mpg123_info (mpg123_handle *mh, struct mpg123_frameinfo *mi)
MPG123_EXPORT int mpg123_info2 (mpg123_handle *mh, struct mpg123_frameinfo2 *mi)
MPG123_EXPORT int mpg123_set_moreinfo (mpg123_handle *mh, struct mpg123_moreinfo *mi)
MPG123_EXPORT size_t mpg123_safe_buffer (void)
MPG123_EXPORT int mpg123_scan (mpg123_handle *mh)
MPG123_EXPORT off_t mpg123_framelength (mpg123_handle *mh)
MPG123_EXPORT off_t mpg123_length (mpg123_handle *mh)
MPG123_EXPORT int mpg123_set_filesize (mpg123_handle *mh, off_t size)
MPG123_EXPORT int64_t mpg123_framelength64 (mpg123_handle *mh)
MPG123_EXPORT int64_t mpg123_length64 (mpg123_handle *mh)
MPG123_EXPORT int mpg123_set_filesize64 (mpg123_handle *mh, int64_t size)
MPG123_EXPORT double mpg123_tpf (mpg123_handle *mh)
MPG123_EXPORT int mpg123_spf (mpg123_handle *mh)
MPG123_EXPORT long mpg123_clip (mpg123_handle *mh)
MPG123_EXPORT int mpg123_getstate (mpg123_handle *mh, enum mpg123_state key, long *val, double *fval)
MPG123_EXPORT int mpg123_getstate2 (mpg123_handle *mh, int key, long *val, double *fval)
MPG123_EXPORT mpg123_stringmpg123_new_string (const char *val)
MPG123_EXPORT void mpg123_delete_string (mpg123_string *sb)
MPG123_EXPORT void mpg123_init_string (mpg123_string *sb)
MPG123_EXPORT void mpg123_free_string (mpg123_string *sb)
MPG123_EXPORT int mpg123_resize_string (mpg123_string *sb, size_t news)
MPG123_EXPORT int mpg123_grow_string (mpg123_string *sb, size_t news)
MPG123_EXPORT int mpg123_copy_string (mpg123_string *from, mpg123_string *to)
MPG123_EXPORT int mpg123_move_string (mpg123_string *from, mpg123_string *to)
MPG123_EXPORT int mpg123_add_string (mpg123_string *sb, const char *stuff)
MPG123_EXPORT int mpg123_add_substring (mpg123_string *sb, const char *stuff, size_t from, size_t count)
MPG123_EXPORT int mpg123_set_string (mpg123_string *sb, const char *stuff)
MPG123_EXPORT int mpg123_set_substring (mpg123_string *sb, const char *stuff, size_t from, size_t count)
MPG123_EXPORT size_t mpg123_strlen (mpg123_string *sb, int utf8)
MPG123_EXPORT int mpg123_chomp_string (mpg123_string *sb)
MPG123_EXPORT int mpg123_same_string (mpg123_string *a, mpg123_string *b)
MPG123_EXPORT enum mpg123_text_encoding mpg123_enc_from_id3 (unsigned char id3_enc_byte)
MPG123_EXPORT int mpg123_enc_from_id3_2 (unsigned char id3_enc_byte)
MPG123_EXPORT int mpg123_store_utf8 (mpg123_string *sb, enum mpg123_text_encoding enc, const unsigned char *source, size_t source_size)
MPG123_EXPORT int mpg123_store_utf8_2 (mpg123_string *sb, int enc, const unsigned char *source, size_t source_size)
MPG123_EXPORT int mpg123_meta_check (mpg123_handle *mh)
MPG123_EXPORT void mpg123_meta_free (mpg123_handle *mh)
MPG123_EXPORT int mpg123_id3 (mpg123_handle *mh, mpg123_id3v1 **v1, mpg123_id3v2 **v2)
MPG123_EXPORT int mpg123_id3_raw (mpg123_handle *mh, unsigned char **v1, size_t *v1_size, unsigned char **v2, size_t *v2_size)
MPG123_EXPORT int mpg123_icy (mpg123_handle *mh, char **icy_meta)
MPG123_EXPORT char * mpg123_icy2utf8 (const char *icy_text)
MPG123_EXPORT mpg123_handlempg123_parnew (mpg123_pars *mp, const char *decoder, int *error)
MPG123_EXPORT mpg123_parsmpg123_new_pars (int *error)
MPG123_EXPORT void mpg123_delete_pars (mpg123_pars *mp)
MPG123_EXPORT int mpg123_fmt_none (mpg123_pars *mp)
MPG123_EXPORT int mpg123_fmt_all (mpg123_pars *mp)
MPG123_EXPORT int mpg123_fmt (mpg123_pars *mp, long rate, int channels, int encodings)
MPG123_EXPORT int mpg123_fmt2 (mpg123_pars *mp, long rate, int channels, int encodings)
MPG123_EXPORT int mpg123_fmt_support (mpg123_pars *mp, long rate, int encoding)
MPG123_EXPORT int mpg123_par (mpg123_pars *mp, enum mpg123_parms type, long value, double fvalue)
MPG123_EXPORT int mpg123_par2 (mpg123_pars *mp, int type, long value, double fvalue)
MPG123_EXPORT int mpg123_getpar (mpg123_pars *mp, enum mpg123_parms type, long *value, double *fvalue)
MPG123_EXPORT int mpg123_getpar2 (mpg123_pars *mp, int type, long *value, double *fvalue)
MPG123_EXPORT int mpg123_replace_buffer (mpg123_handle *mh, void *data, size_t size)
MPG123_EXPORT size_t mpg123_outblock (mpg123_handle *mh)
MPG123_EXPORT int mpg123_replace_reader (mpg123_handle *mh, mpg123_ssize_t(*r_read)(int, void *, size_t), off_t(*r_lseek)(int, off_t, int))
MPG123_EXPORT int mpg123_replace_reader_handle (mpg123_handle *mh, mpg123_ssize_t(*r_read)(void *, void *, size_t), off_t(*r_lseek)(void *, off_t, int), void(*cleanup)(void *))
MPG123_EXPORT int mpg123_reader64 (mpg123_handle *mh, int(*r_read)(void *, void *, size_t, size_t *), int64_t(*r_lseek)(void *, int64_t, int), void(*cleanup)(void *))

Detailed Description

The header file for the libmpg123 MPEG Audio decoder

Definition in file mpg123.h.

Macro Definition Documentation


#define MPG123_API_VERSION   48

A macro to check at compile time which set of API functions to expect. This must be incremented at least each time a new symbol is added to the header.

Definition at line 20 of file mpg123.h.


#define MPG123_PATCHLEVEL   2

library patch level at client build time

Definition at line 22 of file mpg123.h.


#define MPG123_EXPORT

Defines needed for MS Visual Studio(tm) DLL builds. Every public function must be prefixed with MPG123_EXPORT. When building the DLL ensure to define BUILD_MPG123_DLL. This makes the function accessible for clients and includes it in the import library which is created together with the DLL. When consuming the DLL ensure to define LINK_MPG123_DLL which imports the functions from the DLL.

Definition at line 41 of file mpg123.h.

Typedef Documentation

◆ mpg123_ssize_t

typedef ssize_t mpg123_ssize_t

Earlier versions of libmpg123 put enums into public API calls, thich is not exactly safe. There are ABI rules, but you can use compiler switches to change the sizes of enums. It is safer not to have them in API calls. Thus, the default is to remap calls and structs to variants that use plain ints. Define MPG123_ENUM_API to prevent that remapping.

You might want to define this to increase the chance of your binary working with an older version of the library. But if that is your goal, you should better build with an older version to begin with.

Definition at line 83 of file mpg123.h.

Hopefully valid HTML! Valid CSS!