M4AAudioFileDemuxer Class Reference

Demuxer for M4A/MP4 files to extract audio data using an Arduino File. This class locates the mdat and stsz boxes using MP4Parser. More...

#include <M4AAudioFileDemuxer.h>

Inheritance diagram for M4AAudioFileDemuxer:

Public Types
enum class	Codec { Unknown , AAC , ALAC , MP3 }
using	FrameCallback = std::function< void(const Frame &, void *ref)>

Public Member Functions
	M4AAudioFileDemuxer ()
	Default constructor. Sets up parser callbacks.
	M4AAudioFileDemuxer (MultiDecoder &decoder)
	Constructor with decoder.
void	begin ()
bool	begin (File &file)
	Open and parse the given file.
void	beginSampleSizeAccess (File *filePtr, uint32_t sampleCount, uint32_t stszOffset)
	Initializes the demuxer for reading sample sizes from the stsz box.
bool	copy ()
	Copies the next audio frame from the file using the sample size table and mdat offset. Calls the frame callback if set.
void	end ()
	End demuxing and reset state.
M4AAudioConfig	getM4AAudioConfig ()
uint32_t	getMdatOffset () const
uint32_t	getNextSampleSize ()
	Provides the next sample size (= frame size) from the stsz box queue.
uint32_t	getSampleCount () const
	samples in stsz
uint32_t	getStszFileOffset () const
	File offset of stsz box.
	operator bool ()
	Returns true as long as there are samples to process.
bool	parseFile ()
	Parses the file and feeds data to the parser until we have all the necessary data: 1) stsd box processed, 2) mdat offset found, 3) stsz offset found. Usually this method is not needed, but it comes in handy if you need to process a file which is not in streaming format!
void	resize (int size)
uint32_t	sampleIndex () const
void	setAACConfig (int profile, int srIdx, int chCfg)
	Sets the AAC configuration for ADTS header generation.
void	setCallback (FrameCallback cb) override
	Sets the callback for extracted audio frames.
void	setChunkOffsetsBuffer (BaseBuffer< uint32_t > &buffer)
	Sets the buffer to use for sample sizes.
bool	setDecoder (MultiDecoder &decoder)
	Sets the decoder to use for audio frames. Please note that calls setCallback() to register the decoder callback.
void	setM4AAudioConfig (M4AAudioConfig cfg)
void	setSamplesBufferSize (int size)
	Sets the size of the samples buffer (in bytes).
void	setSampleSizesBuffer (BaseBuffer< stsz_sample_size_t > &buffer)
	Sets the buffer to use for sample sizes.
uint32_t	size () const

Protected Member Functions
bool	checkMdat ()
bool	checkType (uint8_t *buffer, const char *type, int offset)
	Checks if the buffer at the given offset matches the specified type.
void	executeCallback (size_t size, SingleBuffer< uint8_t > &buffer)
	Executes the callback for a completed frame.
void	onAlac (const MP4Parser::Box &box)
	Handles the alac box.
void	onEsds (const MP4Parser::Box &box)
	Handles the esds (Elementary Stream Descriptor) box.
void	onMp4a (const MP4Parser::Box &box)
	Handles the mp4a box.
void	onStsd (const MP4Parser::Box &box)
void	onStsz (MP4Parser::Box &box)
	Handles the stsz (Sample Size) box.
void	printHexDump (const MP4Parser::Box &box)
bool	readStszHeader ()
	Reads the stsz header (sample count and fixed sample size) from the file.
uint32_t	readU32Buffer ()
void	setupParser () override
	Sets up the MP4 parser and registers box callbacks.

Static Protected Member Functions
static uint32_t	readU32 (const uint32_t num)
static uint32_t	readU32 (const uint8_t *p)
	Reads a 32-bit big-endian unsigned integer from a buffer.

Protected Attributes
M4AAudioConfig	audio_config
SingleBuffer< uint8_t >	buffer
	Buffer for sample data.
uint32_t	chunk_offsets_count = 0
size_t	default_size = 2 * 1024
	Default buffer size.
uint32_t	fixed_sample_size = 0
	Fixed sample size (if nonzero)
FrameCallback	frame_callback = nullptr
uint64_t	mdat_offset = 0
	Offset of mdat box payload.
uint64_t	mdat_pos = 0
	Current position in mdat box.
uint64_t	mdat_sample_pos = 0
uint64_t	mdat_size = 0
	Size of mdat box payload.
MultiDecoder *	p_decoder = nullptr
	Pointer to decoder.
File *	p_file = nullptr
	Pointer to the open file.
MP4Parser	parser
	Underlying MP4 parser.
uint32_t	sample_count = 0
	Number of samples in stsz.
uint32_t	sample_index = 0
	Current sample index.
SampleExtractor	sampleExtractor
	Extractor for audio samples.
bool	stco_processed = false
	Marks the stco table as processed.
bool	stsd_processed = false
SingleBuffer< uint32_t >	stsz_buf
	Buffer for stsz sample sizes.
int	stsz_bufsize = 256
	Number of sample sizes to buffer.
uint64_t	stsz_offset = 0
	Offset of stsz box.
bool	stsz_processed = false
	Marks the stsz table as processed.
uint64_t	stsz_size = 0
	Size of stsz box.

Detailed Description

Demuxer for M4A/MP4 files to extract audio data using an Arduino File. This class locates the mdat and stsz boxes using MP4Parser.

It provides a copy() method to extract frames from the file by reading sample sizes directly from the stsz box in the file. This class is quite memory efficient because no table of sample sizes are kept in memory. It just reads the sample sizes from the stsz box and uses the mdat offset to read the sample data directly from the file.

The result is written to the provided decoder or alternatively will be provided via the frame_callback.

Author

Phil Schatzmann

Constructor & Destructor Documentation

M4AAudioFileDemuxer()

M4AAudioFileDemuxer ( MultiDecoder &  decoder )

inline

Constructor with decoder.

Parameters

decoder

Reference to MultiDecoder.

Member Function Documentation

begin()

bool begin ( File &  file )

inline

Open and parse the given file.

Parameters

file	Reference to an open Arduino File object.

Returns

true on success, false on failure.

beginSampleSizeAccess()

void beginSampleSizeAccess ( File *  filePtr, uint32_t  sampleCount, uint32_t  stszOffset  )

inline

Initializes the demuxer for reading sample sizes from the stsz box.

This method sets the file pointer, resets the sample index, sets the total sample count, and records the offset of the stsz box in the file. It is typically called before reading sample sizes directly from the file, ensuring the demuxer is properly positioned.

Parameters

filePtr	Pointer to the open file.
sampleCount	Total number of samples in the file.
stszOffset	Offset of the stsz box in the file.

checkType()

bool checkType ( uint8_t *  buffer, const char *  type, int  offset  )

inlineprotectedinherited

Checks if the buffer at the given offset matches the specified type.

Parameters

buffer	Pointer to the buffer.
type	4-character type string (e.g. "mp4a").
offset	Offset in the buffer to check.

Returns

true if the type matches, false otherwise.

copy()

bool copy ( )

inline

Copies the next audio frame from the file using the sample size table and mdat offset. Calls the frame callback if set.

Returns

true if a frame was copied and callback called, false if end of samples or error.

executeCallback()

void executeCallback ( size_t  size, SingleBuffer< uint8_t > &  buffer  )

inlineprotected

Executes the callback for a completed frame.

Parameters

size	Size of the frame.
buffer	Buffer containing the frame data.

getNextSampleSize()

uint32_t getNextSampleSize ( )

inline

Provides the next sample size (= frame size) from the stsz box queue.

Returns

stsz sample size in bytes.

onAlac()

void onAlac ( const MP4Parser::Box &  box )

inlineprotectedinherited

Handles the alac box.

Parameters

box

MP4 box.

onEsds()

void onEsds ( const MP4Parser::Box &  box )

inlineprotectedinherited

Handles the esds (Elementary Stream Descriptor) box.

Parameters

box

MP4 box.

onMp4a()

void onMp4a ( const MP4Parser::Box &  box )

inlineprotectedinherited

Handles the mp4a box.

Parameters

box

MP4 box.

for mp4a we expect to contain a esds: child boxes start at 36

onStsz()

void onStsz ( MP4Parser::Box &  box )

inlineprotectedinherited

Handles the stsz (Sample Size) box.

Parameters

box

MP4 box.

parseFile()

bool parseFile ( )

inline

Parses the file and feeds data to the parser until we have all the necessary data: 1) stsd box processed, 2) mdat offset found, 3) stsz offset found. Usually this method is not needed, but it comes in handy if you need to process a file which is not in streaming format!

Parameters

file	Reference to the file to parse.

readStszHeader()

bool readStszHeader ( )

inlineprotected

Reads the stsz header (sample count and fixed sample size) from the file.

Returns

true if successful, false otherwise.

readU32()

static uint32_t readU32 ( const uint8_t *  p )

inlinestaticprotectedinherited

Reads a 32-bit big-endian unsigned integer from a buffer.

Parameters

p	Pointer to buffer.

Returns

32-bit unsigned integer.

setAACConfig()

void setAACConfig ( int  profile, int  srIdx, int  chCfg  )

inlineinherited

Sets the AAC configuration for ADTS header generation.

Parameters

profile	AAC profile.
srIdx	Sample rate index.
chCfg	Channel configuration.

setCallback()

void setCallback ( FrameCallback  cb )

inlineoverridevirtual

Sets the callback for extracted audio frames.

Parameters

cb	Frame callback function.

Reimplemented from M4ACommonDemuxer.

setChunkOffsetsBuffer()

void setChunkOffsetsBuffer ( BaseBuffer< uint32_t > &  buffer )

inlineinherited

Sets the buffer to use for sample sizes.

Parameters

buffer

Reference to the buffer to use.

setDecoder()

bool setDecoder ( MultiDecoder &  decoder )

inline

Sets the decoder to use for audio frames. Please note that calls setCallback() to register the decoder callback.

Parameters

decoder

Reference to MultiDecoder.

Returns

true if set successfully.

setSamplesBufferSize()

void setSamplesBufferSize ( int  size )

inline

Sets the size of the samples buffer (in bytes).

Parameters

size	Buffer size in bytes.

setSampleSizesBuffer()

void setSampleSizesBuffer ( BaseBuffer< stsz_sample_size_t > &  buffer )

inlineinherited

Sets the buffer to use for sample sizes.

Parameters

buffer

Reference to the buffer to use.

setupParser()

void setupParser ( )

inlineoverrideprotectedvirtual

Sets up the MP4 parser and registers box callbacks.

Implements M4ACommonDemuxer.

Member Data Documentation

sampleExtractor

SampleExtractor sampleExtractor

protectedinherited

Initial value:

{
      audio_config}

Extractor for audio samples.

stsz_buf

SingleBuffer<uint32_t> stsz_buf

protected

Initial value:

{
      stsz_bufsize}

Buffer for stsz sample sizes.

---

The documentation for this class was generated from the following file:

• src/AudioTools/AudioCodecs/M4AAudioFileDemuxer.h