Skip to content

Class audio_data

class audio_data<IsInterleaved> audio

template <bool IsInterleaved = false>
struct 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 parameters
IsInterleaved If true, samples are interleaved; otherwise planar per-channel pointers.

variable channels 

uint32_t channels = 0

Number of channels.

Fully qualified name: kfr::audio_data<IsInterleaved>::channels

Declared at audio/data.hpp:470

variable data 

chan<fbase*, IsInterleaved> data{}

Pointers to channel data.

Fully qualified name: kfr::audio_data<IsInterleaved>::data

Declared at audio/data.hpp:471

variable size 

size_t size

Number of samples per channel.

Fully qualified name: kfr::audio_data<IsInterleaved>::size

Declared at audio/data.hpp:472

variable capacity 

size_t capacity

Allocated capacity per channel.

Fully qualified name: kfr::audio_data<IsInterleaved>::capacity

Declared at audio/data.hpp:473

variable position 

int64_t position = 0

Position of the first sample in the audio data.

Fully qualified name: kfr::audio_data<IsInterleaved>::position

Declared at audio/data.hpp:474

variable deallocator 

std::shared_ptr<void> deallocator

Deallocator for the data.

Fully qualified name: kfr::audio_data<IsInterleaved>::deallocator

Declared at audio/data.hpp:475

function operator==(const audio_data<IsInterleaved> &) 

bool operator==(const audio_data& other) const noexcept = default

Fully qualified name: kfr::audio_data<IsInterleaved>::operator==(const audio_data<IsInterleaved> &)

Declared at audio/data.hpp:477

constructor audio_data<IsInterleaved>() 

[[nodiscard]] constexpr audio_data() noexcept : size(0), capacity(0) { … }

Fully qualified name: kfr::audio_data<IsInterleaved>::audio_data<IsInterleaved>()

Declared at audio/data.hpp:479

constructor audio_data<IsInterleaved>(const audio_data<!IsInterleaved> &) 

audio_data(const audio_data&) noexcept            = default

Converts between planar and interleaved layouts.

Parameters
other Source buffer with the opposite interleaving layout.

Fully qualified name: kfr::audio_data<IsInterleaved>::audio_data<IsInterleaved>(const audio_data<!IsInterleaved> &)

Declared at audio/data.hpp:503

constructor audio_data<IsInterleaved>(audio_data<IsInterleaved> &&) 

audio_data(audio_data&&) noexcept                 = default

Fully qualified name: kfr::audio_data<IsInterleaved>::audio_data<IsInterleaved>(audio_data<IsInterleaved> &&)

Declared at audio/data.hpp:504

function operator=(const audio_data<IsInterleaved> &) 

audio_data& operator=(const audio_data&) noexcept = default

Fully qualified name: kfr::audio_data<IsInterleaved>::operator=(const audio_data<IsInterleaved> &)

Declared at audio/data.hpp:505

function operator=(audio_data<IsInterleaved> &&) 

audio_data& operator=(audio_data&&) noexcept      = default

Fully qualified name: kfr::audio_data<IsInterleaved>::operator=(audio_data<IsInterleaved> &&)

Declared at audio/data.hpp:506

function audio_data<IsInterleaved>(std::span<fbase *const>, size_t, Fn &&) 

template <std::invocable Fn>
[[nodiscard]] audio_data(std::span<fbase* const> pointers, size_t size, Fn&& deallocator)
    requires(!IsInterleaved)

Constructs a planar audio_data view from external channel pointers with a custom deallocator.

Parameters
pointers Span of per-channel fbase pointers (one per channel).
size Number of samples per channel.
deallocator Callable invoked on destruction to release the underlying storage.
Preconditions
pointers.size() > 0 && pointers.size() <= max_audio_channels

Fully qualified name: kfr::audio_data<IsInterleaved>::audio_data<IsInterleaved>(std::span<fbase *const>, size_t, Fn &&)

Declared at audio/data.hpp:521

constructor audio_data<IsInterleaved>(std::span<fbase *const>, size_t) 

[[nodiscard]] audio_data(std::span<fbase* const> pointers, size_t size)
    requires(!IsInterleaved)

Constructs a planar audio_data view from external channel pointers.

Parameters
pointers Span of per-channel fbase pointers (one per channel).
size Number of samples per channel.
Preconditions
pointers.size() > 0 && pointers.size() <= max_audio_channels

Fully qualified name: kfr::audio_data<IsInterleaved>::audio_data<IsInterleaved>(std::span<fbase *const>, size_t)

Declared at audio/data.hpp:539

constructor audio_data<IsInterleaved>(fbase *, size_t, size_t) 

[[nodiscard]] audio_data(fbase* pointer, size_t channels, size_t size)
    requires(IsInterleaved)

Constructs an interleaved audio_data view from an external buffer.

Parameters
pointer Pointer to the interleaved sample buffer (size * channels elements).
channels Number of interleaved channels.
size Number of frames (samples per channel).
Preconditions
channels > 0 && channels <= max_audio_channels

Fully qualified name: kfr::audio_data<IsInterleaved>::audio_data<IsInterleaved>(fbase *, size_t, size_t)

Declared at audio/data.hpp:554

function audio_data<IsInterleaved>(fbase *, size_t, size_t, Fn &&) 

template <std::invocable Fn>
[[nodiscard]] audio_data(fbase* pointer, size_t channels, size_t size, Fn&& deallocator)
    requires(IsInterleaved)

Constructs an interleaved audio_data view from an external buffer with a custom deallocator.

Parameters
pointer Pointer to the interleaved sample buffer (size * channels elements).
channels Number of interleaved channels.
size Number of frames (samples per channel).
deallocator Callable invoked on destruction to release the underlying storage.
Preconditions
channels > 0 && channels <= max_audio_channels

Fully qualified name: kfr::audio_data<IsInterleaved>::audio_data<IsInterleaved>(fbase *, size_t, size_t, Fn &&)

Declared at audio/data.hpp:571

constructor audio_data<IsInterleaved>(size_t, size_t) 

[[nodiscard]] 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().

Parameters
channels Number of audio channels (1..max_audio_channels).
size Optional initial number of samples per channel (capacity); 0 defers allocation.
Preconditions
channels > 0 && channels <= max_audio_channels
Postconditions
Channel pointers are initialized; storage (if allocated) is owned and freed automatically.
Exceptions
std::bad_alloc If memory allocation fails.

Fully qualified name: kfr::audio_data<IsInterleaved>::audio_data<IsInterleaved>(size_t, size_t)

Declared at audio/data.hpp:596

constructor audio_data<IsInterleaved>(size_t, size_t, fbase) 

[[nodiscard]] audio_data(size_t channels, size_t size, fbase value)

Constructs an audio buffer and initializes all samples to a constant value.

Parameters
channels Number of channels to allocate.
size Number of samples per channel.
value Initial sample value applied to every element.

Note

Equivalent to constructing with (channels, size) and then filling with value.

Exceptions
std::bad_alloc If memory allocation fails.

Fully qualified name: kfr::audio_data<IsInterleaved>::audio_data<IsInterleaved>(size_t, size_t, fbase)

Declared at audio/data.hpp:606

function 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.

Fully qualified name: kfr::audio_data<IsInterleaved>::total_samples()

Declared at audio/data.hpp:616

function 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.

Fully qualified name: kfr::audio_data<IsInterleaved>::reset()

Declared at audio/data.hpp:624

function fill(fbase) 

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.

Parameters
value The value to fill the audio data with.

Fully qualified name: kfr::audio_data<IsInterleaved>::fill(fbase)

Declared at audio/data.hpp:633

function multiply(fbase) 

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.

Parameters
value The scalar value to multiply the audio data by.

Fully qualified name: kfr::audio_data<IsInterleaved>::multiply(fbase)

Declared at audio/data.hpp:643

function clear() 

void clear()

Clears all audio data, leaving the container empty (size == 0).

Fully qualified name: kfr::audio_data<IsInterleaved>::clear()

Declared at audio/data.hpp:648

function resize(size_t) 

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.

Parameters
new_size Number of elements desired.

Fully qualified name: kfr::audio_data<IsInterleaved>::resize(size_t)

Declared at audio/data.hpp:662

function resize(size_t, fbase) 

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.

Parameters
new_size Target number of frames (samples per channel).
value Sample value used to initialize newly created elements.

Fully qualified name: kfr::audio_data<IsInterleaved>::resize(size_t, fbase)

Declared at audio/data.hpp:674

function reserve(size_t) 

void reserve(size_t new_capacity)

Increases the allocated capacity, preserving existing samples.

Parameters
new_capacity Target capacity in frames (samples per channel).

Fully qualified name: kfr::audio_data<IsInterleaved>::reserve(size_t)

Declared at audio/data.hpp:686

function append(const audio_data<IsInterleaved> &) 

void append(const audio_data<!IsInterleaved>& other)

Appends samples from a buffer with the opposite layout.

Parameters
other Source buffer with the opposite interleaving layout to append.

Fully qualified name: kfr::audio_data<IsInterleaved>::append(const audio_data<IsInterleaved> &)

Declared at audio/data.hpp:718

function prepend(const audio_data<IsInterleaved> &) 

void prepend(const audio_data<!IsInterleaved>& other)

Prepends samples from a buffer with the opposite layout.

Parameters
other Source buffer with the opposite interleaving layout to prepend.

Fully qualified name: kfr::audio_data<IsInterleaved>::prepend(const audio_data<IsInterleaved> &)

Declared at audio/data.hpp:730

function swap(audio_data<IsInterleaved> &, audio_data<IsInterleaved> &) 

friend void swap(audio_data& a, audio_data& b) noexcept

Swaps two audio_data buffers.

Parameters
a First buffer.
b Second buffer.

Fully qualified name: kfr::audio_data<IsInterleaved>::swap(audio_data<IsInterleaved> &, audio_data<IsInterleaved> &)

Declared at audio/data.hpp:737

function swap(audio_data<IsInterleaved> &) 

void swap(audio_data& other) noexcept

Exchanges the contents of this buffer with other.

Parameters
other Buffer to swap contents with.

Fully qualified name: kfr::audio_data<IsInterleaved>::swap(audio_data<IsInterleaved> &)

Declared at audio/data.hpp:743

function empty() 

[[nodiscard]] bool empty() const noexcept

Check whether this audio data container is empty.

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.

Fully qualified name: kfr::audio_data<IsInterleaved>::empty()

Declared at audio/data.hpp:751

function channel(size_t) 

[[nodiscard]] strided_channel<fbase> channel(size_t index) const noexcept
    requires(IsInterleaved)

Retrieves a reference to the audio data of a specific channel.

Parameters
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.

Fully qualified name: kfr::audio_data<IsInterleaved>::channel(size_t)

Declared at audio/data.hpp:771

function interlaved() 

[[nodiscard]] univector_ref<fbase> interlaved() const noexcept
    requires(IsInterleaved)

Returns a reference to the interleaved audio data.

Returns
A univector_ref<fbase> representing the interleaved audio data. The size of the returned reference is calculated as size * channels .

Fully qualified name: kfr::audio_data<IsInterleaved>::interlaved()

Declared at audio/data.hpp:787

function pointers() 

[[nodiscard]] fbase* const* pointers() const noexcept
    requires(!IsInterleaved)

Retrieves an array of pointers to the base type of the audio data.

Returns
A pointer to the array of fbase* representing the audio data.

Fully qualified name: kfr::audio_data<IsInterleaved>::pointers()

Declared at audio/data.hpp:802

function channel_count() 

[[nodiscard]] size_t channel_count() const noexcept

Retrieves the number of audio channels.

Fully qualified name: kfr::audio_data<IsInterleaved>::channel_count()

Declared at audio/data.hpp:811

function slice(size_t, size_t) 

[[nodiscard]] 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.

Parameters
start The starting position of the slice (in samples).
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
std::logic_error If the starting position is out of range.

- The position of the resulting slice is updated to reflect the starting position of the slice.

Fully qualified name: kfr::audio_data<IsInterleaved>::slice(size_t, size_t)

Declared at audio/data.hpp:829

function truncate(size_t) 

[[nodiscard]] audio_data truncate(size_t length) const

Truncates the audio data to the specified length.

Parameters
length The number of samples to retain in the truncated audio data.
Returns
A new audio_data object containing the truncated data.

Fully qualified name: kfr::audio_data<IsInterleaved>::truncate(size_t)

Declared at audio/data.hpp:842

function slice_past_end(size_t) 

[[nodiscard]] 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.

Parameters
length The length of the slice to create, in samples.
Returns
A new audio_data object representing the slice.

Fully qualified name: kfr::audio_data<IsInterleaved>::slice_past_end(size_t)

Declared at audio/data.hpp:857

function stat() 

[[nodiscard]] audio_stat stat() const noexcept

Retrieves the statistical information of the audio data.

Fully qualified name: kfr::audio_data<IsInterleaved>::stat()

Declared at audio/data.hpp:862

function is_silent(fbase) 

[[nodiscard]] 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.

Parameters
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.

Fully qualified name: kfr::audio_data<IsInterleaved>::is_silent(fbase)

Declared at audio/data.hpp:873

function find_peak() 

[[nodiscard]] size_t find_peak() const noexcept

Fully qualified name: kfr::audio_data<IsInterleaved>::find_peak()

Declared at audio/data.hpp:875

function for_channel(Fn &&) 

template <std::invocable<univector_ref<fbase>> Fn>
void for_channel(Fn&& fn)

Applies a given function to the audio data for each channel.

- 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 parameters
Fn The type of the function object to be applied.
Parameters
fn The function object to be applied to the audio data. It should accept a univector as its argument.

Fully qualified name: kfr::audio_data<IsInterleaved>::for_channel(Fn &&)

Declared at audio/data.hpp:924

Fully qualified name: kfr::audio_data<IsInterleaved>

Declared at audio/data.hpp:468

This file was generated by cxxdox, a C++ documentation generator based on MkDocs Material and libclang.