audio

PipeWire: output and input volume and mute, device lists, per-app streams and Bluetooth codecs.

list {
    items = mantle.audio:map(function(audio)
        return audio.sinks
    end),
    key = function(sink) return tostring(sink.id) end,
    each = function(sink)
        return rect {
            padding = 6,
            background = sink.active and "#45475A" or "#1E1E2E",
            on_click = function() mantle.audio:set_default_sink(sink.id) end,
            children = { text { content = sink.name } },
        }
    end,
}

State

mantle.audio:get() returns AudioState, nil before the first push. A field marked ? may be absent.

mantle.audio’s payload.

AppStream

One app’s playback or recording stream. Streams without a pid are left out.

AudioCard

One ALSA or BlueZ card and every profile it offers.

AudioChannel

One sink or source channel. position is nil if PipeWire omits or does not name its channel map.

AudioDevice

One sinks or sources entry.

CardPort

One entry of AudioCard.ports: a place a card routes sound, such as speakers or headphones.

CardProfile

One entry of AudioCard.profiles.

PortDirection

Whether a port plays or records.

Actions

Call each as mantle.audio:<action>(arguments...); ? marks an argument you may omit.

VirtualDevice

One set_virtual_devices entry.

VirtualKind

What makes a virtual device.

Backend

PipeWire’s native API, on one thread shared with privacy.

The first push waits until PipeWire has reported every object and its volume, so a machine with no audio hardware still gets one push of empty lists. An unreachable PipeWire is logged and audio stays nil until it comes up. A lost connection pushes empty lists, the same as no hardware. Either way the Supervisor retries after 1 s, doubling to every 30 s, and the first push after it reconnects is a full one.

Writes are not optimistic: state changes when PipeWire reports the new value. An action with no target (a stale id, or a volume write or mute toggle before that device’s first report) is dropped with a debug log. Volume, mute and balance writes go to the device named, which need not be the default.

How do I…

Change volume on the scroll wheel, mute on middle click

A handler reads with :get(): it needs the value now, not a binding (input). The default output is the active entry of sinks.

local function default_sink(audio)
    for _, sink in ipairs(audio and audio.sinks or {}) do
        if sink.active then
            return sink
        end
    end
end

rect {
    on_wheel = function(_, steps)
        local sink = default_sink(mantle.audio:get())
        if sink == nil or sink.volume == nil then
            return
        end
        mantle.audio:set_volume(sink.id, math.max(0, math.min(100, sink.volume + steps * 5)))
    end,
    on_click = function(_, which)
        local sink = default_sink(mantle.audio:get())
        if which == "middle" and sink then
            mantle.audio:toggle_mute(sink.id)
        end
    end,
    children = {
        text {
            content = mantle.audio:map(function(audio)
                local sink = default_sink(audio)
                if sink == nil or sink.volume == nil then
                    return "--"
                end
                return sink.muted and "muted" or string.format("%d%%", math.floor(sink.volume + 0.5))
            end, "--"),
        },
    },
}

Show an OSD when volume changes

on_change writes named state that a panel binds, and a timer hides the panel again:

local osd_text = state("osd_text", "")
local osd_visible = state("osd_visible", false)
local hide_timer

local function default_sink(audio)
    for _, sink in ipairs(audio.sinks) do
        if sink.active then
            return sink
        end
    end
end

mantle.audio:on_change(function(audio, previous)
    local sink, before = default_sink(audio), previous and default_sink(previous)
    if before == nil or sink == nil or sink.id ~= before.id or before.volume == nil or sink.volume == nil then
        return -- the first push, or a new default, is learned state, not a change
    end
    if sink.volume == before.volume and sink.muted == before.muted then
        return
    end
    osd_text:set(sink.muted and "Muted" or string.format("Volume %d%%", math.floor(sink.volume + 0.5)))
    osd_visible:set(true)
    if hide_timer then
        hide_timer:cancel()
    end
    hide_timer = timer(2000, function() osd_visible:set(false) end)
end)

local osd = panel {
    id = "osd",
    layer = "overlay",
    anchor = { bottom = true },
    margin = { bottom = 80 },
    visible = osd_visible,
    padding = 12,
    radius = 12,
    background = "#1E1E2ECC",
    child = text { content = osd_text, font_size = 16 },
}
return osd

See also: Volume OSD recipe.

Add a virtual sink or an echo-cancelled microphone

Declare the whole list once; each device shows up in sinks or sources like a hardware one, and args passes PipeWire’s own module arguments through:

mantle.audio:set_virtual_devices({
    { kind = "null_sink", name = "stream_mix", description = "Stream mix" },
    { kind = "echo_cancel", name = "mic_aec", description = "Microphone (echo cancelled)" },
})

return text { content = "Virtual devices declared" }

Source: supervisor/src/capabilities/audio/