How to Configure a PipeWire Audio Output Switching Script on Debian

The simplest reliable way to switch PipeWire outputs from a script on Debian is to use wpctl, the WirePlumber command-line tool: identify the two sink nodes you care about, inspect the current default sink, and call wpctl set-default ID for the other one. This is preferable to hard-coding a numeric node ID because PipeWire object IDs can change when devices disconnect, reconnect, or the session restarts.

This guide uses a two-device toggle—for example, laptop speakers and Bluetooth headphones—and deliberately keeps the logic compatible with both current Debian 13 (Trixie) and Debian 12 (Bookworm). As of October 2026, Debian's package pages list WirePlumber 0.5.8 in Debian 13 and 0.4.13 in Debian 12. Newer WirePlumber releases provide additional listing features, but wpctl status -n, wpctl inspect, and wpctl set-default are the common denominator needed here.

When this method is a good fit

Use this approach when PipeWire is already handling desktop audio and you want a keyboard shortcut, launcher, shell alias, or hotkey to alternate between two outputs. It works well for a built-in analog output plus USB DAC, HDMI monitor, Bluetooth headset, or another sink that appears under the Sinks section of wpctl status.

It is not the right tool for every routing problem. wpctl set-default changes the default target used for streams that need automatic connection. It does not promise that every already-running application will immediately migrate an existing stream. Some applications follow the new default automatically; others may need their stream moved separately or the application restarted.

Before you write the script

Confirm that the user-level PipeWire and WirePlumber session is healthy. The official WirePlumber documentation recommends checking the daemon with systemctl --user status wireplumber. Debian also recommends the pipewire-audio metapackage on Debian 12 and newer when setting up a complete PipeWire audio stack.

systemctl --user status wireplumber
systemctl --user status pipewire pipewire-pulse

If wpctl is missing, install WirePlumber and the normal PipeWire audio components rather than trying to substitute an unrelated mixer utility:

sudo apt update
sudo apt install pipewire-audio wireplumber

Do not run wpctl with sudo. PipeWire and WirePlumber normally operate in your desktop user's session, so the command should connect to that user's media graph.

Step 1: Find the output sink names

Run:

wpctl status -n

The -n option asks wpctl to show object names instead of human-friendly descriptions. Under Audio → Sinks, note the names of the two outputs you want to toggle. A machine might show a built-in sink resembling alsa_output.pci-0000_00_1f.3.analog-stereo and a Bluetooth sink beginning with bluez_output..

Escolha um fragmento que seja suficientemente distinto para corresponder apenas à saída desejada. Para uma placa integrada, o alsa_output...nome completo do nó geralmente é uma escolha sensata. Para um dispositivo Bluetooth, um bluez_output.fragmento mais curto é conveniente apenas se você normalmente tiver apenas um dispositivo de saída de áudio Bluetooth conectado. Se você conectar frequentemente várias saídas Bluetooth, use um fragmento mais longo, exclusivo para o dispositivo em questão.

Passo 2: Verifique uma pia com o comando `wpctl inspect`.

Antes de criar o script para a troca, inspecione um dos IDs exibidos por wpctl status -n:

wpctl inspect 45

Substitua 45pelo ID atual do seu sistema. Procure por propriedades como ` node.nameid` e `id` media.class. Para uma saída de reprodução, `id` media.classdeve identificar um dispositivo de saída de áudio. O ID numérico é útil para inspeção e para o comando imediato set-default, mas o script abaixo gera um novo ID a cada execução.

Você também pode perguntar ao WirePlumber qual pia está configurada como padrão no momento, sem precisar saber seu ID numérico:

wpctl inspect @DEFAULT_AUDIO_SINK@

O identificador especial @DEFAULT_AUDIO_SINK@é documentado pelo WirePlumber e é resolvido em tempo de execução para o nó de reprodução padrão atual.

Passo 3: Crie um script de alternância de duas saídas

Crie um diretório executável pessoal, se necessário, e então abra o script:

mkdir -p ~/.local/bin
nano ~/.local/bin/toggle-audio-output

Cole o seguinte código e substitua `<code> SINK_A` e SINK_B`<code>` por fragmentos da sua própria wpctl status -nsaída:

#!/usr/bin/env bash
set -euo pipefail

# Replace these with distinctive fragments from `wpctl status -n`.
SINK_A="alsa_output.pci-0000_00_1f.3.analog-stereo"
SINK_B="bluez_output."

find_sink_id() {
    local needle="$1"
    wpctl status -n | awk -v n="$needle" '
        /Sinks:/   { in_sinks=1; next }
        /Sources:/ { in_sinks=0 }
        in_sinks && index($0, n) {
            for (i=1; i<=NF; i++) {
                if ($i ~ /^[0-9]+\.$/) {
                    gsub(/\./, "", $i)
                    print $i
                    exit
                }
            }
        }'
}

current_name="$(
    wpctl inspect @DEFAULT_AUDIO_SINK@ |
    awk -F'= ' '/node.name/ {
        gsub(/"/, "", $2)
        print $2
        exit
    }'
)"

if [[ "$current_name" == *"$SINK_A"* ]]; then
    target_pattern="$SINK_B"
elif [[ "$current_name" == *"$SINK_B"* ]]; then
    target_pattern="$SINK_A"
else
    # If the current default is neither target, switch to A first.
    target_pattern="$SINK_A"
fi

target_id="$(find_sink_id "$target_pattern")"

if [[ -z "$target_id" ]]; then
    printf 'No available sink matched: %s\n' "$target_pattern" >&2
    exit 1
fi

wpctl set-default "$target_id"
printf 'Default audio sink changed to ID %s\n' "$target_id"

Por que o script resolve os IDs sempre?

Os IDs de objeto do PipeWire são objetos de sessão, portanto, tratar um ID como 45um identificador permanente de dispositivo é frágil. O script armazena fragmentos reconhecíveis de nomes de nós, analisa a seção Sinks atual e extrai o ID numérico somente no momento da troca.

Por que ele usa o comando `wpcctl inspect` como padrão atual?

O script solicita @DEFAULT_AUDIO_SINK@o seu node.name. Isso evita depender da posição visual de um asterisco em wpctl statusao determinar qual sifão está selecionado no momento. Em seguida, ele compara esse nome com SINK_Ae SINK_B.

Passo 4: Torne o script executável e teste-o.

Salve o arquivo e execute-o:

chmod +x ~/.local/bin/toggle-audio-output
~/.local/bin/toggle-audio-output
wpctl status -n

Se o destino estiver disponível, o script deverá imprimir o ID selecionado. Execute-o novamente e ele deverá escolher o outro destino configurado. Confirme o resultado com wpctl status -nou inspecionando @DEFAULT_AUDIO_SINK@.

O WirePlumber documenta wpctl set-default IDa configuração de um destino (origem ou destino) como padrão. Nas versões modernas do WirePlumber, essa seleção do usuário é memorizada e pode ter prioridade sobre a seleção automática baseada em prioridade. Se posteriormente desejar que o WirePlumber retorne à seleção automática padrão, utilize:

wpctl clear-default

Adicione o script a um atalho de teclado.

Assim que o teste no terminal estiver funcionando corretamente, associe o script /home/YOUR_USER/.local/bin/toggle-audio-outputa um atalho de teclado na área de trabalho. Use o caminho absoluto em vez de um ~atalho físico, pois alguns programas de atalho não expandem abreviações do shell. A interface exata do atalho depende do ambiente de desktop, portanto, o importante é garantir que o script funcione corretamente em um terminal de usuário comum.

Se um atalho for executado, mas wpctlinformar que não consegue se conectar, o iniciador pode não estar herdando o ambiente de sessão de usuário esperado. Verifique o mesmo comando em um terminal dentro da sessão gráfica e, em seguida, revise as regras de execução de atalhos do ambiente de área de trabalho. Não resolva esse problema prefixando o script com ` sudo.`

Solução de problemas em falhas comuns

“Nenhuma pia disponível correspondeu ao modelo”

O alvo provavelmente está desconectado, o nome do nó foi alterado ou seu padrão é muito específico. Execute wpctl status -nnovamente e atualize o valor correspondente SINK_A. SINK_BPara Bluetooth, confirme se o fone de ouvido está conectado e se expôs uma saída de áudio antes de invocar o script.

O script altera a configuração padrão, mas o áudio existente continua sendo reproduzido em outro lugar.

Isso pode ser normal. A documentação original descreve set-defaulta seleção do destino para novos fluxos que exigem conexão automática. Se o fluxo existente de um aplicativo específico permanecer no destino antigo, interrompa e reinicie a reprodução ou abra o aplicativo novamente. Se você precisar migrar fluxos existentes, trate isso como uma tarefa de roteamento separada, em vez de presumir que o set-defaultprocesso será automático.

O dispositivo Bluetooth selecionado está incorreto.

Seja SINK_Bmais específico. Um padrão genérico como este bluez_output.só é adequado quando houver um único dispositivo de saída Bluetooth correspondente. Use o nome completo do nó ou um fragmento intermediário exclusivo quando várias saídas sem fio puderem ser conectadas simultaneamente.

O WirePlumber não está funcionando.

Verificar:

systemctl --user status wireplumber
journalctl --user -u wireplumber

A documentação oficial recomenda o uso systemctl --user --now enable wireplumberdo daemon quando este estiver instalado, mas não ativado. Em um ambiente Debian já configurado, investigue por que o serviço do usuário parou antes de reiniciar repetidamente toda a pilha de áudio.

Debian 12 versus Debian 13: quais são as mudanças?

Não copie exemplos de configuração do WirePlumber 0.5 indiscriminadamente para uma instalação antiga da versão 0.4. O WirePlumber 0.5 alterou seu sistema de configuração; este tutorial evita essa diferença de versão utilizando operações de linha de comando em vez de arquivos de política persistentes.

Lista de verificação rápida

• systemctl --user status wireplumberMostra o gerenciador de sessão em execução.
• wpctl status -nLista ambas as saídas pretendidas em Sinks.
• wpctl inspect @DEFAULT_AUDIO_SINK@Retorna um nó de reprodução atual válido.
• Os dois padrões de script identificam exclusivamente os destinos pretendidos.
• Executar o script duas vezes alterna o valor padrão entre as duas saídas.
• Caso uma aplicação existente não seja migrada, você entende que a seleção padrão e a migração de fluxo ativo são comportamentos distintos.

Referências primárias

Para obter informações sobre a semântica dos comandos e o comportamento atual do WirePlumber, consulte o manual oficial do wpctl do WirePlumber e o guia de primeiros passos oficial do WirePlumber . Para informações específicas sobre pacotes e configuração do Debian, consulte a documentação do PipeWire para Debian , a página do pacote WirePlumber para Debian 12 e a página do pacote WirePlumber para Debian 13 .