plughost 0.2.5

Load and run VST3, Audio Unit, and CLAP plugins from Rust, isolated in helper processes
Documentation
//! The flow of an offline batch application: find a plugin class, prepare a chain, keep a state
//! snapshot, and render several jobs. When the plugin crashes or hangs during a job, the chain is
//! recovered once in a new helper from the snapshot and the job starts again. Effects process a
//! stereo tone and instruments play a note; each job prints its level, and nothing is written.
//!
//! usage: render <helper executable> <bundle.vst3 | bundle.clap | Audio Unit class ID> [class index]

use std::io::Write;
use std::path::{Path, PathBuf};
use std::process::ExitCode;

use plughost::{
    Chain, ChainSlot, Error, Event, Events, FailureKind, Layout, PluginFormat, PluginId,
    PluginInfo, PluginKind, PluginRef, RenderOptions, Rendered, Scanner, SpawnOptions,
    StatePurpose, render,
};

const USAGE: &str = "usage: render <helper executable> <bundle.vst3 | bundle.clap | Audio Unit class ID> [class index]";
const NO_CLASS: &str = "no plugin class found for that bundle and index or class ID";
const RATE: f64 = 48_000.0;
const BLOCK: usize = 512;
const SECONDS: f64 = 2.0;
/// Keys for instruments; effects hear the same pitches as tones.
const JOBS: [u8; 3] = [48, 60, 72];

macro_rules! out {
    ($($arg:tt)*) => {{
        let _ = writeln!(std::io::stdout(), $($arg)*);
    }};
}

/// Finds class `index` of a `.vst3` or `.clap` bundle, or a registered Audio Unit by class ID.
fn find(
    helper: &Path,
    target: &Path,
    index: usize,
) -> Result<Option<(PluginRef, PluginInfo)>, Error> {
    let cache = std::env::temp_dir().join(format!("plughost-render-{}.json", std::process::id()));
    let scanner = Scanner::new(helper, &cache);
    let found = if target
        .extension()
        .is_some_and(|e| e.eq_ignore_ascii_case("vst3") || e.eq_ignore_ascii_case("clap"))
    {
        let scanned = scanner.retry(target)?;
        let found = scanned
            .plugins()
            .into_iter()
            .nth(index)
            .map(|(plugin, class)| (plugin, class.clone()));
        if found.is_none() {
            out!("scan: {:?}", scanned.outcome);
        }
        found
    } else {
        let id = PluginId::new(PluginFormat::AudioUnit, target.to_string_lossy());
        scanner
            .directories(Vec::new())
            .scan(&|_| {})?
            .plugins()
            .into_iter()
            .find(|(plugin, _)| plugin.id() == &id)
            .map(|(plugin, info)| (plugin, info.clone()))
    };
    let _ = std::fs::remove_file(&cache);
    Ok(found)
}

/// One job: a tone at `key`'s pitch on both channels for effects, or the note for instruments.
fn job(chain: &mut Chain, instrument: bool, key: u8) -> Result<Rendered<f32>, Error> {
    let frames = (SECONDS * RATE) as usize;
    let options = RenderOptions::default();
    if instrument {
        let notes = Events::from_iter([
            Event::note_on(0, 0, key, 100),
            Event::note_off(frames / 2, 0, key, 0),
        ]);
        return render::<f32, _>(chain, &[], frames, &notes, &options);
    }
    let pitch = 440.0 * 2f64.powf((f64::from(key) - 69.0) / 12.0);
    let tone: Vec<f32> = (0..frames)
        .map(|i| 0.25 * (i as f64 * pitch / RATE * std::f64::consts::TAU).sin() as f32)
        .collect();
    render(chain, &[&tone, &tone], frames, &Events::new(), &options)
}

fn report(key: u8, rendered: &Rendered<f32>) {
    let samples: Vec<f64> = rendered
        .channels
        .iter()
        .flatten()
        .map(|&s| f64::from(s))
        .collect();
    let rms = (samples.iter().map(|s| s * s).sum::<f64>() / samples.len().max(1) as f64).sqrt();
    let peak = samples.iter().fold(0.0f64, |peak, s| peak.max(s.abs()));
    out!(
        "job {key}: {:.2} s rendered, latency {} samples removed, tail {} samples, rms {rms:.4}, peak {peak:.4}",
        rendered.channels.first().map_or(0, Vec::len) as f64 / RATE,
        rendered.latency,
        rendered.tail,
    );
}

fn run(helper: &Path, target: &Path, index: usize) -> Result<bool, Error> {
    let Some((plugin, class)) = find(helper, target, index)? else {
        out!("{NO_CLASS}");
        return Ok(false);
    };
    let instrument = class.kind == PluginKind::Instrument;
    let input = if instrument {
        Layout::None
    } else {
        Layout::Stereo
    };
    let mut chain = Chain::spawn(helper, &[plugin.clone().into()], &SpawnOptions::default())?;
    let config = chain.main_bus_config(RATE, BLOCK, input, &[Layout::Stereo])?;
    chain.prepare_audio(&config)?;
    // The last known good state. An application refreshes it after the user changes settings.
    // A plugin without saved state recovers in its initial state.
    let snapshot = match chain.save_state(0, StatePurpose::Project) {
        Ok(state) => vec![ChainSlot::new(plugin.clone()).with_state(state)],
        Err(error) if error.kind() == FailureKind::Unsupported => {
            out!("no state snapshot: {}", describe(&error));
            vec![ChainSlot::new(plugin.clone())]
        }
        Err(error) => return Err(error),
    };
    out!("{} prepared", class.name);

    for key in JOBS {
        let mut recovered = false;
        loop {
            chain.reset()?;
            match job(&mut chain, instrument, key) {
                Ok(rendered) => {
                    report(key, &rendered);
                    break;
                }
                Err(error)
                    if !recovered
                        && matches!(error.kind(), FailureKind::Crashed | FailureKind::TimedOut) =>
                {
                    out!(
                        "job {key}: {}; recovering from the snapshot",
                        describe(&error)
                    );
                    // The failed chain stays usable for another attempt if recovery fails.
                    chain = chain.recover(&snapshot)?;
                    recovered = true;
                }
                Err(error) => {
                    out!("job {key}: {}", describe(&error));
                    return Ok(false);
                }
            }
        }
    }
    let diagnostics = chain.take_diagnostics()?;
    out!(
        "plugin diagnostics: {} records, {} dropped",
        diagnostics.records.len(),
        diagnostics.dropped
    );
    Ok(true)
}

fn main() -> ExitCode {
    let args: Vec<PathBuf> = std::env::args_os().skip(1).map(PathBuf::from).collect();
    let (Some(helper), Some(target)) = (args.first(), args.get(1)) else {
        out!("{USAGE}");
        return ExitCode::from(2);
    };
    let index = args
        .get(2)
        .and_then(|i| i.to_str()?.parse().ok())
        .unwrap_or(0);
    match run(helper, target, index) {
        Ok(true) => ExitCode::SUCCESS,
        Ok(false) => ExitCode::FAILURE,
        Err(error) => {
            out!("{}", describe(&error));
            ExitCode::FAILURE
        }
    }
}

/// The error followed by each cause; plughost errors keep the native reason in `source()`.
fn describe(error: &dyn std::error::Error) -> String {
    let mut text = error.to_string();
    let mut cause = error.source();
    while let Some(error) = cause {
        text = format!("{text}: {error}");
        cause = error.source();
    }
    text
}