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

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

    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 bus(self) -> Bus<Self>
    where
        Self: Sized,
    { ... }

    fn take(self, n: usize) -> Take<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

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]);
}

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]]);
}

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);
}

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]

[src]

[src]

[src]

[src]

[src]

[src]

[src]

[src]

[src]

[src]

[src]

[src]

[src]

[src]

[src]

[src]

[src]

[src]

[src]

[src]

[src]

[src]

Implementors