Headless plugin host for testing and offline processing. More...

#include <headless.hpp>

Public Member Functions
	HeadlessHost (ProcessorFactory factory)
	Construct from a factory function that creates a Processor instance.
void	prepare (double sample_rate, int max_buffer_size, int input_channels=2, int output_channels=2)
	Prepare the processor for audio rendering.
bool	try_prepare (double sample_rate, int max_buffer_size, int input_channels=2, int output_channels=2, PrepareResourceLimits resource_limits={})
	Prepare with explicit resource limits.
bool	try_prepare_bus_layout (std::size_t layout_index, double sample_rate, int max_buffer_size, PrepareResourceLimits resource_limits={})
	Prepare one of PluginDescriptor::supported_bus_layouts by index.
PrepareResourceLimit	last_prepare_limit_failure () const
	Last prepare-limit failure from try_prepare().
void	process (audio::BufferView< float > &output, const audio::BufferView< const float > &input)
	Process a block of audio (no MIDI).
void	process (audio::BufferView< float > &output, const audio::BufferView< const float > &input, ProcessContext context)
	Process a block of audio with explicit transport/timeline context.
void	process_with_sidechain (audio::BufferView< float > &output, const audio::BufferView< const float > &input, const audio::BufferView< const float > &sidechain, ProcessContext context={})
	Process with an independently supplied sidechain bus.
void	process (audio::BufferView< float > &output, const audio::BufferView< const float > &input, midi::MidiBuffer &midi_in, midi::MidiBuffer &midi_out)
	Process a block of audio with MIDI input and output.
void	process (audio::BufferView< float > &output, const audio::BufferView< const float > &input, const state::ParameterEventQueue &param_events)
	Process a block with explicit sample-accurate parameter events.
void	process (audio::BufferView< float > &output, const audio::BufferView< const float > &input, midi::MidiBuffer &midi_in, midi::MidiBuffer &midi_out, ProcessContext context)
	Process a block of audio with MIDI and explicit transport/timeline context.
void	process_with_sidechain (audio::BufferView< float > &output, const audio::BufferView< const float > &input, const audio::BufferView< const float > &sidechain, midi::MidiBuffer &midi_in, midi::MidiBuffer &midi_out, ProcessContext context)
void	process (audio::BufferView< float > &output, const audio::BufferView< const float > &input, midi::MidiBuffer &midi_in, midi::MidiBuffer &midi_out, const state::ParameterEventQueue &param_events, ProcessContext context)
	Low-level process call with MIDI, context, and parameter events.
void	process_f64 (audio::BufferView< double > &output, const audio::BufferView< const double > &input)
	Process a double-precision block of audio (no MIDI).
void	process_f64 (audio::BufferView< double > &output, const audio::BufferView< const double > &input, ProcessContext context)
	Process a double-precision block with explicit transport/timeline context.
void	process_f64 (audio::BufferView< double > &output, const audio::BufferView< const double > &input, midi::MidiBuffer &midi_in, midi::MidiBuffer &midi_out)
	Process a double-precision block with MIDI input and output.
void	process_f64 (audio::BufferView< double > &output, const audio::BufferView< const double > &input, const state::ParameterEventQueue &param_events)
	Process a double-precision block with explicit sample-accurate parameter events.
void	process_f64 (audio::BufferView< double > &output, const audio::BufferView< const double > &input, midi::MidiBuffer &midi_in, midi::MidiBuffer &midi_out, ProcessContext context)
	Process a double-precision block with MIDI and explicit transport / timeline context.
void	process_f64 (audio::BufferView< double > &output, const audio::BufferView< const double > &input, midi::MidiBuffer &midi_in, midi::MidiBuffer &midi_out, const state::ParameterEventQueue &param_events, ProcessContext context)
	Low-level double-precision process call with MIDI, context, and parameter events.
std::optional< audio::AudioFileData >	render_offline (const audio::AudioFileData &input, const audio::OfflineRenderOptions &options={})
	Render an effect-shaped in-memory audio file through this processor.
std::optional< audio::AudioFileData >	render_offline_with_sidechain (const audio::AudioFileData &input, const audio::AudioFileData &sidechain, const audio::OfflineRenderOptions &options={})
	Offline render with a separate sidechain file.
void	release ()
	Release processing resources. Safe to call multiple times.
bool	valid () const noexcept
	True when the factory produced a processor instance.
Processor *	processor () noexcept
	The wrapped processor instance (null when the factory returned nullptr).
const Processor *	processor () const noexcept
	The wrapped processor instance (null when the factory returned nullptr).
template<class T>
T *	processor_as () noexcept
	Typed access to the wrapped processor; returns nullptr if the dynamic type does not match `T`.
state::StateStore &	state ()
	Access the parameter store for reading/writing parameter values.
const state::StateStore &	state () const
	Access the parameter store for reading/writing parameter values.
const PluginDescriptor &	descriptor () const
	The plugin's static descriptor (name, vendor, bus layout, etc.).
std::vector< uint8_t >	save_state () const
	Serialize the current plugin state to a binary blob.
bool	load_state (std::span< const uint8_t > data)
	Restore plugin state from a binary blob.

Detailed Description

Headless plugin host for testing and offline processing.

Wraps a Processor and its StateStore so you can drive audio processing entirely from code. No audio device, no UI, no host DAW required.

HeadlessHost host(MyPlugin::create);
host.prepare(48000, 512);
host.state().set_value(kGainID, -6.0f);
 
audio::Buffer<float> in(2, 512), out(2, 512);
auto in_view = in.view();
auto out_view = out.view();
host.process(out_view, in_view);

Constructor & Destructor Documentation

◆ HeadlessHost()

pulp::format::HeadlessHost::HeadlessHost ( ProcessorFactory factory )

explicit

Construct from a factory function that creates a Processor instance.

Member Function Documentation

◆ descriptor()

const PluginDescriptor & pulp::format::HeadlessHost::descriptor ( ) const

inline

The plugin's static descriptor (name, vendor, bus layout, etc.).

◆ last_prepare_limit_failure()

PrepareResourceLimit pulp::format::HeadlessHost::last_prepare_limit_failure ( ) const

inline

Last prepare-limit failure from try_prepare().

None means the last checked prepare either fit the limits or no processor exists.

◆ load_state()

bool pulp::format::HeadlessHost::load_state ( std::span< const uint8_t > data )

Restore plugin state from a binary blob.

Returns: True on success.

◆ prepare()

void pulp::format::HeadlessHost::prepare	(	double	sample_rate,
		int	max_buffer_size,
		int	input_channels = 2,
		int	output_channels = 2 )

Prepare the processor for audio rendering.

Call before process().

Parameters

sample_rate	Sample rate in Hz.
max_buffer_size	Maximum samples per block.
input_channels	Number of input audio channels.
output_channels	Number of output audio channels.

◆ process() [1/6]

void pulp::format::HeadlessHost::process	(	audio::BufferView< float > &	output,
		const audio::BufferView< const float > &	input )

Process a block of audio (no MIDI).

input and output may alias for in-place processing.

◆ process() [2/6]

void pulp::format::HeadlessHost::process	(	audio::BufferView< float > &	output,
		const audio::BufferView< const float > &	input,
		const state::ParameterEventQueue &	param_events )

Process a block with explicit sample-accurate parameter events.

◆ process() [3/6]

void pulp::format::HeadlessHost::process	(	audio::BufferView< float > &	output,
		const audio::BufferView< const float > &	input,
		midi::MidiBuffer &	midi_in,
		midi::MidiBuffer &	midi_out )

Process a block of audio with MIDI input and output.

◆ process() [4/6]

void pulp::format::HeadlessHost::process	(	audio::BufferView< float > &	output,
		const audio::BufferView< const float > &	input,
		midi::MidiBuffer &	midi_in,
		midi::MidiBuffer &	midi_out,
		const state::ParameterEventQueue &	param_events,
		ProcessContext	context )

Low-level process call with MIDI, context, and parameter events.

◆ process() [5/6]

void pulp::format::HeadlessHost::process	(	audio::BufferView< float > &	output,
		const audio::BufferView< const float > &	input,
		midi::MidiBuffer &	midi_in,
		midi::MidiBuffer &	midi_out,
		ProcessContext	context )

Process a block of audio with MIDI and explicit transport/timeline context.

This is the low-level seam for deterministic offline stepping.

◆ process() [6/6]

void pulp::format::HeadlessHost::process	(	audio::BufferView< float > &	output,
		const audio::BufferView< const float > &	input,
		ProcessContext	context )

Process a block of audio with explicit transport/timeline context.

Any non-positive sample_rate / num_samples fields are defaulted from the prepared host configuration and current buffer size.

◆ process_f64() [1/6]

void pulp::format::HeadlessHost::process_f64	(	audio::BufferView< double > &	output,
		const audio::BufferView< const double > &	input )

Process a double-precision block of audio (no MIDI).

input and output may alias for in-place processing.

◆ process_f64() [2/6]

void pulp::format::HeadlessHost::process_f64	(	audio::BufferView< double > &	output,
		const audio::BufferView< const double > &	input,
		const state::ParameterEventQueue &	param_events )

Process a double-precision block with explicit sample-accurate parameter events.

◆ process_f64() [3/6]

void pulp::format::HeadlessHost::process_f64	(	audio::BufferView< double > &	output,
		const audio::BufferView< const double > &	input,
		midi::MidiBuffer &	midi_in,
		midi::MidiBuffer &	midi_out )

Process a double-precision block with MIDI input and output.

◆ process_f64() [4/6]

void pulp::format::HeadlessHost::process_f64	(	audio::BufferView< double > &	output,
		const audio::BufferView< const double > &	input,
		midi::MidiBuffer &	midi_in,
		midi::MidiBuffer &	midi_out,
		const state::ParameterEventQueue &	param_events,
		ProcessContext	context )

Low-level double-precision process call with MIDI, context, and parameter events.

◆ process_f64() [5/6]

void pulp::format::HeadlessHost::process_f64	(	audio::BufferView< double > &	output,
		const audio::BufferView< const double > &	input,
		midi::MidiBuffer &	midi_in,
		midi::MidiBuffer &	midi_out,
		ProcessContext	context )

Process a double-precision block with MIDI and explicit transport / timeline context.

◆ process_f64() [6/6]

void pulp::format::HeadlessHost::process_f64	(	audio::BufferView< double > &	output,
		const audio::BufferView< const double > &	input,
		ProcessContext	context )

Process a double-precision block with explicit transport/timeline context.

Any non-positive sample_rate / num_samples fields are defaulted from the prepared host configuration and current buffer size.

◆ process_with_sidechain() [1/2]

void pulp::format::HeadlessHost::process_with_sidechain	(	audio::BufferView< float > &	output,
		const audio::BufferView< const float > &	input,
		const audio::BufferView< const float > &	sidechain,
		midi::MidiBuffer &	midi_in,
		midi::MidiBuffer &	midi_out,
		ProcessContext	context )

◆ process_with_sidechain() [2/2]

void pulp::format::HeadlessHost::process_with_sidechain	(	audio::BufferView< float > &	output,
		const audio::BufferView< const float > &	input,
		const audio::BufferView< const float > &	sidechain,
		ProcessContext	context = {} )

Process with an independently supplied sidechain bus.

The sidechain is never concatenated with or aliased to the main input; processors reach it through ProcessBuffers::sidechain_input() / sidechain_input().

◆ processor() [1/2]

const Processor * pulp::format::HeadlessHost::processor ( ) const

inlinenoexcept

The wrapped processor instance (null when the factory returned nullptr).

Lets tests reach typed processor state — e.g. a custom meter readout — that the generic host interface does not expose.

◆ processor() [2/2]

Processor * pulp::format::HeadlessHost::processor ( )

inlinenoexcept

The wrapped processor instance (null when the factory returned nullptr).

Lets tests reach typed processor state — e.g. a custom meter readout — that the generic host interface does not expose.

◆ processor_as()

template<class T>

T * pulp::format::HeadlessHost::processor_as ( )

inlinenoexcept

Typed access to the wrapped processor; returns nullptr if the dynamic type does not match T.

◆ release()

void pulp::format::HeadlessHost::release ( )

Release processing resources. Safe to call multiple times.

◆ render_offline()

std::optional< audio::AudioFileData > pulp::format::HeadlessHost::render_offline	(	const audio::AudioFileData &	input,
		const audio::OfflineRenderOptions &	options = {} )

Render an effect-shaped in-memory audio file through this processor.

The host must already be prepared for at least the largest scheduled block size. The rendered artifact has the same channel count as input.

◆ render_offline_with_sidechain()

std::optional< audio::AudioFileData > pulp::format::HeadlessHost::render_offline_with_sidechain	(	const audio::AudioFileData &	input,
		const audio::AudioFileData &	sidechain,
		const audio::OfflineRenderOptions &	options = {} )

Offline render with a separate sidechain file.

Sample rates and frame counts must match; channel widths may differ. Tail frames receive a silent sidechain after the supplied file ends.

◆ save_state()

std::vector< uint8_t > pulp::format::HeadlessHost::save_state ( ) const

Serialize the current plugin state to a binary blob.

Includes StateStore plus any processor-owned plugin state exposed via Processor::serialize_plugin_state().

◆ state() [1/2]

state::StateStore & pulp::format::HeadlessHost::state ( )

inline

Access the parameter store for reading/writing parameter values.

◆ state() [2/2]

const state::StateStore & pulp::format::HeadlessHost::state ( ) const

inline

Access the parameter store for reading/writing parameter values.

◆ try_prepare()

bool pulp::format::HeadlessHost::try_prepare	(	double	sample_rate,
		int	max_buffer_size,
		int	input_channels = 2,
		int	output_channels = 2,
		PrepareResourceLimits	resource_limits = {} )

nodiscard

Prepare with explicit resource limits.

Returns false without calling Processor::prepare() when the processor's estimate exceeds any non-zero limit. This is the fail-closed test and batch-render path; the legacy prepare() overload remains source compatible and uses unlimited limits.

◆ try_prepare_bus_layout()

bool pulp::format::HeadlessHost::try_prepare_bus_layout	(	std::size_t	layout_index,
		double	sample_rate,
		int	max_buffer_size,
		PrepareResourceLimits	resource_limits = {} )

nodiscard

Prepare one of PluginDescriptor::supported_bus_layouts by index.

Returns false for an undeclared/invalid layout or when resource limits reject the derived main-bus widths.

◆ valid()

bool pulp::format::HeadlessHost::valid ( ) const

inlinenoexcept

True when the factory produced a processor instance.

The documentation for this class was generated from the following file:

/home/runner/work/pulp/pulp/core/format/include/pulp/format/headless.hpp

Pulp 1.88.0 Cross-platform audio plugin framework

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ HeadlessHost()

Member Function Documentation

◆ descriptor()

◆ last_prepare_limit_failure()

◆ load_state()

◆ prepare()

◆ process() [1/6]

◆ process() [2/6]

◆ process() [3/6]

◆ process() [4/6]

◆ process() [5/6]

◆ process() [6/6]

◆ process_f64() [1/6]

◆ process_f64() [2/6]

◆ process_f64() [3/6]

◆ process_f64() [4/6]

◆ process_f64() [5/6]

◆ process_f64() [6/6]

◆ process_with_sidechain() [1/2]

◆ process_with_sidechain() [2/2]

◆ processor() [1/2]

◆ processor() [2/2]

◆ processor_as()

◆ release()

◆ render_offline()

◆ render_offline_with_sidechain()

◆ save_state()

◆ state() [1/2]

◆ state() [2/2]

◆ try_prepare()

◆ try_prepare_bus_layout()

◆ valid()