Struct OpCtx 

pub struct OpCtx<'a> {

    pub command: String,
    pub inputs: Vec<PathBuf>,
    pub globals: Globals,
    pub io: &'a dyn AudioIo,
    pub progress: &'a dyn Progress,
    pub cancel: CancelToken,
    pub registry: Option<&'a Registry>,
    pub outputs: Vec<OutputRecord>,
    pub input_records: Vec<InputRecord>,
    pub warnings: Vec<WarningRecord>,
    pub metrics: Map<String, Value>,
    pub notes: Map<String, Value>,
    pub models: Vec<ModelRecord>,
    pub plugins: Vec<Value>,
    pub deterministic: Option<bool>,
    pub stdin: Option<Vec<u8>>,
    pub stdout: Option<Vec<u8>>,
    pub index: usize,
    pub temp_files: Vec<PathBuf>,
    pub result: Option<Value>,
}

Context for one op invocation.

Fields

command: String

The command path being run (e.g. separate).

inputs: Vec<PathBuf>

globals: Globals

io: &'a dyn AudioIo

progress: &'a dyn Progress

cancel: CancelToken

registry: Option<&'a Registry>

Registry of every op, for ops that compose others (master, enhance, hum…).

outputs: Vec<OutputRecord>

input_records: Vec<InputRecord>

warnings: Vec<WarningRecord>

metrics: Map<String, Value>

notes: Map<String, Value>

Parameter values resolved at run time (detected key, chosen noise region…).

models: Vec<ModelRecord>

plugins: Vec<Value>

deterministic: Option<bool>

False when a stage may be nondeterministic (plugins with internal randomness).

stdin: Option<Vec<u8>>

Stdin bytes (when an input is -).

stdout: Option<Vec<u8>>

Bytes to write to stdout when -o -.

index: usize

Index of this item in a batch (for {index} in output templates).

temp_files: Vec<PathBuf>

Files created by this op that must be removed if the op fails.

result: Option<Value>

Result value set by a Transform op (custom ops return theirs directly).

Implementations

impl<'a> OpCtx<'a>

pub fn new( command: &str, inputs: Vec<PathBuf>, globals: Globals, io: &'a dyn AudioIo, progress: &'a dyn Progress, ) -> Self

pub fn child(&self, command: &str, inputs: Vec<PathBuf>) -> OpCtx<'a>

A child context for running a nested op (shares io, progress, globals, registry).

pub fn absorb(&mut self, child: OpCtx<'a>)

Merge a child’s records into this context.

pub fn bpm(&self) -> Option<f64>

pub fn seed(&self) -> u64

pub fn input(&self, i: usize) -> Result<&Path>

pub fn check_allowed(&self, path: &Path) -> Result<()>

Check that a path is inside the sandbox (when one is set).

pub fn read_audio(&mut self, i: usize) -> Result<AudioBuffer>

Decode input i (or stdin for -), applying --channels/--sample-rate only at write time.

pub fn read_audio_path(&mut self, path: &Path) -> Result<AudioBuffer>

pub fn open_audio_stream( &mut self, i: usize, ) -> Result<Option<Box<dyn AudioReader>>>

Input i as a stream of chunks when the IO layer can stream it; Ok(None) means use OpCtx::read_audio. Call OpCtx::record_stream_input once the stream is consumed.

pub fn record_stream_input( &mut self, info: &SourceInfo, sample_rate: u32, channels: usize, frames: u64, )

Record a streamed input as OpCtx::read_audio would (frames = what was decoded).

pub fn note_input(&mut self, path: &Path)

Record a non-audio input (MIDI, score, profile…).

pub fn output_path(&self, role: Option<&str>, ext: &str) -> Result<PathBuf>

Resolve the output path for this op.

• role — e.g. vocals for a stem (fills {stem}); None for the main output.
• ext — default extension when the user gave no -o.

Honours -o templates ({name}, {stem}, {index}, {ext}, {command}), --outdir, --in-place, and the default <input>.<command>[.<role>].<ext> beside the input.

pub fn prepare_output(&self, path: &Path) -> Result<()>

Check overwrite policy and sandbox for an output path, creating its directory.

pub fn encode_options(&self, path: &Path) -> EncodeOptions

Encoding options from global flags for a given output path.

pub fn write_audio( &mut self, path: &Path, buf: &AudioBuffer, role: Option<&str>, ) -> Result<()>

Write an audio output, applying --sample-rate and --channels conversions is the caller’s job (the executor does it for transforms). Records the output.

pub fn write_audio_with( &mut self, path: &Path, buf: &AudioBuffer, role: Option<&str>, opts: &EncodeOptions, ) -> Result<()>

pub fn write_audio_blocks( &mut self, path: &Path, role: Option<&str>, opts: &EncodeOptions, sample_rate: u32, channels: usize, frames: usize, produce: &mut dyn FnMut(&mut dyn FnMut(&[&[f32]]) -> Result<()>) -> Result<()>, ) -> Result<()>

Write an audio output block by block: produce(sink) hands sink consecutive planar blocks covering exactly frames frames. The output streams to the encoder when the IO layer can (memory independent of the length); otherwise the blocks are collected and written with OpCtx::write_audio_with. The file’s bytes are the same either way.

pub fn write_file( &mut self, path: &Path, bytes: &[u8], role: Option<&str>, ) -> Result<()>

Write a non-audio file (JSON, MIDI, text…) and record it.

pub fn record_output(&mut self, path: &Path, role: Option<&str>)

Record an output that was written by other means (e.g. a helper process).

pub fn set_result(&mut self, value: impl Serialize)

Set the envelope result from a Transform op.

pub fn warn(&mut self, code: &str, message: impl Into<String>)

pub fn metric(&mut self, key: &str, value: impl Serialize)

pub fn note(&mut self, key: &str, value: impl Serialize)

Record a parameter resolved at run time (shown in params and the sidecar).

pub fn model_used(&mut self, name: &str, version: &str, sha256: &str)

pub fn set_progress(&self, fraction: f64)

pub fn check_cancel(&self) -> Result<()>

pub fn threads(&self) -> usize

Thread count to use (0 = all cores).