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 MHC, 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 MHC 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 MHC.

If using the MP3 Decoder Library from the audio repository, the helix_mp3 repository must also be downloaded.

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.