Trait sample::signal::Signal[−][src]

pub trait Signal {
    type Frame: Frame;
    fn next(&mut self) -> Self::Frame;

    fn is_exhausted(&self) -> bool { ... }

    fn map<M, F>(self, map: M) -> Map<Self, M, F>
    where
        Self: Sized,
        M: FnMut(Self::Frame) -> F,
        F: Frame,
    { ... }

    fn zip_map<O, M, F>(self, other: O, map: M) -> ZipMap<Self, O, M, F>
    where
        Self: Sized,
        M: FnMut(Self::Frame, O::Frame) -> F,
        O: Signal,
        F: Frame,
    { ... }

    fn add_amp<S>(self, other: S) -> AddAmp<Self, S>
    where
        Self: Sized,
        S: Signal,
        S::Frame: Frame<Sample = <<Self::Frame as Frame>::Sample as Sample>::Signed, NumChannels = <Self::Frame as Frame>::NumChannels>,
    { ... }

    fn mul_amp<S>(self, other: S) -> MulAmp<Self, S>
    where
        Self: Sized,
        S: Signal,
        S::Frame: Frame<Sample = <<Self::Frame as Frame>::Sample as Sample>::Float, NumChannels = <Self::Frame as Frame>::NumChannels>,
    { ... }

    fn offset_amp(
        self, 
        offset: <<Self::Frame as Frame>::Sample as Sample>::Signed
    ) -> OffsetAmp<Self>
    where
        Self: Sized,
    { ... }

    fn scale_amp(
        self, 
        amp: <<Self::Frame as Frame>::Sample as Sample>::Float
    ) -> ScaleAmp<Self>
    where
        Self: Sized,
    { ... }

    fn offset_amp_per_channel<F>(
        self, 
        amp_frame: F
    ) -> OffsetAmpPerChannel<Self, F>
    where
        Self: Sized,
        F: Frame<Sample = <<Self::Frame as Frame>::Sample as Sample>::Signed, NumChannels = <Self::Frame as Frame>::NumChannels>,
    { ... }

    fn scale_amp_per_channel<F>(
        self, 
        amp_frame: F
    ) -> ScaleAmpPerChannel<Self, F>
    where
        Self: Sized,
        F: Frame<Sample = <<Self::Frame as Frame>::Sample as Sample>::Float, NumChannels = <Self::Frame as Frame>::NumChannels>,
    { ... }

    fn mul_hz<M, I>(
        self, 
        interpolator: I, 
        mul_per_frame: M
    ) -> MulHz<Self, M, I>
    where
        Self: Sized,
        M: Signal<Frame = [f64; 1]>,
        I: Interpolator,
    { ... }

    fn from_hz_to_hz<I>(
        self, 
        interpolator: I, 
        source_hz: f64, 
        target_hz: f64
    ) -> Converter<Self, I>
    where
        Self: Sized,
        I: Interpolator,
    { ... }

    fn scale_hz<I>(self, interpolator: I, multi: f64) -> Converter<Self, I>
    where
        Self: Sized,
        I: Interpolator,
    { ... }

    fn delay(self, n_frames: usize) -> Delay<Self>
    where
        Self: Sized,
    { ... }

    fn into_interleaved_samples(self) -> IntoInterleavedSamples<Self>
    where
        Self: Sized,
    { ... }

    fn clip_amp(
        self, 
        thresh: <<Self::Frame as Frame>::Sample as Sample>::Signed
    ) -> ClipAmp<Self>
    where
        Self: Sized,
    { ... }

    fn inspect<F>(self, inspect: F) -> Inspect<Self, F>
    where
        Self: Sized,
        F: FnMut(&Self::Frame),
    { ... }

    fn fork<S>(self, ring_buffer: Bounded<S>) -> Fork<Self, S>
    where
        Self: Sized,
        S: SliceMut<Element = Self::Frame>,
    { ... }

    fn bus(self) -> Bus<Self>
    where
        Self: Sized,
    { ... }

    fn take(self, n: usize) -> Take<Self>
    where
        Self: Sized,
    { ... }

    fn until_exhausted(self) -> UntilExhausted<Self>
    where
        Self: Sized,
    { ... }

    fn buffered<S>(self, ring_buffer: Bounded<S>) -> Buffered<Self, S>
    where
        Self: Sized,
        S: Slice<Element = Self::Frame> + SliceMut,
    { ... }

    fn rms<S>(self, ring_buffer: Fixed<S>) -> Rms<Self, S>
    where
        Self: Sized,
        S: Slice<Element = <Self::Frame as Frame>::Float> + SliceMut,
    { ... }

    fn detect_envelope<D>(
        self, 
        detector: Detector<Self::Frame, D>
    ) -> DetectEnvelope<Self, D>
    where
        Self: Sized,
        D: Detect<Self::Frame>,
    { ... }

    fn by_ref(&mut self) -> &mut Self
    where
        Self: Sized,
    { ... }
}

Types that yield Frames as a multi-channel PCM signal.

For example, Signal allows us to add two signals, modulate a signal's amplitude by another signal, scale a signals amplitude and much more.

Associated Types

The Frame type returned by the Signal.

Required Methods

Yield the next Frame in the Signal.

Example

extern crate sample;

use sample::{signal, Signal};

fn main() {
    let frames = [[0.2], [-0.6], [0.4]];
    let mut signal = signal::from_iter(frames.iter().cloned());
    assert_eq!(signal.next(), [0.2]);
    assert_eq!(signal.next(), [-0.6]);
    assert_eq!(signal.next(), [0.4]);
}

Provided Methods

Whether or not the signal is exhausted of meaningful frames.

By default, this returns false and assumes that the Signal is infinite.

As an example, signal::FromIterator becomes exhausted once the inner Iterator has been exhausted. Sine on the other hand will always return false as it will produce meaningful values infinitely.

It should be rare for users to need to call this method directly, unless they are implementing their own custom Signals. Instead, idiomatic code will tend toward the Signal::until_exhasted method which produces an Iterator that yields Frames until Signal::is_exhausted returns true.

Adaptors that source frames from more than one signal (AddAmp, MulHz, etc) will return true if any of the source signals return true. In this sense exhaustiveness is contagious. This can be likened to the way that Iterator::zip begins returning None when either A or B begins returning None.

extern crate sample;

use sample::{signal, Signal};

fn main() {
    // Infinite signals always return `false`.
    let sine_signal = signal::rate(44_100.0).const_hz(400.0).sine();
    assert_eq!(sine_signal.is_exhausted(), false);

    // Signals over iterators return `true` when the inner iterator is exhausted.
    let frames = [[0.2], [-0.6], [0.4]];
    let mut iter_signal = signal::from_iter(frames.iter().cloned());
    assert_eq!(iter_signal.is_exhausted(), false);
    iter_signal.by_ref().take(3).count();
    assert_eq!(iter_signal.is_exhausted(), true);

    // Adaptors return `true` when the first signal becomes exhausted.
    let a = [[1], [2]];
    let b = [[1], [2], [3], [4]];
    let a_signal = signal::from_iter(a.iter().cloned());
    let b_signal = signal::from_iter(b.iter().cloned());
    let mut added = a_signal.add_amp(b_signal);
    assert_eq!(added.is_exhausted(), false);
    added.by_ref().take(2).count();
    assert_eq!(added.is_exhausted(), true);
}

A signal that maps one set of frames to another.

Example

extern crate sample;

use sample::{signal, Signal};

fn main() {
    let frames = signal::gen(|| [0.5]);
    let mut mapper = frames.map(|f| [f[0], 0.25]);
    assert_eq!(mapper.next(), [0.5, 0.25]);
    assert_eq!(mapper.next(), [0.5, 0.25]);
    assert_eq!(mapper.next(), [0.5, 0.25]);
}

This can also be useful for monitoring the peak values of a signal.

extern crate sample;

use sample::{peak, signal, Frame, Signal};

fn main() {
    let sine_wave = signal::rate(4.0).const_hz(1.0).sine();
    let mut peak = sine_wave
        .map(peak::full_wave)
        .map(|f| [f[0].round()]);
    assert_eq!(
        peak.take(4).collect::<Vec<_>>(),
        vec![[0.0], [1.0], [0.0], [1.0]]
    );
}

A signal that maps one set of frames to another.

Example

extern crate sample;

use sample::{signal, Signal};

fn main() {
    let frames = signal::gen(|| [0.5]);
    let more_frames = signal::gen(|| [0.25]);
    let mut mapper = frames.zip_map(more_frames, |f, o| [f[0], o[0]]);
    assert_eq!(mapper.next(), [0.5, 0.25]);
    assert_eq!(mapper.next(), [0.5, 0.25]);
    assert_eq!(mapper.next(), [0.5, 0.25]);
}

Provides an iterator that yields the sum of the frames yielded by both other and self in lock-step.

Example

extern crate sample;

use sample::{signal, Signal};

fn main() {
    let a = [[0.2], [-0.6], [0.4]];
    let b = [[0.2], [0.1], [-0.8]];
    let a_signal = signal::from_iter(a.iter().cloned());
    let b_signal = signal::from_iter(b.iter().cloned());
    let added: Vec<_> = a_signal.add_amp(b_signal).take(3).collect();
    assert_eq!(added, vec![[0.4], [-0.5], [-0.4]]);
}

Provides an iterator that yields the product of the frames yielded by both other and self in lock-step.

Example

extern crate sample;

use sample::{signal, Signal};

fn main() {
    let a = [[0.25], [-0.8], [-0.5]];
    let b = [[0.2], [0.5], [0.8]];
    let a_signal = signal::from_iter(a.iter().cloned());
    let b_signal = signal::from_iter(b.iter().cloned());
    let added: Vec<_> = a_signal.mul_amp(b_signal).take(3).collect();
    assert_eq!(added, vec![[0.05], [-0.4], [-0.4]]);
}

Provides an iterator that offsets the amplitude of every channel in each frame of the signal by some sample value and yields the resulting frames.

Example

extern crate sample;

use sample::{signal, Signal};

fn main() {
    let frames = [[0.25, 0.4], [-0.2, -0.5]];
    let signal = signal::from_iter(frames.iter().cloned());
    let offset: Vec<_> = signal.offset_amp(0.5).take(2).collect();
    assert_eq!(offset, vec![[0.75, 0.9], [0.3, 0.0]]);
}

Produces an Iterator that scales the amplitude of the sample of each channel in every Frame yielded by self by the given amplitude.

Example

extern crate sample;

use sample::{signal, Signal};

fn main() {
    let frames = [[0.2], [-0.5], [-0.4], [0.3]];
    let signal = signal::from_iter(frames.iter().cloned());
    let scaled: Vec<_> = signal.scale_amp(2.0).take(4).collect();
    assert_eq!(scaled, vec![[0.4], [-1.0], [-0.8], [0.6]]);
}

Produces a new Signal that offsets the amplitude of every Frame in self by the respective amplitudes in each channel of the given amp_frame.

Example

extern crate sample;

use sample::{signal, Signal};

fn main() {
    let frames = [[0.5, 0.3], [-0.25, 0.9]];
    let signal = signal::from_iter(frames.iter().cloned());
    let offset: Vec<_> = signal.offset_amp_per_channel([0.25, -0.5]).take(2).collect();
    assert_eq!(offset, vec![[0.75, -0.2], [0.0, 0.4]]);
}

Produces a new Signal that scales the amplitude of every Frame in self by the respective amplitudes in each channel of the given amp_frame.

Example

extern crate sample;

use sample::{signal, Signal};

fn main() {
    let frames = [[0.2, -0.5], [-0.4, 0.3]];
    let signal = signal::from_iter(frames.iter().cloned());
    let scaled: Vec<_> = signal.scale_amp_per_channel([0.5, 2.0]).take(2).collect();
    assert_eq!(scaled, vec![[0.1, -1.0], [-0.2, 0.6]]);
}

Multiplies the rate at which frames of self are yielded by the given signal.

This happens by wrapping self in a rate::Converter and calling set_playback_hz_scale with each value yielded by signal

Example

extern crate sample;

use sample::{signal, Signal};
use sample::interpolate::Linear;

fn main() {
    let foo = [[0.0], [1.0], [0.0], [-1.0]];
    let mul = [[1.0], [1.0], [0.5], [0.5], [0.5], [0.5]];
    let mut source = signal::from_iter(foo.iter().cloned());
    let interp = Linear::from_source(&mut source);
    let hz_signal = signal::from_iter(mul.iter().cloned());
    let frames: Vec<_> = source.mul_hz(interp, hz_signal).take(6).collect();
    assert_eq!(&frames[..], &[[0.0], [1.0], [0.0], [-0.5], [-1.0], [-0.5]][..]);
}

Converts the rate at which frames of the Signal are yielded using interpolation.

Example

extern crate sample;

use sample::{signal, Signal};
use sample::interpolate::Linear;

fn main() {
    let foo = [[0.0], [1.0], [0.0], [-1.0]];
    let mut source = signal::from_iter(foo.iter().cloned());
    let interp = Linear::from_source(&mut source);
    let frames: Vec<_> = source.from_hz_to_hz(interp, 1.0, 2.0).take(8).collect();
    assert_eq!(&frames[..], &[[0.0], [0.5], [1.0], [0.5], [0.0], [-0.5], [-1.0], [-0.5]][..]);
}

Multiplies the rate at which frames of the Signal are yielded by the given value.

Example

extern crate sample;

use sample::{signal, Signal};
use sample::interpolate::Linear;

fn main() {
    let foo = [[0.0], [1.0], [0.0], [-1.0]];
    let mut source = signal::from_iter(foo.iter().cloned());
    let interp = Linear::from_source(&mut source);
    let frames: Vec<_> = source.scale_hz(interp, 0.5).take(8).collect();
    assert_eq!(&frames[..], &[[0.0], [0.5], [1.0], [0.5], [0.0], [-0.5], [-1.0], [-0.5]][..]);
}

Delays the Signal by the given number of frames.

The delay is performed by yielding Frame::equilibrium() n_frames times before continuing to yield frames from signal.

Example

extern crate sample;

use sample::{signal, Signal};

fn main() {
    let frames = [[0.2], [0.4]];
    let signal = signal::from_iter(frames.iter().cloned());
    let delayed: Vec<_> = signal.delay(2).take(4).collect();
    assert_eq!(delayed, vec![[0.0], [0.0], [0.2], [0.4]]);
}

Converts a Signal into a type that yields the interleaved Samples.

Example

extern crate sample;

use sample::{signal, Signal};

fn main() {
    let frames = [[0.1, 0.2], [0.3, 0.4]];
    let signal = signal::from_iter(frames.iter().cloned());
    let samples = signal.into_interleaved_samples();
    let samples: Vec<_> = samples.into_iter().take(4).collect();
    assert_eq!(samples, vec![0.1, 0.2, 0.3, 0.4]);
}

Clips the amplitude of each channel in each Frame yielded by self to the given threshold amplitude.

Example

extern crate sample;

use sample::{signal, Signal};

fn main() {
    let frames = [[1.2, 0.8], [-0.7, -1.4]];
    let signal = signal::from_iter(frames.iter().cloned());
    let clipped: Vec<_> = signal.clip_amp(0.9).take(2).collect();
    assert_eq!(clipped, vec![[0.9, 0.8], [-0.7, -0.9]]);
}

Create a new Signal that calls the enclosing function on each iteration.

Example

extern crate sample;

use sample::{signal, Signal};

fn main() {
    let mut f = [0.0];
    let mut signal = signal::gen_mut(move || {
        f[0] += 0.1;
        f
    });
    let func = |x: &[f64; 1]| {
        assert_eq!(*x, [0.1]);
    };
    let mut inspected = signal.inspect(func);
    let out = inspected.next();
    assert_eq!(out, [0.1]);
}

Forks Self into two signals that produce the same frames.

The given ring_buffer must be empty to ensure correct behaviour.

Each time a frame is requested from the signal on one branch, that frame will be pushed to the given ring_buffer of pending frames to be collected by the other branch and a flag will be set to indicate that there are pending frames.

Fork can be used to share the queue between the two branches by reference fork.by_ref() or via a reference counted pointer fork.by_rc().

Fork is a slightly more efficient alternative to Bus when only two branches are required.

Note: It is up to the user to ensure that there are never more than ring_buffer.max_len() pending frames - otherwise the oldest frames will be overridden and glitching may occur on the lagging branch.

**Panic!**s if the given ring_buffer is not empty in order to guarantee correct behaviour.

extern crate sample;

use sample::{ring_buffer, signal, Signal};

fn main() {
    let signal = signal::rate(44_100.0).const_hz(440.0).sine();
    let ring_buffer = ring_buffer::Bounded::<[[f64; 1]; 64]>::array();
    let mut fork = signal.fork(ring_buffer);

    // Forks can be split into their branches via reference.
    {
        let (mut a, mut b) = fork.by_ref();
        assert_eq!(a.next(), b.next());
        assert_eq!(a.by_ref().take(64).collect::<Vec<_>>(),
                   b.by_ref().take(64).collect::<Vec<_>>());
    }

    // Forks can also be split via reference counted pointer.
    let (mut a, mut b) = fork.by_rc();
    assert_eq!(a.next(), b.next());
    assert_eq!(a.by_ref().take(64).collect::<Vec<_>>(),
               b.by_ref().take(64).collect::<Vec<_>>());

    // The lagging branch will be missing frames if we exceed `ring_buffer.max_len()`
    // pending frames.
    assert!(a.by_ref().take(67).collect::<Vec<_>>() !=
            b.by_ref().take(67).collect::<Vec<_>>())
}

Moves the Signal into a Bus from which its output may be divided into multiple other Signals in the form of Outputs.

This method allows to create more complex directed acyclic graph structures that incorporate concepts like sends, side-chaining, etc, rather than being restricted to tree structures where signals can only ever be joined but never divided.

Note: When using multiple Outputs in this fashion, you will need to be sure to pull the frames from each Output in sync (whether per frame or per buffer). This is because when output A requests Frames before output B, those frames must remain available for output B and in turn must be stored in an intermediary ring buffer.

Example

extern crate sample;

use sample::{signal, Signal};

fn main() {
    let frames = [[0.1], [0.2], [0.3], [0.4], [0.5], [0.6]];
    let signal = signal::from_iter(frames.iter().cloned());
    let bus = signal.bus();
    let mut a = bus.send();
    let mut b = bus.send();
    assert_eq!(a.by_ref().take(3).collect::<Vec<_>>(), vec![[0.1], [0.2], [0.3]]);
    assert_eq!(b.by_ref().take(3).collect::<Vec<_>>(), vec![[0.1], [0.2], [0.3]]);

    let c = bus.send();
    assert_eq!(c.take(3).collect::<Vec<_>>(), vec![[0.4], [0.5], [0.6]]);
    assert_eq!(b.take(3).collect::<Vec<_>>(), vec![[0.4], [0.5], [0.6]]);
    assert_eq!(a.take(3).collect::<Vec<_>>(), vec![[0.4], [0.5], [0.6]]);
}
ⓘImportant traits for Take<S>

Converts the Signal into an Iterator that will yield the given number for Frames before returning None.

Example

extern crate sample;

use sample::{signal, Signal};

fn main() {
    let frames = [[0.1], [0.2], [0.3], [0.4]];
    let mut signal = signal::from_iter(frames.iter().cloned()).take(2);
    assert_eq!(signal.next(), Some([0.1]));
    assert_eq!(signal.next(), Some([0.2]));
    assert_eq!(signal.next(), None);
}
ⓘImportant traits for UntilExhausted<S>

Converts the Signal into an Iterator yielding frames until the signal.is_exhausted() returns true.

Example

extern crate sample;

use sample::{signal, Signal};

fn main() {
    let frames = [[1], [2]];
    let signal = signal::from_iter(frames.iter().cloned());
    assert_eq!(signal.until_exhausted().count(), 2);
}

Buffers the signal using the given ring buffer.

When next is called on the returned signal, it will first check if the ring buffer is empty. If so, it will completely fill the ring buffer with the inner signal before yielding the next value. If the ring buffer still contains un-yielded values, the next frame will be popped from the front of the ring buffer and immediately returned.

extern crate sample;

use sample::ring_buffer;
use sample::{signal, Signal};

fn main() {
    let frames = [[0.1], [0.2], [0.3], [0.4]];
    let signal = signal::from_iter(frames.iter().cloned());
    let ring_buffer = ring_buffer::Bounded::<[[f32; 1]; 2]>::array();
    let mut buffered_signal = signal.buffered(ring_buffer);
    assert_eq!(buffered_signal.next(), [0.1]);
    assert_eq!(buffered_signal.next(), [0.2]);
    assert_eq!(buffered_signal.next(), [0.3]);
    assert_eq!(buffered_signal.next(), [0.4]);
    assert_eq!(buffered_signal.next(), [0.0]);
}

If the given ring buffer already contains frames, those will be yielded first.

extern crate sample;
use sample::ring_buffer;
use sample::{signal, Signal};

fn main() {
    let frames = [[0.1], [0.2], [0.3], [0.4]];
    let signal = signal::from_iter(frames.iter().cloned());
    let ring_buffer = ring_buffer::Bounded::from_full([[0.8], [0.9]]);
    let mut buffered_signal = signal.buffered(ring_buffer);
    assert_eq!(buffered_signal.next(), [0.8]);
    assert_eq!(buffered_signal.next(), [0.9]);
    assert_eq!(buffered_signal.next(), [0.1]);
    assert_eq!(buffered_signal.next(), [0.2]);
    assert_eq!(buffered_signal.next(), [0.3]);
    assert_eq!(buffered_signal.next(), [0.4]);
    assert_eq!(buffered_signal.next(), [0.0]);
}

An adaptor that yields the RMS of the signal.

The window size of the RMS detector is equal to the given ring buffer length.

Example

extern crate sample;

use sample::ring_buffer;
use sample::{signal, Signal};

fn main() {
    let frames = [[0.9], [-0.8], [0.6], [-0.9]];
    let signal = signal::from_iter(frames.iter().cloned());
    let ring_buffer = ring_buffer::Fixed::from([[0.0]; 2]);
    let mut rms_signal = signal.rms(ring_buffer);
    assert_eq!(
        [rms_signal.next(), rms_signal.next(), rms_signal.next()],
        [[0.6363961030678927], [0.8514693182963201], [0.7071067811865476]]
    );
}

An adaptor that detects and yields the envelope of the signal.

Example

extern crate sample;

use sample::{envelope, signal, Signal};

fn main() {
    let signal = signal::rate(4.0).const_hz(1.0).sine();
    let attack = 1.0;
    let release = 1.0;
    let detector = envelope::Detector::peak(attack, release);
    let mut envelope = signal.detect_envelope(detector);
    assert_eq!(
        envelope.take(4).collect::<Vec<_>>(),
        vec![[0.0], [0.6321205496788025], [0.23254416035257117], [0.7176687675647109]]
    );
}

Borrows a Signal rather than consuming it.

This is useful to allow applying signal adaptors while still retaining ownership of the original signal.

Example

extern crate sample;

use sample::{signal, Signal};

fn main() {
    let frames = [[0], [1], [2], [3], [4]];
    let mut signal = signal::from_iter(frames.iter().cloned());
    assert_eq!(signal.next(), [0]);
    assert_eq!(signal.by_ref().take(2).collect::<Vec<_>>(), vec![[1], [2]]);
    assert_eq!(signal.next(), [3]);
    assert_eq!(signal.next(), [4]);
}

Implementations on Foreign Types

impl<'a, S: ?Sized> Signal for &'a mut S where
    S: Signal, 
[src]

ⓘImportant traits for Take<S>

ⓘImportant traits for UntilExhausted<S>

Implementors