1.3.3 MP3 Decoder Library
Introduction
MP3 is a lossy compression standard. MP3 compression works by reducing (or approximating) the accuracy of certain components of sound that are considered (by psychoacoustic analysis) to be beyond the hearing capabilities of most humans. This method is commonly referred to as perceptual coding or as psychoacoustic modeling. The remaining audio information is then recorded in a space-efficient manner, using MDCT and FFT algorithms. Compared to CD-quality digital audio, MP3 compression can commonly achieve a 75 percent to 95 percent reduction in size.
In Harmony 3, the MP3 decoder is limited to 16-bit audio, typically recorded at either CD quality (44100 samples/second) or DVD quality (48000 samples/second).
In addition to audio, an MP3 file may contain metadata, called ID3 tags, which include the name of the song, name of the artist, name of the album, and other information.
An MP3 file is made up of MP3 frames, which consist of a header and a data block. This sequence of frames is called an elementary stream. Due to the "bit reservoir", frames are not independent items and cannot usually be extracted on arbitrary frame boundaries. The MP3 Data blocks contain the (compressed) audio information in terms of frequencies and amplitudes. The MP3 Header consists of a sync word, which is used to identify the beginning of a valid frame. This is followed by a bit indicating that this is the MPEG standard and two bits that indicate that layer 3 is used; hence MPEG-1 Audio Layer 3 or MP3.
MP3 was originally patented, but the last patent expired on April 16, 2017.
In Harmony 3, an open-source MP3 decoder called Helix MP3 is used. The main portion of the code is located in a separate repository called helix_mp3\. The MP3 Decoder Library in the audio repository is just a wrapper that calls functions in the main library (which is brought in automatically when you generate code in MCC, with the MP3 Decoder Library selected).
Building the Library
This section lists the files that are available in the MP3 Decoder Library.
Description
This section lists the files that are available in the src folder of the MP3 Decoder Library. It lists which files need to be included in the build based on a configuration option selected by the system.
The following three tables list and describe the header (.h) and source (.c) files that implement this library. The parent folder for these files is src/config/<config_dir>/audio/decoder/
Interface File(s)
This table lists and describes the header files that must be included (i.e., using #include) by any code that uses this library.
| Source File Name | Description |
|---|---|
| audio_decoders.h | Header file that includes the lower-level include files (e.g. mp3_dec.h) |
| audio_decoders_config.h | Header file that contains #defines for each enabled decoder MP3_DECODER_ENABLED) |
Required File(s)
All of the required files listed in the following table are automatically added into the MPLAB X IDE project by the MCC when the library is selected for use.
This table lists and describes the header and source files that must always be included in the MPLAB X IDE project to build this library.
| Source File Name | Description |
|---|---|
| audio_decoders/mp3/mp3_dec.c,.h | This file contains implementation of the API for the MP3 Decoder |
| audio_decoders/mp3/id3/id3.c,.h | This file contains implementation of the API for parsing ID3 tags |
| audio_decoders/mp3/id3/utils.c,.h | These files contain utility functions for parsing ID3 tags |
| audio_decoders/mp3/fixpnt/. | Files from the Helix MP3 Decoder repository (see below) |
The MP3 Decoder Library files in the apps repository only contain a wrapper around the Helix open-source MP3 Decoder, located in the helix_mp3 repository. Files from the fixpnt folder in that repo are copied into the fixpnt folder listed above when code is generated using MCC.
Library Interface
This section describes the Application Programming Interface (API) functions of the MP3 Decoder Library.
Functions
| Name | Description |
|---|---|
| isMP3decoder_enabled | This is function isMP3decoder_enabled. |
| MP3_Decoder | This is function MP3_Decoder. |
| MP3_FillReadBuffer | This is function MP3_FillReadBuffer. |
| MP3_FindSyncWord | This is function MP3_FindSyncWord. |
| MP3_GetAudioSize | This is function MP3_GetAudioSize. |
| MP3_GetBitRate | This is function MP3_GetBitRate. |
| MP3_GetBitsPerSample | This is function MP3_GetBitsPerSample. |
| MP3_GetChannels | This is function MP3_GetChannels. |
| MP3_GetDuration | This is function MP3_GetDuration. |
| MP3_GetSampleRate | This is function MP3_GetSampleRate. |
| MP3_HdrGetBytesPerSec | This is function MP3_HdrGetBytesPerSec. |
| MP3_HdrGetDataLen | This is function MP3_HdrGetDataLen. |
| MP3_HdrGetFileSize | This is function MP3_HdrGetFileSize. |
| MP3_HdrGetSamplesPerSec | This is function MP3_HdrGetSamplesPerSec. |
| MP3_Initialize | This is function MP3_Initialize. |
| MP3_Initialize_N | This is function MP3_Initialize_N. |
| MP3_UpdatePlaytime | This is function MP3_UpdatePlaytime. |
| read_ID3Tags | This is function read_ID3Tags. |
Description
This section describes the Application Programming Interface (API) functions of the MP3 Decoder Library.