pipewire/doc/dox/api/spa-index.dox

/** \page page_spa SPA (Simple Plugin API)

\ref api_spa (Simple Plugin API) is an extensible API to implement all kinds of
plugins.

It is inspired by many other plugin APIs, mostly LV2 and
GStreamer. SPA provides two parts:

- A header-only API with no external dependencies.
- A set of support libraries ("plugins") for commonly used functionality.

The usual approach is that PipeWire and PipeWire clients can use the
header-only functions to interact with the plugins. Those plugins are
usually loaded at runtime (through `dlopen(3)`).


# Motivation

SPA was designed with the following goals in mind:

- No dependencies, SPA is shipped as a set of header files that have no dependencies except for the standard C library.
- Very efficient both in space and in time.
- Very configurable and usable in many different environments. All aspects
  of the plugin environment can be configured and changed, like logging,
  poll loops, system calls, etc.
- Consistent API.
- Extensible; new API can be added with minimal effort, existing API can be updated and versioned.

The original user of SPA is PipeWire, which uses SPA to implement the
low-level multimedia processing plugins, device detection, mainloops, CPU
detection, logging, among other things. SPA however can be used outside
of PipeWire with minimal problems.


# The SPA Header-Only API

A very simple example on how SPA headers work are the \ref spa_utils, a set
of utilities commonly required by C projects. SPA functions use the `spa_`
namespace and are easy to identify.

\code
/* cc $(pkg-config --cflags libspa-0.2) -o spa-test spa-test.c */

#include <stdint.h>
#include <spa/utils/string.h>

int main(int argc, char **argv) {
	uint32_t val;

	if (spa_atoi32(argv[1], &val, 16))
		printf("argv[1] is hex %#x\n", val);
	else
		printf("argv[1] is not a hex number\n");

	return 0;
}
\endcode


# SPA Plugins

SPA plugins are shared libraries (`.so` files) that can be loaded at
runtime. Each library provides one or more "factories", each of which may
implement several "interfaces". Code that uses SPA plugins then uses those
interfaces (through SPA header files) to interact with the plugin.

For example, the PipeWire daemon can load the normal `printf`-based logger
or a systemd journal-based logger. Both of those provide the \ref spa_log
interface and once instantiated, PipeWire no longer has to differentiate
between the two logging facilities.

Please see \ref page_spa_plugins for the details on how to use SPA plugins.


# Further details

- \ref api_spa
- \subpage page_spa_design
- \subpage page_spa_plugins
- \subpage page_spa_pod
- \subpage page_spa_buffer


\addtogroup api_spa

See: \ref page_spa, \ref page_spa_design

*/