Plugins
Current model
- built-in filters register first,
- CLI and GUI scan configured plugin directories for compiled plugins,
- CLI and GUI scan the same configured plugin directories for script plugins,
- both plugin kinds are exposed through the same
plugin.namespace in scripts, - verbose version output reports loaded compiled plugins and ABI version.
Configured plugin directories normally come from the conventional platform locations. Set
PF_PLUGIN_DIRS to replace that list entirely. PF_PLUGIN_DIRS is parsed with the operating
system path-list rules. In typical shell usage, separate entries with : on Unix and macOS or ;
on Windows. Empty path-list entries are ignored. Setting PF_PLUGIN_DIRS to an empty value
disables plugin directory scanning.
Plugin kinds
- Compiled plugins use the Rust SDK and register filters into the host registry.
- Script plugins are
.pffiles loaded from the same plugin directories.
Plugin load or registration failures are warned and skipped so CLI startup can continue. Name collisions stop script evaluation to avoid unexpected behavior overrides.
Current compiled authoring path
Current official compiled authoring path is Rust through pixelflow-plugin-sdk.
What compiled plugins can provide today
Compiled Rust plugins can provide:
- filter descriptors through
RegistrationContext::register_filter, - metadata keys through
RegistrationContext::register_metadata, - planner callbacks that receive input media, filter options, and the metadata schema, and
- frame executors that request upstream frames and return metadata-bearing output frames.
The host keeps successfully loaded plugin libraries alive for process lifetime so registered callback pointers remain valid.
Current limits
- Direct C or C++ authoring is not supported in current Phase 1 workflow.
- Compiled plugin failures do not stop CLI startup when host can safely skip failed plugins.