ReactOS  0.4.15-dev-483-ga77a65a
mpg123 output audio format

Enumerations

enum  mpg123_channelcount { MPG123_MONO = 1, MPG123_STEREO = 2 }
 

Functions

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)
 

Detailed Description

Functions to get and select the format of the decoded audio.

Before you dive in, please be warned that you might get confused by this. This seems to happen a lot, therefore I am trying to explain in advance. If you do feel confused and just want to decode your normal MPEG audio files that don't alter properties in the middle, just use mpg123_open_fixed() with a fixed encoding and channel count and forget about a matrix of audio formats. If you want to get funky, read ahead ...

The mpg123 library decides what output format to use when encountering the first frame in a stream, or actually any frame that is still valid but differs from the frames before in the prompted output format. At such a deciding point, an internal table of allowed encodings, sampling rates and channel setups is consulted. According to this table, an output format is chosen and the decoding engine set up accordingly (including optimized routines for different output formats). This might seem unusual but it just follows from the non-existence of "MPEG audio files" with defined overall properties. There are streams, streams are concatenations of (semi) independent frames. We store streams on disk and call them "MPEG audio files", but that does not change their nature as the decoder is concerned (the LAME/Xing header for gapless decoding makes things interesting again).

To get to the point: What you do with mpg123_format() and friends is to fill the internal table of allowed formats before it is used. That includes removing support for some formats or adding your forced sample rate (see MPG123_FORCE_RATE) that will be used with the crude internal resampler. Also keep in mind that the sample encoding is just a question of choice – the MPEG frames do only indicate their native sampling rate and channel count. If you want to decode to integer or float samples, 8 or 16 bit ... that is your decision. In a "clean" world, libmpg123 would always decode to 32 bit float and let you handle any sample conversion. But there are optimized routines that work faster by directly decoding to the desired encoding / accuracy. We prefer efficiency over conceptual tidyness.

People often start out thinking that mpg123_format() should change the actual decoding format on the fly. That is wrong. It only has effect on the next natural change of output format, when libmpg123 will consult its format table again. To make life easier, you might want to call mpg123_format_none() before any thing else and then just allow one desired encoding and a limited set of sample rates / channel choices that you actually intend to deal with. You can force libmpg123 to decode everything to 44100 KHz, stereo, 16 bit integer ... it will duplicate mono channels and even do resampling if needed (unless that feature is disabled in the build, same with some encodings). But I have to stress that the resampling of libmpg123 is very crude and doesn't even contain any kind of "proper" interpolation.

In any case, watch out for MPG123_NEW_FORMAT as return message from decoding routines and call mpg123_getformat() to get the currently active output format.

Enumeration Type Documentation

◆ mpg123_channelcount

They can be combined into one number (3) to indicate mono and stereo...

Enumerator
MPG123_MONO 

mono

MPG123_STEREO 

stereo

Definition at line 515 of file mpg123.h.

516 {
517  MPG123_MONO = 1
518  ,MPG123_STEREO = 2
519 };

Function Documentation

◆ mpg123_encodings()

MPG123_EXPORT void mpg123_encodings ( const int **  list,
size_t number 
)

An array of supported audio encodings. An audio encoding is one of the fully qualified members of mpg123_enc_enum (MPG123_ENC_SIGNED_16, not MPG123_SIGNED).

Parameters
listStore a pointer to the encodings array there.
numberStore the number of encodings there.

Definition at line 125 of file format.c.

126 {
127  if(list != NULL) *list = good_encodings;
128  if(number != NULL) *number = sizeof(good_encodings)/sizeof(int);
129 }
static size_t double number
Definition: printf.c:69
static const int good_encodings[]
Definition: format.c:84
smooth NULL
Definition: ftsmooth.c:416
Definition: _list.h:228

◆ mpg123_encsize()

MPG123_EXPORT int mpg123_encsize ( int  encoding)

Return the size (in bytes) of one mono sample of the named encoding.

Parameters
encodingThe encoding value to analyze.
Returns
positive size of encoding in bytes, 0 on invalid encoding.

Definition at line 131 of file format.c.

132 {
133  return MPG123_SAMPLESIZE(encoding);
134 }
#define MPG123_SAMPLESIZE(enc)
Definition: fmt123.h:101
ed encoding
Definition: write.c:2825

Referenced by frame_output_format(), and postprocess_buffer().

◆ mpg123_format()

MPG123_EXPORT int mpg123_format ( mpg123_handle mh,
long  rate,
int  channels,
int  encodings 
)

Set the audio format support of a mpg123_handle in detail:

Parameters
mhhandle
rateThe sample rate value (in Hertz).
channelsA combination of MPG123_STEREO and MPG123_MONO.
encodingsA combination of accepted encodings for rate and channels, p.ex MPG123_ENC_SIGNED16 | MPG123_ENC_ULAW_8 (or 0 for no support). Please note that some encodings may not be supported in the library build and thus will be ignored here.
Returns
MPG123_OK on success, MPG123_ERR if there was an error.

Definition at line 475 of file format.c.

476 {
477  int r;
478  if(mh == NULL) return MPG123_BAD_HANDLE;
479  r = mpg123_fmt(&mh->p, rate, channels, encodings);
480  if(r != MPG123_OK){ mh->err = r; r = MPG123_ERR; }
481 
482  return r;
483 }
struct mpg123_pars_struct p
Definition: frame.h:289
GLdouble GLdouble GLdouble r
Definition: gl.h:2055
int This channels
Definition: rdpsnd_libao.c:37
int rate
Definition: pcmconverter.c:97
smooth NULL
Definition: ftsmooth.c:416
int attribute_align_arg mpg123_fmt(mpg123_pars *mp, long rate, int channels, int encodings)
Definition: format.c:524

Referenced by open_fixed_post().

◆ mpg123_format2()

MPG123_EXPORT int mpg123_format2 ( mpg123_handle mh,
long  rate,
int  channels,
int  encodings 
)

Set the audio format support of a mpg123_handle in detail:

Parameters
mhhandle
rateThe sample rate value (in Hertz). Special value 0 means all rates (the reason for this variant of mpg123_format()).
channelsA combination of MPG123_STEREO and MPG123_MONO.
encodingsA combination of accepted encodings for rate and channels, p.ex MPG123_ENC_SIGNED16 | MPG123_ENC_ULAW_8 (or 0 for no support). Please note that some encodings may not be supported in the library build and thus will be ignored here.
Returns
MPG123_OK on success, MPG123_ERR if there was an error.

Definition at line 464 of file format.c.

465 {
466  int r;
467  if(mh == NULL) return MPG123_BAD_HANDLE;
468  r = mpg123_fmt2(&mh->p, rate, channels, encodings);
469  if(r != MPG123_OK){ mh->err = r; r = MPG123_ERR; }
470 
471  return r;
472 }
struct mpg123_pars_struct p
Definition: frame.h:289
GLdouble GLdouble GLdouble r
Definition: gl.h:2055
int This channels
Definition: rdpsnd_libao.c:37
int rate
Definition: pcmconverter.c:97
smooth NULL
Definition: ftsmooth.c:416
int attribute_align_arg mpg123_fmt2(mpg123_pars *mp, long rate, int channels, int encodings)
Definition: format.c:485

Referenced by open_fixed_pre().

◆ mpg123_format_all()

MPG123_EXPORT int mpg123_format_all ( mpg123_handle mh)

Configure mpg123 handle to accept all formats (also any custom rate you may set) – this is default.

Parameters
mhhandle
Returns
MPG123_OK on success

Definition at line 438 of file format.c.

439 {
440  int r;
441  if(mh == NULL) return MPG123_BAD_HANDLE;
442 
443  r = mpg123_fmt_all(&mh->p);
444  if(r != MPG123_OK){ mh->err = r; r = MPG123_ERR; }
445 
446  return r;
447 }
struct mpg123_pars_struct p
Definition: frame.h:289
GLdouble GLdouble GLdouble r
Definition: gl.h:2055
smooth NULL
Definition: ftsmooth.c:416
int attribute_align_arg mpg123_fmt_all(mpg123_pars *mp)
Definition: format.c:449

◆ mpg123_format_none()

MPG123_EXPORT int mpg123_format_none ( mpg123_handle mh)

Configure a mpg123 handle to accept no output format at all, use before specifying supported formats with mpg123_format

Parameters
mhhandle
Returns
MPG123_OK on success

Definition at line 417 of file format.c.

418 {
419  int r;
420  if(mh == NULL) return MPG123_BAD_HANDLE;
421 
422  r = mpg123_fmt_none(&mh->p);
423  if(r != MPG123_OK){ mh->err = r; r = MPG123_ERR; }
424 
425  return r;
426 }
struct mpg123_pars_struct p
Definition: frame.h:289
GLdouble GLdouble GLdouble r
Definition: gl.h:2055
smooth NULL
Definition: ftsmooth.c:416
int attribute_align_arg mpg123_fmt_none(mpg123_pars *mp)
Definition: format.c:428

Referenced by open_fixed_post(), and open_fixed_pre().

◆ mpg123_format_support()

MPG123_EXPORT int mpg123_format_support ( mpg123_handle mh,
long  rate,
int  encoding 
)

Check to see if a specific format at a specific rate is supported by mpg123_handle.

Parameters
mhhandle
ratesampling rate
encodingencoding
Returns
0 for no support (that includes invalid parameters), MPG123_STEREO, MPG123_MONO or MPG123_STEREO|MPG123_MONO.

Definition at line 531 of file format.c.

532 {
533  if(mh == NULL) return 0;
534  else return mpg123_fmt_support(&mh->p, rate, encoding);
535 }
struct mpg123_pars_struct p
Definition: frame.h:289
int rate
Definition: pcmconverter.c:97
smooth NULL
Definition: ftsmooth.c:416
ed encoding
Definition: write.c:2825
int attribute_align_arg mpg123_fmt_support(mpg123_pars *mp, long rate, int encoding)
Definition: format.c:537

◆ mpg123_getformat()

MPG123_EXPORT int mpg123_getformat ( mpg123_handle mh,
long rate,
int channels,
int encoding 
)

Get the current output format written to the addresses given. If the stream is freshly loaded, this will try to parse enough of it to give you the format to come. This clears the flag that would otherwise make the first decoding call return MPG123_NEW_FORMAT.

Parameters
mhhandle
ratesampling rate return address
channelschannel count return address
encodingencoding return address
Returns
MPG123_OK on success

Definition at line 1141 of file libmpg123.c.

1142 {
1143  return mpg123_getformat2(mh, rate, channels, encoding, 1);
1144 }
int attribute_align_arg mpg123_getformat2(mpg123_handle *mh, long *rate, int *channels, int *encoding, int clear_flag)
Definition: libmpg123.c:1125
int This channels
Definition: rdpsnd_libao.c:37
int rate
Definition: pcmconverter.c:97
ed encoding
Definition: write.c:2825

Referenced by open_fixed_post().

◆ mpg123_getformat2()

MPG123_EXPORT int mpg123_getformat2 ( mpg123_handle mh,
long rate,
int channels,
int encoding,
int  clear_flag 
)

Get the current output format written to the addresses given. This differs from plain mpg123_getformat() in that you can choose not to clear the flag that would trigger the next decoding call to return MPG123_NEW_FORMAT in case of a new format arriving.

Parameters
mhhandle
ratesampling rate return address
channelschannel count return address
encodingencoding return address
clear_flagif true, clear internal format flag
Returns
MPG123_OK on success

Definition at line 1125 of file libmpg123.c.

1127 {
1128  int b;
1129 
1130  if(mh == NULL) return MPG123_BAD_HANDLE;
1131  b = init_track(mh);
1132  if(b < 0) return b;
1133 
1134  if(rate != NULL) *rate = mh->af.rate;
1135  if(channels != NULL) *channels = mh->af.channels;
1136  if(encoding != NULL) *encoding = mh->af.encoding;
1137  if(clear_flag) mh->new_format = 0;
1138  return MPG123_OK;
1139 }
int This channels
Definition: rdpsnd_libao.c:37
int rate
Definition: pcmconverter.c:97
smooth NULL
Definition: ftsmooth.c:416
#define b
Definition: ke_i.h:79
GLboolean GLboolean GLboolean b
Definition: glext.h:6204
ed encoding
Definition: write.c:2825
struct audioformat af
Definition: frame.h:268
static int init_track(mpg123_handle *mh)
Definition: libmpg123.c:1076

Referenced by mpg123_getformat().

◆ mpg123_rates()

MPG123_EXPORT void mpg123_rates ( const long **  list,
size_t number 
)

An array of supported standard sample rates These are possible native sample rates of MPEG audio files. You can still force mpg123 to resample to a different one, but by default you will only get audio in one of these samplings. This list is in ascending order.

Parameters
listStore a pointer to the sample rates array there.
numberStore the number of sample rates there.

Definition at line 118 of file format.c.

119 {
120  if(list != NULL) *list = my_rates;
121  if(number != NULL) *number = sizeof(my_rates)/sizeof(long);
122 }
static const long my_rates[MPG123_RATES]
Definition: format.c:33
static size_t double number
Definition: printf.c:69
smooth NULL
Definition: ftsmooth.c:416
Definition: _list.h:228