@@ -1,4 +1,9 @@

 -------------------------------------------------------------------

+Thu Nov  7 09:26:42 UTC 2024 - Bjørn Lie <zaitor@opensuse.org>

+

+- Update to version 1.2.6

+

+-------------------------------------------------------------------

 Fri Oct  4 09:01:15 UTC 2024 - Bjørn Lie <zaitor@opensuse.org>

 - Update to version 1.2.5

​

@@ -8,7 +8,7 @@

 %define minimum_version 1.2.0

 Name:           pipewire-aptx

-Version:        1.2.5

+Version:        1.2.6

 Release:        0

 Summary:        PipeWire Bluetooth aptX codec plugin

 License:        MIT

​

@@ -2,6 +2,6 @@

   <service name="download_url">

     <param name="host">gitlab.freedesktop.org</param>

     <param name="protocol">https</param>

-    <param name="path">/pipewire/pipewire/-/archive/1.2.5/pipewire-1.2.5.tar.bz2</param>

+    <param name="path">/pipewire/pipewire/-/archive/1.2.6/pipewire-1.2.6.tar.bz2</param>

   </service>

 </services>

\ No newline at end of file

​

@@ -1,518 +0,0 @@

-\page page_man_pipewire-devices_7 pipewire-devices

-

-PipeWire device and node property reference.

-

-\tableofcontents

-

-# DESCRIPTION

-

-Audio sinks and sources, cameras, Bluetooth endpoints, and other

-objects have properties that can be set in configuration files or at

-runtime.

-

-Some of the properties are "common object properties" (e.g. such as

-`node.description`) and can be set on all types of devices and

-nodes. Other properties control settings of a specific type of a

-device (ALSA, Bluetooth, ...).

-

-All the properties are usually configured in the session manager configuration.

-For how to configure them, see the session manager documentation.

-

-In minimal PipeWire setups without a session manager, they can be configured via

-\ref pipewire_conf__context_objects "context.objects in pipewire.conf(5)".

-

-# RUNTIME SETTINGS  @IDX@ device-param

-

-The settings of most ALSA and virtual device parameters can be

-configured also at runtime.

-

-The settings are available in device `Props` in the `params`

-field. They can be seen e.g. using `pw-dump <id>` for an ALSA device:

-

-```json

-{

-...

-      "Props": 

-        {

-          ...

-          "params": 

-              "audio.channels",

-              2,

-              "audio.rate",

-              0,

-              "audio.format",

-              "UNKNOWN",

-              "audio.position",

-              " FL, FR ",

-              "audio.allowed-rates",

-              "  ",

-              "api.alsa.period-size",

-              0,

-              "api.alsa.period-num",

-              0,

-              "api.alsa.headroom",

-              0,

-              "api.alsa.start-delay",

-              0,

-              "api.alsa.disable-mmap",

-              false,

-              "api.alsa.disable-batch",

-              false,

-              "api.alsa.use-chmap",

-              false,

-              "api.alsa.multi-rate",

-              true,

-              "latency.internal.rate",

-              0,

-              "latency.internal.ns",

-              0,

-              "clock.name",

-              "api.alsa.c-1"

-            

-          }

-...

-```

-

-One or more `params` can be changed using \ref page_man_pw-cli_1 "pw-cli(1)":

-```

-pw-cli s <id> Props '{ params =  "api.alsa.headroom" 1024  }'

-```

-These settings are not saved and need to be reapplied for each session manager restart.

-

-# COMMON NODE PROPERTIES  @IDX@ device-param

-

-The properties listed in \ref client_conf__stream_properties "Stream properties"

-apply also to sink or source nodes corresponding to real or virtual devices.

-

-In addition:

-

-@PAR@ device-param  priority.driver    # integer

-\parblock

-The priority of choosing this device as the driver in the graph. The driver is selected from all linked devices by selecting the device with the highest priority.

-

-Normally, the session manager assigns higher priority to sources so that they become the driver in the graph. The reason for this is that adaptive resampling should be done on the sinks rather than the source to avoid signal distortion when capturing audio.

-\endparblock

-

-@PAR@ device-param  priority.session    # integer

-The priority for selecting this device as the default device.

-

-@PAR@ device-param  clock.name    # string

-\parblock

-The name of the clock. This name is auto generated from the card index and stream direction. Devices with the same clock name will not use a resampler to align the clocks. This can be used to link devices together with a shared word clock.

-

-In Pro Audio mode, nodes from the same device are assumed to have the same clock and no resampling will happen when linked together. So, linking a capture port to a playback port will not use any adaptive resampling in Pro Audio mode.

-

-In Non Pro Audio profile, no such assumption is made and adaptive resampling is done in all cases by default. This can also be disabled by setting the same clock.name on the nodes.

-\endparblock

-

-@PAR@ device-param  node.param.PARAM = JSON    # JSON

-\parblock

-Set value of a node \ref spa_param_type "Param" to a JSON value when the device is loaded.

-This works similarly as \ref page_man_pw-cli_1 "pw-cli(1)" `set-param` command.

-The `PARAM` should be replaced with the name of the Param to set,

-ie. for example `node.param.Props = { ... }` to set `Props`.

-\endparblock

-

-@PAR@ device-param  device.id

-ID of the device the node belongs to.

-

-# COMMON DEVICE PROPERTIES  @IDX@ device-param

-

-These are common properties for devices.

-

-@PAR@ device-param  device.name    # string

-A (unique) name for the device. It can be used by command-line and other tools to identify the device.

-

-@PAR@ device-param  device.param.PARAM = JSON    # JSON

-\parblock

-Set value of a device \ref spa_param_type "Param" to a JSON value when the device is loaded.

-This works similarly as \ref page_man_pw-cli_1 "pw-cli(1)" `set-param` command.

-The `PARAM` should be replaced with the name of the Param to set,

-ie. for example `device.Param.Props = { ... }` to set `Props`.

-\endparblock

-

-Other `device.*` properties: UNDOCUMENTED

-

-# AUDIO CONVERTER PROPERTIES  @IDX@ device-param

-

-Most audio nodes (ALSA, Bluetooth, ...) have common properties for the audio

-converter. See \ref client_conf__stream_properties "pipewire-client.conf(5) stream.properties"

-for explanations.

-

-## Node properties

-

-@PAR@ device-param  clock.quantum-limit

-\ref pipewire_conf__default_clock_quantum-limit "See pipewire.conf(5)"

-

-@PAR@ device-param  channelmix.disable

-\ref client_conf__channelmix_disable "See pipewire-client.conf(5)"

-

-@PAR@ device-param  channelmix.min-volume

-\ref client_conf__channelmix_min-volume "See pipewire-client.conf(5)"

-

-@PAR@ device-param  channelmix.max-volume

-\ref client_conf__channelmix_max-volume "See pipewire-client.conf(5)"

-

-@PAR@ device-param  channelmix.normalize

-\ref client_conf__channelmix_normalize "See pipewire-client.conf(5)"

-

-@PAR@ device-param  channelmix.mix-lfe

-\ref client_conf__channelmix_mix-lfe "See pipewire-client.conf(5)"

-

-@PAR@ device-param  channelmix.upmix

-\ref client_conf__channelmix_upmix "See pipewire-client.conf(5)"

-

-@PAR@ device-param  channelmix.lfe-cutoff

-\ref client_conf__channelmix_lfe-cutoff "See pipewire-client.conf(5)"

-

-@PAR@ device-param  channelmix.fc-cutoff

-\ref client_conf__channelmix_fc-cutoff "See pipewire-client.conf(5)"

-

-@PAR@ device-param  channelmix.rear-delay

-\ref client_conf__channelmix_rear-delay "See pipewire-client.conf(5)"

-

-@PAR@ device-param  channelmix.stereo-widen

-\ref client_conf__channelmix_stereo-widen "See pipewire-client.conf(5)"

-

-@PAR@ device-param  channelmix.hilbert-taps

-\ref client_conf__channelmix_hilbert-taps "See pipewire-client.conf(5)"

-

-@PAR@ device-param  channelmix.upmix-method

-\ref client_conf__channelmix_upmix-method "See pipewire-client.conf(5)"

-

-@PAR@ device-param  channelmix.lock-volumes

-\ref client_conf__channelmix_lock-volumes "See pipewire-client.conf(5)"

-

-@PAR@ device-param  resample.quality

-\ref client_conf__resample_quality "See pipewire-client.conf(5)"

-

-@PAR@ device-param  resample.disable

-\ref client_conf__resample_disable "See pipewire-client.conf(5)"

-

-@PAR@ device-param  resample.peaks = false # boolean

-Instead of actually resampling, produce peak amplitude values as output.

-This is used for volume monitoring, where it is set as a property

-of the "recording" stream.

-

-@PAR@ device-param  resample.prefill = false # boolean

-Prefill resampler buffers with silence. This affects the initial

-samples produced by the resampler.

​

@@ -1,3 +1,48 @@

+# PipeWire 1.2.6 (2024-10-23)

+

+This is a bugfix release that is API and ABI compatible with the previous

+1.2.x and 1.0.x releases.

+

+## Highlights

+  - The filter-chain param changes were not aggregated correctly, causing some

+    param changes to be ignored. (#4331)

+  - Clear the JACK io ports correctly when stopping to avoid crashes. (#4337)

+  - Some more small fixes and improvements.

+

+

+## PipeWire

+  - Stream states are now updated based on the underlying node state.

+  - Exported nodes now have their state change done synchronously so that the

+    server can immediately start the driver and avoid some initial xruns.

+  - Improve stream flush handling and improve the docs.

+  - Don't send mix_info to destroyed ports to avoid some errors in the

+    JACK clients.

+

+## Modules

+  - The filter-chain param changes were not aggregated correctly, causing some

+    param changes to be ignored. (#4331)

+  - The filter-chain now correctly optimizes unlinked nodes in all cases.

+

+## SPA

+  - ALSA PCM node properties are now no longer overwritten with card properties.

+    (#4135)

+  - Increase the adapter retry count to avoid xruns in some cases. (#4334)

+  - Fix potential crash in cleanup of ALSA nodes.

+

+## Bluetooth

+  - Fix a crash with broadcast sinks.

+  - Improve compatibility with Phonak hearing aids.

+  - Don't exit when DBus goes down.

+

+## JACK

+  - Clear the io ports correctly when stopping to avoid crashes. (#4337)

+

+## Docs

+  - Backport docs from master.

+

+Older versions:

+

+

 # PipeWire 1.2.5 (2024-09-27)

 This is an important bugfix release that is API and ABI compatible with the

@@ -44,9 +89,6 @@

   - Some small doc updates. (#4272)

-Older versions:

-

-

 # PipeWire 1.2.4 (2024-09-19)

 This is a bugfix release that is API and ABI compatible with the

​

@@ -26,14 +26,12 @@

 - \ref page_man_pipewire_conf_5 "PipeWire daemon configuration reference"

 - \ref page_man_pipewire-pulse_conf_5 "PipeWire Pulseaudio daemon configuration reference"

 - WirePlumber daemon configuration(https://pipewire.pages.freedesktop.org/wireplumber/)

-- Wiki page on PipeWire daemon configuration(https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/Config-PipeWire)

-- Wiki page on PipeWire PulseAudio daemon configuration(https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/Config-PulseAudio)

 Configuration of devices:

 - WirePlumber configuration(https://pipewire.pages.freedesktop.org/wireplumber/daemon/configuration.html)

-- \ref page_man_pipewire-devices_7 "Device and node property reference"

-- Wiki page on device runtime settings(https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/Config-Devices)

+- \ref page_man_pipewire-props_7 "Object property reference"

+- \subpage page_config_xref "Configuration Index"

 Configuration for client applications, either connecting via the

 native PipeWire interface, or the emulated ALSA, JACK, or PulseAudio

@@ -42,10 +40,6 @@

 - \ref page_man_pipewire-client_conf_5 "PipeWire native and ALSA client configuration reference"

 - \ref page_man_pipewire-jack_conf_5 "PipeWire JACK client configuration reference"

 - \ref page_man_pipewire-pulse_conf_5 "PipeWire Pulseaudio client configuration reference"

-- Wiki page on native clients(https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/Config-client)

-- Wiki page on ALSA clients(https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/Config-ALSA)

-- Wiki page on JACK clients(https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/Config-JACK)

-- Wiki page on PulseAudio clients(https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/Config-PulseAudio)

 # Manual Pages

@@ -54,36 +48,6 @@

 - \subpage page_man_pipewire-pulse_conf_5

 - \subpage page_man_pipewire-jack_conf_5

 - \subpage page_man_pipewire-filter-chain_conf_5

-- \subpage page_man_pipewire-devices_7

+- \subpage page_man_pipewire-props_7

 - \subpage page_man_pipewire-pulse-modules_7

 - \subpage page_man_libpipewire-modules_7

-

-# Configuration Index

-

-\ref page_man_pipewire_conf_5 "pipewire.conf"

-

-@SECREF@ pipewire.conf

-

-\ref page_man_pipewire-pulse_conf_5 "pipewire-pulse.conf"

-

-@SECREF@ pipewire-pulse.conf

-

-\ref page_man_pipewire-client_conf_5 "client.conf, client-rt.conf"

-

-@SECREF@ client.conf

-

-\ref page_man_pipewire-jack_conf_5 "jack.conf"

-

-@SECREF@ jack.conf

-

-**Runtime settings**

-

-@SECREF@ pipewire-settings

-

-**Environment variables**

-

-@SECREF@ pipewire-env client-env jack-env pulse-env

-

-**Device properties**

-

-@SECREF@ device-param

​

@@ -66,7 +66,9 @@

 # STREAM PROPERTIES  @IDX@ client.conf

 The client configuration files contain a stream.properties section that configures the options for client streams:

-```

+```css

+# ~/.config/pipewire/client.conf.d/custom.conf

+

 stream.properties = {

     #node.latency = 1024/48000

     #node.autoconnect = true

@@ -101,429 +103,10 @@

 * How the internal processing will be done.

 * Properties to configure the media format.

-## Identifying Properties  @IDX@ client.conf

-

-These contain properties to identify the node or to display the node in a GUI application.

-

-@PAR@ client.conf  node.name

-A (unique) name for the node. This is usually set on sink and sources to identify them

-as targets for linking by the session manager.

-

-@PAR@ client.conf  node.description

-A human readable description of the node or stream.

-

-@PAR@ client.conf  media.name

-A user readable media name, usually the artist and title.

-These are usually shown in user facing applications

-to inform the user about the current playing media.

-

-@PAR@ client.conf  media.title

-A user readable stream title.

-

-@PAR@ client.conf  media.artist

-A user readable stream artist

-

-@PAR@ client.conf  media.copyright

-User readable stream copyright information

-

-@PAR@ client.conf  media.software

-User readable stream generator software information

-

-@PAR@ client.conf  media.language

-Stream language in POSIX format. Ex: `en_GB`

-

-@PAR@ client.conf  media.filename

-File name for the stream

-

-@PAR@ client.conf  media.icon

-Icon for the media, a base64 blob with PNG image data

-

-@PAR@ client.conf  media.icon-name

-An XDG icon name for the media. Ex: `audio-x-mp3`

-

-@PAR@ client.conf  media.comment

-Extra stream comment

-

-@PAR@ client.conf  media.date

-Date of the media

-

-@PAR@ client.conf  media.format

-User readable stream format information

-

-@PAR@ client.conf  object.linger = false

-If the object should outlive its creator.

-

-## Classifying Properties  @IDX@ client.conf

-

-The classifying properties of a node are use for routing the signal to its destination and

-for configuring the settings.

-

-@PAR@ client.conf  media.type

-The media type contains a broad category of the media that is being processed by the node.

-Possible values include "Audio", "Video", "Midi"

-

-@PAR@ client.conf  media.category

-\parblock

-What kind of processing is done with the media. Possible values include:

-

-* Playback: media playback.

-* Capture: media capture.

-* Duplex: media capture and playback or media processing in general.

-* Monitor: a media monitor application. Does not actively change media data but monitors

-           activity.

-* Manager: Will manage the media graph.

-\endparblock

-

-@PAR@ client.conf  media.role

-\parblock

-The Use case of the media. Possible values include:

-

-* Movie: Movie playback with audio and video.

-* Music: Music listening.

-* Camera: Recording video from a camera.

-* Screen: Recording or sharing the desktop screen.

-* Communication: VOIP or other video chat application.

-* Game: Game.

-* Notification: System notification sounds.

-* DSP: Audio or Video filters and effect processing.

-* Production: Professional audio processing and production.

-* Accessibility: Audio and Visual aid for accessibility.

-* Test: Test program.

-\endparblock

-

-@PAR@ client.conf  media.class

-\parblock

-The media class is to classify the stream function. Possible values include:

-

-* Video/Source: a producer of video, like a webcam.

-* Video/Sink: a consumer of video, like a display window.

-* Audio/Source: a source of audio samples like a microphone.

-* Audio/Sink: a sink for audio samples, like an audio card.

-* Audio/Duplex: a node that is both a sink and a source.

-* Stream/Output/Audio: a playback stream.

-* Stream/Input/Audio: a capture stream.

-

-The session manager assigns special meaning to the nodes based on the media.class. Sink or Source

-classes are used as targets for Stream classes, etc..

-\endparblock

-

-## Scheduling Properties  @IDX@ client.conf

-

-@PAR@ client.conf  node.latency = 1024/48000

-Sets a suggested latency on the node as a fraction. This is just a suggestion, the graph will try to configure this latency or less for the graph. It is however possible that the graph is forced to a higher latency.

-

-@PAR@ client.conf  node.lock-quantum = false

-\parblock

-When this node is active, the quantum of the graph is locked and not allowed to change automatically.

-It can still be changed forcibly with metadata or when a node forces a quantum.

-

-JACK clients use this property to avoid unexpected quantum changes.

-\endparblock

-

-@PAR@ client.conf  node.force-quantum = INTEGER

-\parblock

-While the node is active, force a quantum in the graph. The last node to be activated with this property wins.

-

-A value of 0 unforces the quantum.

-\endparblock

-

-@PAR@ client.conf  node.rate = RATE

-Suggest a rate (samplerate) for the graph. The suggested rate will only be applied when doing so would not cause

-interruptions (devices are idle) and when the rate is in the list of allowed rates in the server.

-

-@PAR@ client.conf  node.lock-rate = false

-When the node is active, the rate of the graph will not change automatically. It is still possible to force a rate change with metadata or with a node property.

-

-@PAR@ client.conf  node.force-rate = RATE

-\parblock

-When the node is active, force a specific sample rate on the graph. The last node to activate with this property wins.

-

-A RATE of 0 means to force the rate in `node.rate` denominator.

-\endparblock

-

-@PAR@ client.conf  node.always-process = false

-\parblock

-When the node is active, it will always be joined with a driver node, even when nothing is linked to the node.

-Setting this property to true also implies node.want-driver = true.

-

-This is the default for JACK nodes, that always need their process callback called.

-\endparblock

-

-@PAR@ client.conf  node.want-driver = true

-The node wants to be linked to a driver so that it can start processing. This is the default for streams

-and filters since 0.3.51. Nodes that are not linked to anything will still be set to the idle state,

-unless node.always-process is set to true.

-

-@PAR@ client.conf  node.pause-on-idle = false

-@PAR@ client.conf  node.suspend-on-idle = false

-\parblock

-When the node is not linked anymore, it becomes idle. Normally idle nodes keep processing and are suspended by the session manager after some timeout.  It is possible to immediately pause a node when idle with this property.

-

-When the session manager does not suspend nodes (or when there is no session manager), the node.suspend-on-idle property can be used instead.

-\endparblock

-

-@PAR@ client.conf  node.loop.name = null

-@PAR@ client.conf  node.loop.class = data.rt

-\parblock

-Add the node to a specific loop name or loop class. By default the node is added to the

-data.rt loop class. You can make more specific data loops and then assign the nodes to those.

-

-Other well known names are main-loop.0 and the main node.loop.class which runs the node data processing

-in the main loop.

-\endparblock

-

-## Session Manager Properties  @IDX@ client.conf

-

-@PAR@ client.conf  node.autoconnect = true

-Instructs the session manager to automatically connect this node to some other node, usually

-a sink or source.

-

-@PAR@ client.conf  node.exclusive = false

-If this node wants to be linked exclusively to the sink/source.

-

-@PAR@ client.conf  node.target = <node.name|object.id>

-Where this node should be linked to. This can be a node.name or an object.id of a node. This property is 

-deprecated, the target.object property should be used instead, which uses the more unique object.serial as

-a possible target.

-

​

@@ -41,8 +41,9 @@

 # JACK PROPERTIES  @IDX@ jack.conf

 The configuration file can contain an extra JACK specific section called `jack.properties` like this:

-```

-...

+```css

+# ~/.config/pipewire/jack.conf.d/custom.conf

+

 jack.properties = {

     #rt.prio             = 88

     #node.latency        = 1024/48000

@@ -204,7 +205,9 @@

 Add a `jack.rules` section in the config file like this:

-```

+```css

+# ~/.config/pipewire/jack.conf.d/custom.conf

+

 jack.rules = 

     {

         matches = 

​

@@ -0,0 +1,1155 @@

+\page page_man_pipewire-props_7 pipewire-props

+

+PipeWire object property reference.

+

+\tableofcontents

+

+# DESCRIPTION

+

+PipeWire describes and configures audio and video elements with

+objects of the following main types:

+

+\par Node

+Audio or video sink/source endpoint

+

+\par Device

+Sound cards, bluetooth devices, cameras, etc. May have multiple nodes.

+

+\par Monitor

+Finding devices and handling hotplugging

+

+\par Port

+Audio/video endpoint in a node

+

+\par Link

+Connection between ports, that transporting audio/video between them.

+

+\par Client

+Application connected to PipeWire.

+

+All objects have *properties* ("props"), most of which can be set in

+configuration files or at runtime when the object is created.

+

+Some of the properties are "common properties" (for example

+`node.description`) and can be set on all objects of the given

+type. Other properties control settings of a specific kinds of device

+or node (ALSA, Bluetooth, ...), and have meaning only for those

+objects.

+

+Usually, all the properties are configured in the session manager

+configuration.  For how to configure them, see the session manager

+documentation. In minimal PipeWire setups without a session manager,

+they can be configured via

+\ref pipewire_conf__context_objects "context.objects in pipewire.conf(5)".

+

+\see WirePlumber configuration(https://pipewire.pages.freedesktop.org/wireplumber/daemon/configuration.html)

+

+# COMMON DEVICE PROPERTIES  @IDX@ props

+

+These are common properties for devices.

+

+@PAR@ device-prop  device.name    # string

+A (unique) name for the device. It can be used by command-line and other tools to identify the device.

+

+@PAR@ device-prop  device.param.PARAM = { ... }   # JSON

+\parblock

+Set value of a device \ref spa_param_type "Param" to a JSON value when the device is loaded.

+This works similarly as \ref page_man_pw-cli_1 "pw-cli(1)" `set-param` command.

+The `PARAM` should be replaced with the name of the Param to set,

+ie. for example `device.Param.Props = { ... }` to set `Props`.

+\endparblock

+

+@PAR@ device-prop  device.plugged # integer

+\parblock

+\copydoc PW_KEY_DEVICE_PLUGGED

+\endparblock

+

+@PAR@ device-prop  device.nick # string

+\parblock

+\copydoc PW_KEY_DEVICE_NICK

+\endparblock

+

+@PAR@ device-prop  device.description # string

+\parblock

+\copydoc PW_KEY_DEVICE_DESCRIPTION

+\endparblock

+

+@PAR@ device-prop  device.serial # string

+\parblock

+\copydoc PW_KEY_DEVICE_SERIAL

+\endparblock

+

+@PAR@ device-prop  device.vendor.id # integer

+\parblock

+\copydoc PW_KEY_DEVICE_VENDOR_ID

+\endparblock

+

+@PAR@ device-prop  device.vendor.name # string

+\parblock

+\copydoc PW_KEY_DEVICE_VENDOR_NAME

+\endparblock

+

+@PAR@ device-prop  device.product.id # integer

+\parblock

+\copydoc PW_KEY_DEVICE_PRODUCT_NAME

+\endparblock

+

+@PAR@ device-prop  device.product.name # string

+\parblock

+\copydoc PW_KEY_DEVICE_PRODUCT_ID

+\endparblock

+

+@PAR@ device-prop  device.class # string

+\parblock

+\copydoc PW_KEY_DEVICE_CLASS

+\endparblock

+

+@PAR@ device-prop  device.form-factor # string

+\parblock

+\copydoc PW_KEY_DEVICE_FORM_FACTOR

+\endparblock

+

+@PAR@ device-prop  device.icon # string

+\parblock

+\copydoc PW_KEY_DEVICE_ICON

+\endparblock

+

+@PAR@ device-prop  device.icon-name # string

+\parblock

+\copydoc PW_KEY_DEVICE_ICON_NAME

+\endparblock

+

+@PAR@ device-prop  device.intended-roles # string

+\parblock

+\copydoc PW_KEY_DEVICE_INTENDED_ROLES

+\endparblock

+

+@PAR@ device-prop  device.disabled = false  # boolean

+Disable the creation of this device in session manager.

+

+

+There are other common `device.*` properties for technical purposes

+and not usually user-configurable.

+

+\see pw_keys in the API documentation for a full list.

+

+# COMMON NODE PROPERTIES @IDX@ props

+

+The properties here apply to general audio or video input/output

+streams, and other nodes such as sinks or sources corresponding to

+real or virtual devices.

+

+## Identifying Properties  @IDX@ props

+

+These contain properties to identify the node or to display the node in a GUI application.

+

+@PAR@ node-prop  node.name

+A (unique) name for the node. This is usually set on sink and sources to identify them

+as targets for linking by the session manager.

+

+@PAR@ node-prop  node.description

+A human readable description of the node or stream.

+

+@PAR@ node-prop  media.name

+A user readable media name, usually the artist and title.

+These are usually shown in user facing applications

+to inform the user about the current playing media.

+

+@PAR@ node-prop  media.title

+A user readable stream title.

+

+@PAR@ node-prop  media.artist

+A user readable stream artist

+

+@PAR@ node-prop  media.copyright

+User readable stream copyright information

+

+@PAR@ node-prop  media.software

+User readable stream generator software information

+

+@PAR@ node-prop  media.language

+Stream language in POSIX format. Ex: `en_GB`

+

+@PAR@ node-prop  media.filename

+File name for the stream

+

+@PAR@ node-prop  media.icon

+Icon for the media, a base64 blob with PNG image data

+

+@PAR@ node-prop  media.icon-name

+An XDG icon name for the media. Ex: `audio-x-mp3`

+

+@PAR@ node-prop  media.comment

+Extra stream comment

+

+@PAR@ node-prop  media.date

+Date of the media

+

+@PAR@ node-prop  media.format

+User readable stream format information

+

+@PAR@ node-prop  object.linger = false

+If the object should outlive its creator.

+

+@PAR@ node-prop  device.id

+ID of the device the node belongs to.

+

+## Classifying Properties  @IDX@ props

+

+The classifying properties of a node are use for routing the signal to its destination and

​

@@ -74,6 +74,8 @@

 ## Example

 ```css

+# ~/.config/pipewire/pipewire-pulse.conf.d/custom.conf

+

 stream.properties = {

     #node.latency = 1024/48000

     #node.autoconnect = true

@@ -124,6 +126,8 @@

 ## Example

 ```css

+# ~/.config/pipewire/pipewire-pulse.conf.d/custom.conf

+

 pulse.rules = 

     {

         # skype does not want to use devices that don't have an S16 sample format.

@@ -154,7 +158,8 @@

 `pipewire-pulse.conf`.

 ```css

-...

+# ~/.config/pipewire/pipewire-pulse.conf.d/custom.conf

+

 pulse.cmd = 

     { cmd = "load-module" args = "module-always-sink" flags =   }

     { cmd = "load-module" args = "module-switch-on-connect" }

​

@@ -53,7 +53,9 @@

 A configuration file `~/.config/pipewire/pipewire.conf.d/custom.conf`

 to change the value of the `default.clock.min-quantum` setting in `pipewire.conf`:

-```css

+```

+# ~/.config/pipewire/pipewire.conf.d/custom.conf

+

 context.properties = {

     default.clock.min-quantum = 128

 }

@@ -172,7 +174,9 @@

 @PAR@ pipewire.conf  context.data-loops =  ... 

 This controls the data loops that will be created for the context. Is is an array of

 data loop specifications, one entry for each data loop to start:

-```json

+```

+# ~/.config/pipewire/pipewire.conf.d/custom.conf

+

 context.data-loops = 

     {

          #library.name.system = support/libspa-support

@@ -310,7 +314,9 @@

 ## Example

-```json

+```

+# ~/.config/pipewire/pipewire.conf.d/custom.conf

+

 context.spa-libs = {

     audio.convert.* = audioconvert/libspa-audioconvert

     avb.*           = avb/libspa-avb

@@ -330,7 +336,9 @@

 PipeWire modules to be loaded. See

 \ref page_man_libpipewire-modules_7 "libpipewire-modules(7)".

-```json

+```

+# ~/.config/pipewire/pipewire.conf.d/custom.conf

+

 context.modules = 

     #{ name = MODULENAME

     #    ( args  = { KEY = VALUE ... } )

@@ -361,7 +369,9 @@

 The `context.objects` section allows you to make some objects from factories (usually created

 by loading modules in `context.modules`).

-```json

+```

+# ~/.config/pipewire/pipewire.conf.d/custom.conf

+

 context.objects = 

     #{ factory = <factory-name>

     #    ( args  = { <key> = <value> ... } )

@@ -391,7 +401,9 @@

 This fragment creates a new dummy driver node, but only if

 `core.daemon` property is true:

-```json

+```

+# ~/.config/pipewire/pipewire.conf.d/custom.conf

+

 context.objects = 

     { factory = spa-node-factory

       args = {

@@ -410,7 +422,9 @@

 The `context.exec` section can be used to start arbitrary commands as

 part of the initialization of the PipeWire program.

-```json

+```

+# ~/.config/pipewire/pipewire.conf.d/custom.conf

+

 context.exec = 

     #{   path = <program-name>

     #    ( args = "<arguments>" |  <arg1> <arg2> ...  )

@@ -434,7 +448,9 @@

 The following fragment executes a pactl command with the given arguments:

-```json

+```

+# ~/.config/pipewire/pipewire.conf.d/custom.conf

+

 context.exec = 

     { path = "pactl" args = "load-module module-always-sink" }

@@ -447,7 +463,7 @@

 stream) is created/updated that matches certain properties.

 The general rules object follows the following pattern:

-```json

+```css

 <rules> = 

     {

         matches = 

@@ -494,7 +510,7 @@

 In the matches array, it is also possible to use regular expressions to match property values.

 For example, to match all nodes with a name that starts with my_, you can use the following condition:

-```

+```css

 matches = 

   {

     node.name = "~my_.*"

@@ -508,7 +524,7 @@

 In addition to regular expressions, you may also use the ! character to negate a condition. For

 example, to match all nodes with a name that does not start with my_, you can use the following condition:

-```

+```css

 matches = 

   {

     node.name = "!~my_.*"

@@ -519,7 +535,7 @@

 The ! character can be used with or without a regular expression. For example, to match all

 nodes with a name that is not equal to my_node, you can use the following condition:

-```

+```css

 matches = 

   {

     node.name = "!my_node"

@@ -530,7 +546,7 @@

 The null value has a special meaning; it checks if the property is not available

 (or unset). To check if a property is not set:

-```

+```css

 matches = 

   {

     node.name = null

@@ -540,7 +556,7 @@

 To check the existence of a property, one can use the !null condition, for example:

-```

+```css

 matches = 

   {

     node.name = "!null"

@@ -553,7 +569,7 @@

 To handle the "null" string, one needs to escape the string. For example, to check

 if a property has the string value "null", use:

-```

+```css

 matches = 

   {

     node.name = "null"

@@ -562,7 +578,7 @@

 ```

 To handle anything but the "null" string, use:

-```

+```css

 matches = 

   {

     node.name = "!\"null\""

@@ -583,7 +599,9 @@

 The `cpu.vm.name` is automatically set when running in a VM with the name of

 the VM. A match rule can be written to set custom properties like this:

-```

+```css

+# ~/.config/pipewire/pipewire.conf.d/custom.conf

+

 context.properties.rules = 

     {   matches =  { cpu.vm.name = !null } 

         actions = {

@@ -607,7 +625,9 @@

 Add a `node.rules` section in the config file like this:

-```

+```css

+# ~/.config/pipewire/pipewire.conf.d/custom.conf

+

 node.rules = 

     {

         matches = 

@@ -638,7 +658,9 @@

 Add a `device.rules` section in the config file like this:

-```

+```css

+# ~/.config/pipewire/pipewire.conf.d/custom.conf

+

 device.rules = 

     {

         matches = 

​

@@ -0,0 +1,51 @@

+\page page_config_xref Index

+

+\ref page_man_pipewire_conf_5 "pipewire.conf"

+

+@SECREF@ pipewire.conf

+

+\ref page_man_pipewire-pulse_conf_5 "pipewire-pulse.conf"

+

+@SECREF@ pipewire-pulse.conf

+

+\ref page_man_pipewire-client_conf_5 "client.conf, client-rt.conf"

+

+@SECREF@ client.conf

+

+\ref page_man_pipewire-jack_conf_5 "jack.conf"

+

+@SECREF@ jack.conf

+

+**Runtime settings**

+

+@SECREF@ pipewire-settings

+

+**Environment variables**

+

+@SECREF@ pipewire-env client-env jack-env pulse-env

+

+**Object properties**

+

+@SECREF@ props

+

+**Monitor properties**

+

+@SECREF@ monitor-prop

+

+**Device properties**

+

+@SECREF@ device-prop

+

+**Node properties**

+

+@SECREF@ node-prop

+

+**Port properties**

+

+@SECREF@ port-prop

+

+**Client properties**

+

+@SECREF@ client-prop

+

+\see pw_keys in API documentation.

​

@@ -89,6 +89,8 @@

   \ref SPA_CHOICE_Enum. In this case announce the \ref SPA_PARAM_Buffers accordingly

   to the selected format and modifier. It is important to query the plane count

   of the used format modifier pair and set `SPA_PARAM_BUFFERS_blocks` accordingly.

+  You might also want to add the option of adding explicit sync support to the

+  buffers, as explained below.

 Note: When test allocating a buffer, collect all possible modifiers, while omitting

 `DRM_FORMAT_MOD_INVALID` from the \ref SPA_FORMAT_VIDEO_modifier property and

@@ -110,7 +112,9 @@

 \ref SPA_DATA_MemPtr use the fallback SHM import mechanism.

 If it's \ref SPA_DATA_DmaBuf

 get the DMA-BUF FDs (the plane count is encoded in the `n_datas` variable of the

-`spa_buffer` struct) and import them with the graphics API.

+`spa_buffer` struct) and import them with the graphics API. Note: that the n_datas

+might also contain extra fds for things like sync_timelime metadata, you need

+to take this into account when persing the planes.

 Note: Some graphics APIs have separated functions for the modifier-less case

 (`DRM_FORMAT_MOD_INVALID`) or are omitting the modifier, since it might be used

@@ -175,4 +179,127 @@

 Note: For now v4l2 uses planar buffers without modifiers. This is the reason for

 this special case.

+# Explicit sync

+

+In addition to DMABUF, a set of synchronization primitives (a SyncObjTimeline) and

+associated metadata can be negotiated on the buffers.

+

+The explicit sync step is performed *after* the Format has been negotiated.

+

+## Query support for explicit sync in the driver.

+

+You might first want to check that the drm render you are using is capable of explicit

+sync by checking support for DRM_CAP_SYNCOBJ and DRM_CAP_SYNCOBJ_TIMELINE before

+attempting to negotiate explicit sync.

+

+## Provide space in the buffer for explicit sync

+

+Explicit sync requires two extra fds in the buffers and an extra

+\ref SPA_META_SyncTimeline metadata structure.

+

+The metadata structure will only be allocated when both sides support explicit

+sync. We can use this to make a fallback \ref SPA_PARAM_Buffers so that we can

+support both explicit sync and a fallback to implicit sync.

+

+So, first announce support for \ref SPA_META_SyncTimeline by adding the

+\ref SPA_TYPE_OBJECT_ParamMeta object to the stream:

+

+```

+  paramsn_params++ = spa_pod_builder_add_object(&b,

+           SPA_TYPE_OBJECT_ParamMeta, SPA_PARAM_Meta,

+           SPA_PARAM_META_type, SPA_POD_Id(SPA_META_SyncTimeline),

+           SPA_PARAM_META_size, SPA_POD_Int(sizeof(struct spa_meta_sync_timeline)));

+```

+

+Next make a \ref SPA_PARAM_Buffers that depends on the negotiation of the SyncTimelime metadata:

+

+```

+    spa_pod_builder_push_object(&b, &f, SPA_TYPE_OBJECT_ParamBuffers, SPA_PARAM_Buffers);

+    spa_pod_builder_add(&b,

+           SPA_PARAM_BUFFERS_buffers, SPA_POD_CHOICE_RANGE_Int(8, 2, MAX_BUFFERS),

+           SPA_PARAM_BUFFERS_blocks,  SPA_POD_Int(3),

+           SPA_PARAM_BUFFERS_size,    SPA_POD_Int(size),

+           SPA_PARAM_BUFFERS_stride,  SPA_POD_Int(data->stride),

+           SPA_PARAM_BUFFERS_dataType, SPA_POD_CHOICE_FLAGS_Int((1<<SPA_DATA_DmaBuf)),

+           0);

+    spa_pod_builder_prop(&b, SPA_PARAM_BUFFERS_metaType, SPA_POD_PROP_FLAG_MANDATORY);

+    spa_pod_builder_int(&b, 1<<SPA_META_SyncTimeline);

+    paramsn_params++ = spa_pod_builder_pop(&b, &f);

+```

+

+Note the mandatory \ref SPA_PARAM_BUFFERS_metaType with the \ref SPA_META_SyncTimeline

+bit set. This forces this buffer layout to be used when SyncTimeline metadata was

+negotiated. Also note the \ref SPA_PARAM_BUFFERS_blocks that is now set to the number

+of DMABUF planes + 2. In this case we have 1 plane/fd for the DMABUF and 2 fds for the

+SyncObjTimelines.

+

+You can also add a fallback \ref SPA_PARAM_Buffers when the \ref SPA_META_SyncTimeline

+was not negotiated:

+

+```

+    paramsn_params++ = spa_pod_builder_add_object(&b,

+       SPA_TYPE_OBJECT_ParamBuffers, SPA_PARAM_Buffers,

+       SPA_PARAM_BUFFERS_buffers, SPA_POD_CHOICE_RANGE_Int(8, 2, MAX_BUFFERS),

+       SPA_PARAM_BUFFERS_blocks,  SPA_POD_Int(1),

+       SPA_PARAM_BUFFERS_size,    SPA_POD_Int(size),

+       SPA_PARAM_BUFFERS_stride,  SPA_POD_Int(data->stride),

+       SPA_PARAM_BUFFERS_dataType, SPA_POD_CHOICE_FLAGS_Int((1<<SPA_DATA_DmaBuf)));

+```

+

+This one has just 1 data block with the DMABUF fd and plane info.

+

+## Check if SPA_META_SyncTimeline was negotiated

+

+After sending the \ref SPA_PARAM_Buffers, the buffer will be allocated by the PipeWire

+server.

+

+In the pw-stream::add_buffer event, check if the \ref SPA_META_SyncTimeline is available

+on the buffer:

+

+```

+    struct spa_meta_sync_timeline *stl;

+    stl = spa_buffer_find_meta_data(buf, SPA_META_SyncTimeline, sizeof(*stl));

+```

+

+When the metadata is available, the SyncObj fds are in the last 2 data planes

+of the buffer, the acquire and release syncobj respectively. You can keep a ref to the

+\ref struct spa_meta_sync_timeline because we will need this later when processing

+the buffers.

+

+If the producer is allocating buffers, when the stream has the \ref PW_STREAM_FLAG_ALLOC_BUFFERS

+flag, it should allocate the DMABUF and syncobj now and place them in the buffer data.

+First the plane fds and then the 2 syncobj fds.

+

+The consumer can directly use the fds. The SyncObj fds can be converted to a handle,

+for example, to make things easier later:

+

+```

+  uint32_t acquire_handle, release_handle;

+  drmSyncobjFDToHandle(drm_fd, buf->datasbuf->n_datas - 2.fd, &acquire_handle);

+  drmSyncobjFDToHandle(drm_fd, buf->datasbuf->n_datas - 1.fd, &release_handle);

+```

+

+## Use the SPA_META_SyncTimeline when processing buffers

+

+The \ref struct spa_meta_sync_timeline contains 2 fields: the acquire_point and

+release_point.

+

+Producers will start a render operation on the DMABUF of the buffer and place

+the acquire_point in the \ref struct spa_meta_sync_timeline. When the rendering is

+complete, the producer should signal the acquire_point on the acquire SyncObjTimeline.

+

+Producers will also add a release_point on the release SyncObjTimeline. They are

+only allowed to reuse the buffer when the release_point has been signaled.

+

+Consumers use the acquire_point to wait for rendering to complete before processing

+the buffer. This can be offloaded to the hardware when submitting the rendering

+operation or it can be done explicitly with drmSyncobjTimelineWait() on the acquire

+SyncObjTimeline handle and the acquire_point of the metadata.

+

+Consumers should then also signal the release_point on the release SyncObjTimeline when

+they complete processing the buffer. This can be done in the hardware as part of

+the render pipeline or explicitly with drmSyncobjTimelineSignal() on the release

+handle and the release_point of the metadata.

+

+

 */

​

@@ -10,6 +10,8 @@

 in `~/.config/pipewire/pipewire-pulse.conf.d/` containing the module

 name and its arguments

 ```

+# ~/.config/pipewire/pipewire-pulse.conf.d/custom.conf

+

 pulse.cmd = 

     { cmd = "load-module" args = "module-null-sink sink_name=foo" flags =   }

​

@@ -54,6 +54,7 @@

   'dox/pulse-modules.dox',

   'dox/programs/index.md',

   'dox/config/index.md',

+  'dox/config/xref.md',

   'dox/internals/index.dox',

   'dox/internals/design.dox',

   'dox/internals/access.dox',

@@ -88,7 +89,7 @@

   'dox/config/pipewire.conf.5.md',

   'dox/config/pipewire-client.conf.5.md',

   'dox/config/pipewire-jack.conf.5.md',

-  'dox/config/pipewire-devices.7.md',

+  'dox/config/pipewire-props.7.md',

   'dox/config/pipewire-filter-chain.conf.5.md',

   'dox/config/pipewire-pulse-modules.7.md',

   'dox/config/libpipewire-modules.7.md',