pulp::format Namespace Reference

What the product grants a device: the quota table indexed by capability tier and live thermal state. More...

Namespaces
namespace	aax
namespace	boundary
namespace	ara
namespace	au
	Apple-only: the whole header is gated on APPLE so it stays an empty no-op on the Linux header-hygiene check.
namespace	clap_adapter
namespace	clap_generic
namespace	detail
	The plugin processor interface.
namespace	host_quirks
namespace	lv2_adapter
namespace	lv2_generic
namespace	mpe
namespace	plugin_state_io
namespace	rack
namespace	reload
namespace	validation
namespace	vst3
namespace	wclap
namespace	wam

Classes
struct	AppUpdateStatus
class	AppUpdateService
class	AppUpdatesSettingsView
class	AraDocumentController
	ARA document controller — manages the plugin's view of the DAW's audio content. More...
struct	AudioInputBusProvider
	A host-owned, realtime-safe view provider for declared processor input buses. More...
class	AudioWorkgroupClient
	Optional capability for processors and graph runtimes which own auxiliary realtime rendering threads. More...
class	BackgroundTaskLane
	One bounded, pre-warmed audio-to-worker task lane. More...
class	ContractSessionRegistry
	The contract sessions one adapter instance opened that a host still holds. More...
class	ContractEditorSession
struct	DescriptorIssue
struct	DeviceQuotas
	Ceilings a consumer may grant at one (tier, thermal state) cell. More...
class	DiagnosticReporter
	Collects and formats diagnostic information about the system, plugin configuration, and audio state for troubleshooting. More...
struct	EmbeddedEditorFile
	One file embedded beside the editor script. More...
struct	EditorAssets
class	ParamSubscription
	Owns one ParamPort listener registration. More...
class	ParamPort
	Parameter access for an editor. More...
class	StateStoreParamPort
	The default ParamPort, over a processor's StateStore. More...
struct	VisualChannelInfo
	What a visual channel is. The strings stay valid for the life of the port. More...
struct	VisualEvent
	One occurrence on an events channel. More...
class	VisualPort
	Read access to the values and meters a processor publishes for its UI. More...
struct	NativeParent
	A native window to attach an editor to, owned by the host. More...
struct	EditorSize
	An editor size in logical pixels, with the backing scale factor that maps them to physical pixels (2.0 on a Retina display). More...
struct	EditorKeyEvent
	A key the host offers to the editor before acting on it itself. More...
class	EditorAutomation
	Optional automation surface of an editor, so tooling (the pulp control UI tools, tests) can see and drive any editor whatever draws it. More...
class	Editor
	One editor instance in one native window. More...
struct	HostActionRequest
	One host action and its arguments. More...
class	EditorContext
	What the host gives an editor. More...
class	EditorFactory
	Builds a processor's editors. More...
class	EditorOwnerObserver
	Implemented by an editor view that reads its plug-in instance (Processor, StateStore or other instance state) directly. More...
struct	EditorUiInstance
struct	EditorUiSource
	Where the default scripted editor's document comes from. More...
class	FactoryProgramTable
struct	GpuHostDecision
struct	GraphRuntimeAudioEdgeProbe
struct	GraphRuntimeCommandDecision
struct	GraphRuntimeNodeProcessContext
struct	GraphRuntimeCommandHandler
struct	GraphRuntimeNodeBinding
class	GraphRuntimeSnapshot
	Control-thread-built graph snapshot for GraphRuntimeExecutor. More...
struct	GraphRuntimeEventSink
struct	GraphRuntimeExecutorStats
struct	GraphRuntimeExecutorResult
class	GraphRuntimeBufferPool
	Pre-allocated scratch buffers backing the routing process() path. More...
class	GraphRuntimeMidiScratch
	Pre-allocated per-node MIDI buffers backing the routing path's event edges. More...
class	GraphRuntimeAutomationScratch
	Pre-allocated scratch backing the routing path's parameter-automation edges. More...
class	GraphRuntimeExecutor
class	GraphRuntimeWorkerPool
	Persistent fork-join worker pool for the levelized parallel graph executor. More...
class	HeadlessHost
	Headless plugin host for testing and offline processing. More...
class	ScopedHostParameterWrite
	Marks the enclosing scope as a HOST-originated parameter write. More...
class	ScopedProcessorParameterWrite
	Marks the enclosing scope as a PROCESSOR-originated parameter write (a plug-in writing its own output parameters during process()). More...
class	HostParameterEditBridge
	Reports EDITOR parameter edits to the host, in protocol order, exactly once. More...
struct	HostQuirks
	Always-on / host-gated defensive behaviors that the adapters consult. More...
struct	HostQuirksMeta
	Per-quirk validation status, parallel to HostQuirks. More...
struct	QuirkFilter
	Selection of validation tiers a HostQuirks instance may keep. More...
struct	ResolvedQuirkPolicy
	The runtime-resolved base filter together with its source. More...
struct	QuirkFieldStatus
	One row of resolved quirk state, for diagnostics (pulp doctor). More...
struct	HostVersion
	Semver-ish host version. More...
struct	HostInfo
	Combined accessor: detect both type and version in one call. More...
class	NativeCoreProcessor
	Owns a native DSP core (via the C ABI vtable) and exposes it as a Processor. More...
struct	NoteName
	One named note. More...
struct	OfflineRenderConfig
	Prepare-time configuration for deterministic offline rendering. More...
struct	OfflineMidiEvent
struct	OfflineParameterEvent
struct	OfflineRenderOptions
struct	OfflineRenderStats
struct	OfflineRenderResult
class	OfflineRenderHost
	General-purpose offline renderer over a ProcessorFactory. More...
struct	OfflineSampleBouncePolicy
	Offline/control-thread bounce policy for turning a rendered processor span into sampler-owned audio. More...
struct	OfflineSampleBounceRequest
struct	OfflineSampleBounceResult
class	OfflineSampleBounce
	Control/background-thread helper over OfflineRenderHost. More...
struct	OfflineSampleSlotBounceResult
class	OfflineSampleSlotBounce
	Control/background-thread adapter from OfflineSampleBounce into SampleSlotBank publication. More...
struct	PanicCapabilities
	What a panic request can do in the current host. More...
struct	PanicOutcome
	What service_panic() did. More...
class	PanicState
	Lock-free panic request and output-note state for one Processor. More...
class	ParamGroupProjection
	Validated, registration-ordered projection of StateStore parameter groups. More...
class	ControlRateParamSmoother
struct	PlaybackContextProjectionOptions
	Format-layer metadata that is intentionally absent from the engine-owned transport snapshot. More...
struct	ViewSize
	Editor size hints (in logical pixels). More...
struct	BusInfo
	Audio bus description — for multi-bus plugins (sidechain, aux, etc.). More...
struct	BusLayoutConfiguration
	One complete host-selectable channel configuration. More...
struct	NodeCapabilities
	Capability sidecar for the node ABI. More...
struct	PluginDescriptor
	Plugin metadata — declared once, immutable. More...
struct	PrepareResourceLimits
	Optional prepare-time resource caps supplied by a host or test harness. More...
struct	PrepareResourceUsage
	Processor-reported prepared resource usage estimate. More...
struct	PrepareContext
struct	ProcessBlockFlags
class	ScratchArenaView
class	PrepareScratch
	Prepare-time scratch view. More...
class	BlockScratch
	Block-local scratch view for realtime/offline processing. More...
struct	BusBuffer
class	BusBufferSet
	Fixed-capacity, non-owning set of block-local bus views. More...
struct	ProcessBusBufferInfo
	Metadata that travels with a non-owning richer-surface process bus view. More...
struct	ProcessBusBufferView
	Non-owning view of one richer-surface process bus. More...
class	ProcessBusBufferSet
	Non-owning span of richer-surface process buses for one direction. More...
struct	ProcessBuffersT
	Additive richer-surface process-buffer view. It is intentionally non-owning. More...
struct	EventDropCounters
struct	AudioRateModulationView
	Non-owning dense per-sample parameter-modulation lane. More...
struct	EventBlock
	Non-owning view of all sparse events visible to one process block. More...
struct	ProcessBlock
	Additive block-scoped process contract. More...
struct	ProcessContext
	Process context — passed every audio callback with transport state. More...
class	Processor
class	ParamEventsOptOutMonitor
	Records, for one adapter, whether an opted-out processor read param_events(), and logs it once. More...
struct	ProcessorBlockAdapterScratch
	Caller-owned fallback storage for process_processor_block(). More...
class	ProcessorNode
	Runs a real pulp::format::Processor as a node inside the routed graph. More...
class	ProcessorNodeInstance
	Retained, self-contained lifetime for an authored in-process graph node. More...
struct	ProjectionResult
struct	PulpsetEvent
	One timed steer in a .pulpset. More...
struct	Pulpset
	A parsed .pulpset — events sorted by sample offset. More...
struct	PulpsetRender
	Rendered stereo result of a replay. More...
struct	PluginRegistration
	One registered plugin. More...
struct	SettingsPanelCallbacks
	Callbacks from SettingsPanel to the standalone host. More...
class	SettingsPanel
	Audio/MIDI Settings panel with two tabs. More...
struct	SpectralFrameView
	Borrowed only during Stage::process(). More...
class	SpectralFrameStage
	Stage instances are owned by the adapter. More...
class	SpectralFrameProcessor
	One audio graph node containing an ordered chain of typed frame stages. More...
struct	StandaloneConfig
class	StandaloneApp
class	StandaloneControlHost
	Optional host-side control composition for one ordinary StandaloneApp. More...
struct	StandaloneControlHostCreation
class	StateRestoreGate
struct	TestSignalConfig
class	TestSignalSource
	Generates test audio for the standalone host: sine tone or file playback. More...
class	TransportValidity
	Compact validity mask for the transport values carried by ProcessContext. More...
struct	TransportQuantizeRequest
struct	TransportQuantizerBlock
struct	TransportQuantizeResult
class	TransportQuantizer
struct	ReportEntry
	One entry in the validation report (matches report schema). More...
struct	ValidationRunOptions
	Options for a validation run. More...
class	ValidationHarness
	Deterministic validation harness. More...
class	ValueChannelVisualPort
	Reads a ValueChannelSet through the VisualPort contract. More...
class	ViewBridge

Typedefs
using	EditorFactoryHook = EditorFactory* (*)()
	Returns the editor factory of the UI package a plug-in binary declares.
using	EditorPrewarmScheduler = void (*)(const Processor::EditorPrewarm&)
using	ScriptedEditorBuilder
	Builds the scripted editor from source, the document select_editor_ui_source() chose for assets (the caller has already checked it is available).
using	GraphRuntimeNodeProcessFn
using	GraphRuntimeCommandApplyFn
using	IosAudioSessionListener
	Typed callback — C++ side of the AVAudioSession bridge.
using	ParamCursor = state::ParamCursor
using	ParamSnapshotEntry = state::ParamSnapshotEntry
using	ProcessBuffers = ProcessBuffersT<float>
using	ProcessBuffers64 = ProcessBuffersT<double>
using	ProcessorFactory = std::unique_ptr<Processor>(*)()
	Factory function type — plugins provide this to create processor instances.
using	StandaloneControlHostFactory = std::unique_ptr<StandaloneControlHost> (*)()

Enumerations
enum class	AppUpdateInstaller : std::uint8_t { unknown , package , app_bundle }
	How an update is installed, as the app declares it (pulp_add_sparkle INSTALLER). More...
enum class	AraRole { None = 0 , PlaybackRenderer = 1 , EditorRenderer = 2 , EditorView = 4 }
	ARA role capabilities. More...
enum class	BackgroundTaskPolicy { Ordered , Latest }
enum class	BusRole : std::uint8_t { Main , Aux , Sidechain }
	Semantic role of a declared audio bus. More...
enum class	DescriptorIssueSeverity { Error , Warning }
enum class	PreviewQuality : std::uint8_t { Disabled = 0 , Reduced = 1 , Full = 2 }
	How much work a preview render may do, ascending in cost. More...
enum class	VisualChannelShape : std::uint8_t { scalar = 0 , meter = 1 , vector = 2 , events = 3 }
	The shape of one visual channel. More...
enum class	EditorRole : std::uint8_t { editor = 0 , inspector = 1 , settings = 2 }
	The UI role an editor plays. A processor may offer several at once. More...
enum class	NativeParentKind : std::uint8_t {   none = 0 , cocoa_view = 1 , uikit_view = 2 , win32_window = 3 ,   x11_window = 4 }
	The kind of native window handle an editor is attached to. More...
enum class	EditorKey : std::uint16_t {   none = 0 , space = 1 , enter = 2 , tab = 3 ,   backspace = 4 , escape = 5 , delete_forward = 6 , left = 7 ,   right = 8 , up = 9 , down = 10 , home = 11 ,   end = 12 , page_up = 13 , page_down = 14 }
	A non-character key. More...
enum	EditorKeyModifier : std::uint8_t { editor_modifier_shift = 1u << 0 , editor_modifier_control = 1u << 1 , editor_modifier_alt = 1u << 2 , editor_modifier_command = 1u << 3 }
	Modifier bits in EditorKeyEvent::modifiers. More...
enum class	KeyDisposition : std::uint8_t { forward = 0 , consumed = 1 }
	The editor's answer to an offered key. More...
enum class	HostAction : std::uint16_t { mark_state_dirty = 0 , parameter_context_menu = 1 , close_editor = 2 }
	Actions an editor can ask its host to take. More...
enum class	EditorHostKind : std::uint8_t { plugin , standalone }
	Where a processor's editor lives, as far as the keyboard is concerned. More...
enum class	GenerationJobClass : std::uint8_t { ProposalGeneration = 0 , ArtifactPlayback = 1 , ReceiptRendering = 2 }
	A kind of generation work, distinguished by what it costs and what it needs. More...
enum class	GenerationRoute : std::uint8_t { OnDevice = 0 , Server = 1 , QueueForLater = 2 }
	Where a job is sent. More...
enum class	GenerationHostContext : std::uint8_t { Standalone = 0 , AudioUnitV3 = 1 }
	The surface the product is running as. More...
enum class	GenerationConnectivity : std::uint8_t { Online = 0 , Offline = 1 }
	Whether the device can reach a server right now. More...
enum class	AudioRateModulationDelivery : std::uint8_t { LegacyParameterEvents = 0 , DenseViews = 1 }
enum class	GraphRuntimeCommandStatus : std::uint8_t { Accepted , Rejected }
enum class	GraphRuntimeExecutorErrorCode : std::uint8_t {   None , InvalidProcessBlock , InvalidSnapshot , CommandScratchTooSmall ,   MissingRequiredProcessor , NodeProcessorFailed , BufferPoolTooSmall , NodePortLimitExceeded }
enum class	QuirkStatus : unsigned char { Validated , Speculative , LessonOnly }
	Validation tier for an individual host-quirk flag. See file header. More...
enum class	QuirkPolicySource : unsigned char { CompileDefault , Environment , Api }
	Where the effective base tier-filter came from (for diagnostics — pulp doctor reports this). More...
enum class	HostType {   Unknown , LogicPro , GarageBand , AbletonLive ,   Reaper , ProTools , Cubase , Nuendo ,   Wavelab , StudioOne , FLStudio , Bitwig ,   Maschine , AudacityTenacity , Ardour , Mixbus32C ,   DigitalPerformer , Standalone , Other }
enum class	OfflineSampleBounceStatus : std::uint8_t {   ok , render_failed , empty_render , invalid_sample_rate ,   channel_budget_exceeded , frame_budget_exceeded , byte_budget_exceeded , sample_rate_not_allowed ,   bank_unprepared , publish_failed }
enum class	PanicMode : std::uint8_t { immediate = 2 , release = 1 }
	How hard a panic stops the plug-in. More...
enum class	ViewportPolicy : uint8_t { Automatic , FixedDesign , Responsive }
	Controls whether a host paints an editor through a fixed authored coordinate space or lets the root lay itself out at the live host size. More...
enum class	PluginCategory { Effect , Instrument , MidiEffect }
	Plugin category — determines bus layout expectations and DAW behavior. More...
enum class	PrepareResourceLimit {   None = 0 , PersistentBytes , BlockScratchBytes , TotalBytes ,   BlockSize , InputChannels , OutputChannels , ParameterEvents ,   MidiEvents , Voices }
	Prepare context — passed once before processing starts. More...
enum class	ProcessMode : std::uint8_t { Realtime , Offline }
	Coarse processing mode for one block. More...
enum class	BusDirection : std::uint8_t { Input , Output }
enum class	FrameRate {   unknown = 0 , fps_24 , fps_25 , fps_29_97 ,   fps_29_97_drop , fps_30 , fps_30_drop , fps_60 }
	SMPTE video frame rate. More...
enum class	RenderSpeedHint { Unknown = 0 , Realtime , FasterThanRealtime , SlowerThanRealtime }
	Host render-speed hint for offline or constrained live rendering. More...
enum class	ProjectionSurface : std::uint8_t {   clap , vst3 , lv2 , wam ,   wclap , au }
	Product surfaces that can consume a baked Processor projection. More...
enum class	ProjectionStatus : std::uint8_t { supported , unsupported }
enum class	SpectralFrameError : std::uint8_t {   None , InvalidGeometry , InvalidBlock , InvalidFrame ,   StageFailure , NonFiniteFrame , SequenceOverflow }
enum class	StandaloneControlUiMode { Headless , DeferToEditor }
enum class	TestSignalType { none , sine , file , noise }
enum class	TransportField : std::uint8_t {   Playing = 0 , Recording , Looping , Tempo ,   BeatPosition , SamplePosition , TimeSignature , LoopRange ,   Bar , HostTime , FrameRate , Count }
	Independently optional fields in a per-block host transport snapshot. More...
enum class	TransportQuantizePolicy : std::uint8_t {   Immediate , NextBeat , NextBar , NextGrid ,   HostLoopStart }
enum class	TransportQuantizeStatus : std::uint8_t {   Scheduled , OutsideBlock , TransportStopped , InvalidBlockSize ,   InvalidSampleRate , InvalidTempo , InvalidTimeSignature , InvalidGrid ,   InvalidTimeline , LoopUnavailable , TransportJumped }
enum class	ValidationStatus { pass , fail , skip , error }
	Result status for individual validation steps. More...
enum class	ViewRole { Editor , Inspector }
	Role of a view attached to a ViewBridge. More...

Functions
void	set_app_update_service (std::shared_ptr< AppUpdateService > service)
	Install (or, with nullptr, remove) the process-wide service.
std::shared_ptr< AppUpdateService >	app_update_service ()
AppUpdateStatus	app_update_status ()
	Convenience wrappers over the installed service.
bool	check_for_app_updates ()
bool	set_app_update_automatic_checks (bool on)
bool	open_app_releases_page ()
std::string	app_update_note (const AppUpdateStatus &status)
	The explanatory note shown under the Settings controls, built only from facts in status, so it stays true for each app.
std::string	app_update_version_text (const AppUpdateStatus &status)
	"Version 1.0.7 (1.0.7.2)" – the build is shown only when it differs.
std::string	app_update_last_check_text (const AppUpdateStatus &status)
	"Last checked: never" or "Last checked: 2026-10-04 14:03" (local time).
std::string	app_update_status_json (const AppUpdateStatus &status)
	The status as a JSON object, the shape the JS bridge returns: {available, canCheckNow, automaticChecks, automaticInstall, stub, appName, version, build, lastCheckUnixSeconds, releasesUrl, feedHost, installer: "package"|"app"|"unknown", note, versionText, lastCheckText}.
void	add_app_update_handlers (view::EditorBridge &bridge)
bool	host_supports_ara ()
	Check if the current host supports ARA.
bool	ara_sdk_compiled_in ()
	True when Pulp was built with the Celemony ARA SDK (PULP_ENABLE_ARA=ON.
int	ara_sdk_generation ()
	Highest ARA API generation Pulp was compiled against.
const void *	ara_companion_factory_for (class AraDocumentController *controller)
	Return an opaque pointer to an ARA::ARAFactory-compatible struct when the processor is ARA-aware and Pulp was built with PULP_HAS_ARA, otherwise nullptr.
void	bind_audio_device_workgroup (AudioWorkgroupClient &client, audio::AudioDevice *device)
	Production device-to-renderer handoff shared by standalone and timeline hosts.
void	close_audio_device_after_workgroup_release (AudioWorkgroupClient *client, audio::AudioDevice &device) noexcept
	Stop-time ownership barrier: release the device-owned handle on every worker before close() can invalidate it.
void	clear_audio_workgroup_after_render_resources (AudioWorkgroupClient *client) noexcept
	Off-RT AU resource teardown.
std::vector< DescriptorIssue >	validate_descriptor (const PluginDescriptor &d)
	Run the validator.
bool	descriptor_is_valid (const std::vector< DescriptorIssue > &issues)
	True iff issues contains no Error severity entries.
constexpr DeviceQuotas	device_quotas (platform::DeviceCapabilityTier tier, platform::ThermalState thermal)
	Returns the quotas granted at one tier under one live thermal state.
bool	declares_editor_assets (const EditorAssets &assets) noexcept
	True when assets names a script, theme, or asset root, or embeds a script.
bool	embeds_editor_script (const EditorAssets &assets) noexcept
	True when assets carries an embedded entry script.
void	register_editor_assets (const EditorAssets &assets) noexcept
	Record this binary's editor assets. Static-init safe; last write wins.
EditorAssets	registered_editor_assets () noexcept
	The binary-wide record from register_editor_assets(), or an empty record.
EditorAssets	editor_assets_for (const char *plugin_id) noexcept
	Editor assets for the plug-in with reverse-DNS id plugin_id.
void	install_scripted_editor_builder () noexcept
	Link and install the scripted editor builder (see scripted_editor_builder_slot() in editor_ui.hpp).
void	reset_editor_assets_for_testing () noexcept
	Test-only: clear the binary-wide record. NOT for production use.
std::function< void()>	make_editor_idle_pump (ViewBridge &bridge)
	Build the per-vsync idle pump for a bridge.
std::function< void()>	make_scripted_idle_pump (ViewBridge &bridge)
	Compatibility spelling retained for downstream adapter code.
	__attribute__ ((visibility("hidden"))) void install_plugin_editor_factory_hook(EditorFactoryHook hook) noexcept
	Install this image's editor-factory hook.
void	set_editor_prewarm_scheduler (EditorPrewarmScheduler scheduler) noexcept
	Installed by the view layer. Passing nullptr uninstalls (tests).
bool	request_editor_prewarm (const Processor &processor)
	Called by format adapters once a host has instantiated processor.
view::ValueChannelAccess	processor_value_channel_access (Processor &processor, runtime::AliveToken::Handle owner_alive)
	Build the UI-thread accessor used by scripted editors.
std::optional< std::filesystem::path >	configured_ui_script_path (const EditorAssets &assets)
	The on-disk scripted-UI entry file assets declares, if any.
std::optional< std::filesystem::path >	configured_ui_theme_path (const EditorAssets &assets)
	The on-disk theme / design-token file assets declares, if any.
std::vector< std::filesystem::path >	configured_ui_asset_roots (const EditorAssets &assets)
	The asset directories assets declares, split on '|'.
std::optional< std::filesystem::path >	configured_ui_script_path ()
	This binary's on-disk scripted-UI entry file (see register_editor_assets()).
std::optional< std::filesystem::path >	configured_ui_theme_path ()
	This binary's on-disk theme / design-token file.
std::vector< std::filesystem::path >	configured_ui_asset_roots ()
	This binary's asset directories.
std::vector< view::WidgetBridge::EmbeddedAsset >	embedded_ui_assets (const EditorAssets &assets)
	The files embedded beside assets' script, as the bridge consumes them.
EditorUiSource	select_editor_ui_source (const EditorAssets &assets, bool enable_hot_reload)
	Pick the document for a default scripted editor from the record the plug-in registered.
std::atomic< ScriptedEditorBuilder > &	scripted_editor_builder_slot () noexcept
	The scripted editor builder this binary links, or null.
EditorUiInstance	build_editor_ui_for_assets (const EditorAssets &assets, state::StateStore &store, bool enable_hot_reload, std::string *error, view::ValueChannelAccess value_channel_access, std::string_view storage_identity={})
	Build the editor assets declares: a scripted UI when it names or embeds a script and the binary links the scripted editor builder, AutoUi otherwise (or when the script fails to load).
EditorUiInstance	build_editor_ui_with_value_channel_access (state::StateStore &store, bool enable_hot_reload, std::string *error, view::ValueChannelAccess value_channel_access)
	The editor this binary declares (see register_editor_assets()).
EditorUiInstance	build_editor_ui (state::StateStore &store, bool enable_hot_reload, std::string *error=nullptr, view::ValueChannelSet *value_channels=nullptr)
	Compatibility entry point for stable processors and callers without a processor.
std::filesystem::path	factory_presets_dir_for_module (const std::filesystem::path &module)
	Map a plug-in module's path to the folder holding its factory presets.
std::filesystem::path	loaded_module_factory_presets_dir ()
	factory_presets_dir_for_module applied to the image this code is linked into.
constexpr GenerationRoute	generation_route (platform::DeviceCapabilityTier tier, platform::ThermalState thermal, GenerationJobClass job, GenerationHostContext context, GenerationConnectivity connectivity) noexcept
	Returns where job runs on a device at tier and thermal, running as context with connectivity.
constexpr bool	runs_inference_on_device (GenerationJobClass job, GenerationRoute route) noexcept
	Returns whether route performs inference on this device.
bool	plugin_gpu_disabled_by_env ()
	Runtime opt-out: PULP_DISABLE_PLUGIN_GPU=1 forces the CoreGraphics CPU path.
GpuHostDecision	decide_gpu_host (const ViewBridge &bridge)
	Decide whether the GPU host should be requested for bridge, and emit the [plugin-gpu-host] debug-parity adapter log (mirrors [gpu-host]).
view::PluginViewHost::Options	editor_host_options (const ViewBridge &bridge, const GpuHostDecision &gpu, view::PluginViewHost::Size size)
	The editor-host options every format adapter builds its PluginViewHost from: the size the adapter negotiated, the GPU decision above, and the plug-in's own background (ViewBridge::editor_background_rgb()).
void	warn_if_unexpected_cpu_fallback (const GpuHostDecision &d, const view::PluginViewHost *host)
	Scream-guard (runtime): after the host's surface state is DECIDED, verify the GPU path actually took.
view::PluginViewHost::GpuSurfaceSubscription	bind_gpu_surface (view::PluginViewHost &host, view::ScriptedEditorSession *session, const GpuHostDecision &decision, const char *format_tag)
	Wire a host's GPU-surface lifecycle to a scripted UI session, for every format.
bool	in_non_editor_parameter_write () noexcept
	True when the calling thread is inside a host- or processor-originated parameter write, i.e.
void	apply_filter (HostQuirks &q, QuirkFilter filter)
	In-place: zero out (reset to default) every field in q whose meta tier is not allowed by filter.
HostQuirks	make_quirks_for (HostType type, HostVersion version)
	Build a HostQuirks populated for the given host + version.
HostQuirks	make_quirks_for_validated_only (HostType type, HostVersion version)
	Same as make_quirks_for(...) followed by apply_filter(..., kQuirkFilterValidatedOnly).
HostQuirks	detect_quirks ()
	Convenience: detect host + version, return the corresponding quirks.
ResolvedQuirkPolicy	resolve_quirk_policy ()
	Resolve the effective base tier-filter at runtime (does NOT apply per-quirk overrides — those layer on inside resolved_quirks).
void	set_host_quirk_policy (std::optional< QuirkFilter > filter)
	Programmatically set the base tier-filter (highest base-layer precedence, above the env var).
void	set_quirk_override (std::string_view flag, bool enabled)
	Force a single quirk flag on or off by its HostQuirks field name, overriding the tier filter for just that flag.
void	clear_quirk_overrides ()
	Clear all per-quirk overrides set via set_quirk_override.
std::vector< QuirkFieldStatus >	enumerate_quirk_fields (const HostQuirks &q)
	Enumerate every quirk field of q with its tier and whether it is currently enforced, in HostQuirks declaration order.
HostQuirks	resolved_quirks (HostType type, HostVersion version)
	The single entry adapters consume: build the host's quirks, apply the runtime base filter (resolve_quirk_policy), then layer per-quirk overrides.
constexpr int	reported_latency_samples (int raw, const HostQuirks &q) noexcept
	Apply clamp_latency_to_nonneg to a raw Processor::latency_samples() value before reporting it to the host.
HostType	detect_host_type ()
	Detect the current plugin host from the running process.
HostType	host_type_from_process_name (std::string_view process_name)
	Classify a host from an executable path or process name.
HostType	host_type_from_auv3_wrapper (std::string_view wrapper_identifier)
	Classify the AU v3 wrapper-reported host identifier (row 22).
std::string	current_auv3_wrapper_identifier ()
	Apple-only: query the AU v3 wrapper-reported host identifier from NSProcessInfo and any environment variables Apple's host services set.
std::string	host_type_name (HostType type)
	Get a human-readable name for the host type.
bool	host_supports_resize (HostType type)
	Whether the host supports specific features (heuristic).
bool	host_supports_sidechain (HostType type)
std::optional< HostVersion >	parse_host_version (std::string_view version_string)
	Best-effort parse of a version string like "10.0.50", "12.0", or "Pro Tools 2024.6".
HostVersion	detect_host_version (HostType type)
	Detect the running host's major/minor version, best-effort.
bool	host_type_uses_version (HostType type) noexcept
	Whether any host quirk for type is version-gated.
HostInfo	detect_host_info ()
void	set_ios_audio_session_listener (IosAudioSessionListener listener)
	Subscribe to session events.
bool	emit_ios_audio_session_event (const PulpIosAudioSessionEvent &event)
	Emit a session event (usually from Swift).
std::string_view	to_string (PulpIosAudioEvent event)
	Human-readable label for an event type (for logs and tests).
constexpr int	clamp_block_to_prepared_max (int requested, int prepared_max) noexcept
	Clamp a requested per-block frame count to the prepared maximum.
template<typename Fn>
void	for_each_midi_subblock (audio::BufferView< float > &output, const audio::BufferView< const float > &input, const midi::MidiBuffer &midi, Fn &&fn)
	Split a process block at MIDI-event boundaries.
const char *	offline_sample_bounce_status_name (OfflineSampleBounceStatus status) noexcept
template<typename Proc>
PanicOutcome	service_panic (Proc &processor, PanicState &state, midi::MidiBuffer &midi_out, std::int32_t sample_offset=0) noexcept
	Service a pending panic request (audio thread, before process()).
template<typename Fn>
void	for_each_subblock (audio::BufferView< float > &output, const audio::BufferView< const float > &input, const state::ParameterEventQueue *events, state::ParamCursor &params, Fn &&fn)
template<typename Fn>
void	for_each_subblock (audio::BufferView< float > &output, const audio::BufferView< const float > &input, const state::StateStore &store, const state::ParameterEventQueue *events, std::span< const state::ParamSnapshotEntry > initial_values, Fn &&fn)
template<typename Fn>
void	for_each_subblock (audio::BufferView< float > &output, const audio::BufferView< const float > &input, const state::StateStore &store, const state::ParameterEventQueue *events, Fn &&fn)
std::string	format_parameter_text (const state::ParamInfo &info, float plain_value)
	Canonical plain-value formatting shared by format adapters and framework UI.
std::optional< float >	parse_parameter_text (const state::ParamInfo &info, std::string_view text)
	Parse host text into a constrained plain value.
ProcessContext	project_process_context (const playback::TransportSnapshot &snapshot, const playback::TransportRange &range, const PlaybackContextProjectionOptions &options={}) noexcept
	Lossy, one-way adapter from the integer-authoritative playback snapshot to the public format ABI.
constexpr uint32_t	design_viewport_width (const ViewSize &hints)
constexpr uint32_t	design_viewport_height (const ViewSize &hints)
constexpr ViewSize	view_size_from_design (uint32_t preferred_width, uint32_t preferred_height, uint32_t min_width=0, uint32_t min_height=0, uint32_t max_width=0, uint32_t max_height=0)
	Build a ViewSize from a design-import preferred size with sensible derived bounds.
constexpr bool	should_pin_design_viewport (const ViewSize &hints)
	Editor-host resize contract shared by the format adapters (VST3 PulpPlugView, the AU v2 Cocoa view; mac AUv3 pins unconditionally and predates the free-resize case).
constexpr bool	should_lock_view_aspect (const ViewSize &hints)
	Aspect locking and viewport pinning are deliberately separate.
constexpr double	native_view_aspect_ratio (const ViewSize &hints)
	Resolve the native host constraint while preserving the legacy fixed-editor contract.
template<typename NativeHost>
void	configure_native_viewport (NativeHost &host, const ViewSize &hints)
	Apply the declared viewport policy to a newly-created native host.
template<typename NativeHost>
void	commit_editor_requested_viewport (NativeHost &host, const ViewSize &hints, uint32_t width, uint32_t height)
	Commit viewport state after an editor-initiated host resize succeeds.
PrepareResourceLimit	first_exceeded_prepare_resource_limit (const PrepareResourceUsage &usage, const PrepareResourceLimits &limits) noexcept
bool	process_processor_block (Processor &processor, ProcessBlock &block, ProcessorBlockAdapterScratch &scratch) noexcept
	Invoke the legacy Processor::process() API from a ProcessBlock.
constexpr ProjectionResult	projection_capability (ProjectionSurface surface, bool baked_processor, bool bounded_descriptor) noexcept
	Return the bounded DSPX-07 projection decision for one target surface.
PulpsetRender	render (HeadlessHost &host, const Pulpset &ps, std::size_t total_samples, std::size_t block_size=512)
	Replay ps over host for total_samples, in block_size blocks.
double	segment_rms (const std::vector< float > &v, std::size_t a, std::size_t b)
	RMS of [a,b) of one channel — for range/property assertions.
bool	write_wav_f32 (const std::string &path, const PulpsetRender &r, std::uint32_t sample_rate=48000)
	Write 32-bit float stereo WAV (offline render artifact).
bool	maybe_synthesize_bypass (state::StateStore &store, const HostQuirks &q)
	synthesize_bypass_parameter: when the plugin declares no Bypass parameter and the quirk is enforced, inject an automatable boolean "Bypass" parameter into the StateStore so the host gets a bypass control.
ProcessorFactory &	registered_factory ()
void	register_plugin (ProcessorFactory factory)
void	register_plugin (const PluginRegistration &reg)
const PluginRegistration *	find_plugin (const char *id)
std::span< const PluginRegistration >	registered_plugins ()
void	reset_registry_for_testing ()
view::TabPanel *	enclosing_settings_chrome (view::View *from)
	The nearest TabPanel ancestor of from, or nullptr.
bool	standalone_settings_available (view::View *from)
	True when from is hosted in the standalone settings chrome (a TabPanel ancestor carrying the Settings tab alongside the editor).
void	open_standalone_settings (view::View *from)
	Switch the enclosing standalone chrome to its Settings tab (Audio/MIDI).
template<typename Sample>
void	silence_block (audio::BufferView< Sample > &out)
	Zero an output bus for a block the plug-in did not render.
template<typename Sample>
void	passthrough_block (audio::BufferView< Sample > &out, const audio::BufferView< const Sample > &in)
	Copy input to output for a block the plug-in did not render.
const char *	to_string (ValidationStatus s)
	Convert status to its JSON string representation.
bool	dev_editor_hot_reload_enabled ()
	Whether a DAW-hosted editor should enable scripted-UI + theme hot reload (item 1.3).
bool	editor_content_first_open_enabled ()
	Whether a DAW-hosted editor opens content-first (the default) or view-first.
std::uint32_t	resolve_editor_background (const Processor &processor, const view::View *root) noexcept
	Manages editor-view lifecycle for a single Processor across all plugin formats.

Variables
constexpr const char *	kAppUpdatesGetMessage = "pulp_updates_get"
constexpr const char *	kAppUpdatesCheckMessage = "pulp_updates_check"
constexpr const char *	kAppUpdatesSetAutomaticMessage = "pulp_updates_set_automatic"
constexpr const char *	kAppUpdatesOpenReleasesMessage = "pulp_updates_open_releases"
constexpr const char *	kClapAraFactoryExtension = "com.celemony.ara/clap-factory-v1"
	Well-known extension id for the CLAP-ARA companion factory.
constexpr const char *	kVst3AraFactoryContextKey = "com.celemony.ara/vst3-host-factory-v1"
	VST3 — IPluginFactory3::setHostContext attribute key under which ARA-aware hosts (Cubase, Studio One) advertise their ARA factory pointer.
constexpr const char *	kAuAraFactoryPropertyKey = "audioUnitARAFactory"
	AU v3 — AUAudioUnit.audioUnitARAFactory property key.
constexpr std::size_t	kGenerationJobClassCount = 3
constexpr std::size_t	kGenerationRouteCount = 3
constexpr std::size_t	kGenerationHostContextCount = 2
constexpr std::size_t	kGenerationConnectivityCount = 2
constexpr HostQuirksMeta	kHostQuirksMeta {}
	Authoritative meta for the in-tree HostQuirks.
constexpr QuirkFilter	kQuirkFilterValidatedOnly
	Filter constant: keep only Validated tier accommodations.
constexpr QuirkFilter	kQuirkFilterOff
	Filter constant: drop every accommodation (including cheap defenses).
constexpr state::ParamID	kSynthesizedBypassParamId = 0x70427970
	Reserved ParamID for the synthesized Bypass parameter.

Detailed Description

What the product grants a device: the quota table indexed by capability tier and live thermal state.

A bounded spectral-frame stage chain hosted as one in-process graph node.

Where a generation job runs, as a pure function of what the device can carry.

This is policy, and it lives above the engine on purpose. The tier and thermal ladders it indexes are platform observations and live in pulp/platform/device_capability.hpp, which is named in every row of the engine's declared dependency floors — so nothing placed there can be objected to by any floor row. A budget over voices, render-graph nodes, editing surfaces, and preview fidelity is exactly the kind of thing those rows exist to keep out of the modules below: core/format appears in no floor row, so an engine module that reaches for this header is rejected.

The direction of consumption is the reason that costs nothing. Every enforcement point this table names already takes its ceilings as injected configuration rather than looking a table up — playback::AudioRendererLimits, playback::AutomationPlaybackLimits, timeline::SessionLimits, graph::GraphRuntimeLimits, format::PrepareResourceLimits. The consumer of the table is therefore whoever constructs those, which is the shell, not the module being bounded. No engine module needs to see this, and none should.

pulp/platform/device_capability.hpp says what the machine is — one tier ladder, one thermal ladder. pulp/format/device_quotas.hpp says how much the product grants at a rung. This header answers the remaining question: for a job the product wants done, where does it run. Same address as the quota table and for the same reason — this is policy, and policy does not belong in the vocabulary header every module can reach.

Like the quota table, the policy is written out cell by cell rather than derived from a scaling rule, so it is reviewable as data and so its invariants are assertions about these cells rather than restatements of a formula that generated them.

This header is constexpr and dependency-free beyond the capability vocabulary. It selects a destination; it never performs, schedules, or bills for the work, and it holds no notion of a model, a server, or a queue beyond naming which of the three a job is sent to.

The graph routes its ordinary audio ports; this adapter owns the STFT/WOLA boundary and invokes typed stages once per coherent channel-group frame.

Typedef Documentation

EditorFactoryHook

using pulp::format::EditorFactoryHook = EditorFactory* (*)()

Returns the editor factory of the UI package a plug-in binary declares.

EditorPrewarmScheduler

using pulp::format::EditorPrewarmScheduler = void (*)(const Processor::EditorPrewarm&)

GraphRuntimeCommandApplyFn

using pulp::format::GraphRuntimeCommandApplyFn

Initial value:

 GraphRuntimeCommandStatus (*)(
    ProcessBlock& block,
    const graph::GraphRuntimePlan& plan,
    const graph::GraphTimedCommand& command,
    void* user_data) noexcept

GraphRuntimeNodeProcessFn

using pulp::format::GraphRuntimeNodeProcessFn

Initial value:

 bool (*)(
    ProcessBlock& block,
    const GraphRuntimeNodeProcessContext& context,
    void* user_data) noexcept

IosAudioSessionListener

using pulp::format::IosAudioSessionListener

Initial value:

 
    std::function<void(const PulpIosAudioSessionEvent&)>

Typed callback — C++ side of the AVAudioSession bridge.

ParamCursor

using pulp::format::ParamCursor = state::ParamCursor

ParamSnapshotEntry

using pulp::format::ParamSnapshotEntry = state::ParamSnapshotEntry

ProcessBuffers

using pulp::format::ProcessBuffers = ProcessBuffersT<float>

ProcessBuffers64

using pulp::format::ProcessBuffers64 = ProcessBuffersT<double>

ProcessorFactory

using pulp::format::ProcessorFactory = std::unique_ptr<Processor>(*)()

Factory function type — plugins provide this to create processor instances.

ScriptedEditorBuilder

using pulp::format::ScriptedEditorBuilder

Initial value:

 EditorUiInstance (*)(const EditorAssets& assets,
                                                   EditorUiSource source, state::StateStore& store,
                                                   bool enable_hot_reload, std::string* error,
                                                   view::ValueChannelAccess value_channel_access,
                                                   std::string_view storage_identity)

Builds the scripted editor from source, the document select_editor_ui_source() chose for assets (the caller has already checked it is available).

Returns an instance whose root is null when the script failed to load; the failure is already logged and copied into error.

StandaloneControlHostFactory

using pulp::format::StandaloneControlHostFactory = std::unique_ptr<StandaloneControlHost> (*)()

Enumeration Type Documentation

AppUpdateInstaller

enum class pulp::format::AppUpdateInstaller : std::uint8_t

strong

How an update is installed, as the app declares it (pulp_add_sparkle INSTALLER).

Decides what the Settings note may truthfully say.

Enumerator
unknown	Not declared; the note says nothing about installing.
package	A signed .pkg: quits the app, asks for an admin password.
app_bundle	A replacement .app: quits and reopens the app.

AraRole

enum class pulp::format::AraRole

strong

ARA role capabilities.

Enumerator
None
PlaybackRenderer
EditorRenderer
EditorView

AudioRateModulationDelivery

enum class pulp::format::AudioRateModulationDelivery : std::uint8_t

strong

Enumerator
LegacyParameterEvents
DenseViews

BackgroundTaskPolicy

enum class pulp::format::BackgroundTaskPolicy

strong

Enumerator
Ordered
Latest

BusDirection

enum class pulp::format::BusDirection : std::uint8_t

strong

Enumerator
Input
Output

BusRole

enum class pulp::format::BusRole : std::uint8_t

strong

Semantic role of a declared audio bus.

This is static host metadata; it does not change when a user switches a product's source mode.

Enumerator
Main
Aux
Sidechain

DescriptorIssueSeverity

enum class pulp::format::DescriptorIssueSeverity

strong

Enumerator
Error	Invalid state — plugin will not load correctly.
Warning	Suspicious — plugin may behave unexpectedly.

EditorHostKind

enum class pulp::format::EditorHostKind : std::uint8_t

strong

Where a processor's editor lives, as far as the keyboard is concerned.

plugin: a DAW or other host owns the window and the keyboard. Plain keys are the host's (transport, Musical Typing, key commands); an editor should consume them only while its own focused field or open popup needs them.

standalone: the Pulp standalone app owns the window, so the editor may bind plain-key global shortcuts.

Enumerator
plugin
standalone

EditorKey

enum class pulp::format::EditorKey : std::uint16_t

strong

A non-character key.

Character keys arrive in EditorKeyEvent::character; Space arrives as both space and U' '. Values are stable; new keys are only ever appended.

Enumerator
none
space
enter
tab
backspace
escape
delete_forward
left
right
up
down
home
end
page_up
page_down

EditorKeyModifier

enum pulp::format::EditorKeyModifier : std::uint8_t

Modifier bits in EditorKeyEvent::modifiers.

Enumerator
editor_modifier_shift
editor_modifier_control
editor_modifier_alt	Option on macOS.
editor_modifier_command	Command on macOS, Windows key elsewhere.

EditorRole

enum class pulp::format::EditorRole : std::uint8_t

strong

The UI role an editor plays. A processor may offer several at once.

Enumerator
editor	the main plug-in or app editor
inspector	a secondary window over the same processor
settings	the processor's own settings content

FrameRate

enum class pulp::format::FrameRate

strong

SMPTE video frame rate.

Used by ProcessContext::frame_rate so plugins that drive video sync or display SMPTE timecode can format positions correctly. unknown is the documented sentinel for hosts that do not provide a frame rate (e.g. CLAP clap_event_transport has no frame-rate field; AU kAudioUnitProperty_HostCallbacks only exposes it inside HostCallback_GetTransportState2's outCurrentSampleInTimeLine indirectly via the project session — adapters report unknown if the host does not surface it).

Enumerator
unknown
fps_24	Film. VST3 kFrameRate24fps.
fps_25	PAL. VST3 kFrameRate25fps.
fps_29_97	NTSC non-drop. VST3 kFrameRate2997fps.
fps_29_97_drop	NTSC drop-frame. VST3 kFrameRate2997DropFps.
fps_30	NTSC integer. VST3 kFrameRate30fps.
fps_30_drop	30 drop-frame. VST3 kFrameRate30DropFps.
fps_60	High-rate. VST3 kFrameRate60fps.

GenerationConnectivity

enum class pulp::format::GenerationConnectivity : std::uint8_t

strong

Whether the device can reach a server right now.

Enumerator
Online
Offline

GenerationHostContext

enum class pulp::format::GenerationHostContext : std::uint8_t

strong

The surface the product is running as.

This is not a device property, which is why it is not on the tier ladder: the same phone is Standalone in the app and AudioUnitV3 inside a host. The distinction is load-bearing because an AUv3 runs inside someone else's process under a memory limit it does not control, so it never gets to spend that budget on inference.

Enumerator
Standalone	Pulp's own application process.
AudioUnitV3	An AUv3 extension hosted by another application.

GenerationJobClass

enum class pulp::format::GenerationJobClass : std::uint8_t

strong

A kind of generation work, distinguished by what it costs and what it needs.

Three classes rather than one job type, because the offline and thermal answers differ sharply between them: a proposal is expensive and deferrable, playing an artifact that already exists is neither, and rendering a receipt is cheap bookkeeping that must never be the thing that fails.

Enumerator
ProposalGeneration	Producing a new proposal. The expensive class, and the only one that would ever want on-device inference.
ArtifactPlayback	Playing an artifact that has already been materialized. No inference is involved; the work is decode and playback.
ReceiptRendering	Rendering a receipt for work already done. Cheap, local, and required even when everything else is degraded — a user must always be able to see what was produced on their behalf.

GenerationRoute

enum class pulp::format::GenerationRoute : std::uint8_t

strong

Where a job is sent.

Enumerator
OnDevice	Runs locally on this device.
Server	Sent to a server for execution now.
QueueForLater	Accepted and deferred; runs when connectivity or headroom returns.

GraphRuntimeCommandStatus

enum class pulp::format::GraphRuntimeCommandStatus : std::uint8_t

strong

Enumerator
Accepted
Rejected

GraphRuntimeExecutorErrorCode

enum class pulp::format::GraphRuntimeExecutorErrorCode : std::uint8_t

strong

Enumerator
None
InvalidProcessBlock
InvalidSnapshot
CommandScratchTooSmall
MissingRequiredProcessor
NodeProcessorFailed
BufferPoolTooSmall
NodePortLimitExceeded

HostAction

enum class pulp::format::HostAction : std::uint16_t

strong

Actions an editor can ask its host to take.

Values are stable; new actions are only ever appended.

Enumerator
mark_state_dirty	State outside the parameters changed (a loaded sample, an editor setting); the host should treat the project as modified.
parameter_context_menu	Show the host's context menu for parameter param at (x, y) in the editor's logical coordinates.
close_editor	Ask the host to close this editor's window.

HostType

enum class pulp::format::HostType

strong

Enumerator
Unknown
LogicPro
GarageBand
AbletonLive
Reaper
ProTools
Cubase
Nuendo
Wavelab
StudioOne
FLStudio
Bitwig
Maschine
AudacityTenacity
Ardour
Mixbus32C
DigitalPerformer
Standalone
Other

KeyDisposition

enum class pulp::format::KeyDisposition : std::uint8_t

strong

The editor's answer to an offered key.

Enumerator
forward	not the editor's: the host acts on it (Space → transport)
consumed	the editor handled it; the host must not act on it

NativeParentKind

enum class pulp::format::NativeParentKind : std::uint8_t

strong

The kind of native window handle an editor is attached to.

Values are stable; new kinds are only ever appended.

Enumerator
none	no window: an offscreen or headless editor
cocoa_view	macOS NSView* in handle
uikit_view	iOS UIView* in handle
win32_window	Windows HWND in handle.
x11_window	X11 Window id in window_id.

OfflineSampleBounceStatus

enum class pulp::format::OfflineSampleBounceStatus : std::uint8_t

strong

Enumerator
ok
render_failed
empty_render
invalid_sample_rate
channel_budget_exceeded
frame_budget_exceeded
byte_budget_exceeded
sample_rate_not_allowed
bank_unprepared
publish_failed

PanicMode

enum class pulp::format::PanicMode : std::uint8_t

strong

How hard a panic stops the plug-in.

Enumerator
immediate	Hard stop: voices are reset and release tails cut (MIDI CC 120 semantic). The default.
release	Release only: voices enter their normal release and tails ring out (MIDI CC 123 semantic).

PluginCategory

enum class pulp::format::PluginCategory

strong

Plugin category — determines bus layout expectations and DAW behavior.

Enumerator
Effect	Audio effect (takes input, produces output).
Instrument	Synth/sampler (receives MIDI, produces audio).
MidiEffect	MIDI processor (receives MIDI, produces MIDI).

PrepareResourceLimit

enum class pulp::format::PrepareResourceLimit

strong

Prepare context — passed once before processing starts.

Contains the host's audio configuration. Use this to allocate buffers, initialize filters at the correct sample rate, etc.

Enumerator
None
PersistentBytes
BlockScratchBytes
TotalBytes
BlockSize
InputChannels
OutputChannels
ParameterEvents
MidiEvents
Voices

PreviewQuality

enum class pulp::format::PreviewQuality : std::uint8_t

strong

How much work a preview render may do, ascending in cost.

Enumerator
Disabled	Previews are not rendered; consumers show authored geometry only.
Reduced	Decimated previews: coarser resolution, fewer passes.
Full	Full-detail previews.

ProcessMode

enum class pulp::format::ProcessMode : std::uint8_t

strong

Coarse processing mode for one block.

Realtime blocks run under the hard audio-thread contract. Offline blocks may be rendered faster or slower than wall clock, but still use bounded buffers and explicit event/scratch contracts.

Enumerator
Realtime
Offline

ProjectionStatus

enum class pulp::format::ProjectionStatus : std::uint8_t

strong

Enumerator
supported
unsupported

ProjectionSurface

enum class pulp::format::ProjectionSurface : std::uint8_t

strong

Product surfaces that can consume a baked Processor projection.

The enum is intentionally independent of adapter implementation types so an installed SDK consumer can make the same decision before selecting a plugin format or browser bridge.

Enumerator
clap
vst3
lv2
wam
wclap
au

QuirkPolicySource

enum class pulp::format::QuirkPolicySource : unsigned char

strong

Where the effective base tier-filter came from (for diagnostics — pulp doctor reports this).

Enumerator
CompileDefault	PULP_HOST_QUIRKS_DEFAULT_POLICY build option.
Environment	PULP_HOST_QUIRKS environment variable.
Api	set_host_quirk_policy().

QuirkStatus

enum class pulp::format::QuirkStatus : unsigned char

strong

Validation tier for an individual host-quirk flag. See file header.

Enumerator
Validated	Exercised by a Pulp regression test under the named DAW.
Speculative	Implemented per docs + reproducer; not yet bench-confirmed.
LessonOnly	Catalog entry only; no Pulp fix wired (kept for record).

RenderSpeedHint

enum class pulp::format::RenderSpeedHint

strong

Host render-speed hint for offline or constrained live rendering.

This is advisory. Processors must still obey the thread contract implied by ProcessContext::process_mode; for example, a realtime block with SlowerThanRealtime is still an audio-thread callback.

Enumerator
Unknown
Realtime
FasterThanRealtime
SlowerThanRealtime

SpectralFrameError

enum class pulp::format::SpectralFrameError : std::uint8_t

strong

Enumerator
None
InvalidGeometry
InvalidBlock
InvalidFrame
StageFailure
NonFiniteFrame
SequenceOverflow

StandaloneControlUiMode

enum class pulp::format::StandaloneControlUiMode

strong

Enumerator
Headless
DeferToEditor

TestSignalType

enum class pulp::format::TestSignalType

strong

Enumerator
none
sine
file
noise

TransportField

enum class pulp::format::TransportField : std::uint8_t

strong

Independently optional fields in a per-block host transport snapshot.

Enumerator
Playing
Recording
Looping
Tempo
BeatPosition
SamplePosition
TimeSignature
LoopRange
Bar
HostTime
FrameRate
Count

TransportQuantizePolicy

enum class pulp::format::TransportQuantizePolicy : std::uint8_t

strong

Enumerator
Immediate
NextBeat
NextBar
NextGrid
HostLoopStart

TransportQuantizeStatus

enum class pulp::format::TransportQuantizeStatus : std::uint8_t

strong

Enumerator
Scheduled
OutsideBlock
TransportStopped
InvalidBlockSize
InvalidSampleRate
InvalidTempo
InvalidTimeSignature
InvalidGrid
InvalidTimeline
LoopUnavailable
TransportJumped

ValidationStatus

enum class pulp::format::ValidationStatus

strong

Result status for individual validation steps.

Enumerator
pass
fail
skip
error

ViewportPolicy

enum class pulp::format::ViewportPolicy : uint8_t

strong

Controls whether a host paints an editor through a fixed authored coordinate space or lets the root lay itself out at the live host size.

Automatic preserves the historical behavior for existing plug-ins.

Enumerator
Automatic
FixedDesign
Responsive

ViewRole

enum class pulp::format::ViewRole

strong

Role of a view attached to a ViewBridge.

The primary editor is Editor; auxiliary inspector panels attach as secondary views with the Inspector role.

Enumerator
Editor
Inspector

VisualChannelShape

enum class pulp::format::VisualChannelShape : std::uint8_t

strong

The shape of one visual channel.

Enumerator
scalar	one number per publish (gain reduction, an envelope level)
meter	per-channel RMS and peak levels
vector	a block of samples for a scope-style display
events	a bounded list of occurrences from one audio block

Function Documentation

__attribute__()

pulp::format::__attribute__ ( (visibility("hidden")) )

noexcept

Install this image's editor-factory hook.

The editor factory the installed hook returns, or null when this image installed none.

The source that pulp_add_plugin(... UI <package>) generates calls this at static init. Static-init safe; a later call replaces the hook, and null clears it.

add_app_update_handlers()

void pulp::format::add_app_update_handlers

(

view::EditorBridge &

bridge

)

app_update_last_check_text()

std::string pulp::format::app_update_last_check_text ( const AppUpdateStatus & status )

nodiscard

"Last checked: never" or "Last checked: 2026-10-04 14:03" (local time).

app_update_note()

std::string pulp::format::app_update_note ( const AppUpdateStatus & status )

nodiscard

The explanatory note shown under the Settings controls, built only from facts in status, so it stays true for each app.

Empty when unavailable. e.g. "Updates download from Spectr's GitHub releases. Installing an update quits and reopens Spectr, briefly stopping its audio, and asks for an administrator password. Updates are never installed automatically."

app_update_service()

std::shared_ptr< AppUpdateService > pulp::format::app_update_service ( )

nodiscard

app_update_status()

AppUpdateStatus pulp::format::app_update_status ( )

nodiscard

Convenience wrappers over the installed service.

With none installed: status().available is false and the two actions return false.

app_update_status_json()

std::string pulp::format::app_update_status_json ( const AppUpdateStatus & status )

nodiscard

The status as a JSON object, the shape the JS bridge returns: {available, canCheckNow, automaticChecks, automaticInstall, stub, appName, version, build, lastCheckUnixSeconds, releasesUrl, feedHost, installer: "package"|"app"|"unknown", note, versionText, lastCheckText}.

app_update_version_text()

std::string pulp::format::app_update_version_text ( const AppUpdateStatus & status )

nodiscard

"Version 1.0.7 (1.0.7.2)" – the build is shown only when it differs.

apply_filter()

void pulp::format::apply_filter	(	HostQuirks &	q,
		QuirkFilter	filter )

In-place: zero out (reset to default) every field in q whose meta tier is not allowed by filter.

Numeric fields are reset to their default-constructed value (logic_au_channel_probe_cap → 64). Cheap defenses are not special-cased here — when their Validated tier is filtered out, they too are reset.

Idempotent + safe to call multiple times.

ara_companion_factory_for()

const void * pulp::format::ara_companion_factory_for

(

class AraDocumentController *

controller

)

Return an opaque pointer to an ARA::ARAFactory-compatible struct when the processor is ARA-aware and Pulp was built with PULP_HAS_ARA, otherwise nullptr.

Called by format-adapter get_extension handlers. The returned pointer is owned by Pulp and lives as long as the processor. void* at the public boundary so non-ARA TUs do not need to pull ARA_API/ARAInterface.h.

ara_sdk_compiled_in()

bool pulp::format::ara_sdk_compiled_in

(

)

True when Pulp was built with the Celemony ARA SDK (PULP_ENABLE_ARA=ON.

• PULP_ARA_SDK_DIR pointing at a valid checkout). Separate from host_supports_ara(): SDK-compiled-in is a build-time fact; host support is resolved at load time per format adapter.

ara_sdk_generation()

int pulp::format::ara_sdk_generation

(

)

Highest ARA API generation Pulp was compiled against.

Returns 0 when PULP_HAS_ARA is not set. When non-zero, the value matches the ARA SDK's kARAAPIGeneration_* enum — e.g. 6 for 2_3_Final. Callers gate feature use by comparing to a known constant.

bind_audio_device_workgroup()

void pulp::format::bind_audio_device_workgroup ( AudioWorkgroupClient & client, audio::AudioDevice * device )

inline

Production device-to-renderer handoff shared by standalone and timeline hosts.

The device owns the borrowed handle.

bind_gpu_surface()

view::PluginViewHost::GpuSurfaceSubscription pulp::format::bind_gpu_surface ( view::PluginViewHost & host, view::ScriptedEditorSession * session, const GpuHostDecision & decision, const char * format_tag )

inlinenodiscard

Wire a host's GPU-surface lifecycle to a scripted UI session, for every format.

This is the one call an adapter needs after building its host. It replaces the scripted->attach_gpu_surface(host->gpu_surface()) one-shot read that each format did independently — a read that is only correct on hosts which build their surface in the constructor. On Windows it always returned null, so navigator.gpu fell through to mocks and JS-rendered 3D was black in every DAW.

Also owns the CPU-fallback diagnostic, so it fires exactly once, when the host's surface state is actually decided, rather than on a pre-attach null.

The returned subscription must be dropped before session is destroyed — adapters keep it next to their host and reset it in their close/removed path. Dropping it is enough: no callback can fire afterwards.

build_editor_ui()

EditorUiInstance pulp::format::build_editor_ui ( state::StateStore & store, bool enable_hot_reload, std::string * error = nullptr, view::ValueChannelSet * value_channels = nullptr )

inline

Compatibility entry point for stable processors and callers without a processor.

Reloadable processors use build_editor_ui_with_value_channel_access().

build_editor_ui_for_assets()

EditorUiInstance pulp::format::build_editor_ui_for_assets ( const EditorAssets & assets, state::StateStore & store, bool enable_hot_reload, std::string * error, view::ValueChannelAccess value_channel_access, std::string_view storage_identity = {} )

inline

Build the editor assets declares: a scripted UI when it names or embeds a script and the binary links the scripted editor builder, AutoUi otherwise (or when the script fails to load).

value_channel_access leases the hosting processor's current named value channels while scripted UI code resolves and snapshots them. storage_identity names the plug-in (its bundle id) so an embedded editor, which has no script directory to be keyed by, keeps stable persisted stores.

build_editor_ui_with_value_channel_access()

EditorUiInstance pulp::format::build_editor_ui_with_value_channel_access ( state::StateStore & store, bool enable_hot_reload, std::string * error, view::ValueChannelAccess value_channel_access )

inline

The editor this binary declares (see register_editor_assets()).

check_for_app_updates()

bool pulp::format::check_for_app_updates

(

)

clamp_block_to_prepared_max()

int pulp::format::clamp_block_to_prepared_max ( int requested, int prepared_max )

constexprnoexcept

Clamp a requested per-block frame count to the prepared maximum.

Returns requested unchanged when it fits within prepared_max (the overwhelmingly common path), or when prepared_max is unset (<= 0, i.e. "unbounded" — the adapter never established a max). Otherwise returns prepared_max, and the caller must zero-fill the tail [prepared_max, requested) on every main output channel.

Pure + constexpr so the contract is unit-tested directly, without standing up an adapter or a host SDK.

clear_audio_workgroup_after_render_resources()

void pulp::format::clear_audio_workgroup_after_render_resources ( AudioWorkgroupClient * client )

inlinenoexcept

Off-RT AU resource teardown.

Publish explicit render-context removal and wait until every auxiliary worker has left the host-owned workgroup before Processor::release() tears down the render graph.

clear_quirk_overrides()

void pulp::format::clear_quirk_overrides

(

)

Clear all per-quirk overrides set via set_quirk_override.

close_audio_device_after_workgroup_release()

void pulp::format::close_audio_device_after_workgroup_release ( AudioWorkgroupClient * client, audio::AudioDevice & device )

inlinenoexcept

Stop-time ownership barrier: release the device-owned handle on every worker before close() can invalidate it.

The device callback must already be stopped; this helper is intentionally allowed to block.

commit_editor_requested_viewport()

template<typename NativeHost>

void pulp::format::commit_editor_requested_viewport	(	NativeHost &	host,
		const ViewSize &	hints,
		uint32_t	width,
		uint32_t	height )

Commit viewport state after an editor-initiated host resize succeeds.

An completely authored viewport keeps its coordinate space so the native host scales rather than reflows it. A legacy or partially authored pinned editor adopts the requested coordinate space rather than mixing coordinate systems. A responsive editor changes only its host aspect and continues laying out at live host bounds.

configure_native_viewport()

template<typename NativeHost>

void pulp::format::configure_native_viewport	(	NativeHost &	host,
		const ViewSize &	hints )

Apply the declared viewport policy to a newly-created native host.

Keeping this decision here prevents format adapters from accidentally coupling responsive layout to aspect locking.

configured_ui_asset_roots() [1/2]

std::vector< std::filesystem::path > pulp::format::configured_ui_asset_roots ( )

inline

This binary's asset directories.

configured_ui_asset_roots() [2/2]

std::vector< std::filesystem::path > pulp::format::configured_ui_asset_roots ( const EditorAssets & assets )

inline

The asset directories assets declares, split on '|'.

configured_ui_script_path() [1/2]

std::optional< std::filesystem::path > pulp::format::configured_ui_script_path ( )

inline

This binary's on-disk scripted-UI entry file (see register_editor_assets()).

configured_ui_script_path() [2/2]

std::optional< std::filesystem::path > pulp::format::configured_ui_script_path ( const EditorAssets & assets )

inline

The on-disk scripted-UI entry file assets declares, if any.

Only a dev build (PULP_DEV_BUILD) records one; see select_editor_ui_source().

configured_ui_theme_path() [1/2]

std::optional< std::filesystem::path > pulp::format::configured_ui_theme_path ( )

inline

This binary's on-disk theme / design-token file.

configured_ui_theme_path() [2/2]

std::optional< std::filesystem::path > pulp::format::configured_ui_theme_path ( const EditorAssets & assets )

inline

The on-disk theme / design-token file assets declares, if any.

current_auv3_wrapper_identifier()

std::string pulp::format::current_auv3_wrapper_identifier

(

)

Apple-only: query the AU v3 wrapper-reported host identifier from NSProcessInfo and any environment variables Apple's host services set.

Returns an empty string on non-Apple platforms or when no wrapper context is detected. Exposed for tests + detect_host_type.

decide_gpu_host()

GpuHostDecision pulp::format::decide_gpu_host ( const ViewBridge & bridge )

inline

Decide whether the GPU host should be requested for bridge, and emit the [plugin-gpu-host] debug-parity adapter log (mirrors [gpu-host]).

GPU is wanted when the editor renders through the Skia/Dawn pipeline:

• the framework scripted-UI path (the plug-in's UI_SCRIPT), detected via ViewBridge::uses_script_ui(), or
• a custom Processor::create_view() whose view set View::set_requires_gpu_host(true) (e.g. ChainerSynth).

declares_editor_assets()

bool pulp::format::declares_editor_assets ( const EditorAssets & assets )

noexcept

True when assets names a script, theme, or asset root, or embeds a script.

descriptor_is_valid()

bool pulp::format::descriptor_is_valid

(

const std::vector< DescriptorIssue > &

issues

)

True iff issues contains no Error severity entries.

Warnings are informational only. Callers gating on "may the plugin load" use this helper.

design_viewport_height()

uint32_t pulp::format::design_viewport_height ( const ViewSize & hints )

constexpr

design_viewport_width()

uint32_t pulp::format::design_viewport_width ( const ViewSize & hints )

constexpr

detect_host_info()

HostInfo pulp::format::detect_host_info

(

)

detect_host_type()

HostType pulp::format::detect_host_type

(

)

Detect the current plugin host from the running process.

Call once during plugin initialization and cache the result.

On Apple platforms this prefers the AU v3 wrapper-reported host identifier (see host_type_from_auv3_wrapper) before falling back to the executable-path heuristic — AU v3 plug-ins live in a sandboxed .appex whose own process name is the wrapper service, not the host. DAW-quirks row 22 (item 5.11 / 3.1).

detect_host_version()

HostVersion pulp::format::detect_host_version

(

HostType

type

)

Detect the running host's major/minor version, best-effort.

On macOS, attempts to read the host process's Info.plist (CFBundleShortVersionString). On Windows / Linux, attempts the platform's version-resource / --version introspection. Returns an empty (zero-valued) HostVersion when detection fails — callers should treat that as "unknown" and avoid version-gated quirks.

detect_quirks()

HostQuirks pulp::format::detect_quirks

(

)

Convenience: detect host + version, return the corresponding quirks.

Applies the default policy chosen at build time (CMake option PULP_HOST_QUIRKS_DEFAULT_POLICY):

• all (default) — every detected quirk fires regardless of tier.
• validated_only — only Validated accommodations fire.
• off — no accommodations fire (returns a filtered-empty struct).

Plugin authors can still override at runtime by ignoring this helper and constructing their own HostQuirks via make_quirks_for(...) + apply_filter(...).

This routes through resolved_quirks(...), so the runtime policy (env / API / per-quirk override) applies here too. With no runtime override set, the effective filter is the compile-time default.

dev_editor_hot_reload_enabled()

bool pulp::format::dev_editor_hot_reload_enabled ( )

inline

Whether a DAW-hosted editor should enable scripted-UI + theme hot reload (item 1.3).

OFF by default — a shipping plugin must not watch and reload from disk inside a host — but a developer opts in for the edit→see-it loop by exporting PULP_DEV_HOT_RELOAD=1 in the DAW's environment. (The standalone app always enables it; it IS the dev tool.) Polling already runs on every editor tick, so this only decides whether the watcher acts. Kept header-inline so the platform view controllers (au_view_controller_*.mm, au_v2_cocoa_view.mm) share one definition.

device_quotas()

DeviceQuotas pulp::format::device_quotas ( platform::DeviceCapabilityTier tier, platform::ThermalState thermal )

nodiscardconstexpr

Returns the quotas granted at one tier under one live thermal state.

A value cast in from outside the declared enumerators clamps to the most restrictive cell rather than reading past the table: a quota lookup that cannot be trusted should grant the least, not the most.

editor_assets_for()

EditorAssets pulp::format::editor_assets_for ( const char * plugin_id )

noexcept

Editor assets for the plug-in with reverse-DNS id plugin_id.

A keyed bundle registration (PluginRegistration::ui_*) that declares any asset wins, so each plug-in in a multi-plug-in bundle can carry its own editor; otherwise the binary-wide record applies. A null id selects the binary-wide record.

editor_content_first_open_enabled()

bool pulp::format::editor_content_first_open_enabled ( )

inline

Whether a DAW-hosted editor opens content-first (the default) or view-first.

PULP_EDITOR_OPEN=view-first in the host's environment selects view-first, for an A/B of the two or a host that must not block in its view-creation call. Read once per editor open.

editor_host_options()

view::PluginViewHost::Options pulp::format::editor_host_options ( const ViewBridge & bridge, const GpuHostDecision & gpu, view::PluginViewHost::Size size )

inline

The editor-host options every format adapter builds its PluginViewHost from: the size the adapter negotiated, the GPU decision above, and the plug-in's own background (ViewBridge::editor_background_rgb()).

One definition so a new host option reaches every format at once. The background is the case that motivated it: a host that skipped it would open that format's editor on the framework default colour while the others opened on the plug-in's own.

embedded_ui_assets()

std::vector< view::WidgetBridge::EmbeddedAsset > pulp::format::embedded_ui_assets ( const EditorAssets & assets )

inline

The files embedded beside assets' script, as the bridge consumes them.

embeds_editor_script()

bool pulp::format::embeds_editor_script ( const EditorAssets & assets )

noexcept

True when assets carries an embedded entry script.

emit_ios_audio_session_event()

bool pulp::format::emit_ios_audio_session_event

(

const PulpIosAudioSessionEvent &

event

)

Emit a session event (usually from Swift).

Header-only so test harnesses can exercise the subscriber path without linking the real Swift target. Returns true if a subscriber was called.

enclosing_settings_chrome()

view::TabPanel * pulp::format::enclosing_settings_chrome ( view::View * from )

inline

The nearest TabPanel ancestor of from, or nullptr.

The standalone settings chrome is the only place a Pulp plugin editor is nested under a TabPanel, so this doubles as "am I in the settings chrome?".

enumerate_quirk_fields()

std::vector< QuirkFieldStatus > pulp::format::enumerate_quirk_fields

(

const HostQuirks &

q

)

Enumerate every quirk field of q with its tier and whether it is currently enforced, in HostQuirks declaration order.

Used by pulp doctor to render the host-quirks table.

factory_presets_dir_for_module()

std::filesystem::path pulp::format::factory_presets_dir_for_module

(

const std::filesystem::path &

module

)

Map a plug-in module's path to the folder holding its factory presets.

A bundled plug-in keeps them in <Bundle>/Contents/Resources/Presets, and its binary sits one or two levels below Contents (Contents/MacOS/Foo, Contents/x86_64-win/Foo.vst3, Contents/x86_64-linux/Foo.so). Returns an empty path for a module outside such a bundle, so discovery degrades to "no factory presets" instead of scanning an unrelated directory.

find_plugin()

const PluginRegistration * pulp::format::find_plugin

(

const char *

id

)

first_exceeded_prepare_resource_limit()

PrepareResourceLimit pulp::format::first_exceeded_prepare_resource_limit ( const PrepareResourceUsage & usage, const PrepareResourceLimits & limits )

inlinenoexcept

for_each_midi_subblock()

template<typename Fn>

void pulp::format::for_each_midi_subblock	(	audio::BufferView< float > &	output,
		const audio::BufferView< const float > &	input,
		const midi::MidiBuffer &	midi,
		Fn &&	fn )

Split a process block at MIDI-event boundaries.

The block output / input is divided into contiguous sub-blocks at the sample offsets carried by midi (which must already be sorted by sample_offset). For each sub-block fn is invoked with:

• an output BufferView slice covering the sub-block,
• the matching input BufferView slice,
• a std::span<const midi::MidiEvent> of the events whose offset coincides with the sub-block's leading sample.

Boundary semantics, matching the parameter helper:

• Events at or before sample 0 (offset <= 0) are grouped onto the first sub-block's leading boundary, so the callback can apply them before any audio is rendered.
• Events sharing a sample offset are grouped into a single boundary span; a coincident offset is not re-split into zero-length sub-blocks.
• Events at or past the block end (offset >= num_samples) are ignored; there is no audio left to render after them this block, so a host that time-stamps an event at the block boundary sees it next block. Clamping them into the final sub-block would reorder them relative to the audio, so ignoring is the safe choice.
• A zero-frame block invokes the callback zero times (nothing to render), mirroring for_each_subblock().
• An empty buffer (or one with only out-of-range events) invokes the callback exactly once with the full block and an empty event span.

The output/input slices and the event span handed to fn are borrowed views into the caller's buffers, valid only for the duration of that single callback invocation. Do not retain them past the call, and do not mutate midi while iterating.

for_each_subblock() [1/3]

template<typename Fn>

void pulp::format::for_each_subblock	(	audio::BufferView< float > &	output,
		const audio::BufferView< const float > &	input,
		const state::ParameterEventQueue *	events,
		state::ParamCursor &	params,
		Fn &&	fn )

for_each_subblock() [2/3]

template<typename Fn>

void pulp::format::for_each_subblock	(	audio::BufferView< float > &	output,
		const audio::BufferView< const float > &	input,
		const state::StateStore &	store,
		const state::ParameterEventQueue *	events,
		Fn &&	fn )

for_each_subblock() [3/3]

template<typename Fn>

void pulp::format::for_each_subblock	(	audio::BufferView< float > &	output,
		const audio::BufferView< const float > &	input,
		const state::StateStore &	store,
		const state::ParameterEventQueue *	events,
		std::span< const state::ParamSnapshotEntry >	initial_values,
		Fn &&	fn )

format_parameter_text()

std::string pulp::format::format_parameter_text ( const state::ParamInfo & info, float plain_value )

inline

Canonical plain-value formatting shared by format adapters and framework UI.

generation_route()

GenerationRoute pulp::format::generation_route ( platform::DeviceCapabilityTier tier, platform::ThermalState thermal, GenerationJobClass job, GenerationHostContext context, GenerationConnectivity connectivity )

nodiscardconstexprnoexcept

Returns where job runs on a device at tier and thermal, running as context with connectivity.

Total by construction: every combination has an answer, and the answer is never "fail". Offline does not error — it degrades, which is why an offline proposal is QueueForLater rather than a rejection, and why playback and receipts are unaffected by it.

host_supports_ara()

bool pulp::format::host_supports_ara

(

)

Check if the current host supports ARA.

Returns false if ARA is not available (most hosts).

host_supports_resize()

bool pulp::format::host_supports_resize

(

HostType

type

)

Whether the host supports specific features (heuristic).

host_supports_sidechain()

bool pulp::format::host_supports_sidechain

(

HostType

type

)

host_type_from_auv3_wrapper()

HostType pulp::format::host_type_from_auv3_wrapper

(

std::string_view

wrapper_identifier

)

Classify the AU v3 wrapper-reported host identifier (row 22).

AU v3 plug-ins run in a sandboxed extension; the host executable path is not visible in the bundle's address space. Apple's AUHostingService (and the older XPC wrappers Logic Pro / MainStage / GarageBand spawn) make the bundle identifier of the wrapping host available through [NSProcessInfo processInfo].processName (the wrapper executable name, prefixed with the host bundle id) or the auHostIdentifier user-info key on some wrappers. This helper normalizes any such identifier to a HostType.

The function is platform-independent so it can be unit-tested without having to run inside a real AU extension. The Apple-only detect_host_type() calls this with the wrapper-reported string before falling back to the executable-path heuristic.

Returns HostType::Unknown when the identifier is empty or does not match any known wrapper. Examples that resolve to known hosts: • "com.apple.logic10" → HostType::LogicPro • "com.apple.garageband10" → HostType::GarageBand • "com.apple.mainstage" → HostType::LogicPro (Logic/MainStage share the same Pro Audio quirk family) • "AUHostingServiceXPC_arrow" → HostType::LogicPro (Logic 10.5+ XPC wrapper service name) • "AUHostingService" → HostType::Unknown (generic — host identity needs to come from another channel; caller falls back) • "com.kymatica.AUM" → HostType::Unknown (iOS host; first known wrapper to graduate goes here when it does)

host_type_from_process_name()

HostType pulp::format::host_type_from_process_name

(

std::string_view

process_name

)

Classify a host from an executable path or process name.

host_type_name()

std::string pulp::format::host_type_name

(

HostType

type

)

Get a human-readable name for the host type.

host_type_uses_version()

bool pulp::format::host_type_uses_version ( HostType type )

noexcept

Whether any host quirk for type is version-gated.

Unknown, Other and the Pulp standalone have no version-dependent behavior, so their version is never read (on macOS that read can cost about a millisecond in a process whose main bundle has no Info.plist loaded yet).

in_non_editor_parameter_write()

bool pulp::format::in_non_editor_parameter_write ( )

inlinenoexcept

True when the calling thread is inside a host- or processor-originated parameter write, i.e.

when an edit bridge must stay silent.

install_scripted_editor_builder()

void pulp::format::install_scripted_editor_builder ( )

noexcept

Link and install the scripted editor builder (see scripted_editor_builder_slot() in editor_ui.hpp).

The generated source of a target that declares a UI script calls this at static init; a binary whose script comes only from a keyed bundle registration calls it itself. Defined in pulp-format-view, so only a binary that calls it links the script runtime. Static-init safe.

loaded_module_factory_presets_dir()

std::filesystem::path pulp::format::loaded_module_factory_presets_dir

(

)

factory_presets_dir_for_module applied to the image this code is linked into.

Empty when that image is not inside a bundle.

make_editor_idle_pump()

std::function< void()> pulp::format::make_editor_idle_pump ( ViewBridge & bridge )

inline

Build the per-vsync idle pump for a bridge.

The editor idle pump — the sole production caller of the host pull.

GPU hosts invoke it once per display-link tick to drain host automation, consume restore/reload edges, and poll scripted UI work while the editor is embedded. Captures the bridge by pointer; the host MUST drop this callback (via detach() / destruction) before the bridge is destroyed — every adapter resets its host before bridge.close().

make_quirks_for()

HostQuirks pulp::format::make_quirks_for	(	HostType	type,
		HostVersion	version )

Build a HostQuirks populated for the given host + version.

Default-constructed HostQuirks already turns on the cheap always-on defenses. This factory layers the host-gated flags on top based on the detected host (and version where the quirk is version-keyed).

make_quirks_for_validated_only()

HostQuirks pulp::format::make_quirks_for_validated_only	(	HostType	type,
		HostVersion	version )

Same as make_quirks_for(...) followed by apply_filter(..., kQuirkFilterValidatedOnly).

Convenience for plugin authors who want to opt out of every accommodation that hasn't been bench-validated yet — they get cheap defenses (currently Validated) and any future Validated host quirks, but no Speculative or LessonOnly rows.

make_scripted_idle_pump()

std::function< void()> pulp::format::make_scripted_idle_pump ( ViewBridge & bridge )

inline

Compatibility spelling retained for downstream adapter code.

New code should use make_editor_idle_pump(); both names have identical behavior.

maybe_synthesize_bypass()

bool pulp::format::maybe_synthesize_bypass ( state::StateStore & store, const HostQuirks & q )

inline

synthesize_bypass_parameter: when the plugin declares no Bypass parameter and the quirk is enforced, inject an automatable boolean "Bypass" parameter into the StateStore so the host gets a bypass control.

Returns true if one was synthesized.

The range (min 0, max 1, default 0, step 1) matches the boolean-bypass shape the VST3 / AU v3 adapters already detect (they tag it kIsBypass / the AU bypass surface and pass-through audio in process when it is engaged), so callers just inject it before their existing bypass-param detection pass and the rest flows through unchanged.

No-op (returns false) when: the quirk is filtered out, a parameter named "Bypass" already exists, or the reserved ID is already taken. Not real-time safe — call once at adapter init, before processing.

native_view_aspect_ratio()

double pulp::format::native_view_aspect_ratio ( const ViewSize & hints )

constexpr

Resolve the native host constraint while preserving the legacy fixed-editor contract.

Older plug-ins commonly leave aspect_ratio at zero because the adapters historically derived it from the pinned viewport. Responsive editors keep zero as "no host aspect constraint".

offline_sample_bounce_status_name()

const char * pulp::format::offline_sample_bounce_status_name ( OfflineSampleBounceStatus status )

nodiscardnoexcept

open_app_releases_page()

bool pulp::format::open_app_releases_page

(

)

open_standalone_settings()

void pulp::format::open_standalone_settings ( view::View * from )

inline

Switch the enclosing standalone chrome to its Settings tab (Audio/MIDI).

A no-op if from is not inside such a chrome.

parse_host_version()

std::optional< HostVersion > pulp::format::parse_host_version

(

std::string_view

version_string

)

Best-effort parse of a version string like "10.0.50", "12.0", or "Pro Tools 2024.6".

Returns std::nullopt if no leading numeric component is found.

parse_parameter_text()

std::optional< float > pulp::format::parse_parameter_text ( const state::ParamInfo & info, std::string_view text )

inline

Parse host text into a constrained plain value.

Enum/toggle parameters with declared labels accept only those labels unless the author supplied a custom parser; without labels they are shown as their number, so that number (with the unit, if any) parses back to the same step.

passthrough_block()

template<typename Sample>

void pulp::format::passthrough_block	(	audio::BufferView< Sample > &	out,
		const audio::BufferView< const Sample > &	in )

Copy input to output for a block the plug-in did not render.

Output channels with no matching input are zeroed, so a wider output bus never carries whatever was left in the host's buffer. For an instrument — no input — this is silence, which is the only correct answer there anyway.

Shared by every "the Processor is unavailable for this block" path so they all degrade identically: the state-restore gate below and reload::ProcessorHotSwapSlot's swap contention.

plugin_gpu_disabled_by_env()

bool pulp::format::plugin_gpu_disabled_by_env ( )

inline

Runtime opt-out: PULP_DISABLE_PLUGIN_GPU=1 forces the CoreGraphics CPU path.

DAW/plugin host processes vary; a GPU failure must never make an editor vanish, so the operator can always force CPU.

process_processor_block()

bool pulp::format::process_processor_block ( Processor & processor, ProcessBlock & block, ProcessorBlockAdapterScratch & scratch )

noexcept

Invoke the legacy Processor::process() API from a ProcessBlock.

Returns false without calling the processor when the block is invalid or no active main output bus is present. Sidecar pointers on Processor are restored before return, including when Processor::process() throws. Throwing from process remains a realtime-contract violation; the catch is a safety boundary for tests and offline misuse.

processor_value_channel_access()

view::ValueChannelAccess pulp::format::processor_value_channel_access ( Processor & processor, runtime::AliveToken::Handle owner_alive )

inline

Build the UI-thread accessor used by scripted editors.

The liveness handle deliberately does not own the Processor; once its owner retires, every future visit fails closed without dereferencing the captured pointer. Visits and owner retirement/destruction must remain serialized on the host UI thread. AliveToken prevents deferred post-destruction calls; it is not a cross-thread reclamation or hazard-pointer mechanism.

project_process_context()

ProcessContext pulp::format::project_process_context ( const playback::TransportSnapshot & snapshot, const playback::TransportRange & range, const PlaybackContextProjectionOptions & options = {} )

inlinenoexcept

Lossy, one-way adapter from the integer-authoritative playback snapshot to the public format ABI.

Engine code never includes a format header.

projection_capability()

ProjectionResult pulp::format::projection_capability ( ProjectionSurface surface, bool baked_processor, bool bounded_descriptor )

constexprnoexcept

Return the bounded DSPX-07 projection decision for one target surface.

A graph descriptor is not itself a plugin ABI. It must first be lowered to a self-contained, bounded Processor descriptor. Unknown or unbounded input is refused so callers cannot accidentally advertise a graph feature that an adapter or browser host cannot represent.

register_editor_assets()

void pulp::format::register_editor_assets ( const EditorAssets & assets )

noexcept

Record this binary's editor assets. Static-init safe; last write wins.

register_plugin() [1/2]

void pulp::format::register_plugin

(

const PluginRegistration &

reg

)

register_plugin() [2/2]

void pulp::format::register_plugin

(

ProcessorFactory

factory

)

registered_editor_assets()

EditorAssets pulp::format::registered_editor_assets ( )

noexcept

The binary-wide record from register_editor_assets(), or an empty record.

registered_factory()

ProcessorFactory & pulp::format::registered_factory

(

)

registered_plugins()

std::span< const PluginRegistration > pulp::format::registered_plugins

(

)

render()

PulpsetRender pulp::format::render ( HeadlessHost & host, const Pulpset & ps, std::size_t total_samples, std::size_t block_size = 512 )

inline

Replay ps over host for total_samples, in block_size blocks.

Parameter events are applied at the start of the block they fall in; MIDI notes are placed sample-accurately within the block. The host must already be prepare()d.

reported_latency_samples()

int pulp::format::reported_latency_samples ( int raw, const HostQuirks & q )

constexprnoexcept

Apply clamp_latency_to_nonneg to a raw Processor::latency_samples() value before reporting it to the host.

When the quirk is enforced, a negative latency is clamped to 0 (VST3/CLAP report unsigned, so a raw negative would wrap to a huge value); when it is filtered out, the raw value passes through unchanged. Pure + constexpr so it is unit-tested directly without instantiating an adapter.

request_editor_prewarm()

bool pulp::format::request_editor_prewarm

(

const Processor &

processor

)

Called by format adapters once a host has instantiated processor.

Does nothing when the processor has no editor or nothing to prewarm, when the environment blocks editors (headless, CI, PULP_DISABLE_PLUGIN_EDITOR), when PULP_EDITOR_PREWARM=0, when no scheduler is installed, or when this plug-in bundle (descriptor bundle id + name) was already requested in this process. Returns true when it handed a request to the scheduler.

reset_editor_assets_for_testing()

void pulp::format::reset_editor_assets_for_testing ( )

noexcept

Test-only: clear the binary-wide record. NOT for production use.

reset_registry_for_testing()

void pulp::format::reset_registry_for_testing

(

)

resolve_editor_background()

std::uint32_t pulp::format::resolve_editor_background ( const Processor & processor, const view::View * root )

noexcept

Manages editor-view lifecycle for a single Processor across all plugin formats.

A ViewBridge owns the constructed view tree, tracks its attached/detached state, and dispatches lifecycle callbacks (on_view_opened, on_view_closed, on_view_resized) to the processor.

One processor can have multiple ViewBridges (multi-view): each host editor window and inspector own their own primary View instance. Parameter binding is shared through the processor's StateStore, so all attached views stay in sync automatically.

Construction is cheap — no view is built until open() is called. Destruction closes the view if it is still open. Resolve an editor's background (0xRRGGBB): the processor's declared editor_background(), else root's theme bg.primary, else view::kEditorHostClearRgb. A throwing override falls through to the next source rather than failing the editor open.

resolve_quirk_policy()

ResolvedQuirkPolicy pulp::format::resolve_quirk_policy

(

)

Resolve the effective base tier-filter at runtime (does NOT apply per-quirk overrides — those layer on inside resolved_quirks).

The PULP_HOST_QUIRKS env var is parsed once and cached; recognized values (case-insensitive) are off, validated-only, and all. An unrecognized value is ignored with a one-time warning and resolution falls through to the next layer.

resolved_quirks()

HostQuirks pulp::format::resolved_quirks	(	HostType	type,
		HostVersion	version )

The single entry adapters consume: build the host's quirks, apply the runtime base filter (resolve_quirk_policy), then layer per-quirk overrides.

Equivalent to make_quirks_for + the runtime policy.

runs_inference_on_device()

bool pulp::format::runs_inference_on_device ( GenerationJobClass job, GenerationRoute route )

nodiscardconstexprnoexcept

Returns whether route performs inference on this device.

Named rather than left as a comparison so the AUv3 invariant reads as the property it is at every call site that asserts it.

scripted_editor_builder_slot()

std::atomic< ScriptedEditorBuilder > & pulp::format::scripted_editor_builder_slot ( )

inlinenoexcept

The scripted editor builder this binary links, or null.

install_scripted_editor_builder() fills it. Editor glue that every plug-in links calls through this slot, so a binary whose editor never runs a script does not link the script runtime (QuickJS, the widget bridge, Skia's text and canvas code it draws through) just to be able to construct a session it never constructs.

segment_rms()

double pulp::format::segment_rms ( const std::vector< float > & v, std::size_t a, std::size_t b )

inline

RMS of [a,b) of one channel — for range/property assertions.

select_editor_ui_source()

EditorUiSource pulp::format::select_editor_ui_source ( const EditorAssets & assets, bool enable_hot_reload )

inline

Pick the document for a default scripted editor from the record the plug-in registered.

The embedded script wins whenever the image carries one; the on-disk path a dev build also records is honored only for a hot-reloading editor (the standalone host, or a DAW launched with PULP_DEV_HOT_RELOAD=1), and only while that file exists, so the edit-and-see loop keeps reading the file the build points at while a shipped image never depends on the developer's source tree. Without an embedded script the path is used as before.

service_panic()

template<typename Proc>

PanicOutcome pulp::format::service_panic ( Proc & processor, PanicState & state, midi::MidiBuffer & midi_out, std::int32_t sample_offset = 0 )

inlinenoexcept

Service a pending panic request (audio thread, before process()).

Proc is any type with void on_panic(PanicMode), i.e. a Processor. The plug-in's own voices are reset once per request; MIDI is written only when the state's adapter reported MIDI output, and a panic too large for one block's MIDI buffer continues over the following blocks without a new request. Returns serviced == false when nothing was pending or carried.

set_app_update_automatic_checks()

bool pulp::format::set_app_update_automatic_checks

(

bool

on

)

set_app_update_service()

void pulp::format::set_app_update_service

(

std::shared_ptr< AppUpdateService >

service

)

Install (or, with nullptr, remove) the process-wide service.

The standalone host calls this; plug-ins never do.

set_editor_prewarm_scheduler()

void pulp::format::set_editor_prewarm_scheduler ( EditorPrewarmScheduler scheduler )

noexcept

Installed by the view layer. Passing nullptr uninstalls (tests).

set_host_quirk_policy()

void pulp::format::set_host_quirk_policy

(

std::optional< QuirkFilter >

filter

)

Programmatically set the base tier-filter (highest base-layer precedence, above the env var).

Pass std::nullopt to clear it and fall back to env / compile default. Init-time only.

set_ios_audio_session_listener()

void pulp::format::set_ios_audio_session_listener

(

IosAudioSessionListener

listener

)

Subscribe to session events.

Replaces any existing subscription. Pass an empty std::function to detach.

set_quirk_override()

void pulp::format::set_quirk_override	(	std::string_view	flag,
		bool	enabled )

Force a single quirk flag on or off by its HostQuirks field name, overriding the tier filter for just that flag.

enabled = true keeps the host-populated value even when its tier is filtered out; enabled = false forces it back to the default (off). Unknown names are ignored. Init-time only.

should_lock_view_aspect()

bool pulp::format::should_lock_view_aspect ( const ViewSize & hints )

constexpr

Aspect locking and viewport pinning are deliberately separate.

A responsive root can reflow at the live host bounds while the host still constrains the resize gesture to the declared aspect ratio.

should_pin_design_viewport()

bool pulp::format::should_pin_design_viewport ( const ViewSize & hints )

constexpr

Editor-host resize contract shared by the format adapters (VST3 PulpPlugView, the AU v2 Cocoa view; mac AUv3 pins unconditionally and predates the free-resize case).

One predicate so the formats cannot drift:

• not resizable (min==0): pin the design viewport at preferred so an off-size DAW pane letterbox-scales the content.
• resizable (min>0, CLAP's gui_can_resize convention) + aspect_ratio>0: pin viewport + lock aspect (design-import path).
• resizable + aspect_ratio==0: free drag within [min,max] — NO pin, NO aspect lock; the root reflows via Yoga at the host size. True == the editor host should call set_design_viewport(authored-or-preferred) + set_fixed_aspect_ratio(preferred_w / preferred_h).

silence_block()

template<typename Sample>

void pulp::format::silence_block

(

audio::BufferView< Sample > &

out

)

Zero an output bus for a block the plug-in did not render.

The counterpart to passthrough_block() for sources with no input to pass through — instruments, and any bus whose input side is absent.

standalone_settings_available()

bool pulp::format::standalone_settings_available ( view::View * from )

inline

True when from is hosted in the standalone settings chrome (a TabPanel ancestor carrying the Settings tab alongside the editor).

Editors gate their gear / "Settings" control on this so it never appears when running as a plugin in a DAW.

to_string() [1/2]

std::string_view pulp::format::to_string

(

PulpIosAudioEvent

event

)

Human-readable label for an event type (for logs and tests).

to_string() [2/2]

const char * pulp::format::to_string ( ValidationStatus s )

inline

Convert status to its JSON string representation.

validate_descriptor()

std::vector< DescriptorIssue > pulp::format::validate_descriptor

(

const PluginDescriptor &

d

)

Run the validator.

Returns every issue found — never stops at the first problem so a developer sees the full report.

view_size_from_design()

ViewSize pulp::format::view_size_from_design ( uint32_t preferred_width, uint32_t preferred_height, uint32_t min_width = 0, uint32_t min_height = 0, uint32_t max_width = 0, uint32_t max_height = 0 )

constexpr

Build a ViewSize from a design-import preferred size with sensible derived bounds.

Used by Processor::view_size()'s default when pulp_add_plugin(... DESIGN_WIDTH N DESIGN_HEIGHT N) is set, and callable directly by plugins that compute dimensions at runtime.

Derivation rules (only when the corresponding explicit value is 0):

• min = preferred * 2/3
• max = preferred * 2
• aspect_ratio = preferred_width / preferred_height

CLAP's gui_can_resize requires min > 0 (see clap_entry.hpp), so the derived min is what makes corner-drag resize work across all formats with no per-plugin override. A generated-plugin sidecar can populate these inputs once import-design supplies them.

warn_if_unexpected_cpu_fallback()

void pulp::format::warn_if_unexpected_cpu_fallback ( const GpuHostDecision & d, const view::PluginViewHost * host )

inline

Scream-guard (runtime): after the host's surface state is DECIDED, verify the GPU path actually took.

If GPU was expected (requested + Skia compiled in) but the host has no surface, log LOUDLY — the same "expected-but-not-used → scream" philosophy as the build-time Skia-not-linked guard (c6da9c4da). On a no-Skia build the request is moot, so no scream fires.

pending is silent on purpose. A host that has not built its surface yet has not fallen back to anything: the Windows host cannot create its Dawn surface until attach_to_parent() reparents the HWND, so calling this right after create() — which every adapter used to do — reported a CPU fallback on an editor that was about to run on the GPU. Prefer bind_gpu_surface(), which defers this to the transition that actually decides.

write_wav_f32()

bool pulp::format::write_wav_f32 ( const std::string & path, const PulpsetRender & r, std::uint32_t sample_rate = 48000 )

inline

Write 32-bit float stereo WAV (offline render artifact).

Variable Documentation

kAppUpdatesCheckMessage

const char* pulp::format::kAppUpdatesCheckMessage = "pulp_updates_check"

inlineconstexpr

kAppUpdatesGetMessage

const char* pulp::format::kAppUpdatesGetMessage = "pulp_updates_get"

inlineconstexpr

kAppUpdatesOpenReleasesMessage

const char* pulp::format::kAppUpdatesOpenReleasesMessage = "pulp_updates_open_releases"

inlineconstexpr

kAppUpdatesSetAutomaticMessage

const char* pulp::format::kAppUpdatesSetAutomaticMessage = "pulp_updates_set_automatic"

inlineconstexpr

kAuAraFactoryPropertyKey

const char* pulp::format::kAuAraFactoryPropertyKey = "audioUnitARAFactory"

constexpr

AU v3 — AUAudioUnit.audioUnitARAFactory property key.

Logic Pro and other AU-ARA hosts observe this property to obtain the plugin's companion factory. Exposed through the PulpAudioUnit subclass.

kClapAraFactoryExtension

const char* pulp::format::kClapAraFactoryExtension = "com.celemony.ara/clap-factory-v1"

constexpr

Well-known extension id for the CLAP-ARA companion factory.

Matches Celemony's convention for identifying the ARA extension inside a CLAP plugin's clap_plugin::get_extension callback. The CLAP adapter surfaces this to hosts that know how to pair a CLAP plugin with an ARA document controller.

kGenerationConnectivityCount

std::size_t pulp::format::kGenerationConnectivityCount = 2

inlineconstexpr

kGenerationHostContextCount

std::size_t pulp::format::kGenerationHostContextCount = 2

inlineconstexpr

kGenerationJobClassCount

std::size_t pulp::format::kGenerationJobClassCount = 3

inlineconstexpr

kGenerationRouteCount

std::size_t pulp::format::kGenerationRouteCount = 3

inlineconstexpr

kHostQuirksMeta

HostQuirksMeta pulp::format::kHostQuirksMeta {}

inlineconstexpr

Authoritative meta for the in-tree HostQuirks.

Plugin authors and tests should consult this rather than re-deriving the tier from the field name. Edited in lock-step with the file header summary and the row in core/format/host-quirks.json for each promotion.

kQuirkFilterOff

QuirkFilter pulp::format::kQuirkFilterOff

inlineconstexpr

Initial value:

{
    .allow_validated = false,
    .allow_speculative = false,
    .allow_lesson_only = false,
}

Filter constant: drop every accommodation (including cheap defenses).

Intended for diagnostic / fully-spec-compliant builds — use with care.

kQuirkFilterValidatedOnly

QuirkFilter pulp::format::kQuirkFilterValidatedOnly

inlineconstexpr

Initial value:

{
    .allow_validated = true,
    .allow_speculative = false,
    .allow_lesson_only = false,
}

Filter constant: keep only Validated tier accommodations.

kSynthesizedBypassParamId

state::ParamID pulp::format::kSynthesizedBypassParamId = 0x70427970

inlineconstexpr

Reserved ParamID for the synthesized Bypass parameter.

Chosen high + distinctive so it does not collide with plugin-declared IDs. Stable across builds so host automation envelopes survive reloads.

kVst3AraFactoryContextKey

const char* pulp::format::kVst3AraFactoryContextKey = "com.celemony.ara/vst3-host-factory-v1"

constexpr

VST3 — IPluginFactory3::setHostContext attribute key under which ARA-aware hosts (Cubase, Studio One) advertise their ARA factory pointer.

The VST3 entry reads it in PulpVst3Processor::initialize and calls ara_companion_factory_for() to surface the plugin side. String is stable because hosts match it exactly.