Main functions¶

bw64::Bw64Reader and bw64::Bw64Writer classes usually should not be created manually. Instead the two builder functions to either read or write a file should be used.

std::unique_ptr<Bw64Reader> bw64::readFile(const std::string &filename)¶

Open a BW64 file for reading.

Convenience function to open a BW64 file for reading.

Parameters

filename: path of the file to read

Return: unique_ptr to a Bw64Reader instance that is ready to read samples.

std::unique_ptr<Bw64Writer> bw64::writeFile(const std::string &filename, uint16_t channels = 1u, uint32_t sampleRate = 48000u, uint16_t bitDepth = 24u, std::shared_ptr<ChnaChunk> chnaChunk = nullptr, std::shared_ptr<AxmlChunk> axmlChunk = nullptr)¶

Open a BW64 file for writing.

Convenience function to open a new BW64 file for writing, adding axml and chna chunks.

If passed to this function, the axml and chna chunks will be added to the BW64 file before the actual data chunk, which is the recommended practice if all components are already known before writing a file.

Return

unique_ptr to a Bw64Writer instance that is ready to write samples.

Parameters

filename: path of the file to write
channels: the channel count of the new file
sampleRate: the samplerate of the new file
bitDepth: target bitdepth of the new file
chnaChunk: Channel allocation chunk to include, if any
axmlChunk: AXML chunk to include, if any

BW64 file classes¶

class Bw64Reader¶

Representation of a BW64 file.

Normally, you will create an instance of this class using bw64::readFile().

This is a RAII class, meaning that the file will be openend and initialized (parse header, format etc.) on construction, and closed on destruction.

Public Functions

Bw64Reader(const char *filename)¶

Open a new BW64 file for reading.

Opens a new BW64 file for reading, parses the whole file to read the format and identify all chunks in it.

Note: For convenience, you might consider using the readFile helper function.

~Bw64Reader()¶

Bw64Reader destructor.

The destructor will automatically close the file opened in the constructor.

uint32_t fileFormat() const¶: Get file format (RIFF, BW64 or RF64)

uint32_t fileSize() const¶: Get file size.

uint16_t formatTag() const¶: Get format tag.

uint16_t channels() const¶: Get number of channels.

uint32_t sampleRate() const¶: Get sample rate.

uint16_t bitDepth() const¶: Get bit depth.

uint64_t numberOfFrames() const¶: Get number of frames.

uint16_t blockAlignment() const¶: Get block alignment.

std::shared_ptr<DataSize64Chunk> ds64Chunk() const¶

Get ‘ds64’ chunk.

Return: std::shared_ptr to DataSize64Chunk if present and otherwise a nullptr.

std::shared_ptr<FormatInfoChunk> formatChunk() const¶

Get ‘fmt ‘ chunk.

Return: std::shared_ptr to FormatInfoChunk if present and otherwise a nullptr.

std::shared_ptr<DataChunk> dataChunk() const¶

Get ‘data’ chunk.

Warning: This method usually should not be called, as the acces to the DataChunk is handled seperately by the Bw64Reader class .
Return: std::shared_ptr to DataChunk if present and otherwise a nullptr.

std::shared_ptr<ChnaChunk> chnaChunk() const¶

Get ‘chna’ chunk.

Return: std::shared_ptr to ChnaChunk if present and otherwise a nullptr.

std::shared_ptr<AxmlChunk> axmlChunk() const¶

Get ‘axml’ chunk.

Return: std::shared_ptr to AxmlChunk if present and otherwise a nullptr.

std::vector<ChunkHeader> chunks() const¶: Get list of all chunks which are present in the file.

bool hasChunk(uint32_t id) const¶: Check if a chunk with the given id is present.

void seek(int32_t offset, std::ios_base::seekdir way = std::ios::beg)¶: Seek a frame position in the DataChunk.

template<typename T, typename std::enable_if< std::is_floating_point< T >::value, int >::type = 0>uint64_t bw64::Bw64Reader::read(T * outBuffer, uint64_t frames)

Read frames from dataChunk.

Return

number of frames read

Parameters

[out] outBuffer: Buffer to write the samples to
[in] frames: Number of frames to read

uint64_t tell()¶

Tell the current frame position of the dataChunk.

Return: current frame position of the dataChunk

bool eof()¶

Check if end of data is reached.

Return: true if end of data is reached and otherwise false

class Bw64Writer¶

BW64 Writer class.

Normally, you will create an instance of this class using bw64::writeFile().

This is a RAII class, meaning that the file will be opened and initialized (required headers etc.) on construction, and closed and finalized (writing chunk sizes etc.) on destruction.

Public Functions

Bw64Writer(const char *filename, uint16_t channels, uint32_t sampleRate, uint16_t bitDepth, std::vector<std::shared_ptr<Chunk>> additionalChunks)¶

Open a new BW64 file for writing.

Opens a new BW64 file for writing, initializes everything up to the data chunk. Afterwards, you may write interleaved audio samples to this file.

If you need any chunks to appear

before the data chunk, include them in the additionalChunks. They will be written directly after opening the file.

Warning: If the file already exists it will be overwritten.

Note: For convenience, you might consider using the writeFile helper function.

~Bw64Writer()¶

Finalize file.

This destructor will write all yet-to-be-written chunks to the file and will also finalize all required information, i.e. the final chunk sizes etc.

uint16_t formatTag() const¶: Get format tag.

uint16_t channels() const¶: Get number of channels.

uint32_t sampleRate() const¶: Get sample rate.

uint16_t bitDepth() const¶: Get bit depth.

uint64_t framesWritten() const¶: Get number of frames.

bool isBw64File()¶: Check if file is bigger than 4GB and therefore a BW64 file.

void useRf64Id(bool state)¶: Use RF64 ID for outer chunk (when >4GB) rather than BW64.

uint32_t chunkSizeForHeader(uint32_t id)¶: Get the chunk size for header.

uint64_t riffChunkSize()¶: Calculate riff chunk size.

void writeRiffHeader()¶: Write RIFF header.

void finalizeRiffChunk()¶: Update RIFF header.

template<typename ChunkType> void writeChunk(std::shared_ptr<ChunkType> chunk)¶: Write chunk template.

template<typename ChunkType> void overwriteChunk(uint32_t id, std::shared_ptr<ChunkType> chunk)¶: Overwrite chunk template.

template<typename T, typename std::enable_if< std::is_floating_point< T >::value, int >::type = 0>uint64_t bw64::Bw64Writer::write(T * inBuffer, uint64_t frames)

Write frames to dataChunk.

Return

number of frames written

Parameters

[out] inBuffer: Buffer to read samples from
[in] frames: Number of frames to write

Chunks¶

class Chunk¶

RIFF chunk base class.

Subclassed by bw64::AxmlChunk, bw64::ChnaChunk, bw64::DataChunk, bw64::DataSize64Chunk, bw64::FormatInfoChunk, bw64::JunkChunk, bw64::UnknownChunk

Public Functions

virtual uint32_t id() const = 0¶: Get FourCC id.

virtual uint64_t size() const = 0¶: Get the size of the chunk.

virtual void write(std::ostream &stream) const = 0¶: Write the chunk to a stream.

class FormatInfoChunk : public bw64::Chunk ¶

Class representation of a FormatInfoChunk.

Public Functions

FormatInfoChunk(uint16_t channels, uint32_t sampleRate, uint32_t bitDepth, std::shared_ptr<ExtraData> extraData = nullptr, uint16_t formatTag = 1)¶

Simple FormatInfoChunk constructor.

Parameters

channels: number of channels
sampleRate: sample rate of the audio data
bitDepth: bit depth used in file
extraData: custom ExtraData (optional, nullptr if not custom)
formatTag: format tag, defaults to PCM

uint32_t id() const¶: Get FourCC id.

uint64_t size() const¶: Get the size of the chunk.

uint16_t formatTag() const¶: FormatTag getter.

uint16_t channelCount() const¶: ChannelCount getter.

uint32_t sampleRate() const¶: SampleRate getter.

uint32_t bytesPerSecond() const¶: BytesPerSecond getter.

uint16_t blockAlignment() const¶: BlockAlignment getter.

uint16_t bitsPerSample() const¶: BitsPerSample getter.

const std::shared_ptr<ExtraData> extraData() const¶: ExtraData getter.

void write(std::ostream &stream) const¶: Write the chunk to a stream.

class ExtraData¶

Class representation of the ExtraData of a FormatInfoChunk.

Public Functions

ExtraData(uint16_t validBitsPerSample, uint32_t dwChannelMask, uint16_t subFormat, std::string subFormatString)¶: ExtraData constructor.

uint16_t validBitsPerSample() const¶: ValidBitsPerSample getter.

uint32_t dwChannelMask() const¶: DwChannelMask getter.

uint16_t subFormat() const¶: SubFormat getter.

std::string subFormatString() const¶: SubFormatString getter.

class DataChunk : public bw64::Chunk ¶

Class representation of a DataChunk.

Public Functions

uint32_t id() const¶: Get FourCC id.

uint64_t size() const¶: Get the size of the chunk.

void write(std::ostream&) const¶

Not to be used write chunk to stream.

Warning: As the data chunk is usually not written in one piece the override for this function is not used. Using this method will throw an exception.

class JunkChunk : public bw64::Chunk ¶

Class representation of a DataChunk.

Public Functions

uint32_t id() const¶: Get FourCC id.

uint64_t size() const¶: Get the size of the chunk.

void write(std::ostream &stream) const¶: Write the chunk to a stream.

class AxmlChunk : public bw64::Chunk ¶

Class representation of an AxmlChunk.

Public Functions

uint32_t id() const¶: Get FourCC id.

uint64_t size() const¶: Get the size of the chunk.

void write(std::ostream &stream) const¶: Write the chunk to a stream.

class AudioId¶

Class representation of an AudioId field.

class ChnaChunk : public bw64::Chunk ¶

Class representation of an ChnaChunk.

Public Functions

uint32_t id() const¶: Get FourCC id.

uint64_t size() const¶: Get the size of the chunk.

uint16_t numTracks() const¶: NumTracks getter.

uint16_t numUids() const¶: NumUids getter.

std::vector<AudioId> audioIds() const¶: AudioIds getter.

void addAudioId(AudioId id)¶: Add AudioId to AudioId table.

void write(std::ostream &stream) const¶: Write the chunk to a stream.

class DataSize64Chunk : public bw64::Chunk ¶

Class representation of a DataSize64 chunk.

Public Functions

DataSize64Chunk(uint64_t bw64Size = 0, uint64_t dataSize = 0, std::map<uint32_t, uint64_t> table = std::map<uint32_t, uint64_t>())¶: DataSize64Chunk constructor.

uint32_t id() const¶: Get FourCC id.

uint64_t size() const¶: Get the size of the chunk.

uint64_t bw64Size() const¶: Bw64Size getter.

uint64_t dataSize() const¶: DataSize getter.

uint64_t dummySize() const¶: DummySize getter.

uint32_t tableLength() const¶: TableLength getter.

void bw64Size(uint64_t size)¶: Bw64Size setter.

void dataSize(uint64_t size)¶: DataSize setter.

void dummySize(uint64_t size)¶: DummySize setter.

const std::map<uint32_t, uint64_t> &table() const¶: Get table.

bool hasChunkSize(uint32_t id) const¶: Has chunkSize for id.

uint64_t getChunkSize(uint32_t id) const¶: Get chunkSize for id.

void setChunkSize(uint32_t id, uint64_t size)¶: Set or add a ChunkSize.

void removeChunkSize(uint32_t id)¶: Remove a ChunkSize from table.

void clearChunkSizeTable()¶: Clear ChunkSize table.

void write(std::ostream &stream) const¶: Write the chunk to a stream.

class UnknownChunk : public bw64::Chunk ¶

Class representation of a custom chunk.

This class can be used to copy unknown chunks from an input file to an output file.

Public Functions

uint32_t id() const¶: Get FourCC id.

uint64_t size() const¶: Get the size of the chunk.

void write(std::ostream &stream) const¶: Write the chunk to a stream.

Utilities¶

constexpr uint32_t bw64::utils::fourCC(char const p[5])¶: Convert char array chunkIds to uint32_t.

std::string bw64::utils::fourCCToStr(uint32_t value)¶: Convert uint32_t chunkId to string.