rundsp/stream/run/

start.rs

//! All of the free functions which start the creation of a [`Run`].
//!
//! Each of these corresponds to a builder method on [`Run`]; these are purely convenience methods
//! which are shorthands for `Run::new().method(...)`.

use fundsp::hacker::{U1, U2, multipass};

use crate::{FromStereo, ToStereo};

use super::*;

impl Default for Run {
    fn default() -> Self {
        Self::new()
    }
}

impl Run {
    /// Create a new [`Run`] with default parameters.
    ///
    /// This cannot be [`run`](Run::run) without a type error until at least one of
    /// [`input`](Run::input) or [`output`](Run::output) are specified.
    pub fn new() -> Self {
        Run {
            host: None,
            select_device: Arc::new(|_, _| None),
            select_config: Arc::new(|_, _| None),
            input_info: |_| {},
            output_info: |_| {},
            timeout: None,
            start_paused: false,
            retrying: Arc::new(Mutex::new(|_: &Error| Retry::stop())),
            control: mpsc::channel(1).1,
            input: NoInput,
            output: NoOutput,
        }
    }
}

impl<L, M, I, O> Run<I, O, L, M>
where
    L: InputInfo,
    M: OutputInfo,
{
    /// Use the given audio [`Host`].
    pub fn host(mut self, host: Host) -> Self {
        self.host = Some(Arc::new(host));
        self
    }

    /// Use the specified closure to select which [`Device`] should be used for each end of the
    /// pipeline.
    pub fn device(mut self, select_device: impl SelectDevice) -> Self {
        self.select_device = Arc::new(select_device);
        self
    }

    /// Use the specified closure to select which [`SupportedStreamConfig`] should be used for each
    /// end of the pipeline.
    pub fn config(mut self, select_config: impl SelectConfig) -> Self {
        self.select_config = Arc::new(select_config);
        self
    }

    /// Use the specified audio node as the input end of the pipeline.
    ///
    /// After specifying this, it is now possible to [`run`](Run::run) the pipline, although other
    /// options may also be specified afterwards.
    pub fn input<N: StereoInput>(self, input: An<N>) -> Run<An<N>, O, L, M> {
        let Run {
            host,
            select_device,
            select_config,
            input_info,
            output_info,
            timeout,
            start_paused,
            retrying,
            control,
            input: _,
            output,
        } = self;
        Run {
            host,
            select_device,
            select_config,
            input_info,
            output_info,
            timeout,
            start_paused,
            retrying,
            control,
            input,
            output,
        }
    }

    /// Feed the microphone's input directly to the output of the pipeline.
    ///
    /// In case of ambiguous type inference, use [`mono_mic`](Run::mono_mic) or
    /// [`stereo_mic`](Run::stereo_mic) to disambiguate.
    ///
    /// After specifying this, it is now possible to [`run`](Run::run) the pipline, although other
    /// options may also be specified afterwards.
    pub fn mic<N: FromStereo>(self) -> Run<An<impl StereoInput<Outputs = N>>, O, L, M> {
        self.input(multipass())
    }

    /// Feed the microphone's input directly to the output of the pipeline, as *mono* audio.
    ///
    /// After specifying this, it is now possible to [`run`](Run::run) the pipline, although other
    /// options may also be specified afterwards.
    pub fn mono_mic(self) -> Run<An<impl StereoInput<Outputs = U1>>, O, L, M> {
        self.mic::<U1>()
    }

    /// Feed the microphone's input directly to the output of the pipeline, as *stereo* audio.
    ///
    /// After specifying this, it is now possible to [`run`](Run::run) the pipline, although other
    /// options may also be specified afterwards.
    pub fn stereo_mic(self) -> Run<An<impl StereoInput<Outputs = U2>>, O, L, M> {
        self.mic::<U2>()
    }

    /// Use the specified audio node as the output end of the pipeline.
    ///
    /// After specifying this, it is now possible to [`run`](Run::run) the pipline, although other
    /// options may also be specified afterwards.
    pub fn output<N: StereoOutput>(self, output: An<N>) -> Run<I, An<N>, L, M> {
        let Run {
            host,
            select_device,
            select_config,
            input_info,
            output_info,
            timeout,
            start_paused,
            retrying,
            control,
            input,
            output: _,
        } = self;
        Run {
            host,
            select_device,
            select_config,
            input_info,
            output_info,
            timeout,
            start_paused,
            retrying,
            control,
            input,
            output,
        }
    }

    /// Feed the output of the pipeline directly to the speaker (or headphones).
    ///
    /// In case of ambiguous type inference, use [`mono_speaker`](Run::mono_speaker) or
    /// [`stereo_speaker`](Run::stereo_speaker) to disambiguate.
    ///
    /// After specifying this, it is now possible to [`run`](Run::run) the pipline, although other
    /// options may also be specified afterwards.
    pub fn speaker<N: ToStereo>(self) -> Run<I, An<impl StereoOutput<Inputs = N>>, L, M> {
        self.output(multipass())
    }

    /// Feed the output of the pipeline directly to the speaker (or headphones), as *mono* audio.
    ///
    /// After specifying this, it is now possible to [`run`](Run::run) the pipline, although other
    /// options may also be specified afterwards.
    pub fn mono_speaker(self) -> Run<I, An<impl StereoOutput<Inputs = U1>>, L, M> {
        self.speaker::<U1>()
    }

    /// Feed the output of the pipeline directly to the speaker (or headphones), as *stereo* audio.
    ///
    /// After specifying this, it is now possible to [`run`](Run::run) the pipline, although other
    /// options may also be specified afterwards.
    pub fn stereo_speaker(self) -> Run<I, An<impl StereoOutput<Inputs = U2>>, L, M> {
        self.speaker::<U2>()
    }

    /// Call the given closure every time an input buffer is received.
    ///
    /// The closure specified should be fast, non-allocating, and non-blocking; otherwise, audio
    /// glitches may occur.
    pub fn on_input<X: InputInfo>(self, input_info: X) -> Run<I, O, X, M> {
        let Run {
            host,
            select_device,
            select_config,
            input_info: _,
            output_info,
            timeout,
            start_paused,
            retrying,
            control,
            input,
            output,
        } = self;
        Run {
            host,
            select_device,
            select_config,
            input_info,
            output_info,
            timeout,
            start_paused,
            retrying,
            control,
            input,
            output,
        }
    }

    /// Call the given closure every time an input buffer is produced.
    ///
    /// The closure specified should be fast, non-allocating, and non-blocking; otherwise, audio
    /// glitches may occur.
    pub fn on_output<X: OutputInfo>(self, output_info: X) -> Run<I, O, L, X> {
        let Run {
            host,
            select_device,
            select_config,
            input_info,
            output_info: _,
            timeout,
            start_paused,
            retrying,
            control,
            input,
            output,
        } = self;
        Run {
            host,
            select_device,
            select_config,
            input_info,
            output_info,
            timeout,
            start_paused,
            retrying,
            control,
            input,
            output,
        }
    }

    /// Use the given closure to determine how to retry in the event of an error while building or
    /// running a stream. See [`Retrying`] for more information.
    pub fn on_error<R: Into<Retry>>(mut self, mut retry: impl Retrying<R>) -> Self {
        self.retrying = Arc::new(Mutex::new(move |error: &Error| retry(error).into()));
        self
    }

    /// Start the audio pipeline paused, so that it has to be manually played.
    pub fn paused(mut self) -> Self {
        self.start_paused = true;
        self
    }

    /// Run the audio pipeline as specified.
    ///
    /// This method call will not type-check unless you have specified at least one of
    /// [`input`](Run::input) or [`output`](Run::output), or equivalently unless you started the
    /// builder using [`input`] or [`output`].
    pub fn run(self) -> Running
    where
        I: RunWith<O>,
    {
        self.run_audio()
    }
}

// Free functions to start building a `Run`:

/// Create a new [`Run`] using a given audio [`Host`].
///
/// The resultant [`Run`] cannot be [`run`](Run::run) without a type error until at least one of
/// [`input`](Run::input) or [`output`](Run::output) are specified.
pub fn host(host: Host) -> Run {
    Run::new().host(host)
}

/// Create a new [`Run`] using the given closure to select an audio [`Device`].
///
/// The resultant [`Run`] cannot be [`run`](Run::run) without a type error until at least one of
/// [`input`](Run::input) or [`output`](Run::output) are specified.
pub fn device(select_device: impl SelectDevice) -> Run {
    Run::new().device(select_device)
}

/// Create a new [`Run`] using the given closure to select an audio [`SupportedStreamConfig`].
///
/// The resultant [`Run`] cannot be [`run`](Run::run) without a type error until at least one of
/// [`input`](Run::input) or [`output`](Run::output) are specified.
pub fn config(select_config: impl SelectConfig) -> Run {
    Run::new().config(select_config)
}

/// Create a new [`Run`] using the given audio node as the input end.
///
/// The resultant [`Run`] can be immediately [`run`](Run::run), or further options may be specified.
pub fn input<I: StereoInput>(input: An<I>) -> Run<An<I>, NoOutput> {
    Run::new().input(input)
}

/// Create a new [`Run`] that feeds the microphone's input directly to the output of the pipeline.
///
/// In case of ambiguous type inference, use [`mono_mic`](Run::mono_mic) or
/// [`stereo_mic`](Run::stereo_mic) to disambiguate.
///
/// After specifying this, it is now possible to [`run`](Run::run) the pipline, although other
/// options may also be specified afterwards.
pub fn mic<N: FromStereo>() -> Run<An<impl StereoInput<Outputs = N>>, NoOutput> {
    Run::new().mic()
}

/// Create a new [`Run`] that feeds the microphone's input directly to the output of the pipeline,
/// as *mono* audio.
///
/// After specifying this, it is now possible to [`run`](Run::run) the pipline, although other
/// options may also be specified afterwards.
pub fn mono_mic() -> Run<An<impl StereoInput<Outputs = U1>>, NoOutput> {
    Run::new().mono_mic()
}

/// Create a new [`Run`] that feeds the microphone's input directly to the output of the pipeline,
/// as *stereo* audio.
///
/// After specifying this, it is now possible to [`run`](Run::run) the pipline, although other
/// options may also be specified afterwards.
pub fn stereo_mic() -> Run<An<impl StereoInput<Outputs = U2>>, NoOutput> {
    Run::new().stereo_mic()
}

/// Create a new [`Run`] using the given audio node as the output end.
///
/// The resultant [`Run`] can be immediately [`run`](Run::run), or further options may be specified.
pub fn output<O: StereoOutput>(output: An<O>) -> Run<NoInput, An<O>> {
    Run::new().output(output)
}

/// Create a new [`Run`] that feeds the output of the pipeline directly to the speaker (or
/// headphones).
///
/// In case of ambiguous type inference, use [`mono_speaker`](Run::mono_speaker) or
/// [`stereo_speaker`](Run::stereo_speaker) to disambiguate.
///
/// After specifying this, it is now possible to [`run`](Run::run) the pipline, although other
/// options may also be specified afterwards.
pub fn speaker<N: ToStereo>() -> Run<NoInput, An<impl StereoOutput<Inputs = N>>> {
    Run::new().speaker()
}

/// Create a new [`Run`] that feeds the output of the pipeline directly to the speaker (or
/// headphones), as *mono* audio.
///
/// After specifying this, it is now possible to [`run`](Run::run) the pipline, although other
/// options may also be specified afterwards.
pub fn mono_speaker() -> Run<NoInput, An<impl StereoOutput<Inputs = U1>>> {
    Run::new().mono_speaker()
}

/// Create a new [`Run`] that feeds the output of the pipeline directly to the speaker (or
/// headphones), as *stereo* audio.
///
/// After specifying this, it is now possible to [`run`](Run::run) the pipline, although other
/// options may also be specified afterwards.
pub fn stereo_speaker() -> Run<NoInput, An<impl StereoOutput<Inputs = U2>>> {
    Run::new().stereo_speaker()
}

/// Create a new [`Run`] which will call the given closure every time an input buffer is received.
///
/// The closure specified should be fast, non-allocating, and non-blocking; otherwise, audio
/// glitches may occur.
///
/// The resultant [`Run`] cannot be [`run`](Run::run) without a type error until at least one of
/// [`input`](Run::input) or [`output`](Run::output) are specified.
pub fn on_input<I: InputInfo>(input_info: I) -> Run<NoInput, NoOutput, I, FnOutputInfo> {
    Run::new().on_input(input_info)
}

/// Create a new [`Run`] which will call the given closure every time an output buffer is produced.
///
/// The closure specified should be fast, non-allocating, and non-blocking; otherwise, audio
/// glitches may occur.
///
/// The resultant [`Run`] cannot be [`run`](Run::run) without a type error until at least one of
/// [`input`](Run::input) or [`output`](Run::output) are specified.
pub fn on_output<O: OutputInfo>(output_info: O) -> Run<NoInput, NoOutput, FnInputInfo, O> {
    Run::new().on_output(output_info)
}

/// Create a new [`Run`] which will use the given closure to determine how to retry in the event of
/// an error while building or running a stream. See [`Retrying`] for more information.
///
/// The resultant [`Run`] cannot be [`run`](Run::run) without a type error until at least one of
/// [`input`](Run::input) or [`output`](Run::output) are specified.
pub fn on_error<R: Into<Retry>>(retry: impl Retrying<R>) -> Run {
    Run::new().on_error(retry)
}

/// Create a new [`Run`] which will start paused, so that it has to be manually played before audio
/// will happen.
///
/// The resultant [`Run`] cannot be [`run`](Run::run) without a type error until at least one of
/// [`input`](Run::input) or [`output`](Run::output) are specified.
pub fn start_paused() -> Run {
    Run::new().paused()
}