echomap::Signal Class Reference

A single channel of discretely sampled audio data. More...

#include <Signal.hpp>

Inheritance diagram for echomap::Signal:

Classes
struct	Sample
	A PCM float-32 sampled audio point at an explicit time offset. More...
struct	Source
	Indicates an external source of a Signal on the filesystem. More...
struct	Baseline
	Provides basic timing information relating to the Signal samples. More...

Public Member Functions
std::uint64_t	get_sample_count () const noexcept
	Retrieves the total number of samples in the Signal stream.
const std::optional< Source > &	observe_source () const noexcept
	Retrieves the optional Source of the Signal.
Sample::TimeT	get_time_offset () const noexcept
std::size_t	get_sample_rate () const noexcept
decltype(samples) ::const_iterator	begin () const
decltype(samples) ::const_iterator	end () const
decltype(samples) ::const_iterator	cbegin () const noexcept
decltype(samples) ::const_iterator	cend () const noexcept
auto	timed_samples () const
Sample::AmplitudeT	operator[] (std::size_t index) const noexcept
std::span< const Sample::AmplitudeT >	amplitudes () const noexcept
bool	is_uniformly_sampled () const noexcept
Sample::TimeT	get_time_at_index (std::size_t index) const noexcept
	Determines the corresponding time of the amplitude appearing at the given index in the sample array.
	Signal (const Signal &old_signal)
	Signal (const Signal &old_signal, std::string_view new_name)
Public Member Functions inherited from echomap::Object< Signal >
	~Object ()=default
	Non-virtual base destructor.
id_type	get_id () const noexcept
bool	is_valid () const noexcept
void	set_name (const std::string_view new_name)
std::string_view	get_name () const noexcept
const char *	get_imgui_name () const noexcept
	Object (const Object &)=delete
Object &	operator= (const Object &)=delete
bool	operator== (const Object &other) const noexcept
	Determine shallow equality between two Object instances.

Static Public Attributes
static constexpr std::pair< Sample::AmplitudeT, Sample::AmplitudeT >	normalised_range = {-1.0f, 1.0f}
	The range within which the amplitude values are normalised.

Private Member Functions
	Signal (std::string_view name={}, const std::optional< Source > &source={})
	Creates an empty optionally named Signal.
void	emplace_sample (Sample::AmplitudeT amplitude)
	Emplace a sample to the back of the channel sample data.
void	emplace_sample (Sample::TimeT time, Sample::AmplitudeT amplitude)
	Emplace a sample to the back of the channel sample data.
void	emplace_sample (const Sample &sample)
	Emplace a sample to the back of the channel sample data.
void	emplace_sample_from_source (Sample::AmplitudeT amplitude)
	Emplace an externally sourced sample to the back of the channel sample data.
void	emplace_sample_from_source (Sample::TimeT time, Sample::AmplitudeT amplitude)
	Emplace an externally sourced sample to the back of the channel sample data.
void	emplace_sample_from_source (const Sample &sample)
	Emplace an externally sourced sample to the back of the channel sample data.
void	reserve_samples (std::size_t count)
	Reserves memory to store the given number of total samples in the channel.
void	set_source (const std::filesystem::path &path, std::size_t channel)
void	set_time_offset (Sample::TimeT new_time_offset) noexcept
void	set_sample_rate (std::size_t new_sample_rate) noexcept
void	emplace_time (Sample::TimeT given_time)
	Implementation helper to associate the latest amplitude sample with the given time.

Private Attributes
std::vector< Sample::AmplitudeT >	samples
	Amplitude sample stream.
Baseline	timing_baseline
	A baseline of timing parameters.
std::optional< Source >	fs_source
	External source, if any, of the Signal Sample stream.
std::optional< std::vector< Sample::TimeT > >	time_offsets
	An optional vector of explicit timestamps for each sample.

Friends
class	SignalFactory

Additional Inherited Members
Static Public Member Functions inherited from echomap::Object< Signal >
static std::string_view	get_class_name () noexcept
Protected Member Functions inherited from echomap::Object< Signal >
void	move_identity_from (Object &&other) noexcept
	Helper for derived classes to provide move-assignment operations.

Detailed Description

A single channel of discretely sampled audio data.

Signals always store their sampled time series in memory, but they optionally express an external source. This is currently a file specification on the local file system, and an internal channel number, indicating the origin of the sample data.

Signal objects must be constructed by a SignalFactory. Following release from the factory, all non-metadata state is immutable, particularly the Sample time series. Trivial metadata (such as the display name from Object) may be modified at will.

Invariant

Amplitude samples are stored contiguously in memory. Timing information may either be inferred from the baseline sampling model or adjusted by an optional per-sample offset array. The timed samples range is a lazy logical view and is not contiguous.

Definition at line 39 of file Signal.hpp.

Constructor & Destructor Documentation

Signal() [1/3]

echomap::Signal::Signal

(

const Signal &

old_signal

)

Definition at line 105 of file Signal.cpp.

  :
    Object(CopyTag{},
           old_signal),
    samples(old_signal.samples),
    timing_baseline(old_signal.timing_baseline),
    fs_source(old_signal.fs_source),
    time_offsets(old_signal.time_offsets)
{
}

Signal() [2/3]

echomap::Signal::Signal	(	const Signal &	old_signal,
		std::string_view	new_name )

Definition at line 117 of file Signal.cpp.

  :
    Object(CopyTag{},
           old_signal,
           new_name),
    samples(old_signal.samples),
    timing_baseline(old_signal.timing_baseline),
    fs_source(old_signal.fs_source),
    time_offsets(old_signal.time_offsets)
{
}

Signal() [3/3]

echomap::Signal::Signal ( std::string_view name = {}, const std::optional< Source > & source = {} )

explicitprivate

Creates an empty optionally named Signal.

Parameters

name	Optional display name.
source	Optional file system source path indicating the origin of the file.

Definition at line 19 of file Signal.cpp.

  :
    Object(name),
    fs_source(source)
{
}

Member Function Documentation

amplitudes()

std::span< const Signal::Sample::AmplitudeT > echomap::Signal::amplitudes ( ) const

nodiscardnoexcept

Definition at line 85 of file Signal.cpp.

{
    return samples;
}

begin()

decltype(Signal::samples) const_iterator echomap::Signal::begin ( ) const

nodiscard

Definition at line 58 of file Signal.cpp.

{
    return samples.begin();
}

cbegin()

decltype(Signal::samples) const_iterator echomap::Signal::cbegin ( ) const

nodiscardnoexcept

Definition at line 68 of file Signal.cpp.

{
    return samples.cbegin();
}

cend()

decltype(Signal::samples) const_iterator echomap::Signal::cend ( ) const

nodiscardnoexcept

Definition at line 73 of file Signal.cpp.

{
    return samples.cend();
}

emplace_sample() [1/3]

void echomap::Signal::emplace_sample ( const Sample & sample )

private

Emplace a sample to the back of the channel sample data.

Parameters

sample

The Sample to insert at the back of the stream.

Exceptions

std::runtime_error

The time of the Sample violated the monotonically increasing invariant.

Precondition

The given amplitude is within the fixed normalised range.

Definition at line 157 of file Signal.cpp.

{
    emplace_sample(sample.time, sample.amplitude);
}

emplace_sample() [2/3]

void echomap::Signal::emplace_sample ( Sample::AmplitudeT amplitude )

private

Emplace a sample to the back of the channel sample data.

The inserted amplitude sample will be associated with the next timestep, computed automatically based on the defined sample rate and time offset.

Parameters

amplitude

Amplitude of the sample to insert.

Precondition

The given amplitude is within the fixed normalised range.

Definition at line 131 of file Signal.cpp.

{
    assert(amplitude >= normalised_range.first && amplitude <= normalised_range.second);
    samples.emplace_back(amplitude);
    if (time_offsets.has_value())
        time_offsets->emplace_back(0);
 
    if (fs_source.has_value())
        fs_source->dirty = true;
}

emplace_sample() [3/3]

void echomap::Signal::emplace_sample ( Sample::TimeT time, Sample::AmplitudeT amplitude )

private

Emplace a sample to the back of the channel sample data.

Parameters

time	The time to associate with the amplitude, in seconds.
amplitude	The amplitude to associate with the time.

Exceptions

std::runtime_error

The time of the Sample violated the monotonically increasing invariant.

Precondition

The given amplitude is within the fixed normalised range.

Definition at line 144 of file Signal.cpp.

{
    assert(amplitude >= normalised_range.first && amplitude <= normalised_range.second);
    samples.emplace_back(amplitude);
    emplace_time(time);
 
    if (fs_source.has_value())
        fs_source->dirty = true;
}

emplace_sample_from_source() [1/3]

void echomap::Signal::emplace_sample_from_source ( const Sample & sample )

private

Emplace an externally sourced sample to the back of the channel sample data.

Parameters

sample

The Sample to insert at the back of the stream.

Exceptions

std::runtime_error

The time of the Sample violated the monotonically increasing invariant.

Precondition

The given amplitude is within the fixed normalised range.

Definition at line 184 of file Signal.cpp.

{
    return emplace_sample_from_source(sample.time, sample.amplitude);
}

emplace_sample_from_source() [2/3]

void echomap::Signal::emplace_sample_from_source ( Sample::AmplitudeT amplitude )

private

Emplace an externally sourced sample to the back of the channel sample data.

The inserted amplitude sample will be associated with the next timestep, computed automatically based on the defined sample rate and time offset.

Parameters

amplitude

Amplitude of the sample to insert.

Precondition

The given amplitude is within the fixed normalised range.

Definition at line 164 of file Signal.cpp.

{
    assert(amplitude >= normalised_range.first && amplitude <= normalised_range.second);
    samples.emplace_back(amplitude);
    if (time_offsets.has_value())
        time_offsets->emplace_back(0);
}

emplace_sample_from_source() [3/3]

void echomap::Signal::emplace_sample_from_source ( Sample::TimeT time, Sample::AmplitudeT amplitude )

private

Emplace an externally sourced sample to the back of the channel sample data.

Parameters

time	The time to associate with the amplitude, in seconds.
amplitude	The amplitude to associate with the time.

Exceptions

std::runtime_error

The time of the Sample violated the monotonically increasing invariant.

Precondition

The given amplitude is within the fixed normalised range.

Definition at line 174 of file Signal.cpp.

{
    assert(amplitude >= normalised_range.first && amplitude <= normalised_range.second);
    samples.emplace_back(amplitude);
    emplace_time(time);
}

emplace_time()

void echomap::Signal::emplace_time ( Sample::TimeT given_time )

private

Implementation helper to associate the latest amplitude sample with the given time.

Parameters

given_time

The time to associate with the latest sample.

Exceptions

std::runtime_error

The time of the Sample violated the monotonically increasing invariant.

Definition at line 224 of file Signal.cpp.

{
    assert(!samples.empty());
 
    constexpr Sample::TimeT epsilon = 1.0e-6f;
    const auto expected =
        timing_baseline.time_offset + static_cast<float>(samples.size() - 1) * timing_baseline.sample_rate_r;
 
    // Check the time derived from the baseline, as if we're continuing with a uniformly sampled signal.
    if (const auto offset = given_time - expected; std::abs(offset) <= epsilon) {
        /*
         * If the given time matches what we expect, we don't need to do anything. Only update the explicit offsets
         * (with an offset of zero) if they're already there.
         */
        if (time_offsets.has_value())
            time_offsets->emplace_back(0.0f);
    } else {
        /*
         * If the given time doesn't match what we expect, then a variably sampled entry has been introduced. We need to
         * consider:
         *
         *  1. if insertion of the time would violate the class invariant, such that time values are monotonically
         *     increasing, then an exception is due; or
         *
         *  2. if the time preserves the invariant, but is the first non-uniform entry, then we need to create offset
         *     entries (which will have offset of zero, since they followed the uniform pattern by construction), and
         *     emplace our offset on the end.
         *
         *  3. if the time preserves the invariant, and is being emplaced into an already-variable signal, then we
         *     simply note the offset.
         */
 
        if (samples.size() >= 2)
            if (const auto previous_time = get_time_at_index(samples.size() - 2); given_time <= previous_time + epsilon)
                // Case 1.
                throw std::runtime_error(
                    std::format(
                        "Signal {} rejected out-of-order sample at time {}s (previous sample was accepted at "
                        "time {}s).",
                        get_name(),
                        given_time,
                        previous_time
                    )
                );
 
        if (time_offsets.has_value())
        // Case 3.
            time_offsets->emplace_back(offset);
        else {
            // Case 2.
            time_offsets.emplace(samples.size(), 0.0f);
            time_offsets->back() = offset;
        }
    }
}

end()

decltype(Signal::samples) const_iterator echomap::Signal::end ( ) const

nodiscard

Definition at line 63 of file Signal.cpp.

{
    return samples.end();
}

get_sample_count()

std::uint64_t echomap::Signal::get_sample_count ( ) const

nodiscardnoexcept

Retrieves the total number of samples in the Signal stream.

Returns

The number of samples detained by the Signal.

Definition at line 38 of file Signal.cpp.

{
    return samples.size();
}

get_sample_rate()

std::size_t echomap::Signal::get_sample_rate ( ) const

nodiscardnoexcept

Definition at line 53 of file Signal.cpp.

{
    return timing_baseline.sample_rate;
}

get_time_at_index()

Signal::Sample::TimeT echomap::Signal::get_time_at_index ( std::size_t index ) const

nodiscardnoexcept

Determines the corresponding time of the amplitude appearing at the given index in the sample array.

Parameters

index

The index of the amplitude in the sample array.

Returns

The timestamp corresponding to the referenced sample.

Precondition

The index is within the bounds of the sample array.

Definition at line 95 of file Signal.cpp.

{
    assert(index < samples.size());
    const Sample::TimeT baseline_time =
        timing_baseline.time_offset + static_cast<Sample::TimeT>(index) * timing_baseline.sample_rate_r;
    return time_offsets.has_value() ? baseline_time + (*time_offsets)[index] : baseline_time;
}

get_time_offset()

Signal::Sample::TimeT echomap::Signal::get_time_offset ( ) const

nodiscardnoexcept

Definition at line 48 of file Signal.cpp.

{
    return timing_baseline.time_offset;
}

is_uniformly_sampled()

bool echomap::Signal::is_uniformly_sampled ( ) const

nodiscardnoexcept

Definition at line 90 of file Signal.cpp.

{
    return !time_offsets.has_value();
}

observe_source()

const std::optional< Signal::Source > & echomap::Signal::observe_source ( ) const

nodiscardnoexcept

Retrieves the optional Source of the Signal.

The return value of this operation can be used to determine the origin of the Signal: if the optional is empty, the signal should be considered "embedded". Otherwise, it has an origin on the filesystem at the given SignalSource.

If the Signal has an external source, the stored samples in the Signal object do not necessarily match the external file, as callers may have invoked emplace_sample with arbitrary samples. The Source should only be considered a hint. This can be checked by inspecting the Source::dirty flag.

Returns

The Source of the Signal, or an empty optional if the Signal is not externally sourced.

Definition at line 43 of file Signal.cpp.

{
    return fs_source;
}

operator[]()

Signal::Sample::AmplitudeT echomap::Signal::operator[] ( std::size_t index ) const

nodiscardnoexcept

Definition at line 78 of file Signal.cpp.

{
    return samples[index];
}

reserve_samples()

void echomap::Signal::reserve_samples ( std::size_t count )

private

Reserves memory to store the given number of total samples in the channel.

Parameters

count

The number of Sample objects to pre-allocate.

Definition at line 191 of file Signal.cpp.

{
    samples.reserve(count);
 
    if (time_offsets.has_value())
        time_offsets->reserve(count);
}

set_sample_rate()

void echomap::Signal::set_sample_rate ( std::size_t new_sample_rate )

privatenoexcept

Definition at line 216 of file Signal.cpp.

{
    timing_baseline.sample_rate = new_sample_rate;
    timing_baseline.sample_rate_r = new_sample_rate == 0 ? 0 : 1.0f / static_cast<float>(new_sample_rate);
}

set_source()

void echomap::Signal::set_source ( const std::filesystem::path & path, std::size_t channel )

private

Definition at line 201 of file Signal.cpp.

{
    fs_source = Source(path, channel);
}

set_time_offset()

void echomap::Signal::set_time_offset ( Sample::TimeT new_time_offset )

privatenoexcept

Definition at line 209 of file Signal.cpp.

{
    timing_baseline.time_offset = new_time_offset;
}

timed_samples()

auto echomap::Signal::timed_samples ( ) const

inlinenodiscard

Definition at line 109 of file Signal.hpp.

    {
        return std::views::iota(std::size_t{0}, samples.size()) |
               std::views::transform([this](const std::size_t index) -> Sample {
                   return {.time = get_time_at_index(index), .amplitude = samples[index]};
               });
    }

Friends And Related Symbol Documentation

SignalFactory

friend class SignalFactory

friend

Definition at line 147 of file Signal.hpp.

Member Data Documentation

fs_source

std::optional<Source> echomap::Signal::fs_source

private

External source, if any, of the Signal Sample stream.

Definition at line 257 of file Signal.hpp.

normalised_range

std::pair<Sample::AmplitudeT, Sample::AmplitudeT> echomap::Signal::normalised_range = {-1.0f, 1.0f}

staticconstexpr

The range within which the amplitude values are normalised.

Definition at line 74 of file Signal.hpp.

{-1.0f, 1.0f};

samples

std::vector<Sample::AmplitudeT> echomap::Signal::samples

private

Amplitude sample stream.

Definition at line 55 of file Signal.hpp.

time_offsets

std::optional<std::vector<Sample::TimeT> > echomap::Signal::time_offsets

private

An optional vector of explicit timestamps for each sample.

If provided, the timestamps provide a sample-by-sample indication of the time corresponding with amplitudes in the sample time series data. The scalars are specified as offsets relative to the baseline time, which is computed as \( b_i = t_0 + i \delta t \), where \( t_0 \) is the global time offset, \( \delta t \) is the reciprocal of the sample rate, and \( i \) is the integer zero-based index such that \( 0 < i \leq \vert S \vert \), where \( \vert S \vert \) denotes the size of the sample set \( S \).

This is useful to support variably sampled time series, such as in the result of LTTB downsampling. Whether explicit timestamps are provided is rather opaque to the user: they can request timing information, which may be inferred from the baseline or indexed from this array as appropriate.

When a new sample is emplaced, a time can be provided. If the given time is different than what would be expected from the baseline, this vector is updated with the suitable offset. If it doesn't exist, it is created.

Invariant

Timestamp elements are in bijective correspondence with the amplitude samples.

Definition at line 281 of file Signal.hpp.

timing_baseline

Baseline echomap::Signal::timing_baseline

private

A baseline of timing parameters.

Definition at line 256 of file Signal.hpp.

---

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

• src/objects/Signal.hpp
• src/objects/Signal.cpp