1/*
2 libmpg123: MPEG Audio Decoder library
3
4 separate header just for audio format definitions not tied to
5 library code
6
7 copyright 1995-2020 by the mpg123 project
8 free software under the terms of the LGPL 2.1
9 see COPYING and AUTHORS files in distribution or http://mpg123.org
10*/
11
12#ifndef MPG123_ENC_H
13#define MPG123_ENC_H
14
15/** \file fmt123.h Audio format definitions. */
16
17/** \defgroup mpg123_enc mpg123 PCM sample encodings
18 * These are definitions for audio formats used by libmpg123 and
19 * libout123.
20 *
21 * @{
22 */
23
24/** An enum over all sample types possibly known to mpg123.
25 * The values are designed as bit flags to allow bitmasking for encoding
26 * families.
27 * This is also why the enum is not used as type for actual encoding variables,
28 * plain integers (at least 16 bit, 15 bit being used) cover the possible
29 * combinations of these flags.
30 *
31 * Note that (your build of) libmpg123 does not necessarily support all these.
32 * Usually, you can expect the 8bit encodings and signed 16 bit.
33 * Also 32bit float will be usual beginning with mpg123-1.7.0 .
34 * What you should bear in mind is that (SSE, etc) optimized routines may be
35 * absent for some formats. We do have SSE for 16, 32 bit and float, though.
36 * 24 bit integer is done via postprocessing of 32 bit output -- just cutting
37 * the last byte, no rounding, even. If you want better, do it yourself.
38 *
39 * All formats are in native byte order. If you need different endinaness, you
40 * can simply postprocess the output buffers (libmpg123 wouldn't do anything
41 * else). The macro MPG123_SAMPLESIZE() can be helpful there.
42 */
43enum mpg123_enc_enum
44{
45/* 0000 0000 0000 1111 Some 8 bit integer encoding. */
46 MPG123_ENC_8 = 0x00f
47/* 0000 0000 0100 0000 Some 16 bit integer encoding. */
48, MPG123_ENC_16 = 0x040
49/* 0100 0000 0000 0000 Some 24 bit integer encoding. */
50, MPG123_ENC_24 = 0x4000
51/* 0000 0001 0000 0000 Some 32 bit integer encoding. */
52, MPG123_ENC_32 = 0x100
53/* 0000 0000 1000 0000 Some signed integer encoding. */
54, MPG123_ENC_SIGNED = 0x080
55/* 0000 1110 0000 0000 Some float encoding. */
56, MPG123_ENC_FLOAT = 0xe00
57/* 0000 0000 1101 0000 signed 16 bit */
58, MPG123_ENC_SIGNED_16 = (MPG123_ENC_16|MPG123_ENC_SIGNED|0x10)
59/* 0000 0000 0110 0000 unsigned 16 bit */
60, MPG123_ENC_UNSIGNED_16 = (MPG123_ENC_16|0x20)
61/* 0000 0000 0000 0001 unsigned 8 bit */
62, MPG123_ENC_UNSIGNED_8 = 0x01
63/* 0000 0000 1000 0010 signed 8 bit */
64, MPG123_ENC_SIGNED_8 = (MPG123_ENC_SIGNED|0x02)
65/* 0000 0000 0000 0100 ulaw 8 bit */
66, MPG123_ENC_ULAW_8 = 0x04
67/* 0000 0000 0000 1000 alaw 8 bit */
68, MPG123_ENC_ALAW_8 = 0x08
69/* 0001 0001 1000 0000 signed 32 bit */
70, MPG123_ENC_SIGNED_32 = MPG123_ENC_32|MPG123_ENC_SIGNED|0x1000
71/* 0010 0001 0000 0000 unsigned 32 bit */
72, MPG123_ENC_UNSIGNED_32 = MPG123_ENC_32|0x2000
73/* 0101 0000 1000 0000 signed 24 bit */
74, MPG123_ENC_SIGNED_24 = MPG123_ENC_24|MPG123_ENC_SIGNED|0x1000
75/* 0110 0000 0000 0000 unsigned 24 bit */
76, MPG123_ENC_UNSIGNED_24 = MPG123_ENC_24|0x2000
77/* 0000 0010 0000 0000 32bit float */
78, MPG123_ENC_FLOAT_32 = 0x200
79/* 0000 0100 0000 0000 64bit float */
80, MPG123_ENC_FLOAT_64 = 0x400
81/* Any possibly known encoding from the list above. */
82, MPG123_ENC_ANY = ( MPG123_ENC_SIGNED_16 | MPG123_ENC_UNSIGNED_16
83 | MPG123_ENC_UNSIGNED_8 | MPG123_ENC_SIGNED_8
84 | MPG123_ENC_ULAW_8 | MPG123_ENC_ALAW_8
85 | MPG123_ENC_SIGNED_32 | MPG123_ENC_UNSIGNED_32
86 | MPG123_ENC_SIGNED_24 | MPG123_ENC_UNSIGNED_24
87 | MPG123_ENC_FLOAT_32 | MPG123_ENC_FLOAT_64 )
88};
89
90/** Get size of one PCM sample with given encoding.
91 * This is included both in libmpg123 and libout123. Both offer
92 * an API function to provide the macro results from library
93 * compile-time, not that of you application. This most likely
94 * does not matter as I do not expect any fresh PCM sample
95 * encoding to appear. But who knows? Perhaps the encoding type
96 * will be abused for funny things in future, not even plain PCM.
97 * And, by the way: Thomas really likes the ?: operator.
98 * \param enc the encoding (mpg123_enc_enum value)
99 * \return size of one sample in bytes
100 */
101#define MPG123_SAMPLESIZE(enc) ( \
102 (enc) < 1 \
103 ? 0 \
104 : ( (enc) & MPG123_ENC_8 \
105 ? 1 \
106 : ( (enc) & MPG123_ENC_16 \
107 ? 2 \
108 : ( (enc) & MPG123_ENC_24 \
109 ? 3 \
110 : ( ( (enc) & MPG123_ENC_32 \
111 || (enc) == MPG123_ENC_FLOAT_32 ) \
112 ? 4 \
113 : ( (enc) == MPG123_ENC_FLOAT_64 \
114 ? 8 \
115 : 0 \
116) ) ) ) ) )
117
118/** Representation of zero in differing encodings.
119 * This exists to define proper silence in various encodings without
120 * having to link to libsyn123 to do actual conversions at runtime.
121 * You have to handle big/little endian order yourself, though.
122 * This takes the shortcut that any signed encoding has a zero with
123 * all-zero bits. Unsigned linear encodings just have the highest bit set
124 * (2^(n-1) for n bits), while the nonlinear 8-bit ones are special.
125 * \param enc the encoding (mpg123_enc_enum value)
126 * \param siz bytes per sample (return value of MPG123_SAMPLESIZE(enc))
127 * \param off byte (octet) offset counted from LSB
128 * \return unsigned byte value for the designated octet
129 */
130#define MPG123_ZEROSAMPLE(enc, siz, off) ( \
131 (enc) == MPG123_ENC_ULAW_8 \
132 ? (off == 0 ? 0xff : 0x00) \
133 : ( (enc) == MPG123_ENC_ALAW_8 \
134 ? (off == 0 ? 0xd5 : 0x00) \
135 : ( (((enc) & (MPG123_ENC_SIGNED|MPG123_ENC_FLOAT)) || (siz) != ((off)+1)) \
136 ? 0x00 \
137 : 0x80 \
138 ) ) )
139
140/** Structure defining an audio format.
141 * Providing the members as individual function arguments to define a certain
142 * output format is easy enough. This struct makes is more comfortable to deal
143 * with a list of formats.
144 * Negative values for the members might be used to communicate use of default
145 * values.
146 */
147struct mpg123_fmt
148{
149 long rate; /**< sampling rate in Hz */
150 int channels; /**< channel count */
151 /** encoding code, can be single value or bitwise or of members of
152 * mpg123_enc_enum */
153 int encoding;
154};
155
156/** @} */
157
158#endif
159
160