README.md
1minimp3
2==========
3
4[![Build Status](https://travis-ci.org/lieff/minimp3.svg)](https://travis-ci.org/lieff/minimp3)
5<a href="https://scan.coverity.com/projects/lieff-minimp3">
6 <img alt="Coverity Scan Build Status"
7 src="https://scan.coverity.com/projects/14844/badge.svg"/>
8</a>
9[![codecov](https://codecov.io/gh/lieff/minimp3/branch/master/graph/badge.svg)](https://codecov.io/gh/lieff/minimp3)
10
11Minimalistic, single-header library for decoding MP3. minimp3 is designed to be
12small, fast (with SSE and NEON support), and accurate (ISO conformant). You can
13find a rough benchmark below, measured using ``perf`` on an i7-6700K, IO
14included, no CPU heat to address speedstep:
15
16| Vector | Hz | Samples| Sec | Clockticks | Clockticks per second | PSNR | Max diff |
17| ----------- | ----- | ------ | ------ | --------- | ------ | ------ | - |
18|compl.bit | 48000 | 248832 | 5.184 | 14306684 | 2.759M | 124.22 | 1 |
19|he_32khz.bit | 32000 | 172800 | 5.4 | 8426158 | 1.560M | 139.67 | 1 |
20|he_44khz.bit | 44100 | 472320 | 10.710 | 21296300 | 1.988M | 144.04 | 1 |
21|he_48khz.bit | 48000 | 172800 | 3.6 | 8453846 | 2.348M | 139.67 | 1 |
22|hecommon.bit | 44100 | 69120 | 1.567 | 3169715 | 2.022M | 133.93 | 1 |
23|he_free.bit | 44100 | 156672 | 3.552 | 5798418 | 1.632M | 137.48 | 1 |
24|he_mode.bit | 44100 | 262656 | 5.955 | 9882314 | 1.659M | 118.00 | 1 |
25|si.bit | 44100 | 135936 | 3.082 | 7170520 | 2.326M | 120.30 | 1 |
26|si_block.bit | 44100 | 73728 | 1.671 | 4233136 | 2.533M | 125.18 | 1 |
27|si_huff.bit | 44100 | 86400 | 1.959 | 4785322 | 2.442M | 107.98 | 1 |
28|sin1k0db.bit | 44100 | 725760 | 16.457 | 24842977 | 1.509M | 111.03 | 1 |
29
30Conformance test passed on all vectors (PSNR > 96db).
31
32## Comparison with keyj's [minimp3](http://keyj.emphy.de/minimp3/)
33
34Comparison by features:
35
36| Keyj minimp3 | Current |
37| ------------ | ------- |
38| Fixed point | Floating point |
39| source: 84kb | 70kb |
40| binary: 34kb (20kb compressed) | 30kb (20kb) |
41| no vector opts | SSE/NEON intrinsics |
42| no free format | free format support |
43
44Below, you can find the benchmark and conformance test for keyj's minimp3:
45
46
47| Vector | Hz | Samples| Sec | Clockticks | Clockticks per second | PSNR | Max diff |
48| ----------- | ----- | ------ | ------ | --------- | ------ | ----- | - |
49|compl.bit | 48000 | 248832 | 5.184 | 31849373 | 6.143M | 71.50 | 41 |
50|he_32khz.bit | 32000 | 172800 | 5.4 | 26302319 | 4.870M | 71.63 | 24 |
51|he_44khz.bit | 44100 | 472320 | 10.710 | 41628861 | 3.886M | 71.63 | 24 |
52|he_48khz.bit | 48000 | 172800 | 3.6 | 25899527 | 7.194M | 71.63 | 24 |
53|hecommon.bit | 44100 | 69120 | 1.567 | 20437779 | 13.039M | 71.58 | 25 |
54|he_free.bit | 44100 | 0 | 0 | - | - | - | - |
55|he_mode.bit | 44100 | 262656 | 5.955 | 30988984 | 5.203M | 71.78 | 27 |
56|si.bit | 44100 | 135936 | 3.082 | 24096223 | 7.817M | 72.35 | 36 |
57|si_block.bit | 44100 | 73728 | 1.671 | 20722017 | 12.394M | 71.84 | 26 |
58|si_huff.bit | 44100 | 86400 | 1.959 | 21121376 | 10.780M | 27.80 | 65535 |
59|sin1k0db.bit | 44100 | 730368 | 16.561 | 55569636 | 3.355M | 0.15 | 58814 |
60
61Keyj minimp3 conformance test fails on all vectors (PSNR < 96db), and free
62format is unsupported. This caused some problems when it was used
63[here](https://github.com/lieff/lvg), and was the main motivation for this work.
64
65## Usage
66
67First, we need to initialize the decoder structure:
68
69```c
70//#define MINIMP3_ONLY_MP3
71//#define MINIMP3_ONLY_SIMD
72//#define MINIMP3_NO_SIMD
73//#define MINIMP3_NONSTANDARD_BUT_LOGICAL
74//#define MINIMP3_FLOAT_OUTPUT
75#define MINIMP3_IMPLEMENTATION
76#include "minimp3.h"
77...
78 static mp3dec_t mp3d;
79 mp3dec_init(&mp3d);
80```
81
82Note that you must define ``MINIMP3_IMPLEMENTATION`` in exactly one source file.
83You can ``#include`` ``minimp3.h`` in as many files as you like.
84Also you can use ``MINIMP3_ONLY_MP3`` define to strip MP1/MP2 decoding code.
85MINIMP3_ONLY_SIMD define controls generic (non SSE/NEON) code generation (always enabled on x64/arm64 targets).
86In case you do not want any platform-specific SIMD optimizations, you can define ``MINIMP3_NO_SIMD``.
87MINIMP3_NONSTANDARD_BUT_LOGICAL define saves some code bytes, and enforces non-stadnard but logical behaviour of mono-stereo transition (rare case).
88MINIMP3_FLOAT_OUTPUT makes ``mp3dec_decode_frame()`` output to be float instead of short and additional function mp3dec_f32_to_s16 will be available for float->short conversion if needed.
89
90Then. we decode the input stream frame-by-frame:
91
92```c
93 /*typedef struct
94 {
95 int frame_bytes;
96 int channels;
97 int hz;
98 int layer;
99 int bitrate_kbps;
100 } mp3dec_frame_info_t;*/
101 mp3dec_frame_info_t info;
102 short pcm[MINIMP3_MAX_SAMPLES_PER_FRAME];
103 /*unsigned char *input_buf; - input byte stream*/
104 samples = mp3dec_decode_frame(&mp3d, input_buf, buf_size, pcm, &info);
105```
106
107The ``mp3dec_decode_frame()`` function decodes one full MP3 frame from the
108input buffer, which must be large enough to hold one full frame.
109
110The decoder will analyze the input buffer to properly sync with the MP3 stream,
111and will skip ID3 data, as well as any data which is not valid. Short buffers
112may cause false sync and can produce 'squealing' artefacts. The bigger the size
113of the input buffer, the more reliable the sync procedure. We recommend having
114as many as 10 consecutive MP3 frames (~16KB) in the input buffer at a time.
115
116The size of the consumed MP3 data is returned in the ``mp3dec_frame_info_t``
117field of the ``frame_bytes`` struct; you must remove the data corresponding to
118the ``frame_bytes`` field from the input buffer before the next decoder
119invocation.
120
121The decoding function returns the number of decoded samples. The following cases
122are possible:
123
124- **0:** No MP3 data was found in the input buffer
125- **384:** Layer 1
126- **576:** MPEG 2 Layer 3
127- **1152:** Otherwise
128
129The following is a description of the possible combinations of the number of
130samples and ``frame_bytes`` field values:
131
132- More than 0 samples and ``frame_bytes > 0``: Succesful decode
133- 0 samples and ``frame_bytes > 0``: The decoder skipped ID3 or invalid data
134- 0 samples and ``frame_bytes == 0``: Insufficient data
135
136If ``frame_bytes == 0``, the other fields may be uninitialized or unchanged; if
137``frame_bytes != 0``, the other fields are available. The application may call
138``mp3dec_init()`` when changing decode position, but this is not necessary.
139
140As a special case, the decoder supports already split MP3 streams (for example,
141after doing an MP4 demux). In this case, the input buffer must contain _exactly
142one_ non-free-format frame.
143
144## Seeking
145
146You can seek to any byte in the stream and call ``mp3dec_decode_frame``; this
147will work in almost all cases, but is not completely guaranteed. Probablility of
148sync procedure failure lowers when MAX_FRAME_SYNC_MATCHES value grows. Default
149MAX_FRAME_SYNC_MATCHES=10 and probablility of sync failure should be very low.
150If granule data is accidentally detected as a valid MP3 header, short audio artefacting is
151possible.
152
153High-level mp3dec_ex_seek function supports precise seek to sample (MP3D_SEEK_TO_SAMPLE)
154using index and binary search.
155
156## Track length detect
157
158If the file is known to be cbr, then all frames have equal size and
159lack ID3 tags, which allows us to decode the first frame and calculate all frame
160positions as ``frame_bytes * N``. However, because of padding, frames can differ
161in size even in this case.
162
163In general case whole stream scan is needed to calculate it's length. Scan can be
164omitted if vbr tag is present (added by encoders like lame and ffmpeg), which contains
165length info. High-level functions automatically use the vbr tag if present.
166
167## High-level API
168
169If you need only decode file/buffer or use precise seek, you can use optional high-level API.
170Just ``#include`` ``minimp3_ex.h`` instead and use following additional functions:
171
172```c
173#define MP3D_SEEK_TO_BYTE 0
174#define MP3D_SEEK_TO_SAMPLE 1
175
176#define MINIMP3_PREDECODE_FRAMES 2 /* frames to pre-decode and skip after seek (to fill internal structures) */
177/*#define MINIMP3_SEEK_IDX_LINEAR_SEARCH*/ /* define to use linear index search instead of binary search on seek */
178#define MINIMP3_IO_SIZE (128*1024) /* io buffer size for streaming functions, must be greater than MINIMP3_BUF_SIZE */
179#define MINIMP3_BUF_SIZE (16*1024) /* buffer which can hold minimum 10 consecutive mp3 frames (~16KB) worst case */
180#define MINIMP3_ENABLE_RING 0 /* enable hardware magic ring buffer if available, to make less input buffer memmove(s) in callback IO mode */
181
182#define MP3D_E_MEMORY -1
183#define MP3D_E_IOERROR -2
184
185typedef struct
186{
187 mp3d_sample_t *buffer;
188 size_t samples; /* channels included, byte size = samples*sizeof(mp3d_sample_t) */
189 int channels, hz, layer, avg_bitrate_kbps;
190} mp3dec_file_info_t;
191
192typedef size_t (*MP3D_READ_CB)(void *buf, size_t size, void *user_data);
193typedef int (*MP3D_SEEK_CB)(uint64_t position, void *user_data);
194
195typedef struct
196{
197 MP3D_READ_CB read;
198 void *read_data;
199 MP3D_SEEK_CB seek;
200 void *seek_data;
201} mp3dec_io_t;
202
203typedef struct
204{
205 uint64_t samples;
206 mp3dec_frame_info_t info;
207 int last_error;
208 ...
209} mp3dec_ex_t;
210
211typedef int (*MP3D_ITERATE_CB)(void *user_data, const uint8_t *frame, int frame_size, int free_format_bytes, size_t buf_size, uint64_t offset, mp3dec_frame_info_t *info);
212typedef int (*MP3D_PROGRESS_CB)(void *user_data, size_t file_size, uint64_t offset, mp3dec_frame_info_t *info);
213
214/* decode whole buffer block */
215int mp3dec_load_buf(mp3dec_t *dec, const uint8_t *buf, size_t buf_size, mp3dec_file_info_t *info, MP3D_PROGRESS_CB progress_cb, void *user_data);
216int mp3dec_load_cb(mp3dec_t *dec, mp3dec_io_t *io, uint8_t *buf, size_t buf_size, mp3dec_file_info_t *info, MP3D_PROGRESS_CB progress_cb, void *user_data);
217/* iterate through frames */
218int mp3dec_iterate_buf(const uint8_t *buf, size_t buf_size, MP3D_ITERATE_CB callback, void *user_data);
219int mp3dec_iterate_cb(mp3dec_io_t *io, uint8_t *buf, size_t buf_size, MP3D_ITERATE_CB callback, void *user_data);
220/* streaming decoder with seeking capability */
221int mp3dec_ex_open_buf(mp3dec_ex_t *dec, const uint8_t *buf, size_t buf_size, int seek_method);
222int mp3dec_ex_open_cb(mp3dec_ex_t *dec, mp3dec_io_t *io, int seek_method);
223void mp3dec_ex_close(mp3dec_ex_t *dec);
224int mp3dec_ex_seek(mp3dec_ex_t *dec, uint64_t position);
225size_t mp3dec_ex_read(mp3dec_ex_t *dec, mp3d_sample_t *buf, size_t samples);
226#ifndef MINIMP3_NO_STDIO
227/* stdio versions of file load, iterate and stream */
228int mp3dec_load(mp3dec_t *dec, const char *file_name, mp3dec_file_info_t *info, MP3D_PROGRESS_CB progress_cb, void *user_data);
229int mp3dec_iterate(const char *file_name, MP3D_ITERATE_CB callback, void *user_data);
230int mp3dec_ex_open(mp3dec_ex_t *dec, const char *file_name, int seek_method);
231#ifdef _WIN32
232int mp3dec_load_w(mp3dec_t *dec, const wchar_t *file_name, mp3dec_file_info_t *info, MP3D_PROGRESS_CB progress_cb, void *user_data);
233int mp3dec_iterate_w(const wchar_t *file_name, MP3D_ITERATE_CB callback, void *user_data);
234int mp3dec_ex_open_w(mp3dec_ex_t *dec, const wchar_t *file_name, int seek_method);
235#endif
236#endif
237```
238
239Use MINIMP3_NO_STDIO define to exclude STDIO functions.
240MINIMP3_ALLOW_MONO_STEREO_TRANSITION allows mixing mono and stereo in same file.
241In that case ``mp3dec_frame_info_t->channels = 0`` is reported on such files and correct channels number passed to progress_cb callback for each frame in mp3dec_frame_info_t structure.
242MP3D_PROGRESS_CB is optional and can be NULL, example of file decoding:
243
244```c
245 mp3dec_t mp3d;
246 mp3dec_file_info_t info;
247 if (mp3dec_load(&mp3d, input_file_name, &info, NULL, NULL))
248 {
249 /* error */
250 }
251 /* mp3dec_file_info_t contains decoded samples and info,
252 use free(info.buffer) to deallocate samples */
253```
254
255Example of file decoding with seek capability:
256
257```c
258 mp3dec_ex_t dec;
259 if (mp3dec_ex_open(&dec, input_file_name, MP3D_SEEK_TO_SAMPLE))
260 {
261 /* error */
262 }
263 /* dec.samples, dec.info.hz, dec.info.layer, dec.info.channels should be filled */
264 if (mp3dec_ex_seek(&dec, position))
265 {
266 /* error */
267 }
268 mp3d_sample_t *buffer = malloc(dec.samples*sizeof(mp3d_sample_t));
269 size_t readed = mp3dec_ex_read(&dec, buffer, dec.samples);
270 if (readed != dec.samples) /* normal eof or error condition */
271 {
272 if (dec.last_error)
273 {
274 /* error */
275 }
276 }
277```
278
279## Bindings
280
281 * https://github.com/tosone/minimp3 - go bindings
282 * https://github.com/notviri/rmp3 - rust `no_std` bindings which don't allocate.
283 * https://github.com/germangb/minimp3-rs - rust bindings
284 * https://github.com/johangu/node-minimp3 - NodeJS bindings
285 * https://github.com/pyminimp3/pyminimp3 - python bindings
286 * https://github.com/bashi/minimp3-wasm - wasm bindings
287
288## Interesting links
289
290 * http://keyj.emphy.de/minimp3/
291 * https://github.com/technosaurus/PDMP3
292 * https://github.com/technosaurus/PDMP2
293 * https://github.com/packjpg/packMP3
294 * https://sites.google.com/a/kmlager.com/www/projects
295 * https://sourceforge.net/projects/mp3dec/
296 * http://blog.bjrn.se/2008/10/lets-build-mp3-decoder.html
297 * http://www.mp3-converter.com/mp3codec/
298 * http://www.multiweb.cz/twoinches/mp3inside.htm
299 * https://www.mp3-tech.org/
300 * http://id3.org/mp3Frame
301 * https://www.datavoyage.com/mpgscript/mpeghdr.htm
302