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 | |
| void | mpg123_rates (const long **list, size_t *number) |
| void | mpg123_encodings (const int **list, size_t *number) |
| int | mpg123_encsize (int encoding) |
| int | mpg123_format_none (mpg123_handle *mh) |
| int | mpg123_format_all (mpg123_handle *mh) |
| int | mpg123_format (mpg123_handle *mh, long rate, int channels, int encodings) |
| int | mpg123_format_support (mpg123_handle *mh, long rate, int encoding) |
| int | mpg123_getformat (mpg123_handle *mh, long *rate, int *channels, int *encoding) |
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.
| enum mpg123_enc_enum |
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.
| enum mpg123_channelcount |
| 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.
| list | Store a pointer to the sample rates array there. | |
| number | Store the number of sample rates there. |
| 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).
| list | Store a pointer to the encodings array there. | |
| number | Store the number of encodings there. |
| int mpg123_encsize | ( | int | encoding | ) |
Return the size (in bytes) of one mono sample of the named encoding.
| encoding | The encoding value to analyze. |
| 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
| int mpg123_format_all | ( | mpg123_handle * | mh | ) |
Configure mpg123 handle to accept all formats (also any custom rate you may set) -- this is default.
| int mpg123_format | ( | mpg123_handle * | mh, | |
| long | rate, | |||
| int | channels, | |||
| int | encodings | |||
| ) |
Set the audio format support of a mpg123_handle in detail:
| mh | audio decoder handle | |
| rate | The sample rate value (in Hertz). | |
| channels | A combination of MPG123_STEREO and MPG123_MONO. | |
| encodings | A 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. |
| 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.
| int mpg123_getformat | ( | mpg123_handle * | mh, | |
| long * | rate, | |||
| int * | channels, | |||
| int * | encoding | |||
| ) |
Get the current output format written to the addresses givenr.
1.5.6