audio¶
audio_decoder class¶
audio_decoder
audio_encoding_options class¶
audio_encoding_options
Represents options for audio encoding, including dithering settings.
audio_encoder class¶
audio_encoder
Abstract base class for audio encoders, providing methods for opening, writing, and closing audio files.
~audio_encoder function (audio_encoder::~audio_encoder)¶
virtual ~audio_encoder()
Destructor to close and finalize file encoding.
open function (audio_encoder::open)¶
virtual expected<void, audiofile_error>
open(std::shared_ptr<binary_writer> writer,
const audiofile_format &format,
audio_decoder *copyMetadataFrom = nullptr) = 0
Opens the encoder with a binary writer and format.
Param writer Shared pointer to the binary writer.
Param format Audio file format to use.
Param copyMetadataFrom Optional decoder to copy metadata from.
Returns Expected result indicating success or an audiofile error.
expected<void, audiofile_error>
open(const file_path &path, const audiofile_format &format,
audio_decoder *copyMetadataFrom = nullptr)
Opens the encoder with a file path and format.
Param path Path to the file to open.
Param format Audio file format to use.
Param copyMetadataFrom Optional decoder to copy metadata from.
Returns Expected result indicating success or an audiofile error.
write function (audio_encoder::write)¶
virtual expected<void, audiofile_error>
write(const audio_data_interleaved &data) = 0
Writes a chunk of interleaved audio data to the encoder.
Param data Interleaved audio data to write.
Returns Expected result indicating success or an audiofile error.
close function (audio_encoder::close)¶
virtual expected<uint64_t, audiofile_error> close() = 0
Closes the encoder and finalizes the file.
Returns Expected result with the total number of frames written or an audiofile error.
format function (audio_encoder::format)¶
const std::optional<audiofile_format> &
format() const noexcept
Retrieves the current audio file format.
Returns Optional containing the audio file format if set.
writer function (audio_encoder::writer)¶
std::shared_ptr<binary_writer> writer() const noexcept
Retrieves the binary writer associated with the encoder.
Returns Shared pointer to the binary writer.
create_encoder_for_container function¶
std::unique_ptr<audio_encoder> create_encoder_for_container(
audiofile_container container, const audio_encoding_options& options =
Creates an audio encoder for the specified container format with optional encoding options.
Param container The audio file container format.
Param options Optional encoding options.
Returns A unique pointer to the created audio encoder.
audio_writing_software variable¶
extern std::string audio_writing_software
Software string to write into metadata, if supported by format
raw_encoding_options class¶
raw_encoding_options
Represents options for raw audio encoding.
create_raw_encoder function¶
std::unique_ptr<audio_encoder> create_raw_encoder(const raw_encoding_options& options =
Creates a raw audio encoder with optional encoding options.
Param options Optional raw encoding options.
Returns A unique pointer to the created raw audio encoder.
wave_encoding_options class¶
wave_encoding_options
Represents options for WAVE audio encoding, including RF64 support for large files.
create_wave_encoder function¶
std::unique_ptr<audio_encoder> create_wave_encoder(const wave_encoding_options& options =
Creates a WAVE audio encoder with optional encoding options.
Param options Optional WAVE encoding options.
Returns A unique pointer to the created WAVE audio encoder.
w64_encoding_options class¶
w64_encoding_options
Represents options for W64 audio encoding.
create_w64_encoder function¶
std::unique_ptr<audio_encoder> create_w64_encoder(const w64_encoding_options& options =
Creates a W64 audio encoder with optional encoding options.
Param options Optional W64 encoding options.
Returns A unique pointer to the created W64 audio encoder.
aiff_encoding_options class¶
aiff_encoding_options
Represents options for AIFF audio encoding.
create_aiff_encoder function¶
std::unique_ptr<audio_encoder> create_aiff_encoder(const aiff_encoding_options& options =
Creates an AIFF audio encoder with optional encoding options.
Param options Optional AIFF encoding options.
Returns A unique pointer to the created AIFF audio encoder.
caff_encoding_options class¶
caff_encoding_options
Represents options for CAFF audio encoding.
create_caff_encoder function¶
std::unique_ptr<audio_encoder> create_caff_encoder(const caff_encoding_options& options =
Creates a CAFF audio encoder with optional encoding options.
Param options Optional CAFF encoding options.
Returns A unique pointer to the created CAFF audio encoder.
encode_audio_file function¶
expected<void, audiofile_error> encode_audio_file(const file_path& path,
const audio_data_interleaved& data,
const audiofile_format& format,
audio_decoder* copyMetadataFrom = nullptr,
const audio_encoding_options& options =
Encodes interleaved audio data and writes it to a file.
Param path The file path for the encoded audio.
Param data The interleaved audio data to encode.
Param format The desired audio file format.
Param copyMetadataFrom Optional audio decoder to copy metadata from.
Param options Optional encoding options.
Returns An expected object containing an audiofile_error on failure.
expected<void, audiofile_error> encode_audio_file(const file_path& path,
const audio_data_planar& data,
const audiofile_format& format,
audio_decoder* copyMetadataFrom = nullptr,
const audio_encoding_options& options =
Encodes planar audio data and writes it to a file.
Param path The file path for the encoded audio.
Param data The planar audio data to encode.
Param format The desired audio file format.
Param copyMetadataFrom Optional audio decoder to copy metadata from.
Param options Optional encoding options.
Returns An expected object containing an audiofile_error on failure.
audiofile_error enum¶
enum class audiofile_error : uint32_t
audiofile_errorEnumerates possible error codes for audio file operations.
unknown enumerator (audiofile_error::unknown)¶
An unknown error occurred
io_error enumerator (audiofile_error::io_error)¶
An input/output error occurred.
format_error enumerator (audiofile_error::format_error)¶
The audio file format is invalid or unsupported.
internal_error enumerator (audiofile_error::internal_error)¶
An internal error occurred.
too_large enumerator (audiofile_error::too_large)¶
data chunk too large for standard WAV
end_of_file enumerator (audiofile_error::end_of_file)¶
End of file reached
abort enumerator (audiofile_error::abort)¶
Operation aborted
not_implemented enumerator (audiofile_error::not_implemented)¶
Not implemented
invalid_argument enumerator (audiofile_error::invalid_argument)¶
Invalid argument passed
closed enumerator (audiofile_error::closed)¶
The audio file is closed
empty_file enumerator (audiofile_error::empty_file)¶
The file is empty or does not contain any audio data
not_found enumerator (audiofile_error::not_found)¶
The file was not found
access_denied enumerator (audiofile_error::access_denied)¶
Access to the file was denied
from_error_code function¶
audiofile_error from_error_code(std::error_code ec)
Converts a standard error code to an audiofile_error.
This function maps a given std::error_code to the corresponding
audiofile_error enumeration value.
Param ec The standard error code to convert.
Returns The corresponding audiofile_error value.
to_string function¶
std::string to_string(audiofile_error err)
Converts an audiofile_error to its string representation.
This function provides a human-readable string representation of
the given audiofile_error value.
Param err The audiofile_error value to convert.
Returns A string describing the error.
default_audio_frames_to_read variable¶
constexpr inline size_t default_audio_frames_to_read = 16384
The default number of audio frames to read in one operation.
This constant defines the default number of audio frames to process in a single read operation.
audio_decoder class¶
audio_decoder
Abstract base class for audio decoders providing methods for opening and reading audio files.
open function (audio_decoder::open)¶
virtual expected<audiofile_format, audiofile_error>
open(std::shared_ptr<binary_reader> reader) = 0
Opens an audio file using a binary reader and retrieves its format.
Param reader Shared pointer to a binary reader.
Returns Audio format on success, or an error code on failure.
expected<audiofile_format, audiofile_error>
open(const file_path &path)
Opens an audio file from a file path and retrieves its format.
Param path Path to the audio file.
Returns Audio format on success, or an error code on failure.
read_to function (audio_decoder::read_to)¶
virtual expected<size_t, audiofile_error>
read_to(const audio_data_interleaved &output) = 0
Reads audio frames into an interleaved buffer.
Param output Destination buffer for decoded samples.
Returns Number of frames read on success, or an error code on failure.
read function (audio_decoder::read)¶
expected<audio_data_interleaved, audiofile_error>
read(size_t maximum_frames)
Reads up to a maximum number of audio frames into a newly allocated buffer.
Param maximum_frames Maximum number of frames to read.
Returns Audio data on success, or an error code on failure.
seek_is_precise function (audio_decoder::seek_is_precise)¶
virtual bool seek_is_precise() const
Determines whether seeking is precise for this decoder.
Returns True if seeking is precise, false otherwise.
seek function (audio_decoder::seek)¶
virtual expected<void, audiofile_error>
seek(uint64_t position) = 0
Seeks to a specific sample position in the audio stream.
Param position Target position in sample frames.
Returns Success, or an error code if seeking fails.
read_all function (audio_decoder::read_all)¶
expected<audio_data_interleaved, audiofile_error> read_all()
Reads the entire audio stream into an interleaved buffer.
Returns Audio data on success, or an error code on failure.
read_all_planar function (audio_decoder::read_all_planar)¶
expected<audio_data_planar, audiofile_error>
read_all_planar()
Reads the entire audio stream into a planar buffer.
Returns Audio data on success, or an error code on failure.
format function (audio_decoder::format)¶
const std::optional<audiofile_format> &format() const
Retrieves the format of the currently opened audio file.
Returns Audio format if available, or std::nullopt.
has_chunk function (audio_decoder::has_chunk)¶
virtual std::optional<uint64_t>
has_chunk(std::span<const std::byte> chunk_id) const
Checks if the file contains a chunk with the specified ID.
Param chunk_id Identifier of the chunk.
Returns Chunk size if found, or std::nullopt.
read_chunk function (audio_decoder::read_chunk)¶
virtual expected<void, audiofile_error> read_chunk(
std::span<const std::byte> chunk_id,
const std::function<bool(std::span<const std::byte>)>
&handler,
size_t buffer_size = 65536)
Reads a RIFF chunk by its identifier.
Param chunk_id Chunk ID to read.
Param handler Callback invoked with chunk data.
Param buffer_size Buffer size for reading, defaults to 64 KiB.
Returns Success or an error code.
close function (audio_decoder::close)¶
virtual void close() = 0
Closes the audio file and releases resources.
reader function (audio_decoder::reader)¶
std::shared_ptr<binary_reader> reader() const noexcept
Retrieves the binary reader associated with the decoder.
Returns Shared pointer to the binary reader.
read_buffered function (audio_decoder::read_buffered)¶
expected<size_t, audiofile_error> read_buffered(
const audio_data_interleaved &output,
const std::function<
expected<audio_data_interleaved, audiofile_error>()>
&read_packet,
audio_data_interleaved &buffer)
Reads audio frames into a buffer using a custom read function.
Param output Destination buffer for decoded samples.
Param read_packet Function to read audio packets.
Param buffer Temporary buffer for intermediate data.
Returns Number of frames read on success, or an error code on failure.
audiofile_header typedef¶
audiofile_header = std::array<std::byte, 16>
Represents a fixed-size audio file header.
read_audiofile_header function¶
expected<audiofile_header, std::error_code>
read_audiofile_header(const file_path &path)
Reads the header of an audio file.
Param path Path to the audio file.
Returns Audio file header on success, or an error code on failure.
audiofile_container_from_extension function¶
audiofile_container audiofile_container_from_extension(
std::string_view extension)
Determines the audio container type from a file extension.
Param extension File extension with leading dot.
Returns Detected audio container type.
audio_decoding_options class¶
audio_decoding_options
Options for generic audio decoding.
read_metadata variable (audio_decoding_options::read_metadata)¶
bool read_metadata = false
Whether to read metadata tags during decoding.
create_decoder_for_container function¶
std::unique_ptr<audio_decoder> create_decoder_for_container(
audiofile_container container, const audio_decoding_options& options =
Creates an audio decoder for a specific container type.
Param container Audio container type.
Param options Optional decoding options.
Returns Unique pointer to the created decoder.
create_decoder_for_file function¶
std::unique_ptr<audio_decoder> create_decoder_for_file(
const file_path& path, const audio_decoding_options& options =
Creates an audio decoder for a file.
Param path Path to the audio file.
Param options Optional decoding options.
Returns Unique pointer to the created decoder.
create_decoder_from_header function¶
std::unique_ptr<audio_decoder> create_decoder_from_header(
const audiofile_header& header, const audio_decoding_options& options =
Creates an audio decoder from a file header.
Param header The audio file header.
Param options Optional decoding options.
Returns A unique pointer to the created decoder.
raw_decoding_options class¶
raw_decoding_options
Options for decoding raw audio streams.
create_raw_decoder function¶
std::unique_ptr<audio_decoder> create_raw_decoder(const raw_decoding_options& options =
Creates a decoder for raw audio streams.
Param options Optional raw decoding options.
Returns A unique pointer to the created decoder.
wave_decoding_options class¶
wave_decoding_options
Options for decoding WAVE audio files.
create_wave_decoder function¶
std::unique_ptr<audio_decoder> create_wave_decoder(const wave_decoding_options& options =
Creates a decoder for WAVE audio files.
Param options Optional wave decoding options.
Returns A unique pointer to the created decoder.
w64_decoding_options class¶
w64_decoding_options
Options for decoding W64 audio files.
create_w64_decoder function¶
std::unique_ptr<audio_decoder> create_w64_decoder(const w64_decoding_options& options =
Creates a decoder for W64 audio files.
Param options Optional W64 decoding options.
Returns A unique pointer to the created decoder.
aiff_decoding_options class¶
aiff_decoding_options
Options for decoding AIFF audio files.
create_aiff_decoder function¶
std::unique_ptr<audio_decoder> create_aiff_decoder(const aiff_decoding_options& options =
Creates a decoder for AIFF audio files.
Param options Optional AIFF decoding options.
Returns A unique pointer to the created decoder.
caff_decoding_options class¶
caff_decoding_options
Options for decoding CAFF audio files.
create_caff_decoder function¶
std::unique_ptr<audio_decoder> create_caff_decoder(const caff_decoding_options& options =
Creates a decoder for CAFF audio files.
Param options Optional CAFF decoding options.
Returns A unique pointer to the created decoder.
mp3_decoding_options class¶
mp3_decoding_options
Options for decoding MP3 audio files.
create_mp3_decoder function¶
std::unique_ptr<audio_decoder> create_mp3_decoder(const mp3_decoding_options& options =
Creates an MP3 audio decoder with the specified decoding options.
Param options Optional MP3 decoding options.
Returns A unique pointer to the created MP3 decoder.
decode_audio_file function¶
expected<audio_data_interleaved, audiofile_error> decode_audio_file(
const file_path& path, audiofile_format* out_format = nullptr,
const audio_decoding_options& options =
Decodes an audio file and returns the audio data in an interleaved format.
Param path The file path to the audio file.
Param out_format Optional pointer to store the decoded audio format.
Param options Optional decoding options.
Returns The decoded audio data on success, or an error code on failure.
header_is function (details::header_is)¶
bool header_is(const audiofile_header &header,
const char (&h)[17])
Checks whether an audio file header matches a specific pattern (dot is any byte).
Param header The audio file header.
Param h The expected header string.
Returns True if the header matches, false otherwise.
max_audio_channels variable¶
constexpr inline size_t max_audio_channels = 16
*/
audiofile_container enum¶
enum class audiofile_container : uint8_t
Supported audio file container formats.
wave enumerator (audiofile_container::wave)¶
RIFF WAVE
w64 enumerator (audiofile_container::w64)¶
Sony WAVE64
rf64 enumerator (audiofile_container::rf64)¶
RF64 by EBU
bw64 enumerator (audiofile_container::bw64)¶
BW64 as per EBU Tech 3285 v2 (no metadata support yet)
flac enumerator (audiofile_container::flac)¶
FLAC
caf enumerator (audiofile_container::caf)¶
Apple CAF
mp3 enumerator (audiofile_container::mp3)¶
MPEG audio
audiofile_codec enum¶
enum class audiofile_codec : uint8_t
Supported audio file codecs.
audiofile_endianness enum¶
enum class audiofile_endianness : uint8_t
Endianness of audio data.
is_single_codec function¶
constexpr bool
is_single_codec(audiofile_container container)
Checks if a container supports a single codec.
Param container Audio file container format.
Returns True if the container supports a single codec, false otherwise.
audio_quantization class¶
audio_quantization
Represents audio quantization parameters.
samples_load function¶
template <typename Tin>
void samples_load(fbase *out, const Tin *in, size_t size,
bool swap_bytes = false) noexcept
Loads audio samples into a floating-point buffer.
Template param Tin Input sample type.
Param out Destination buffer.
Param in Source buffer.
Param size Number of samples.
Param swap_bytes Whether to swap bytes.
template <typename Tin>
void samples_load(fbase *const out[], const Tin *in,
size_t channels, size_t size,
bool swap_bytes = false) noexcept
Loads interleaved audio samples into a planar floating-point buffer.
Template param Tin Input sample type.
Param out Destination buffers for each channel.
Param in Source buffer.
Param channels Number of channels.
Param size Number of samples per channel.
Param swap_bytes Whether to swap bytes.
samples_store function¶
template <typename Tout>
void samples_store(Tout *out, const fbase *in, size_t size,
const audio_quantization &quantization,
bool swap_bytes = false) noexcept
Stores floating-point samples into a buffer with quantization.
Template param Tout Output sample type.
Param out Destination buffer.
Param in Source buffer.
Param size Number of samples.
Param quantization Quantization parameters.
Param swap_bytes Whether to swap bytes.
template <typename Tout>
void samples_store(Tout *out, const fbase *const in[],
size_t channels, size_t size,
const audio_quantization &quantization,
bool swap_bytes = false) noexcept
Stores planar floating-point samples into an interleaved buffer with quantization.
Template param Tout Output sample type.
Param out Destination buffer.
Param in Source buffers for each channel.
Param channels Number of channels.
Param size Number of samples per channel.
Param quantization Quantization parameters.
Param swap_bytes Whether to swap bytes.
template <typename Tout>
void samples_store(Tout *out, const fbase *const in[],
size_t channels, size_t size,
bool swap_bytes = false) noexcept
Stores planar floating-point samples into a interleaved buffer.
Template param Tout Output sample type.
Param out Destination buffer.
Param in Source buffers for each channel.
Param channels Number of channels.
Param size Number of samples per channel.
Param swap_bytes Whether to swap bytes.
samples_load function¶
void samples_load(audio_sample_type type, fbase *out,
const std::byte *in, size_t size,
bool swap_bytes = false) noexcept
Loads audio samples based on sample type.
Param type Audio sample type.
Param out Destination buffer.
Param in Source buffer.
Param size Number of samples.
Param swap_bytes Whether to swap bytes.
void samples_load(audio_sample_type type,
fbase *const out[], const std::byte *in,
size_t channels, size_t size,
bool swap_bytes = false) noexcept
Loads interleaved audio samples based on sample type.
Param type Audio sample type.
Param out Destination buffers for each channel.
Param in Source buffer.
Param channels Number of channels.
Param size Number of samples per channel.
Param swap_bytes Whether to swap bytes.
samples_store function¶
void samples_store(audio_sample_type type, std::byte *out,
const fbase *in, size_t size,
const audio_quantization &quantization,
bool swap_bytes = false) noexcept
Stores audio samples based on sample type with quantization.
Param type Audio sample type.
Param out Destination buffer.
Param in Source buffer.
Param size Number of samples.
Param quantization Quantization parameters.
Param swap_bytes Whether to swap bytes.
void samples_store(audio_sample_type type, std::byte *out,
const fbase *const in[], size_t channels,
size_t size,
const audio_quantization &quantization,
bool swap_bytes = false) noexcept
Stores interleaved audio samples based on sample type with quantization.
Param type Audio sample type.
Param out Destination buffer.
Param in Source buffers for each channel.
Param channels Number of channels.
Param size Number of samples per channel.
Param quantization Quantization parameters.
Param swap_bytes Whether to swap bytes.
void samples_store(audio_sample_type type, std::byte *out,
const fbase *const in[], size_t channels,
size_t size,
bool swap_bytes = false) noexcept
Stores interleaved audio samples based on sample type.
Param type Audio sample type.
Param out Destination buffer.
Param in Source buffers for each channel.
Param channels Number of channels.
Param size Number of samples per channel.
Param swap_bytes Whether to swap bytes.
audiofile_format class¶
audiofile_format
Represents the format of an audio file.
container variable (audiofile_format::container)¶
audiofile_container container = audiofile_container::unknown
*/
codec variable (audiofile_format::codec)¶
audiofile_codec codec = audiofile_codec::unknown
*/
endianness variable (audiofile_format::endianness)¶
audiofile_endianness endianness =
audiofile_endianness::little
*/
bit_depth variable (audiofile_format::bit_depth)¶
uint8_t bit_depth = 0
*/
channels variable (audiofile_format::channels)¶
uint32_t channels = 0
*/
sample_rate variable (audiofile_format::sample_rate)¶
uint32_t sample_rate = 0
*/
speakers variable (audiofile_format::speakers)¶
speaker_arrangement speakers
*/
metadata variable (audiofile_format::metadata)¶
metadata_map metadata
*/
audio_stat class¶
audio_stat
Represents audio statistics such as peak and RMS values.
aligned_deallocator class (details::aligned_deallocator)¶
aligned_deallocator
lambda_deallocator class (details::lambda_deallocator)¶
template <typename Fn> lambda_deallocator
strided_channel class¶
template <typename T> strided_channel
Represents a strided audio channel.
Template param T Data type.
expression_traits class¶
template <typename T> expression_traits
audio_data class¶
template <bool Interleaved = false> audio_data
Contiguous audio buffer with optional interleaving.
Stores multi-channel audio either as planar (separate channel buffers) or interleaved
(single strided buffer). Provides allocation, slicing, arithmetic, and traversal utilities.
Template param Interleaved If true, samples are interleaved; otherwise planar per-channel pointers.
channels variable (audio_data::channels)¶
uint32_t channels = 0
*/
data variable (audio_data::data)¶
chan<fbase *, Interleaved> data
*/
size variable (audio_data::size)¶
size_t size
*/
capacity variable (audio_data::capacity)¶
size_t capacity
*/
position variable (audio_data::position)¶
int64_t position = 0
*/
deallocator variable (audio_data::deallocator)¶
std::shared_ptr<void> deallocator
*/
audio_data<Interleaved> function (audio_data::audio_data<Interleaved>)¶
audio_data(const audio_data<!Interleaved> &other)
: audio_data(other.channels, other.size)
Converts between planar and interleaved layouts.
Constructs an audio_data with the same channel count and frame count as @p other,
converting sample storage between interleaved and non-interleaved layouts as needed.
If @p other is empty, the result is empty.
Param other Source buffer with the opposite interleaving layout.
explicit audio_data(size_t channels, size_t size = 0)
Constructs an audio_data buffer with the specified channel count and optional initial size.
Allocates aligned storage and initializes channel pointers according to layout: - Interleaved: a single contiguous block. - Planar: per-channel blocks aligned to 64 bytes (allocated as single memory block).
If size is 0, an empty buffer is created without allocating sample storage.
Capacity is set to size, and can be increased later via reserve().
Param channels Number of audio channels (1..max_audio_channels).
Param size Optional initial number of samples per channel (capacity); 0 defers allocation.
@pre channels > 0 && channels <= max_audio_channels
@post Channel pointers are initialized; storage (if allocated) is owned and freed automatically.
Exceptions If memory allocation fails.
audio_data(size_t channels, size_t size, fbase value)
Constructs an audio buffer and initializes all samples to a constant value.
Param channels Number of channels to allocate.
Param size Number of samples per channel.
Param value Initial sample value applied to every element.
Note Equivalent to constructing with (channels, size) and then filling with value.
Exceptions If memory allocation fails.
total_samples function (audio_data::total_samples)¶
size_t total_samples() const noexcept
Calculates the total number of audio samples.
This function computes the total number of samples by multiplying the size
(number of frames) by the number of channels in the audio data.
Returns The total number of samples as a size_t value.
reset function (audio_data::reset)¶
void reset()
Resets the object to its default state.
This function assigns a default-constructed instance of the object to itself, effectively resetting all its members to their default values.
fill function (audio_data::fill)¶
void fill(fbase value)
Fills the audio data with the specified value.
This function sets all elements of the audio data to the given value.
Param value The value to fill the audio data with.
multiply function (audio_data::multiply)¶
void multiply(fbase value)
Multiplies the audio data by a specified scalar value.
This function scales the audio data by the given factor, modifying
the current data in place.
Param value The scalar value to multiply the audio data by.
clear function (audio_data::clear)¶
void clear()
Clears all audio data, leaving the container empty (size == 0).
resize function (audio_data::resize)¶
void resize(size_t new_size)
Resizes the container to hold exactly new_size elements.
- If new_size <= current capacity, adjusts size without reallocating.
- Otherwise, increases capacity (rounded up) via reserve() and then updates size.
Preserves existing elements up to min(old_size, new_size). When growing, newly
added elements may be left uninitialized. Shrinking does not reduce capacity.
May reallocate on growth, invalidating pointers/references to elements.
Param new_size Number of elements desired.
void resize(size_t new_size, fbase value)
Resize to the specified length and initialize newly added samples.
Preserves existing data. If the size grows, the appended region is filled with the given value;
if it shrinks, the buffer is truncated. Works with both interleaved and planar layouts, applying
initialization across all channels as appropriate.
Param new_size Target number of frames (samples per channel).
Param value Sample value used to initialize newly created elements.
empty function (audio_data::empty)¶
bool empty() const noexcept
Check whether this audio data container is empty.
Details Considered empty if either the number of channels is zero or the size (samples/frames) is
zero.
Returns true if no channels or no samples.
channel function (audio_data::channel)¶
univector_ref<fbase> channel(size_t index) const noexcept
requires(!Interleaved)
Retrieves a reference to the audio data of a specific channel.
This function returns a univector_ref<fbase\> representing the audio data
for the specified channel index. It is only available when the audio data
is not interleaved (i.e., Interleaved is false).
Param index The index of the channel to retrieve. Must be less than the
total number of channels.
Returns A univector_ref<fbase\> representing the audio data for the specified channel.
interlaved function (audio_data::interlaved)¶
univector_ref<fbase> interlaved() const noexcept
requires(Interleaved)
Returns a reference to the interleaved audio data.
This function provides access to the interleaved audio data as a univector_ref<fbase\>.
It is only available when the audio data is interleaved (i.e., Interleaved is true).
Returns A univector_ref<fbase\> representing the interleaved audio data.
The size of the returned reference is calculated as size * channels.
pointers function (audio_data::pointers)¶
fbase *const *pointers() const noexcept
requires(!Interleaved)
Retrieves an array of pointers to the base type of the audio data.
This function returns a pointer to the underlying data array, which contains
pointers to the base type (fbase*). It is only available when the audio data
is not interleaved (i.e., Interleaved is false).
Returns A pointer to the array of fbase* representing the audio data.
channel_count function (audio_data::channel_count)¶
size_t channel_count() const noexcept
Retrieves the number of audio channels.
slice function (audio_data::slice)¶
audio_data slice(size_t start,
size_t length = SIZE_MAX) const
Creates a slice of the audio data starting at a specified position and with a specified length.
Param start The starting position of the slice (in samples).
Param length The length of the slice (in samples). Defaults to SIZE_MAX, which means the slice will
extend to the end of the audio data if not specified.
Returns audio_data A new audio_data object representing the sliced portion of the original data.
Note The function ensures that the slice does not exceed the bounds of the audio data. If the
requested length exceeds the available data, the slice will be truncated to fit within the bounds.
Exceptions If the starting position is out of range.
Details - The position of the resulting slice is updated to reflect the starting position of the slice.
truncate function (audio_data::truncate)¶
audio_data truncate(size_t length) const
Truncates the audio data to the specified length.
This function creates a new audio_data object that contains only the
first length samples from the current audio data. If the specified
length is greater than the size of the current audio data, the entire
audio data is returned.
Param length The number of samples to retain in the truncated audio data.
Returns A new audio_data object containing the truncated data.
slice_past_end function (audio_data::slice_past_end)¶
audio_data slice_past_end(size_t length)
Creates a new audio_data object representing a slice of audio data starting past the end of the current data.
This function reserves additional space in the current audio data to
accommodate the specified length, then creates a new audio_data object
that represents a slice of the specified length starting from the end
of the current data. The new slice shares the same underlying data buffer
as the original object.
Param length The length of the slice to create, in samples.
Returns A new audio_data object representing the slice.
stat function (audio_data::stat)¶
audio_stat stat() const noexcept
Retrieves the statistical information of the audio data.
is_silent function (audio_data::is_silent)¶
bool is_silent(fbase threshold = fbase(1e-5)) const noexcept
Checks whether all samples in the buffer are effectively silent within a given amplitude
threshold.
Param threshold Non-negative amplitude threshold. Any sample with absolute value
strictly greater than this threshold makes the buffer non-silent. Values exactly
equal to the threshold are treated as silent. Default: 1e-5.
Returns true if every sample lies within [-threshold, threshold]; false otherwise.
for_channel function (audio_data::for_channel)¶
template <std::invocable<fbase *> Fn>
void for_channel(Fn &&fn)
Executes a provided function for each audio channel's data.
This function applies the given callable object fn to the audio data.
If the audio data is interleaved, the function is called once with the
entire data. Otherwise, the function is called for each channel's data
individually.
Template param Fn The type of the callable object.
Param fn The callable object to be executed. It should accept either
the entire data (if interleaved) or a single channel's data
(if not interleaved).
template <std::invocable<univector_ref<fbase>> Fn>
void for_channel(Fn &&fn)
Applies a given function to the audio data for each channel.
This function iterates over the audio channels and applies the provided
function object fn to the data. The behavior depends on whether the
audio data is interleaved or not:
- If the data is interleaved, the function is called once with a single univector containing all the interleaved data.
- If the data is not interleaved, the function is called for each channel
separately with a univector containing the data for that specific channel.
Template paramFnThe type of the function object to be applied.
ParamfnThe function object to be applied to the audio data. It should accept a univector as its argument.
audio_data_planar typedef¶
audio_data_planar = audio_data<false>
audio_data_planarAlias for audio_data with planar (non-interleaved) storage format.
This type alias represents audio data stored in a planar format, where each channel's samples are stored in a separate contiguous block of memory.
audio_data_interleaved typedef¶
audio_data_interleaved = audio_data<true>
audio_data_interleavedAlias for audio_data with interleaved storage.
This type alias represents audio data where the samples are stored
in an interleaved format. Interleaved audio data means that the
samples for multiple channels are stored sequentially in memory.
For example, in a stereo audio signal, the data would be stored as:
L1, R1, L2, R2, ..., where L and R represent the left and right
channel samples, respectively.
Note audio_data
audio_dithering enum¶
enum class audio_dithering
Supported audio dithering methods.
audio_dithering_state class¶
audio_dithering_state
Represents the state of audio dithering.
audio_quantization class¶
audio_quantization
Represents audio quantization parameters.
stdFILE_deleter class (details::stdFILE_deleter)¶
stdFILE_deleter
Auto-generated from sources, Revision , https://github.com/kfrlib/kfr/blob//include/kfr/