mirror of
https://gitlab.freedesktop.org/pipewire/pipewire
synced 2024-10-14 11:53:16 +00:00
doc: add general audio configuration
This commit is contained in:
parent
b6405b761f
commit
ab99f4d027
129
doc/pipewire-audio.dox
Normal file
129
doc/pipewire-audio.dox
Normal file
|
@ -0,0 +1,129 @@
|
||||||
|
/** \page page_audio PipeWire Audio
|
||||||
|
|
||||||
|
This document explains how Audio is implemented.
|
||||||
|
|
||||||
|
# Use cases
|
||||||
|
|
||||||
|
## Audio devices are made available as processing nodes/ports
|
||||||
|
|
||||||
|
Applications need to be able to see a port for each stream of an
|
||||||
|
Audio device.
|
||||||
|
|
||||||
|
## Audio devices can be plugged and unplugged
|
||||||
|
|
||||||
|
When devices are plugged and unplugged the associated nodes/ports
|
||||||
|
need to be created and removed.
|
||||||
|
|
||||||
|
## Audio port in cannonical format
|
||||||
|
|
||||||
|
It must be possible to make individual audio channels available
|
||||||
|
as a single mono stream with a fixed format and samplerate.
|
||||||
|
|
||||||
|
This makes it possible to link any of the audio ports together
|
||||||
|
without doing conversions.
|
||||||
|
|
||||||
|
## Applications can connect to Audio devices
|
||||||
|
|
||||||
|
Applications can create ports that can connect to the Audio ports
|
||||||
|
so that data can be provided to or consumed from them.
|
||||||
|
|
||||||
|
It should be possible to automatically connect an application to
|
||||||
|
a sink/source when it requests this.
|
||||||
|
|
||||||
|
## Default Audio sink and sources
|
||||||
|
|
||||||
|
It should be possible to mark a source or sink as the default source
|
||||||
|
and sink so that applications are routed to them by default.
|
||||||
|
|
||||||
|
It should be possible to change the default audio sink/source.
|
||||||
|
|
||||||
|
## Application should be able to move between sinks/sources
|
||||||
|
|
||||||
|
It should be possible to move an application from one device to
|
||||||
|
another dynamically.
|
||||||
|
|
||||||
|
## Exclusive access
|
||||||
|
|
||||||
|
Application should be able to connect to a device in exclusive mode.
|
||||||
|
This allows the application to negotiate a specific format with the
|
||||||
|
device such as a compressed format.
|
||||||
|
|
||||||
|
Exclusive access means that only one application can access the device
|
||||||
|
because mixing is in general not possible when negotiating
|
||||||
|
compressed formats.
|
||||||
|
|
||||||
|
|
||||||
|
# Design
|
||||||
|
|
||||||
|
## SPA
|
||||||
|
|
||||||
|
Audio devices are implemented with an SPA Device object.
|
||||||
|
\ref spa_device .
|
||||||
|
|
||||||
|
This object is then responsable for controlling the SPA Nodes that
|
||||||
|
provide the audio ports to interface with the device.
|
||||||
|
|
||||||
|
The Nodes operate on the native audio formats supported by the device.
|
||||||
|
This incluides the sample rate as well as the number of channels and
|
||||||
|
the audio format.
|
||||||
|
|
||||||
|
## Audio Adapter
|
||||||
|
|
||||||
|
An SPA Node called the adapter is usually used with the SPA device Node
|
||||||
|
as the internal node.
|
||||||
|
|
||||||
|
The function of the adapter is to convert the device native format to
|
||||||
|
the required external format. This can include format or samplerate
|
||||||
|
conversion but also channel remixing/remapping.
|
||||||
|
|
||||||
|
The audio adapter is also responsable for exposing the audio channels
|
||||||
|
as separate mono ports. This is called the DSP setup.
|
||||||
|
|
||||||
|
The audio adapter can also be configured in passthrough mode when it
|
||||||
|
will not do any conversions but simply pass through the port information
|
||||||
|
of the internal Node. This can be used to implement exclusive access.
|
||||||
|
|
||||||
|
Setup of the different configurations of the adapter can be done with
|
||||||
|
the PortConfig parameter.
|
||||||
|
|
||||||
|
## The session manager
|
||||||
|
|
||||||
|
The session manager is responsable for creating Nodes and Ports for
|
||||||
|
the various audio devices. It will need to wrap them into an audio
|
||||||
|
adapter so that the specific configuration of the node can be
|
||||||
|
decided by the policy mode.
|
||||||
|
|
||||||
|
The session manager should create name and description for the
|
||||||
|
devices and nodes.
|
||||||
|
|
||||||
|
The session manager is responsable for assigning priorities to the
|
||||||
|
Nodes. At least PW_KEY_PRIORITY_SESSION and PW_KEY_PRIORITY_DRIVER
|
||||||
|
need to be set.
|
||||||
|
|
||||||
|
The session manager might need to work with other services to gain
|
||||||
|
exclusive access to the device, like though DBus.
|
||||||
|
|
||||||
|
|
||||||
|
# Implementation
|
||||||
|
|
||||||
|
## pipewire-media-session (alsa-monitor)
|
||||||
|
|
||||||
|
PipeWire media session uses the SPA_NAME_API_ALSA_ENUM_UDEV plugin
|
||||||
|
for enumerating the ALSA devices. For each device it does:
|
||||||
|
|
||||||
|
- Try to acquire the DBus device reservation object to gain exclusive
|
||||||
|
access to the device.
|
||||||
|
- Create an SPA Device instance for the device and monitor this.
|
||||||
|
- For each Node created by the device, it creates an adapter with
|
||||||
|
an ALSA PCM node in the context of the PipeWire daemon.
|
||||||
|
|
||||||
|
The session manager will also create suitable names and descriptions
|
||||||
|
for the Devices and Nodes that it creates as well as assign session
|
||||||
|
and driver priorities.
|
||||||
|
|
||||||
|
The session manager has the option to add extra properties on the
|
||||||
|
Devices and Node that it creates to control their behaviour. This
|
||||||
|
is implemented with match rules.
|
||||||
|
|
||||||
|
|
||||||
|
*/
|
Loading…
Reference in a new issue