download : svn :: features :: sf.net project - bug tracker :: news archive

libmpg123 API :: testing :: benchmarking :: faq :: links :: contact

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 and the overall NEWS file on libmpg123 versions and important changes between them.
Let me emphasize that the policy for libmpg123 is to always stay backwards compatible -- only additions are planned (and it's not yet planned to change the plans;-).

mpg123.h

Go to the documentation of this file.

/*
        libmpg123: MPEG Audio Decoder library (version 1.5.1)

        copyright 1995-2007 by the mpg123 project - free software under the terms of the LGPL 2.1
        see COPYING and AUTHORS files in distribution or http://mpg123.org
*/

#ifndef MPG123_LIB_H
#define MPG123_LIB_H

/* These aren't actually in use... seems to work without using libtool. */
#ifdef BUILD_MPG123_DLL
/* The dll exports. */
#define EXPORT __declspec(dllexport)
#else
#ifdef LINK_MPG123_DLL
/* The exe imports. */
#define EXPORT __declspec(dllimport)
#else
/* Nothing on normal/UNIX builds */
#define EXPORT
#endif
#endif

#include <stdlib.h>
#include <sys/types.h>


#ifdef __cplusplus
extern "C" {
#endif

struct mpg123_handle_struct;

typedef struct mpg123_handle_struct mpg123_handle;

EXPORT int  mpg123_init(void);

EXPORT void mpg123_exit(void);

EXPORT mpg123_handle *mpg123_new(const char* decoder, int *error);

EXPORT void mpg123_delete(mpg123_handle *mh);

enum mpg123_parms
{
        MPG123_VERBOSE,        
        MPG123_FLAGS,          
        MPG123_ADD_FLAGS,      
        MPG123_FORCE_RATE,     
        MPG123_DOWN_SAMPLE,    
        MPG123_RVA,            
        MPG123_DOWNSPEED,      
        MPG123_UPSPEED,        
        MPG123_START_FRAME,    
        MPG123_DECODE_FRAMES,  
        MPG123_ICY_INTERVAL,   
        MPG123_OUTSCALE,       
        MPG123_TIMEOUT,        
        MPG123_REMOVE_FLAGS,   
        MPG123_RESYNC_LIMIT    
};

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

enum mpg123_param_rva
{
         MPG123_RVA_OFF   = 0 
        ,MPG123_RVA_MIX   = 1 
        ,MPG123_RVA_ALBUM = 2 
        ,MPG123_RVA_MAX   = MPG123_RVA_ALBUM 
};

/* TODO: Assess the possibilities and troubles of changing parameters during playback. */

EXPORT int mpg123_param(mpg123_handle *mh, enum mpg123_parms type, long value, double fvalue);

EXPORT int mpg123_getparam(mpg123_handle *mh, enum mpg123_parms type, long *val, double *fval);

/* @} */


enum mpg123_errors
{
        MPG123_DONE=-12,        
        MPG123_NEW_FORMAT=-11,  
        MPG123_NEED_MORE=-10,   
        MPG123_ERR=-1,                  
        MPG123_OK=0,                    
        MPG123_BAD_OUTFORMAT,   
        MPG123_BAD_CHANNEL,             
        MPG123_BAD_RATE,                
        MPG123_ERR_16TO8TABLE,  
        MPG123_BAD_PARAM,               
        MPG123_BAD_BUFFER,              
        MPG123_OUT_OF_MEM,              
        MPG123_NOT_INITIALIZED, 
        MPG123_BAD_DECODER,             
        MPG123_BAD_HANDLE,              
        MPG123_NO_BUFFERS,              
        MPG123_BAD_RVA,                 
        MPG123_NO_GAPLESS,              
        MPG123_NO_SPACE,                
        MPG123_BAD_TYPES,               
        MPG123_BAD_BAND,                
        MPG123_ERR_NULL,                
        MPG123_ERR_READER,              
        MPG123_NO_SEEK_FROM_END,
        MPG123_BAD_WHENCE,              
        MPG123_NO_TIMEOUT,              
        MPG123_BAD_FILE,                
        MPG123_NO_SEEK,                 
        MPG123_NO_READER,               
        MPG123_BAD_PARS,                
        MPG123_BAD_INDEX_PAR,   
        MPG123_OUT_OF_SYNC,     
        MPG123_RESYNC_FAIL,     
        MPG123_NO_8BIT, 
        MPG123_BAD_ALIGN,       
        MPG123_NULL_BUFFER      
};

EXPORT const char* mpg123_plain_strerror(int errcode);

EXPORT const char* mpg123_strerror(mpg123_handle *mh);

EXPORT int mpg123_errcode(mpg123_handle *mh);

EXPORT char **mpg123_decoders();

EXPORT char **mpg123_supported_decoders();

EXPORT int mpg123_decoder(mpg123_handle *mh, const char* decoder_name);

enum mpg123_enc_enum
{
         MPG123_ENC_8      = 0x00f  
        ,MPG123_ENC_16     = 0x040  
        ,MPG123_ENC_32     = 0x100  
        ,MPG123_ENC_SIGNED = 0x080  
        ,MPG123_ENC_FLOAT  = 0x800  
        ,MPG123_ENC_SIGNED_16   = (MPG123_ENC_16|MPG123_ENC_SIGNED|0x10) 
        ,MPG123_ENC_UNSIGNED_16 = (MPG123_ENC_16|0x20)                   
        ,MPG123_ENC_UNSIGNED_8  = 0x01                                   
        ,MPG123_ENC_SIGNED_8    = (MPG123_ENC_SIGNED|0x02)               
        ,MPG123_ENC_ULAW_8      = 0x04                                   
        ,MPG123_ENC_ALAW_8      = 0x08                                   
        ,MPG123_ENC_SIGNED_32   = MPG123_ENC_32|MPG123_ENC_SIGNED|0x10   
        ,MPG123_ENC_UNSIGNED_32 = MPG123_ENC_32|0x20                     
        ,MPG123_ENC_FLOAT_32    = 0x200                                  
        ,MPG123_ENC_FLOAT_64    = 0x400                                  
        ,MPG123_ENC_ANY = ( MPG123_ENC_SIGNED_16  | MPG123_ENC_UNSIGNED_16 | MPG123_ENC_UNSIGNED_8 
                          | MPG123_ENC_SIGNED_8   | MPG123_ENC_ULAW_8      | MPG123_ENC_ALAW_8
                          | MPG123_ENC_FLOAT_32   | MPG123_ENC_FLOAT_64 ) 
};

enum mpg123_channelcount
{
         MPG123_MONO   = 1
        ,MPG123_STEREO = 2
};

EXPORT void mpg123_rates(const long **list, size_t *number);

EXPORT void mpg123_encodings(const int **list, size_t *number);

EXPORT int mpg123_format_none(mpg123_handle *mh);

EXPORT int mpg123_format_all(mpg123_handle *mh);

EXPORT int mpg123_format(mpg123_handle *mh, long rate, int channels, int encodings);

EXPORT int mpg123_format_support(mpg123_handle *mh, long rate, int encoding);

EXPORT int mpg123_getformat(mpg123_handle *mh, long *rate, int *channels, int *encoding);

/* reading samples / triggering decoding, possible return values: */
EXPORT int mpg123_open(mpg123_handle *mh, char *path);

EXPORT int mpg123_open_fd(mpg123_handle *mh, int fd);

EXPORT int mpg123_open_feed(mpg123_handle *mh);

EXPORT int mpg123_close(mpg123_handle *mh);

EXPORT int mpg123_read(mpg123_handle *mh, unsigned char *outmemory, size_t outmemsize, size_t *done);

EXPORT int mpg123_feed(mpg123_handle *mh, const unsigned char *in, size_t size);

EXPORT int mpg123_decode(mpg123_handle *mh, const unsigned char *inmemory, size_t inmemsize,
                         unsigned char *outmemory, size_t outmemsize, size_t *done);

EXPORT int mpg123_decode_frame(mpg123_handle *mh, off_t *num, unsigned char **audio, size_t *bytes);

EXPORT off_t mpg123_tell(mpg123_handle *mh);

EXPORT off_t mpg123_tellframe(mpg123_handle *mh);

EXPORT off_t mpg123_seek(mpg123_handle *mh, off_t sampleoff, int whence);

EXPORT off_t mpg123_feedseek(mpg123_handle *mh, off_t sampleoff, int whence, off_t *input_offset);

EXPORT off_t mpg123_seek_frame(mpg123_handle *mh, off_t frameoff, int whence);

EXPORT off_t mpg123_timeframe(mpg123_handle *mh, double sec);

EXPORT int mpg123_index(mpg123_handle *mh, off_t **offsets, off_t *step, size_t *fill);

EXPORT int mpg123_position( mpg123_handle *mh, off_t frame_offset,
                            off_t buffered_bytes,  off_t *current_frame,  
                            off_t *frames_left, double *current_seconds,
                            double *seconds_left);

enum mpg123_channels
{
        MPG123_LEFT=0x1,        
        MPG123_RIGHT=0x2        
};

EXPORT int mpg123_eq(mpg123_handle *mh, enum mpg123_channels channel, int band, double val);

EXPORT int mpg123_reset_eq(mpg123_handle *mh);

EXPORT int mpg123_volume(mpg123_handle *mh, double vol);

EXPORT int mpg123_volume_change(mpg123_handle *mh, double change);

EXPORT int mpg123_getvolume(mpg123_handle *mh, double *base, double *really, double *rva_db);

/* TODO: Set some preamp in addition / to replace internal RVA handling? */

enum mpg123_vbr {
        MPG123_CBR=0,   
        MPG123_VBR,             
        MPG123_ABR              
};

enum mpg123_version {
        MPG123_1_0=0,   
        MPG123_2_0,             
        MPG123_2_5              
};


enum mpg123_mode {
        MPG123_M_STEREO=0,      
        MPG123_M_JOINT,         
        MPG123_M_DUAL,          
        MPG123_M_MONO           
};


enum mpg123_flags {
        MPG123_CRC=0x1,                 
        MPG123_COPYRIGHT=0x2,   
        MPG123_PRIVATE=0x4,             
        MPG123_ORIGINAL=0x8     
};

struct mpg123_frameinfo
{
        enum mpg123_version version;    
        int layer;                                              
        long rate;                                              
        enum mpg123_mode mode;                  
        int mode_ext;                                   
        int framesize;                                  
        enum mpg123_flags flags;                
        int emphasis;                                   
        int bitrate;                                    
        int abr_rate;                                   
        enum mpg123_vbr vbr;                    
};

EXPORT int mpg123_info(mpg123_handle *mh, struct mpg123_frameinfo *mi);

EXPORT size_t mpg123_safe_buffer(); 

EXPORT int mpg123_scan(mpg123_handle *mh);

EXPORT off_t mpg123_length(mpg123_handle *mh);

EXPORT int mpg123_set_filesize(mpg123_handle *mh, off_t size);

EXPORT double mpg123_tpf(mpg123_handle *mh);

EXPORT long mpg123_clip(mpg123_handle *mh);

typedef struct 
{
        char* p;     
        size_t size; 
        size_t fill; 
} mpg123_string;

EXPORT void mpg123_init_string(mpg123_string* sb);

EXPORT void mpg123_free_string(mpg123_string* sb);

EXPORT int  mpg123_resize_string(mpg123_string* sb, size_t news);

EXPORT int  mpg123_grow_string(mpg123_string* sb, size_t news);

EXPORT int  mpg123_copy_string(mpg123_string* from, mpg123_string* to);

EXPORT int  mpg123_add_string(mpg123_string* sb, const char* stuff);

EXPORT int  mpg123_add_substring(mpg123_string *sb, const char *stuff, size_t from, size_t count);

EXPORT int  mpg123_set_string(mpg123_string* sb, const char* stuff);

EXPORT int  mpg123_set_substring(mpg123_string *sb, const char *stuff, size_t from, size_t count);


typedef struct
{
        char lang[3]; 
        char id[4];   
        mpg123_string description; 
        mpg123_string text;        
} mpg123_text;

typedef struct
{
        unsigned char version; 
        mpg123_string *title;   
        mpg123_string *artist;  
        mpg123_string *album;   
        mpg123_string *year;    
        mpg123_string *genre;   
        mpg123_string *comment; 
        /* Encountered ID3v2 fields are appended to these lists.
           There can be multiple occurences, the pointers above always point to the last encountered data. */
        mpg123_text    *comment_list; 
        size_t          comments;     
        mpg123_text    *text;         
        size_t          texts;        
        mpg123_text    *extra;        
        size_t          extras;       
} mpg123_id3v2;

typedef struct
{
        char tag[3];         
        char title[30];      
        char artist[30];     
        char album[30];      
        char year[4];        
        char comment[30];    
        unsigned char genre; 
} mpg123_id3v1;

#define MPG123_ID3     0x3 
#define MPG123_NEW_ID3 0x1 
#define MPG123_ICY     0xc 
#define MPG123_NEW_ICY 0x4 
EXPORT int mpg123_meta_check(mpg123_handle *mh); /* On error (no valid handle) just 0 is returned. */

EXPORT int mpg123_id3(mpg123_handle *mh, mpg123_id3v1 **v1, mpg123_id3v2 **v2);

EXPORT int mpg123_icy(mpg123_handle *mh, char **icy_meta); /* same for ICY meta string */

EXPORT char* mpg123_icy2utf8(const char* icy_text);


/* @} */


struct mpg123_pars_struct;

typedef struct mpg123_pars_struct   mpg123_pars;

EXPORT mpg123_handle *mpg123_parnew(mpg123_pars *mp, const char* decoder, int *error);

EXPORT mpg123_pars *mpg123_new_pars(int *error);

EXPORT void         mpg123_delete_pars(mpg123_pars* mp);

EXPORT int mpg123_fmt_none(mpg123_pars *mp);

EXPORT int mpg123_fmt_all(mpg123_pars *mp);

EXPORT int mpg123_fmt(mpg123_pars *mh, long rate, int channels, int encodings); /* 0 is good, -1 is error */

EXPORT int mpg123_fmt_support(mpg123_pars *mh,   long rate, int encoding);

EXPORT int mpg123_par(mpg123_pars *mp, enum mpg123_parms type, long value, double fvalue);

EXPORT int mpg123_getpar(mpg123_pars *mp, enum mpg123_parms type, long *val, double *fval);

/* @} */


EXPORT int mpg123_replace_buffer(mpg123_handle *mh, unsigned char *data, size_t size);

EXPORT size_t mpg123_outblock(mpg123_handle *mh);

EXPORT int mpg123_replace_reader( mpg123_handle *mh,
                                  ssize_t (*r_read) (int, void *, size_t),
                                  off_t   (*r_lseek)(int, off_t, int) );

/* @} */


#ifdef __cplusplus
}
#endif

#endif

---