mirrors/pipewire
1
0
Fork 0
mirror of https://gitlab.freedesktop.org/pipewire/pipewire.git synced 2025-12-14 08:56:37 -05:00
Code Issues Projects Releases Packages Wiki Activity Actions

doc: improve the pipewire-audio page for readability

Browse source 
Typos, some header changes, etc.
This commit is contained in:
Peter Hutterer 2021-07-29 14:21:33 +10:00
parent 7871f33da6
commit 85435cd525
1 changed files with 21 additions and 22 deletions
Download patch file Download diff file Expand all files Collapse all files

43
doc/pipewire-audio.dox
View file

@ -9,12 +9,12 @@ This document explains how Audio is implemented.
Applications need to be able to see a port for each stream of an Applications need to be able to see a port for each stream of an
Audio device. Audio device.
## Audio devices can be plugged and unplugged ### Audio devices can be plugged and unplugged
When devices are plugged and unplugged the associated nodes/ports When devices are plugged and unplugged the associated nodes/ports
need to be created and removed. need to be created and removed.
## Audio port in cannonical format ### Audio port in canonical format
It must be possible to make individual audio channels available It must be possible to make individual audio channels available
as a single mono stream with a fixed format and samplerate. as a single mono stream with a fixed format and samplerate.
@ -22,27 +22,27 @@ as a single mono stream with a fixed format and samplerate.
This makes it possible to link any of the audio ports together This makes it possible to link any of the audio ports together
without doing conversions. without doing conversions.
## Applications can connect to Audio devices ### Applications can connect to audio devices
Applications can create ports that can connect to the Audio ports Applications can create ports that can connect to the audio ports
so that data can be provided to or consumed from them. so that data can be provided to or consumed from them.
It should be possible to automatically connect an application to It should be possible to automatically connect an application to
a sink/source when it requests this. a sink/source when it requests this.
## Default Audio sink and sources ### Default audio sink and sources
It should be possible to mark a source or sink as the default source 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. and sink so that applications are routed to them by default.
It should be possible to change the default audio sink/source. It should be possible to change the default audio sink/source.
## Application should be able to move between sinks/sources ### Application should be able to move between sinks/sources
It should be possible to move an application from one device to It should be possible to move an application from one device to
another dynamically. another dynamically.
## Exclusive access ### Exclusive access
Application should be able to connect to a device in exclusive mode. Application should be able to connect to a device in exclusive mode.
This allows the application to negotiate a specific format with the This allows the application to negotiate a specific format with the
@ -57,26 +57,25 @@ compressed formats.
## SPA ## SPA
Audio devices are implemented with an SPA Device object. Audio devices are implemented with an \ref spa_device "SPA Device" object.
\ref spa_device .
This object is then responsable for controlling the SPA Nodes that This object is then responsible for controlling the \ref spa_node "SPA Nodes" that
provide the audio ports to interface with the device. provide the audio ports to interface with the device.
The Nodes operate on the native audio formats supported by 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 This includes the sample rate as well as the number of channels and
the audio format. the audio format.
## Audio Adapter ## Audio Adapter
An SPA Node called the adapter is usually used with the SPA device Node An SPA Node called the "adapter" is usually used with the SPA device Node as
as the internal node. the internal node.
The function of the adapter is to convert the device native format to The function of the adapter is to convert the device native format to
the required external format. This can include format or samplerate the required external format. This can include format or samplerate
conversion but also channel remixing/remapping. conversion but also channel remixing/remapping.
The audio adapter is also responsable for exposing the audio channels The audio adapter is also responsible for exposing the audio channels
as separate mono ports. This is called the DSP setup. as separate mono ports. This is called the DSP setup.
The audio adapter can also be configured in passthrough mode when it The audio adapter can also be configured in passthrough mode when it
@ -88,7 +87,7 @@ the PortConfig parameter.
## The session manager ## The session manager
The session manager is responsable for creating Nodes and Ports for The session manager is responsible for creating Nodes and Ports for
the various audio devices. It will need to wrap them into an audio the various audio devices. It will need to wrap them into an audio
adapter so that the specific configuration of the node can be adapter so that the specific configuration of the node can be
decided by the policy mode. decided by the policy mode.
@ -96,25 +95,25 @@ decided by the policy mode.
The session manager should create name and description for the The session manager should create name and description for the
devices and nodes. devices and nodes.
The session manager is responsable for assigning priorities to the The session manager is responsible for assigning priorities to the
Nodes. At least PW_KEY_PRIORITY_SESSION and PW_KEY_PRIORITY_DRIVER Nodes. At least \ref PW_KEY_PRIORITY_SESSION and \ref PW_KEY_PRIORITY_DRIVER
need to be set. need to be set.
The session manager might need to work with other services to gain The session manager might need to work with other services to gain
exclusive access to the device, like though DBus. exclusive access to the device (e.g. DBus).
# Implementation # Implementation
## pipewire-media-session (alsa-monitor) ## pipewire-media-session (alsa-monitor)
PipeWire media session uses the SPA_NAME_API_ALSA_ENUM_UDEV plugin PipeWire media session uses the \ref SPA_NAME_API_ALSA_ENUM_UDEV plugin
for enumerating the ALSA devices. For each device it does: for enumerating the ALSA devices. For each device it does:
- Try to acquire the DBus device reservation object to gain exclusive - Try to acquire the DBus device reservation object to gain exclusive
access to the device. access to the device.
- Create an SPA Device instance for the device and monitor this. - Create an SPA Device instance for the device and monitor this device instance.
- For each Node created by the device, it creates an adapter with - For each Node created by the device, create an adapter with
an ALSA PCM node in the context of the PipeWire daemon. an ALSA PCM node in the context of the PipeWire daemon.
The session manager will also create suitable names and descriptions The session manager will also create suitable names and descriptions
@ -122,7 +121,7 @@ for the Devices and Nodes that it creates as well as assign session
and driver priorities. and driver priorities.
The session manager has the option to add extra properties on the The session manager has the option to add extra properties on the
Devices and Node that it creates to control their behaviour. This Devices and Node that it creates to control their behavior. This
is implemented with match rules. is implemented with match rules.