Trait dsp::Signal [−] [src]

pub trait Signal: Iterator where Self::Item: Frame {
    fn add_amp<S>(self, other: S) -> AddAmp<Self, S> where S: Signal, S::Item: Frame, S::Item::Sample == Self::Item::Sample::Signed, S::Item::NumChannels == Self::Item::NumChannels { ... }
    fn mul_amp<S>(self, other: S) -> MulAmp<Self, S> where S: Signal, S::Item: Frame, S::Item::Sample == Self::Item::Sample::Float, S::Item::NumChannels == Self::Item::NumChannels { ... }
    fn offset_amp(self, offset: Self::Item::Sample::Signed) -> OffsetAmp<Self> { ... }
    fn scale_amp(self, amp: Self::Item::Sample::Float) -> ScaleAmp<Self> { ... }
    fn offset_amp_per_channel<F>(self, amp_frame: F) -> OffsetAmpPerChannel<Self, F> where F: Frame<Sample=Self::Item::Sample::Signed, NumChannels=Self::Item::NumChannels> { ... }
    fn scale_amp_per_channel<F>(self, amp_frame: F) -> ScaleAmpPerChannel<Self, F> where F: Frame<Sample=Self::Item::Sample::Float, NumChannels=Self::Item::NumChannels> { ... }
    fn mul_hz<I>(self, mul_per_frame: I) -> MulHz<Self, I> where I: Iterator<Item=f64> { ... }
    fn from_hz_to_hz(self, source_hz: f64, target_hz: f64) -> Converter<Self> { ... }
    fn scale_hz(self, multi: f64) -> Converter<Self> { ... }
    fn delay(self, n_frames: usize) -> Delay<Self> { ... }
    fn to_samples(self) -> ToSamples<Self> { ... }
    fn clip_amp(self, thresh: Self::Item::Sample::Signed) -> ClipAmp<Self> { ... }
    fn bus(self) -> Bus<Self> { ... }
}

A trait that allows us to treat Iterators 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.

Signal has a blanket implementation for all Iterators whose Item associated types implement Frame.

Provided Methods

`fn add_amp<S>(self, other: S) -> AddAmp<Self, S> where S: Signal, S::Item: Frame, S::Item::Sample == Self::Item::Sample::Signed, S::Item::NumChannels == Self::Item::NumChannels`

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;

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

`fn mul_amp<S>(self, other: S) -> MulAmp<Self, S> where S: Signal, S::Item: Frame, S::Item::Sample == Self::Item::Sample::Float, S::Item::NumChannels == Self::Item::NumChannels`

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;

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

`fn offset_amp(self, offset: Self::Item::Sample::Signed) -> OffsetAmp<Self>`

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;

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

`fn scale_amp(self, amp: Self::Item::Sample::Float) -> ScaleAmp<Self>`

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;

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

`fn offset_amp_per_channel<F>(self, amp_frame: F) -> OffsetAmpPerChannel<Self, F> where F: Frame<Sample=Self::Item::Sample::Signed, NumChannels=Self::Item::NumChannels>`

Produces an Iterator 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;

fn main() {
    let frames = [[0.5, 0.3], [-0.25, 0.9]];
    let mut signal = frames.iter().cloned().offset_amp_per_channel([0.25, -0.5]);
    assert_eq!(signal.next().unwrap(), [0.75, -0.2]);
    assert_eq!(signal.next().unwrap(), [0.0, 0.4]);
}

`fn scale_amp_per_channel<F>(self, amp_frame: F) -> ScaleAmpPerChannel<Self, F> where F: Frame<Sample=Self::Item::Sample::Float, NumChannels=Self::Item::NumChannels>`

Produces an Iterator 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;

fn main() {
    let frames = [[0.2, -0.5], [-0.4, 0.3]];
    let mut signal = frames.iter().cloned().scale_amp_per_channel([0.5, 2.0]);
    assert_eq!(signal.next().unwrap(), [0.1, -1.0]);
    assert_eq!(signal.next().unwrap(), [-0.2, 0.6]);
}

`fn mul_hz<I>(self, mul_per_frame: I) -> MulHz<Self, I> where I: Iterator<Item=f64>`

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 the value yielded by signal

Example

extern crate sample;

use sample::Signal;

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 frames: Vec<_> = foo.iter().cloned().mul_hz(mul.iter().cloned()).collect();
    assert_eq!(&frames[..], &[[0.0], [1.0], [0.0], [-0.5], [-1.0]][..]);
}

`fn from_hz_to_hz(self, source_hz: f64, target_hz: f64) -> Converter<Self>`

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

Example

extern crate sample;

use sample::Signal;

fn main() {
    let foo = [[0.0], [1.0], [0.0], [-1.0]];
    let frames: Vec<_> = foo.iter().cloned().from_hz_to_hz(1.0, 2.0).collect();
    assert_eq!(&frames[..], &[[0.0], [0.5], [1.0], [0.5], [0.0], [-0.5], [-1.0]][..]);
}

`fn scale_hz(self, multi: f64) -> Converter<Self>`

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

Example

extern crate sample;

use sample::Signal;

fn main() {
    let foo = [[0.0], [1.0], [0.0], [-1.0]];
    let frames: Vec<_> = foo.iter().cloned().scale_hz(0.5).collect();
    assert_eq!(&frames[..], &[[0.0], [0.5], [1.0], [0.5], [0.0], [-0.5], [-1.0]][..]);
}

`fn delay(self, n_frames: usize) -> Delay<Self>`

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;

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

`fn to_samples(self) -> ToSamples<Self>`

Converts a Iterator yielding Frames into an Iterator yielding Samples.

Example

extern crate sample;

use sample::Signal;

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

`fn clip_amp(self, thresh: Self::Item::Sample::Signed) -> ClipAmp<Self>`

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

Example

extern crate sample;

use sample::Signal;

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

`fn bus(self) -> Bus<Self>`

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 mjust remain available for output B and in turn must be stored in an intermediary ring buffer.

Example

extern crate sample;

use sample::Signal;

fn main() {
    let frames = [[0.1], [0.2], [0.3]];
    let bus = frames.iter().cloned().bus();
    let mut a = bus.send();
    let mut b = bus.send();
    assert_eq!(a.collect::<Vec<_>>(), vec![[0.1], [0.2], [0.3]]);
    assert_eq!(b.collect::<Vec<_>>(), vec![[0.1], [0.2], [0.3]]);
}

Implementors

impl<I> Signal for I where I: Iterator, I::Item: Frame