dspark::AudioFile Class Reference

Abstract base class for audio file readers and writers. More...

#include <AudioFile.h>

Inheritance diagram for dspark::AudioFile:

Public Member Functions
virtual	~AudioFile ()=default
virtual bool	openRead (const std::filesystem::path &path)=0
	Opens a file for reading.
virtual bool	openWrite (const std::filesystem::path &path, const AudioFileInfo &info)=0
	Opens a file for writing, creating it or overwriting if it exists.
virtual AudioFileInfo	getInfo () const =0
	Retrieves metadata of the currently opened file.
virtual bool	readSamples (AudioBufferView< float > dest)=0
	Reads samples from the start of the file into the destination view.
virtual bool	readSamples (AudioBufferView< float > dest, int64_t startFrame, int64_t numFrames)=0
	Reads a specific range of sample frames. Useful for chunked streaming.
virtual bool	writeSamples (AudioBufferView< const float > src)=0
	Writes samples from the view to the file.
virtual void	close ()=0
	Finalizes file headers and releases system handles.
virtual bool	isOpen () const noexcept=0
	Checks if a valid file handle is currently open.

Detailed Description

Abstract base class for audio file readers and writers.

Provides a uniform API to transfer audio to/from AudioBufferView objects. Samples are normalized to the [-1.0, 1.0] float range: implementations convert to/from the stored bit depth transparently.

Note

Reading 32-bit integer PCM files into float buffers will result in a loss of the 8 least significant bits due to 24-bit mantissa limitations.

Definition at line 106 of file AudioFile.h.

Constructor & Destructor Documentation

~AudioFile()

virtual dspark::AudioFile::~AudioFile ( )

virtualdefault

Member Function Documentation

close()

virtual void dspark::AudioFile::close ( )

pure virtual

Finalizes file headers and releases system handles.

Safe to call multiple times. Implementations invoke this from their destructor, so an open file is always finalized; call it explicitly when you need the write error-checked (a destructor cannot report failure) or the file released before the object dies.

Implemented in dspark::Mp3File, and dspark::WavFile.

getInfo()

virtual AudioFileInfo dspark::AudioFile::getInfo ( ) const

pure virtual

Retrieves metadata of the currently opened file.

Returns

AudioFileInfo struct. Returns default values if no file is open.

Implemented in dspark::Mp3File, and dspark::WavFile.

isOpen()

virtual bool dspark::AudioFile::isOpen ( ) const

pure virtualnoexcept

Checks if a valid file handle is currently open.

Implemented in dspark::Mp3File, and dspark::WavFile.

openRead()

virtual bool dspark::AudioFile::openRead ( const std::filesystem::path &  path )

pure virtual

Opens a file for reading.

Any previously open file is closed first.

Parameters

path	File path using C++20 std::filesystem (handles UTF-8/cross-platform safely).

Returns

True if opened and header parsed successfully. False otherwise.

Implemented in dspark::Mp3File, and dspark::WavFile.

openWrite()

virtual bool dspark::AudioFile::openWrite ( const std::filesystem::path &  path, const AudioFileInfo &  info  )

pure virtual

Opens a file for writing, creating it or overwriting if it exists.

Any previously open file is closed first.

Parameters

path	File path.
info	Desired output format metadata.

Returns

True if created and header written successfully. False otherwise.

Implemented in dspark::Mp3File, and dspark::WavFile.

readSamples() [1/2]

virtual bool dspark::AudioFile::readSamples ( AudioBufferView< float >  dest )

pure virtual

Reads samples from the start of the file into the destination view.

Reads up to min(view length, file length) frames into up to min(view channels, file channels) channels. Excess buffer space and channels beyond those present in the file are left untouched.

Parameters

dest	Buffer view to receive the audio data.

Returns

True if read successfully. False if an I/O error occurred or no file is open for reading.

Implemented in dspark::Mp3File, and dspark::WavFile.

readSamples() [2/2]

virtual bool dspark::AudioFile::readSamples ( AudioBufferView< float >  dest, int64_t  startFrame, int64_t  numFrames  )

pure virtual

Reads a specific range of sample frames. Useful for chunked streaming.

The requested range must lie entirely within the file (startFrame >= 0, numFrames > 0, startFrame + numFrames <= numSamples); out-of-range requests return false without reading. As with the full-file overload, the transfer is clamped to the view's capacity.

Parameters

dest	Buffer view to receive the audio data.
startFrame	The absolute frame index in the file to start reading from.
numFrames	The number of frames to read.

Returns

True if the range was read successfully.

Implemented in dspark::Mp3File, and dspark::WavFile.

writeSamples()

virtual bool dspark::AudioFile::writeSamples ( AudioBufferView< const float >  src )

pure virtual

Writes samples from the view to the file.

Converts float [-1.0, 1.0] back to the native bit-depth defined in openWrite(). May be called repeatedly to append blocks (streaming writes).

Parameters

src	Buffer view containing the data to write.

Returns

True on success, False if disk is full or an I/O error occurred.

Implemented in dspark::Mp3File, and dspark::WavFile.

---

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

• IO/AudioFile.h