ReactOS  r73918
mpg123 output audio format

Enumerations

enum  mpg123_enc_enum {
  MPG123_ENC_8 = 0x00f, MPG123_ENC_16 = 0x040, MPG123_ENC_24 = 0x4000, MPG123_ENC_32 = 0x100,
  MPG123_ENC_SIGNED = 0x080, MPG123_ENC_FLOAT = 0xe00, 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|0x1000, MPG123_ENC_UNSIGNED_32 = MPG123_ENC_32|0x2000, MPG123_ENC_SIGNED_24 = MPG123_ENC_24|MPG123_ENC_SIGNED|0x1000, MPG123_ENC_UNSIGNED_24 = MPG123_ENC_24|0x2000,
  MPG123_ENC_FLOAT_32 = 0x200, MPG123_ENC_FLOAT_64 = 0x400, MPG123_ENC_ANY
}
 
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_format_support (mpg123_handle *mh, long rate, int encoding)
 
MPG123_EXPORT int mpg123_getformat (mpg123_handle *mh, long *rate, int *channels, int *encoding)
 

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.

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 ptimized 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

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

Enumerator
MPG123_MONO 
MPG123_STEREO 

Definition at line 423 of file mpg123.h.

424 {
425  MPG123_MONO = 1
426  ,MPG123_STEREO = 2
427 };

An enum over all sample types possibly known to mpg123. The values are designed as bit flags to allow bitmasking for encoding families.

Note that (your build of) libmpg123 does not necessarily support all these. Usually, you can expect the 8bit encodings and signed 16 bit. Also 32bit float will be usual beginning with mpg123-1.7.0 . What you should bear in mind is that (SSE, etc) optimized routines may be absent for some formats. We do have SSE for 16, 32 bit and float, though. 24 bit integer is done via postprocessing of 32 bit output – just cutting the last byte, no rounding, even. If you want better, do it yourself.

All formats are in native byte order. If you need different endinaness, you can simply postprocess the output buffers (libmpg123 wouldn't do anything else). mpg123_encsize() can be helpful there.

Enumerator
MPG123_ENC_8 

0000 0000 1111 Some 8 bit integer encoding.

MPG123_ENC_16 

0000 0100 0000 Some 16 bit integer encoding.

MPG123_ENC_24 

0100 0000 0000 0000 Some 24 bit integer encoding.

MPG123_ENC_32 

0001 0000 0000 Some 32 bit integer encoding.

MPG123_ENC_SIGNED 

0000 1000 0000 Some signed integer encoding.

MPG123_ENC_FLOAT 

1110 0000 0000 Some float encoding.

MPG123_ENC_SIGNED_16 

1101 0000 signed 16 bit

MPG123_ENC_UNSIGNED_16 

0110 0000 unsigned 16 bit

MPG123_ENC_UNSIGNED_8 

0000 0001 unsigned 8 bit

MPG123_ENC_SIGNED_8 

1000 0010 signed 8 bit

MPG123_ENC_ULAW_8 

0000 0100 ulaw 8 bit

MPG123_ENC_ALAW_8 

0000 1000 alaw 8 bit

MPG123_ENC_SIGNED_32 

0001 0001 1000 0000 signed 32 bit

MPG123_ENC_UNSIGNED_32 

0010 0001 0000 0000 unsigned 32 bit

MPG123_ENC_SIGNED_24 

0101 0000 1000 0000 signed 24 bit

MPG123_ENC_UNSIGNED_24 

0110 0000 0000 0000 unsigned 24 bit

MPG123_ENC_FLOAT_32 

0010 0000 0000 32bit float

MPG123_ENC_FLOAT_64 

0100 0000 0000 64bit float

MPG123_ENC_ANY 

Any encoding on the list.

Definition at line 395 of file mpg123.h.

396 {
397  MPG123_ENC_8 = 0x00f
398  ,MPG123_ENC_16 = 0x040
399  ,MPG123_ENC_24 = 0x4000
400  ,MPG123_ENC_32 = 0x100
401  ,MPG123_ENC_SIGNED = 0x080
402  ,MPG123_ENC_FLOAT = 0xe00
405  ,MPG123_ENC_UNSIGNED_8 = 0x01
407  ,MPG123_ENC_ULAW_8 = 0x04
408  ,MPG123_ENC_ALAW_8 = 0x08
413  ,MPG123_ENC_FLOAT_32 = 0x200
414  ,MPG123_ENC_FLOAT_64 = 0x400
420 };

Function Documentation

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 120 of file format.c.

121 {
122  if(list != NULL) *list = good_encodings;
123  if(number != NULL) *number = sizeof(good_encodings)/sizeof(int);
124 }
static size_t double number
Definition: printf.c:63
#define NULL
Definition: mystdio.h:57
static const int good_encodings[]
Definition: format.c:79
Definition: _list.h:228
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 126 of file format.c.

Referenced by frame_output_format().

127 {
128  if(encoding & MPG123_ENC_8)
129  return 1;
130  else if(encoding & MPG123_ENC_16)
131  return 2;
132  else if(encoding & MPG123_ENC_24)
133  return 3;
135  return 4;
136  else if(encoding == MPG123_ENC_FLOAT_64)
137  return 8;
138  else
139  return 0;
140 }
const XML_Char const XML_Char * encoding
Definition: expat.h:187
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
mhaudio decoder handle
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 405 of file format.c.

406 {
407  int r;
408  if(mh == NULL) return MPG123_BAD_HANDLE;
409  r = mpg123_fmt(&mh->p, rate, channels, encodings);
410  if(r != MPG123_OK){ mh->err = r; r = MPG123_ERR; }
411 
412  return r;
413 }
struct mpg123_pars_struct p
Definition: frame.h:286
GLdouble GLdouble GLdouble r
Definition: gl.h:2055
int This channels
Definition: rdpsnd_libao.c:37
int rate
Definition: pcmconverter.c:77
#define NULL
Definition: mystdio.h:57
int attribute_align_arg mpg123_fmt(mpg123_pars *mp, long rate, int channels, int encodings)
Definition: format.c:415
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.

Returns
MPG123_OK on success

Definition at line 379 of file format.c.

380 {
381  int r;
382  if(mh == NULL) return MPG123_BAD_HANDLE;
383 
384  r = mpg123_fmt_all(&mh->p);
385  if(r != MPG123_OK){ mh->err = r; r = MPG123_ERR; }
386 
387  return r;
388 }
struct mpg123_pars_struct p
Definition: frame.h:286
GLdouble GLdouble GLdouble r
Definition: gl.h:2055
#define NULL
Definition: mystdio.h:57
int attribute_align_arg mpg123_fmt_all(mpg123_pars *mp)
Definition: format.c:390
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

Returns
MPG123_OK on success

Definition at line 358 of file format.c.

359 {
360  int r;
361  if(mh == NULL) return MPG123_BAD_HANDLE;
362 
363  r = mpg123_fmt_none(&mh->p);
364  if(r != MPG123_OK){ mh->err = r; r = MPG123_ERR; }
365 
366  return r;
367 }
struct mpg123_pars_struct p
Definition: frame.h:286
GLdouble GLdouble GLdouble r
Definition: gl.h:2055
#define NULL
Definition: mystdio.h:57
int attribute_align_arg mpg123_fmt_none(mpg123_pars *mp)
Definition: format.c:369
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.

Returns
0 for no support (that includes invalid parameters), MPG123_STEREO, MPG123_MONO or MPG123_STEREO|MPG123_MONO.

Definition at line 442 of file format.c.

443 {
444  if(mh == NULL) return 0;
445  else return mpg123_fmt_support(&mh->p, rate, encoding);
446 }
struct mpg123_pars_struct p
Definition: frame.h:286
const XML_Char const XML_Char * encoding
Definition: expat.h:187
int rate
Definition: pcmconverter.c:77
#define NULL
Definition: mystdio.h:57
int attribute_align_arg mpg123_fmt_support(mpg123_pars *mp, long rate, int encoding)
Definition: format.c:448
MPG123_EXPORT int mpg123_getformat ( mpg123_handle mh,
long rate,
int channels,
int encoding 
)

Get the current output format written to the addresses given.

Returns
MPG123_OK on success

Definition at line 1037 of file libmpg123.c.

1038 {
1039  int b;
1040 
1041  if(mh == NULL) return MPG123_BAD_HANDLE;
1042  b = init_track(mh);
1043  if(b < 0) return b;
1044 
1045  if(rate != NULL) *rate = mh->af.rate;
1046  if(channels != NULL) *channels = mh->af.channels;
1047  if(encoding != NULL) *encoding = mh->af.encoding;
1048  mh->new_format = 0;
1049  return MPG123_OK;
1050 }
const XML_Char const XML_Char * encoding
Definition: expat.h:187
int This channels
Definition: rdpsnd_libao.c:37
int rate
Definition: pcmconverter.c:77
#define NULL
Definition: mystdio.h:57
#define b
Definition: ke_i.h:79
struct audioformat af
Definition: frame.h:265
static int init_track(mpg123_handle *mh)
Definition: libmpg123.c:988
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.

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

Definition at line 113 of file format.c.

114 {
115  if(list != NULL) *list = my_rates;
116  if(number != NULL) *number = sizeof(my_rates)/sizeof(long);
117 }
static const long my_rates[MPG123_RATES]
Definition: format.c:32
static size_t double number
Definition: printf.c:63
#define NULL
Definition: mystdio.h:57
Definition: _list.h:228