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

Member Typedef Documentation

FrameCallback

using FrameCallback = std::function<void(const Frame&, void* ref)>

Member Enumeration Documentation

Codec

enum class Codec

stronginherited

Enumerator
Unknown
AAC
ALAC
MP3

Constructor & Destructor Documentation

M4AAudioFileDemuxer() [1/2]

M4AAudioFileDemuxer ( )

inline

Default constructor. Sets up parser callbacks.

M4AAudioFileDemuxer() [2/2]

M4AAudioFileDemuxer ( MultiDecoder &  decoder )

inline

Constructor with decoder.

Parameters

decoder

Reference to MultiDecoder.

Member Function Documentation

begin() [1/2]

void begin ( )

inlineinherited

begin() [2/2]

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.

checkMdat()

bool checkMdat ( )

inlineprotected

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.

end()

void end ( )

inline

End demuxing and reset state.

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.

getM4AAudioConfig()

M4AAudioConfig getM4AAudioConfig ( )

inlineinherited

getMdatOffset()

uint32_t getMdatOffset ( ) const

inline

getNextSampleSize()

uint32_t getNextSampleSize ( )

inline

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

Returns

stsz sample size in bytes.

getSampleCount()

uint32_t getSampleCount ( ) const

inlineinherited

samples in stsz

getStszFileOffset()

uint32_t getStszFileOffset ( ) const

inlineinherited

File offset of stsz box.

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

onStsd()

void onStsd ( const MP4Parser::Box &  box )

inlineprotectedinherited

onStsz()

void onStsz ( MP4Parser::Box &  box )

inlineprotectedinherited

Handles the stsz (Sample Size) box.

Parameters

box

MP4 box.

operator bool()

operator bool ( )

inline

Returns true as long as there are samples to process.

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.

printHexDump()

void printHexDump ( const MP4Parser::Box &  box )

inlineprotectedinherited

readStszHeader()

bool readStszHeader ( )

inlineprotected

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

Returns

true if successful, false otherwise.

readU32() [1/2]

static uint32_t readU32 ( const uint32_t  num )

inlinestaticprotectedinherited

readU32() [2/2]

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.

readU32Buffer()

uint32_t readU32Buffer ( )

inlineprotectedinherited

resize()

void resize ( int  size )

inlineinherited

sampleIndex()

uint32_t sampleIndex ( ) const

inline

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.

setM4AAudioConfig()

void setM4AAudioConfig ( M4AAudioConfig  cfg )

inlineinherited

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.

size()

uint32_t size ( ) const

inline

Member Data Documentation

audio_config

M4AAudioConfig audio_config

protectedinherited

buffer

SingleBuffer<uint8_t> buffer

protected

Buffer for sample data.

chunk_offsets_count

uint32_t chunk_offsets_count = 0

protectedinherited

default_size

size_t default_size = 2 * 1024

protectedinherited

Default buffer size.

fixed_sample_size

uint32_t fixed_sample_size = 0

protected

Fixed sample size (if nonzero)

frame_callback

FrameCallback frame_callback = nullptr

protectedinherited

mdat_offset

uint64_t mdat_offset = 0

protected

Offset of mdat box payload.

mdat_pos

uint64_t mdat_pos = 0

protected

Current position in mdat box.

mdat_sample_pos

uint64_t mdat_sample_pos = 0

protected

mdat_size

uint64_t mdat_size = 0

protected

Size of mdat box payload.

p_decoder

MultiDecoder* p_decoder = nullptr

protected

Pointer to decoder.

p_file

File* p_file = nullptr

protected

Pointer to the open file.

parser

MP4Parser parser

protectedinherited

Underlying MP4 parser.

sample_count

uint32_t sample_count = 0

protectedinherited

Number of samples in stsz.

sample_index

uint32_t sample_index = 0

protected

Current sample index.

sampleExtractor

SampleExtractor sampleExtractor

protectedinherited

Initial value:

{
      audio_config}

Extractor for audio samples.

stco_processed

bool stco_processed = false

protectedinherited

Marks the stco table as processed.

stsd_processed

bool stsd_processed = false

protectedinherited

stsz_buf

SingleBuffer<uint32_t> stsz_buf

protected

Initial value:

{
      stsz_bufsize}

Buffer for stsz sample sizes.

stsz_bufsize

int stsz_bufsize = 256

protected

Number of sample sizes to buffer.

stsz_offset

uint64_t stsz_offset = 0

protected

Offset of stsz box.

stsz_processed

bool stsz_processed = false

protectedinherited

Marks the stsz table as processed.

stsz_size

uint64_t stsz_size = 0

protected

Size of stsz box.

---

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

• src/AudioTools/AudioCodecs/M4AAudioFileDemuxer.h