LIBPIPEWIRE-MODULE-PROTOCOL-PULSE(7)

📦
version 1.6.11 · 13 versions
, in fedora 44

🌸 libpipewire-module-protocol-pulse 🌸

okay bestie, so this is a page from the Miscellaneous Information Manual — say hi to libpipewire-module-protocol-pulse(7). she's long. she's iconic. let's get into it 💅

✨ NAME ✨

libpipewire-module-protocol-pulse — Protocol Pulse 🫶

💖 DESCRIPTION 💖

okay so boom: this module implements a whole entire PulseAudio server on top of PipeWire. like, the entire thing. no cap.

and listen — this is only the server implementation. the clients are expected to use the original PulseAudio client library. which is literally the whole point, because that gives you a high level of compatibility with existing applications. fr fr, all the usual PulseAudio tools — like pavucontrol, pactl, pamon, paplay — should just keep working exactly like they did before. they don't even know. main character energy ✨

this module is usually loaded as part of a standalone pipewire process, called pipewire-pulse, with the pipewire-pulse.conf config file. iykyk.

and one more thing bestie — the pulse server implements a sample cache that is otherwise not available in PipeWire. yeah. that one's special. 👑

🎀 MODULE NAME 🎀

libpipewire-module-protocol-pulse

🌈 MODULE OPTIONS 🌈

the module arguments can be the contents of the pulse.properties, but ngl it's recommended to make a separate pulse.properties section in the config file so that overrides can be done. do it the polite way, bestie. 💖

🦋 PULSE.PROPERTIES 🦋

a config section with server properties can be given. here's the vibe:

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

pulse.properties = {
    # the addresses this server listens on
    server.address = [
        "unix:native"
        #"unix:/tmp/something"              # absolute paths may be used
        #"tcp:4713"                         # IPv4 and IPv6 on all addresses
        #"tcp:[::]:9999"                    # IPv6 on all addresses
        #"tcp:127.0.0.1:8888"               # IPv4 on a single address
        #
        #{ address = "tcp:4713"             # address
        #  max-clients = 64                 # maximum number of clients
        #  listen-backlog = 32              # backlog in the server listen queue
        #  client.access = "restricted"     # permissions for clients
        #}
    ]
    #server.dbus-name       = "org.pulseaudio.Server"
    #pulse.allow-module-loading = true
    #pulse.min.req          = 256/48000     # 5.3ms
    #pulse.default.req      = 960/48000     # 20 milliseconds
    #pulse.min.frag         = 256/48000     # 5.3ms
    #pulse.default.frag     = 96000/48000   # 2 seconds
    #pulse.default.tlength  = 96000/48000   # 2 seconds
    #pulse.min.quantum      = 256/48000     # 5.3ms
    #pulse.default.format   = F32
    #pulse.default.position = [ FL FR ]
    #pulse.idle.timeout     = 0
}

pulse.properties.rules = [
    {   matches = [ { cpu.vm.name = !null } ]
        actions = {
            update-props = {
                # These overrides are only applied when running in a vm.
                pulse.min.quantum = 1024/48000      # 22ms
            }
        }
    }
]

💜 Connection options 💜

...
server.address = [
    "unix:native"
    # "tcp:4713"
]
...

these are the addresses the server listens on when starting. uncomment the tcp:4713 entry to also make the server listen on a tcp socket. that's equivalent to loading libpipewire-module-native-protocol-tcp, btw. ✨

there's also a slightly more verbose syntax with more options, if you're feeling extra:

....
server.address = [
  {  address = "tcp:4713"             # address
     max-clients = 64                 # maximum number of clients
     listen-backlog = 32              # backlog in the server listen queue
     client.access = "restricted"     # permissions for clients
  }
....

use client.access to use one of the access methods to restrict the permissions given to clients connected via this address. 🚧

by default network access is given the "restricted" permissions. the session manager is the one responsible for assigning permission to clients with restricted permissions (usually read-only permissions). so like, don't be surprised, that's just how it is. 💅

  • server.dbus-name = "org.pulseaudio.Server" — the DBus name to reserve for the server. if you have multiple servers, you might want to change the name. two servers, one name? not the move, bestie. 🙈
  • pulse.allow-module-loading = true — by default, clients are allowed to load and unload modules. you can disable this feature with this option. (yes, that's the default. yes, that's a choice. it's fine, it's configurable.)

🎧 Playback buffering options 🎧

  • pulse.min.req = 256/48000 # 5.3ms — the minimum amount of data to request for clients. the client requested values will be clamped to this value. lowering this value together with tlength can decrease latency if the client wants this, but it will increase CPU overhead. trade-offs, bestie, always trade-offs.
  • pulse.default.req = 960/48000 # 20 milliseconds — the default amount of data to request for clients. if the client does not specify any particular value, this default will be used. lowering this value together with tlength can decrease latency but increase CPU overhead. same deal as above, just the fallback one.
  • pulse.default.tlength = 96000/48000 # 2 seconds — the target amount of data to buffer on the server side. if the client did not specify a value, this default will be used. lower values can decrease the latency. ⚡

🌸 Record buffering options 🌸

  • pulse.min.frag = 256/48000 # 5.3ms — the minimum allowed size of the capture buffer before it is sent to a client. the requested value of the client will be clamped to this. lowering this value can reduce latency at the expense of more CPU usage. it's giving "pick your poison" but make it configurable. 😌
  • pulse.default.frag = 96000/48000 # 2 seconds — the default size of the capture buffer before it is sent to a client. if the client did not specify any value, this default will be used. lowering this value can reduce latency at the expense of more CPU usage. yeah. same energy.

⏱️ Scheduling options ⏱️

  • pulse.min.quantum = 256/48000 # 5.3ms — the minimum quantum (buffer size in samples) to use for pulseaudio clients. this value is calculated based on the frag and req/tlength for record and playback streams respectively, and then clamped to this value to ensure no pulseaudio client asks for too small quantums. lowering this value might decrease latency at the expense of more CPU usage. she said "no tiny quantums in this house". 🫶

🎨 Format options 🎨

  • pulse.default.format = F32 — some modules will default to this format when no other format was given. this is equivalent to the PulseAudio default-sample-format option in /etc/pulse/daemon.conf. ✨
  • pulse.default.position = [ FL FR ] — some modules will default to this channelmap (with its number of channels). this is equivalent to the PulseAudio default-sample-channels and default-channel-map options in /etc/pulse/daemon.conf. 🎚️

💀 Quirk options 💀

  • pulse.fix.format = "S16LE" — when a stream uses the FIX_FORMAT flag, fixate the format to this value. normally the format would be fixed to the sink/source that the stream connects to. when an invalid format (null or "") is set, the FIX_FORMAT flag is ignored.
  • pulse.fix.rate = 48000 — when a stream uses the FIX_RATE flag, fixate the sample rate to this value. normally the rate would be fixed to the sink/source that the stream connects to. when a 0 rate is set, the FIX_RATE flag is ignored.
  • pulse.fix.position = "[ FL FR ]" — when a stream uses the FIX_CHANNELS flag, fixate the channels to this value. normally the channels would be fixed to the sink/source that the stream connects to. when an invalid position (null or "") is set, the FIX_CHANNELS flag is ignored.
  • pulse.idle.timeout = 0 — okay so some clients are not sending data when they should and cause underruns. 😭 when setting this option such clients will be set to paused if they underrun for the given amount of seconds. this makes sure that sinks can suspend and save battery power. when the client resumes, it will unpause again. a value of 0 disables this feature. so 0 = feature off, periodt.

🚀 COMMAND EXECUTION 🚀

as part of the server startup sequence, a set of commands can be executed. currently, this can be used to load additional modules into the server. slay. 💅

# Extra commands can be executed here.
#   load-module : loads a module with args and flags
#      args = "<module-name> <module-args>"
#      ( flags = [ "no-fail" ] )
#      ( condition = [ { <key1> = <value1>, ... } ... ] )
# conditions will check the pulse.properties key/values.
pulse.cmd = [
    { cmd = "load-module" args = "module-always-sink" flags = [ ] }
    #{ cmd = "load-module" args = "module-switch-on-connect" condition = [ { pulse.cmd.switch-on-connect = true } ]
    #{ cmd = "load-module" args = "module-gsettings" flags = [ "nofail" ] }
]

🔥 DYNAMIC PROPERTIES 🔥

the pulse.properties can be dynamically updated with rules. it supports an update-props action. the matches will be performed on the values in context.properties. ooooh fancy, right? 👑

pulse.properties.rules = [
    {   matches = [ { cpu.vm.name = !null } ]
        actions = {
            update-props = {
                # These overrides are only applied when running in a vm.
                pulse.min.quantum = 1024/48000      # 22ms
            }
        }
    }
]

in the above example, when running in a VM, the rule will override the properties in pulse.properties with the given values. this might be interesting because VMs usually can't support the low latency settings that are possible on real hardware. real ones know 💖

🧚 STREAM SETTINGS AND RULES 🧚

streams created by module-protocol-pulse will use the stream.properties section and stream.rules sections as usual. nothing weird, nothing extra. just the standard treatment. ✨

okay bestie, that's only part one — and there is SO much more coming, so don't go anywhere. 💖✨

🎀 APPLICATION SETTINGS (RULES) 🎀

The pulse protocol module supports generic config rules, bestie. It supports a pulse.rules section with a quirks and an update-props action. These rules operate on the client properties (not the stream properties, peep the section above 👀).

# ~/.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.
        matches = [
             { application.process.binary = "teams" }
             { application.process.binary = "teams-insiders" }
             { application.process.binary = "skypeforlinux" }
        ]
        actions = { quirks = [ force-s16-info ] }
    }
    {
        # speech dispatcher asks for too small latency and then underruns.
        matches = [ { application.name = "~speech-dispatcher*" } ]
        actions = {
            update-props = {
                pulse.min.req          = 1024/48000     # 21ms
                pulse.min.quantum      = 1024/48000     # 21ms
                pulse.idle.timeout     = 5              # pause after 5 seconds of underrun
            }
        }
    }
]

💅 Quirks

The quirks action takes an array of quirks to apply for the client. It's giving ✨vibes✨-based patching, fr fr.

  • force-s16-info makes the sink and source introspect code pretend that the sample format is S16 (16 bits) samples. Some application refuse the sink/source if this is not the case. Like, they're just dramatic about it. 🙄
  • remove-capture-dont-move Removes the DONT_MOVE flag on capture streams. Some applications set this flag so that the stream can't be moved anymore with tools such as pavucontrol. So rude of them tbh.
  • block-source-volume blocks the client from updating any source volumes. This can be used to disable things like automatic gain control. No more sneaky volume gremlins. 😤
  • block-sink-volume blocks the client from updating any sink volumes.
  • block-record-stream blocks the client from creating any record stream. Not today, bestie, no recording. 🎤🚫
  • block-playback-stream blocks the client from creating any playback stream.

🦋 update-props

Takes an object with the properties to update on the client. Common actions are to tweak the quantum values. You can use the stream specific keys in pulse.properties. Slay, that's literally the whole thing. 💅

🌸 startup notification

A newline will be written into the notification file descriptor when the server has started if the following environment variable is set:

  • PIPEWIRE_PULSE_NOTIFICATION_FD

Like a little "we're up, bestie 🫶" text message to your fd. Obsessed.

🌈 EXAMPLE CONFIGURATION 🌈

Okay here's the full look, the whole fit, no notes:

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

context.modules = [
{   name = libpipewire-module-protocol-pulse
    args = { }
}
]

pulse.properties = {
    server.address = [ "unix:native" ]
}

pulse.rules = [
    {
       # skype does not want to use devices that don't have an S16 sample format.
       matches = [
            { application.process.binary = "teams" }
            { application.process.binary = "teams-insiders" }
            { application.process.binary = "skypeforlinux" }
       ]
       actions = { quirks = [ force-s16-info ] }
   }
   {
       # speech dispatcher asks for too small latency and then underruns.
       matches = [ { application.name = "~speech-dispatcher*" } ]
       actions = {
           update-props = {
               pulse.min.req          = 1024/48000     # 21ms
               pulse.min.quantum      = 1024/48000     # 21ms
               pulse.idle.timeout     = 5              # pause after 5 seconds of underrun
           }
       }
   }
]

and that's a wrap on part 2, bestie 🎀 this whole thing is from PipeWire, version 1.6.11, and the page is libpipew...col-pulse(7). thanks for reading my yapping about audio config, you ate 💅✨🦋

📦 where this page comes from