ReactOS 0.4.15-dev-5836-g942b022
Collaboration diagram for mpg123 file input and decoding:


 mpg123 position and seeking


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

Detailed Description

Functions for input bitstream and decoding operations. Decoding/seek functions may also return message codes MPG123_DONE, MPG123_NEW_FORMAT and MPG123_NEED_MORE (please read up on these on how to react!).

Function Documentation

◆ mpg123_close()

MPG123_EXPORT int mpg123_close ( mpg123_handle mh)

Closes the source, if libmpg123 opened it.

MPG123_OK on success

Definition at line 1694 of file libmpg123.c.

1696 if(mh == NULL) return MPG123_BAD_HANDLE;
1698 /* mh->rd is never NULL! */
1699 if(mh->rd->close != NULL) mh->rd->close(mh);
1701 if(mh->new_format)
1702 {
1703 debug("Hey, we are closing a track before the new format has been queried...");
1704 invalidate_format(&mh->af);
1705 mh->new_format = 0;
1706 }
1707 /* Always reset the frame buffers on close, so we cannot forget it in funky opening routines (wrappers, even). */
1708 frame_reset(mh);
1709 return MPG123_OK;
#define NULL
Definition: types.h:112
Definition: mpg123.h:393
@ MPG123_OK
Definition: mpg123.h:383
#define invalidate_format
Definition: intsym.h:178
#define frame_reset
Definition: intsym.h:184
#define debug(msg)
Definition: key_call.c:71
struct reader * rd
Definition: frame.h:287
struct audioformat af
Definition: frame.h:268

Referenced by mpg123_delete(), mpg123_open(), mpg123_open_fd(), mpg123_open_feed(), mpg123_open_handle(), mpg123_replace_reader(), mpg123_replace_reader_handle(), and open_fixed_post().

◆ mpg123_decode()

MPG123_EXPORT int mpg123_decode ( mpg123_handle mh,
const unsigned char inmemory,
size_t  inmemsize,
void outmemory,
size_t  outmemsize,
size_t done 

Decode MPEG Audio from inmemory to outmemory. This is very close to a drop-in replacement for old mpglib. When you give zero-sized output buffer the input will be parsed until decoded data is available. This enables you to get MPG123_NEW_FORMAT (and query it) without taking decoded data. Think of this function being the union of mpg123_read() and mpg123_feed() (which it actually is, sort of;-). You can actually always decide if you want those specialized functions in separate steps or one call this one here.

Note: The type of outmemory changed to a void pointer in mpg123 1.26.0 (API version 45).

inmemoryinput buffer
inmemsizenumber of input bytes
outmemoryoutput buffer
outmemsizemaximum number of output bytes
doneaddress to store the number of actually decoded bytes to
error/message code (watch out especially for MPG123_NEED_MORE)

Definition at line 992 of file libmpg123.c.

994 int ret = MPG123_OK;
995 size_t mdone = 0;
996 unsigned char *outmemory = outmem;
998 if(done != NULL) *done = 0;
999 if(mh == NULL) return MPG123_BAD_HANDLE;
1000 if(inmemsize > 0 && mpg123_feed(mh, inmemory, inmemsize) != MPG123_OK)
1001 {
1002 ret = MPG123_ERR;
1003 goto decodeend;
1004 }
1005 if(outmemory == NULL) outmemsize = 0; /* Not just give error, give chance to get a status message. */
1007 while(ret == MPG123_OK)
1008 {
1009 debug4("decode loop, fill %i (%li vs. %li); to_decode: %i", (int)mh->buffer.fill, (long)mh->num, (long)mh->firstframe, mh->to_decode);
1010 /* Decode a frame that has been read before.
1011 This only happens when buffer is empty! */
1012 if(mh->to_decode)
1013 {
1014 if(mh->new_format)
1015 {
1016 debug("notifiying new format");
1017 mh->new_format = 0;
1019 goto decodeend;
1020 }
1021 if(mh->buffer.size - mh->buffer.fill < mh->outblock)
1022 {
1024 goto decodeend;
1025 }
1026 if(mh->decoder_change && decode_update(mh) < 0)
1027 {
1028 ret = MPG123_ERR;
1029 goto decodeend;
1030 }
1031 decode_the_frame(mh);
1032 mh->to_decode = mh->to_ignore = FALSE;
1033 mh->buffer.p = mh->;
1034 debug2("decoded frame %li, got %li samples in buffer", (long)mh->num, (long)(mh->buffer.fill / (samples_to_bytes(mh, 1))));
1036 }
1037 if(mh->buffer.fill) /* Copy (part of) the decoded data to the caller's buffer. */
1038 {
1039 /* get what is needed - or just what is there */
1040 int a = mh->buffer.fill > (outmemsize - mdone) ? outmemsize - mdone : mh->buffer.fill;
1041 debug4("buffer fill: %i; copying %i (%i - %li)", (int)mh->buffer.fill, a, (int)outmemsize, (long)mdone);
1042 memcpy(outmemory, mh->buffer.p, a);
1043 /* less data in frame buffer, less needed, output pointer increase, more data given... */
1044 mh->buffer.fill -= a;
1045 outmemory += a;
1046 mdone += a;
1047 mh->buffer.p += a;
1048 if(!(outmemsize > mdone)) goto decodeend;
1049 }
1050 else /* If we didn't have data, get a new frame. */
1051 {
1052 int b = get_next_frame(mh);
1053 if(b < 0){ ret = b; goto decodeend; }
1054 }
1055 }
1057 if(done != NULL) *done = mdone;
1058 return ret;
#define FALSE
Definition: types.h:117
unsigned int(__cdecl typeof(jpeg_read_scanlines))(struct jpeg_decompress_struct *
Definition: typeof.h:31
Definition: gapless.h:111
GLboolean GLboolean GLboolean b
Definition: glext.h:6204
GLboolean GLboolean GLboolean GLboolean a
Definition: glext.h:6204
@ MPG123_ERR
Definition: mpg123.h:382
Definition: mpg123.h:397
Definition: mpg123.h:380
int attribute_align_arg mpg123_feed(mpg123_handle *mh, const unsigned char *in, size_t size)
Definition: libmpg123.c:947
#define samples_to_bytes
Definition: intsym.h:225
#define decode_update
Definition: intsym.h:223
#define a
Definition: ke_i.h:78
#define b
Definition: ke_i.h:79
static void decode_the_frame(mpg123_handle *fr)
Definition: libmpg123.c:776
static int get_next_frame(mpg123_handle *mh)
Definition: libmpg123.c:662
#define memcpy(s1, s2, n)
Definition: mkisofs.h:878
#define debug2(s, a, b)
Definition: debug.h:62
#define debug4(s, a, b, c, d)
Definition: debug.h:64
struct outbuffer buffer
Definition: frame.h:267
int ret

Referenced by mpg123_read().

◆ mpg123_decode_frame()

MPG123_EXPORT int mpg123_decode_frame ( mpg123_handle mh,
off_t num,
unsigned char **  audio,
size_t bytes 

Decode next MPEG frame to internal buffer or read a frame and return after setting a new format.

numcurrent frame offset gets stored there
audioThis pointer is set to the internal buffer to read the decoded audio from.
bytesnumber of output bytes ready in the buffer
MPG123_OK or error/message code

Definition at line 166 of file lfs_wrap.c.

168 off_t largenum;
169 int err;
171 err = MPG123_LARGENAME(mpg123_decode_frame)(mh, &largenum, audio, bytes);
172 if(err == MPG123_OK && num != NULL)
173 {
174 *num = largenum;
175 if(*num != largenum)
176 {
178 err = MPG123_ERR;
179 }
180 }
181 return err;
static unsigned char bytes[4]
Definition: adnsresfilter.c:74
__kernel_off_t off_t
Definition: linux.h:201
GLuint GLuint num
Definition: glext.h:9618
Definition: mpg123.h:425
int attribute_align_arg mpg123_decode_frame(mpg123_handle *mh, long *num, unsigned char **audio, size_t *bytes)
Definition: lfs_wrap.c:166
#define err(...)

Referenced by mpg123_decode_frame().

◆ mpg123_feed()

MPG123_EXPORT int mpg123_feed ( mpg123_handle mh,
const unsigned char in,
size_t  size 

Feed data for a stream that has been opened with mpg123_open_feed(). It's give and take: You provide the bytestream, mpg123 gives you the decoded samples.

ininput buffer
sizenumber of input bytes
MPG123_OK or error/message code.

Definition at line 947 of file libmpg123.c.

949 if(mh == NULL) return MPG123_BAD_HANDLE;
950#ifndef NO_FEEDER
951 if(size > 0)
952 {
953 if(in != NULL)
954 {
955 if(feed_more(mh, in, size) != 0) return MPG123_ERR;
956 else
957 {
958 /* The need for more data might have triggered an error.
959 This one is outdated now with the new data. */
960 if(mh->err == MPG123_ERR_READER) mh->err = MPG123_OK;
962 return MPG123_OK;
963 }
964 }
965 else
966 {
968 return MPG123_ERR;
969 }
970 }
971 return MPG123_OK;
974 return MPG123_ERR;
GLsizeiptr size
Definition: glext.h:5919
GLuint in
Definition: glext.h:9616
Definition: mpg123.h:401
Definition: mpg123.h:414
Definition: mpg123.h:421
#define feed_more
Definition: intsym.h:254

Referenced by mpg123_decode().

◆ mpg123_framebyframe_decode()

MPG123_EXPORT int mpg123_framebyframe_decode ( mpg123_handle mh,
off_t num,
unsigned char **  audio,
size_t bytes 

Decode current MPEG frame to internal buffer. Warning: This is experimental API that might change in future releases! Please watch mpg123 development closely when using it.

numlast frame offset gets stored there
audiothis pointer is set to the internal buffer to read the decoded audio from.
bytesnumber of output bytes ready in the buffer
MPG123_OK or error/message code

Definition at line 186 of file lfs_wrap.c.

188 off_t largenum;
189 int err;
191 err = MPG123_LARGENAME(mpg123_framebyframe_decode)(mh, &largenum, audio, bytes);
192 if(err == MPG123_OK && num != NULL)
193 {
194 *num = largenum;
195 if(*num != largenum)
196 {
198 err = MPG123_ERR;
199 }
200 }
201 return err;
int attribute_align_arg mpg123_framebyframe_decode(mpg123_handle *mh, long *num, unsigned char **audio, size_t *bytes)
Definition: lfs_wrap.c:186

Referenced by mpg123_framebyframe_decode().

◆ mpg123_framebyframe_next()

MPG123_EXPORT int mpg123_framebyframe_next ( mpg123_handle mh)

Find, read and parse the next mp3 frame Warning: This is experimental API that might change in future releases! Please watch mpg123 development closely when using it.

MPG123_OK or error/message code

Definition at line 860 of file libmpg123.c.

862 int b;
863 if(mh == NULL) return MPG123_BAD_HANDLE;
865 mh->to_decode = mh->to_ignore = FALSE;
866 mh->buffer.fill = 0;
868 b = get_next_frame(mh);
869 if(b < 0) return b;
870 debug1("got next frame, %i", mh->to_decode);
872 /* mpg123_framebyframe_decode will return MPG123_OK with 0 bytes decoded if mh->to_decode is 0 */
873 if(!mh->to_decode)
874 return MPG123_OK;
876 if(mh->new_format)
877 {
878 debug("notifiying new format");
879 mh->new_format = 0;
880 return MPG123_NEW_FORMAT;
881 }
883 return MPG123_OK;
#define debug1(s, a)
Definition: debug.h:61

◆ mpg123_framedata()

MPG123_EXPORT int mpg123_framedata ( mpg123_handle mh,
unsigned long header,
unsigned char **  bodydata,
size_t bodybytes 

Get access to the raw input data for the last parsed frame. This gives you a direct look (and write access) to the frame body data. Together with the raw header, you can reconstruct the whole raw MPEG stream without junk and meta data, or play games by actually modifying the frame body data before decoding this frame (mpg123_framebyframe_decode()). A more sane use would be to use this for CRC checking (see mpg123_info() and MPG123_CRC), the first two bytes of the body make up the CRC16 checksum, if present. You can provide NULL for a parameter pointer when you are not interested in the value.

headerthe 4-byte MPEG header
bodydatapointer to the frame body stored in the handle (without the header)
bodybytessize of frame body in bytes (without the header)
MPG123_OK if there was a yet un-decoded frame to get the data from, MPG123_BAD_HANDLE or MPG123_ERR otherwise (without further explanation, the error state of the mpg123_handle is not modified by this function).

Definition at line 626 of file frame.c.

628 if(mh == NULL) return MPG123_BAD_HANDLE;
629 if(!mh->to_decode) return MPG123_ERR;
631 if(header != NULL) *header = mh->oldhead;
632 if(bodydata != NULL) *bodydata = mh->bsbuf;
633 if(bodybytes != NULL) *bodybytes = mh->framesize;
635 return MPG123_OK;
unsigned long oldhead
Definition: frame.h:258
unsigned char * bsbuf
Definition: frame.h:254

◆ mpg123_framepos()

MPG123_EXPORT off_t mpg123_framepos ( mpg123_handle mh)

Get the input position (byte offset in stream) of the last parsed frame. This can be used for external seek index building, for example. It just returns the internally stored offset, regardless of validity – you ensure that a valid frame has been parsed before!

byte offset in stream

Definition at line 1054 of file frame.c.

1056 if(mh == NULL) return MPG123_ERR;
1058 return mh->input_offset;
off_t input_offset
Definition: frame.h:217

Referenced by mpg123_framepos().

◆ mpg123_open()

MPG123_EXPORT int mpg123_open ( mpg123_handle mh,
const char path 

Open and prepare to decode the specified file by filesystem path. This does not open HTTP urls; libmpg123 contains no networking code. If you want to decode internet streams, use mpg123_open_fd() or mpg123_open_feed().

pathfilesystem path
MPG123_OK on success

Definition at line 112 of file lfs_alias.c.

114 return NATIVE_NAME(mpg123_open)(mh, path);
int NATIVE_NAME() mpg123_open(mpg123_handle *mh, const char *path)
Definition: lfs_alias.c:112
#define NATIVE_NAME(func)
Definition: lfs_alias.c:52

Referenced by mpg123_open(), and mpg123_open_fixed().

◆ mpg123_open_fd()

MPG123_EXPORT int mpg123_open_fd ( mpg123_handle mh,
int  fd 

Use an already opened file descriptor as the bitstream input mpg123_close() will not close the file descriptor.

fdfile descriptor
MPG123_OK on success

Definition at line 118 of file lfs_alias.c.

120 return NATIVE_NAME(mpg123_open_fd)(mh, fd);
int NATIVE_NAME() mpg123_open_fd(mpg123_handle *mh, int fd)
Definition: lfs_alias.c:118
static int fd
Definition: io.c:51

Referenced by mpg123_open_fd().

◆ mpg123_open_feed()

MPG123_EXPORT int mpg123_open_feed ( mpg123_handle mh)

Open a new bitstream and prepare for direct feeding This works together with mpg123_decode(); you are responsible for reading and feeding the input bitstream. Also, you are expected to handle ICY metadata extraction yourself. This input method does not handle MPG123_ICY_INTERVAL. It does parse ID3 frames, though.

MPG123_OK on success

Definition at line 535 of file libmpg123.c.

537 if(mh == NULL) return MPG123_BAD_HANDLE;
539 mpg123_close(mh);
540 return open_feed(mh);
int attribute_align_arg mpg123_close(mpg123_handle *mh)
Definition: libmpg123.c:1694
#define open_feed
Definition: intsym.h:253

◆ mpg123_open_fixed()

MPG123_EXPORT int mpg123_open_fixed ( mpg123_handle mh,
const char path,
int  channels,
int  encoding 

Open a simple MPEG file with fixed properties.

This function shall simplify the common use case of a plain MPEG file on disk that you want to decode, with one fixed sample rate and channel count, and usually a length defined by a Lame/Info/Xing tag. It will:

  • set the MPG123_NO_FRANKENSTEIN flag
  • set up format support according to given parameters,
  • open the file,
  • query audio format,
  • fix the audio format support table to ensure the format stays the same,
  • call mpg123_scan() if there is no header frame to tell the track length.

From that on, you can call mpg123_getformat() for querying the sample rate (and channel count in case you allowed both) and mpg123_length() to get a pretty safe number for the duration. Only the sample rate is left open as that indeed is a fixed property of MPEG files. You could set MPG123_FORCE_RATE beforehand, but that may trigger low-quality resampling in the decoder, only do so if in dire need. The library will convert mono files to stereo for you, and vice versa. If any constraint cannot be satisified (most likely because of a non-default build of libmpg123), you get MPG123_ERR returned and can query the detailed cause from the handle. Only on MPG123_OK there will an open file that you then close using mpg123_close(), or implicitly on mpg123_delete() or the next call to open another file.

So, for your usual CD rip collection, you could use

mpg123_open_fixed(mh, path, MPG123_STEREO, MPG123_ENC_SIGNED_16)

and be happy calling mpg123_getformat() to verify 44100 Hz rate, then just playing away with mpg123_read(). The occasional mono file, or MP2 file, will also be decoded without you really noticing. Just the speed could be wrong if you do not care about sample rate at all.

pathfilesystem path
channelsallowed channel count, either 1 (MPG123_MONO) or 2 (MPG123_STEREO), or bitwise or of them, but then you're halfway back to calling mpg123_format() again;-)
encodinga definite encoding from enum mpg123_enc_enum or a bitmask like for mpg123_format(), defeating the purpose somewhat

Definition at line 105 of file lfs_alias.c.

int NATIVE_NAME() mpg123_open_fixed(mpg123_handle *mh, const char *path, int channels, int encoding)
Definition: lfs_alias.c:105
int This channels
Definition: rdpsnd_libao.c:37
static char * encoding
Definition: xmllint.c:155

Referenced by mpg123_open_fixed().

◆ mpg123_open_handle()

MPG123_EXPORT int mpg123_open_handle ( mpg123_handle mh,
void iohandle 

Use an opaque handle as bitstream input. This works only with the replaced I/O from mpg123_replace_reader_handle()! mpg123_close() will call the cleanup callback for your handle (if you gave one).

iohandleyour handle
MPG123_OK on success

Definition at line 124 of file lfs_alias.c.

126 return NATIVE_NAME(mpg123_open_handle)(mh, iohandle);
int NATIVE_NAME() mpg123_open_handle(mpg123_handle *mh, void *iohandle)
Definition: lfs_alias.c:124

Referenced by mpg123_open_handle().

◆ mpg123_read()

MPG123_EXPORT int mpg123_read ( mpg123_handle mh,
void outmemory,
size_t  outmemsize,
size_t done 

Read from stream and decode up to outmemsize bytes.

Note: The type of outmemory changed to a void pointer in mpg123 1.26.0 (API version 45).

outmemoryaddress of output buffer to write to
outmemsizemaximum number of bytes to write
doneaddress to store the number of actually decoded bytes to
MPG123_OK or error/message code

Definition at line 942 of file libmpg123.c.

944 return mpg123_decode(mh, NULL, 0, out, size, done);
int attribute_align_arg mpg123_decode(mpg123_handle *mh, const unsigned char *inmemory, size_t inmemsize, void *outmem, size_t outmemsize, size_t *done)
Definition: libmpg123.c:992
static FILE * out
Definition: regtests2xml.c:44