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.

typedef value_type 

using value_type      = fbase

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

Declared at audio/data.hpp:470

typedef pointer 

using pointer         = fbase*

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

Declared at audio/data.hpp:471

typedef const_pointer 

using const_pointer   = const fbase*

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

Declared at audio/data.hpp:472

typedef reference 

using reference       = fbase&

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

Declared at audio/data.hpp:473

typedef const_reference 

using const_reference = const fbase&

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

Declared at audio/data.hpp:474

typedef size_type 

using size_type       = size_t

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

Declared at audio/data.hpp:475

typedef difference_type 

using difference_type = ptrdiff_t

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

Declared at audio/data.hpp:476

variable is_interleaved 

static constexpr bool is_interleaved = IsInterleaved

Whether samples are interleaved.

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

Declared at audio/data.hpp:478

variable channels 

uint32_t channels = 0

Number of channels.

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

Declared at audio/data.hpp:480

variable data 

chan<fbase*, IsInterleaved> data{}

Pointers to channel data.

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

Declared at audio/data.hpp:481

variable size 

size_t size

Number of samples per channel.

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

Declared at audio/data.hpp:482

variable capacity 

size_t capacity

Allocated capacity per channel.

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

Declared at audio/data.hpp:483

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:484

variable deallocator 

std::shared_ptr<void> deallocator

Deallocator for the data.

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

Declared at audio/data.hpp:485

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:487

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:489

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:513

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:514

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:515

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:516

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:531

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:549

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:564

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:581

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:606

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:616

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:626

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:634

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:643

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:653

function apply_gain_dB(fbase) 

void apply_gain_dB(fbase gain_db)

Applies a gain in decibels (dB) in place.

Parameters
gain_db Gain in decibels.

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

Declared at audio/data.hpp:659

function normalize(fbase) 

void normalize(fbase target_peak = fbase(1.0))

Normalizes the audio data to a target peak amplitude.

Parameters
target_peak Target absolute peak amplitude (default: 1.0).

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

Declared at audio/data.hpp:669

function clamp(fbase, fbase) 

void clamp(fbase min_val = fbase(-1.0), fbase max_val = fbase(1.0))

Clamps all samples to the range [min_val, max_val] in place.

Parameters
min_val Minimum allowed sample value (default: -1.0).
max_val Maximum allowed sample value (default: +1.0).

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

Declared at audio/data.hpp:677

function to_mono() 

[[nodiscard]] audio_data to_mono() const

Downmixes all channels to a single mono channel by averaging.

Computes the mean across all channels for each frame. Returns a 1-channel audio_data.

Returns
A new 1-channel audio_data containing the downmixed audio.

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

Declared at audio/data.hpp:686

function to_interleaved() 

[[nodiscard]] audio_data<true> to_interleaved() const

Returns an interleaved copy of this audio data.

If the audio data is already interleaved, creates a deep copy.

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

Declared at audio/data.hpp:693

function to_planar() 

[[nodiscard]] audio_data<false> to_planar() const

Returns a planar copy of this audio data.

If the audio data is already planar, creates a deep copy.

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

Declared at audio/data.hpp:700

function select_channel(size_t) 

[[nodiscard]] audio_data select_channel(size_t ch) const
    requires(!IsInterleaved)

Selects a single channel view, referencing the original data and retaining the deallocator.

Parameters
ch Channel index to select.
Returns
A 1-channel audio_data referencing the selected channel.

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

Declared at audio/data.hpp:708

function select_channels(size_t, size_t) 

[[nodiscard]] audio_data select_channels(size_t min_ch, size_t max_ch) const
    requires(!IsInterleaved)

Selects a range of channels [min_ch, max_ch], referencing the original data and retaining the deallocator.

Parameters
min_ch Starting channel index (inclusive).
max_ch Ending channel index (inclusive).
Returns
An audio_data view containing the selected channel range.

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

Declared at audio/data.hpp:719

function clone() 

[[nodiscard]] audio_data clone() const

Creates an independent deep copy of this audio data.

Allocates new storage and copies all sample values into the new buffer.

Returns
A deep copy of this audio_data.

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

Declared at audio/data.hpp:729

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:734

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:748

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:760

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:772

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:804

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:816

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:823

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:829

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:837

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:857

function interleaved() 

[[nodiscard]] univector_ref<fbase> interleaved() 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>::interleaved()

Declared at audio/data.hpp:873

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:888

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:897

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:915

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:928

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:943

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:948

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:959

function find_peak() 

[[nodiscard]] size_t find_peak() const noexcept

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

Declared at audio/data.hpp:961

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:1010

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.