spa-inspect

Display information about a SPA plugin

$ spa-inspect [path/to/plugin.so]

spa-inspect [OPTIONS] [ID]

-h, --help
    Displays a help message and exits, showing available options and their usage.

-v, --version
    Shows the version information of the spa-inspect utility and exits.

-L, --list-plugins
    Lists all available SPA plugins that PipeWire can load and utilize.

-F, --list-factory-types
    Lists all available SPA factory types (e.g., Audio/Sink, Video/Source) supported by the system.

-i <name|id>, --inspect-plugin=<name|id>
    Inspects a specific SPA plugin, identified either by its unique name or its numeric ID. Provides detailed information about its capabilities.

-n <id>, --inspect-node=<id>
    Inspects a specific active PipeWire node, identified by its numeric ID. This shows the current state and properties of a running node.

-p, --properties
    When used with --inspect-plugin or --inspect-node, displays the properties (parameters and settings) associated with the specified plugin or node.

-m, --methods
    When used with --inspect-plugin or --inspect-node, displays the methods (callable functions or operations) that can be performed on the specified plugin or node.

-e, --events
    When used with --inspect-plugin or --inspect-node, displays the events (notifications or signals) that the specified plugin or node can emit.

-l, --long
    Displays output in a long, more detailed format, providing additional context and information for listings or inspections.

spa-inspect is a powerful utility provided as part of the PipeWire multimedia framework. Its primary function is to inspect and provide detailed information about SPA (Simple Plugin API) plugins and active nodes within the PipeWire graph. SPA is a crucial component of PipeWire, defining the interface for audio and video processing plugins and their functionalities.

This command allows developers and power users to gain insights into the capabilities, properties, and parameters of these plugins and nodes without directly interacting with the PipeWire daemon. It can list all available plugins, show the factory types they implement (e.g., source, sink, filter), and delve into the specific features, properties, methods, and events supported by individual plugins or active nodes. spa-inspect is an invaluable tool for debugging, understanding plugin behavior, and configuring complex PipeWire setups, offering a transparent view into the underlying audio and video processing components.

Using spa-inspect to inspect active nodes (with -n) requires the PipeWire daemon to be running. The command's output can be quite verbose, especially with the -l (long) option or when inspecting complex plugins, which may require careful parsing or filtering. A basic understanding of PipeWire and SPA concepts is beneficial for interpreting the detailed output.

When using --inspect-plugin, spa-inspect queries the available SPA factories to show what a plugin can do, essentially its blueprint. In contrast, when using --inspect-node, it inspects an active, running instance of a node within the live PipeWire graph, reflecting its current state, properties, and connections.

The detailed output for plugins typically includes information such as the plugin's name, version, author, copyright, description, and importantly, its factory types. For properties, methods, and events, it lists their identifiers, types, and default values or possible ranges, which is crucial for understanding how to interact with or configure these multimedia components programmatically or through other tools.

spa-inspect is an integral part of the PipeWire project, which was initiated by Wim Taymans (Red Hat) and first publicly announced in 2017. PipeWire aims to be a next-generation multimedia server for Linux, unifying audio, video, and hardware access. spa-inspect was developed as a fundamental diagnostic and introspection tool alongside PipeWire's core development, providing a window into the Simple Plugin API (SPA) components that form the building blocks of PipeWire's processing capabilities. Its usage grew as PipeWire gained adoption, becoming essential for developers and users to understand and troubleshoot the intricate multimedia graphs managed by the system, ensuring transparent control over audio and video streams.

pw-cli(1), pw-top(1), pw-dot(1), pipewire(1)