Come configurare uno script di commutazione dell'uscita audio PipeWire su Debian

Il modo più semplice e affidabile per cambiare gli output di PipeWire da uno script su Debian è utilizzare wpctllo strumento da riga di comando WirePlumber: identifica i due nodi sink che ti interessano, ispeziona il sink predefinito corrente e chiama wpctl set-default IDil comando per l'altro. Questo è preferibile all'inserimento manuale di un ID nodo numerico perché gli ID degli oggetti PipeWire possono cambiare quando i dispositivi si disconnettono, si riconnettono o la sessione viene riavviata.

Questa guida utilizza un interruttore a due dispositivi, ad esempio altoparlanti del laptop e cuffie Bluetooth, e mantiene volutamente la logica compatibile sia con le attuali versioni di Debian 13 (Trixie) che con Debian 12 (Bookworm). A ottobre 2026, le pagine dei pacchetti di Debian elencano WirePlumber 0.5.8 in Debian 13 e 0.4.13 in Debian 12. Le versioni più recenti di WirePlumber offrono funzionalità di elenco aggiuntive, ma wpctl status -n, wpctl inspect, e wpctl set-defaultsono il denominatore comune necessario in questo caso.

Quando questo metodo è adatto

Utilizza questo approccio quando PipeWire gestisce già l'audio del desktop e desideri una scorciatoia da tastiera, un launcher, un alias della shell o un tasto di scelta rapida per alternare tra due uscite. Funziona bene per un'uscita analogica integrata più un DAC USB, un monitor HDMI, un auricolare Bluetooth o un altro sink che appare nella sezione Sinkswpctl status di .

Non è lo strumento adatto per ogni problema di routing. wpctl set-defaultModifica la destinazione predefinita utilizzata per i flussi che necessitano di connessione automatica. Non garantisce che ogni applicazione già in esecuzione migrerà immediatamente un flusso esistente. Alcune applicazioni si adegueranno automaticamente alla nuova impostazione predefinita; altre potrebbero richiedere lo spostamento del flusso separatamente o il riavvio dell'applicazione.

Prima di scrivere la sceneggiatura

Verificare che la sessione PipeWire e WirePlumber a livello utente sia intatta. La documentazione ufficiale di WirePlumber consiglia di controllare il demone con systemctl --user status wireplumber. Debian consiglia inoltre il pipewire-audiometapackage su Debian 12 e versioni successive quando si configura uno stack audio PipeWire completo.

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

Se wpctlmanca, installa WirePlumber e i normali componenti audio di PipeWire anziché tentare di sostituirli con un'utilità mixer non correlata:

sudo apt update
sudo apt install pipewire-audio wireplumber

Non eseguire wpctlcon sudo. PipeWire e WirePlumber normalmente operano nella sessione dell'utente desktop, quindi il comando dovrebbe connettersi al grafico multimediale di tale utente.

Passaggio 1: Trova i nomi dei sink di output

Correre:

wpctl status -n

L' -nopzione chiede wpctldi visualizzare i nomi degli oggetti anziché descrizioni comprensibili all'uomo. In Audio → Uscite , annota i nomi delle due uscite che desideri attivare/disattivare. Una macchina potrebbe mostrare un'uscita integrata simile a alsa_output.pci-0000_00_1f.3.analog-stereoe un'uscita Bluetooth che inizia con bluez_output..

Scegliete un frammento sufficientemente distintivo da corrispondere solo all'output desiderato. Per una scheda integrata, il alsa_output...nome completo del nodo è solitamente una scelta sensata. Per un dispositivo Bluetooth, un bluez_output.frammento più breve è conveniente solo se normalmente si collega un solo dispositivo audio Bluetooth. Se si collegano frequentemente più uscite Bluetooth, è consigliabile utilizzare un frammento più lungo e univoco per il dispositivo in questione.

Passaggio 2: Verifica un sink con wpcltl inspect

Prima di creare lo script per lo switch, esamina uno degli ID mostrati da wpctl status -n:

wpctl inspect 45

Sostituisci 45con l'ID corrente sul tuo sistema. Cerca proprietà come node.namee media.class. Per un'uscita di riproduzione, media.classdovrebbe identificare un sink audio. L'ID numerico è utile per l'ispezione e per il set-defaultcomando immediato, ma lo script seguente risolve un nuovo ID ogni volta che viene eseguito.

È anche possibile chiedere a WirePlumber quale sink è attualmente quello predefinito, senza conoscerne l'ID numerico:

wpctl inspect @DEFAULT_AUDIO_SINK@

L'identificativo speciale @DEFAULT_AUDIO_SINK@è documentato da WirePlumber e si risolve in fase di esecuzione nel nodo di riproduzione predefinito corrente.

Passaggio 3: Creare uno script di attivazione/disattivazione a due uscite

Se necessario, crea una directory eseguibile personale, quindi apri lo script:

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

Incolla il seguente codice e sostituisci SINK_Ae SINK_Bcon frammenti del tuo wpctl status -noutput:

#!/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"

Perché lo script risolve gli ID ogni volta

Gli ID degli oggetti PipeWire sono oggetti di sessione, quindi trattare un ID come 45un identificatore di dispositivo permanente è inefficace. Lo script memorizza invece frammenti riconoscibili del nome del nodo, analizza la sezione Sinks corrente ed estrae l'ID numerico solo al momento del cambio.

Perché utilizza wpctl inspect per l'impostazione predefinita corrente

Lo script richiede @DEFAULT_AUDIO_SINK@il suo node.name. Ciò evita di dipendere dalla posizione visiva di un asterisco in wpctl statusquando determina quale lavandino è attualmente selezionato. Quindi confronta quel nome con SINK_Ae SINK_B.

Passaggio 4: rendere lo script eseguibile e testarlo

Salva il file, quindi eseguilo:

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

Se il sink di destinazione è disponibile, lo script dovrebbe stampare l'ID selezionato. Eseguilo di nuovo e dovrebbe scegliere l'altro sink configurato. Conferma il risultato con wpctl status -no ispezionando @DEFAULT_AUDIO_SINK@.

Nella documentazione di WirePlumber wpctl set-default ID, si imposta un sink o una sorgente come destinazione predefinita. Nelle versioni più recenti di WirePlumber, questa selezione dell'utente viene memorizzata e può avere la precedenza sulla selezione automatica basata sulla priorità. Se in seguito si desidera che WirePlumber torni alla selezione predefinita automatica, utilizzare:

wpctl clear-default

Aggiungi lo script a una scorciatoia da tastiera

Una volta verificato che il test del terminale sia affidabile, associa il comando /home/YOUR_USER/.local/bin/toggle-audio-outputa una scorciatoia da tastiera sul desktop. Utilizza il percorso assoluto anziché ~quello abbreviato, poiché alcuni gestori di scorciatoie non espandono le scorciatoie della shell. L'interfaccia utente esatta della scorciatoia dipende dall'ambiente desktop, quindi il test più importante è che lo script funzioni correttamente da un normale terminale utente.

Se un collegamento viene eseguito ma wpctlsegnala un errore di connessione, il launcher potrebbe non ereditare l'ambiente di sessione utente previsto. Verifica lo stesso comando da un terminale all'interno della sessione grafica, quindi rivedi le regole di esecuzione dei collegamenti dell'ambiente desktop. Non risolvere il problema anteponendo un punto allo script sudo.

Risoluzione dei problemi più comuni

"Nessun lavandino disponibile corrispondente"

Il target è probabilmente disconnesso, il suo nome nodo è cambiato oppure il pattern è troppo specifico. Esegui wpctl status -nnuovamente lo script e aggiorna il valore corrispondente SINK_A. SINK_BPer il Bluetooth, verifica che le cuffie siano connesse e abbiano esposto un sink audio prima di avviare lo script.

Lo script cambia l'impostazione predefinita, ma l'audio esistente continua a essere riprodotto altrove.

Questo può essere normale. La documentazione a monte descrive set-defaultla selezione della destinazione per i nuovi flussi che richiedono la connessione automatica. Se il flusso esistente di una particolare applicazione rimane sul vecchio sink, interrompere e riavviare la riproduzione o riaprire l'applicazione. Se è necessario migrare specificamente i flussi esistenti, considerarlo come un'attività di routing separata anziché dare per scontato che set-defaultsia garantita.

È stato selezionato il dispositivo Bluetooth sbagliato

Sii SINK_Bpiù specifico. Un modello generico come questo bluez_output.è adatto solo quando è presente un sink Bluetooth corrispondente. Usa il nome completo del nodo o un frammento centrale univoco quando è possibile connettere più uscite wireless contemporaneamente.

WirePlumber non è in esecuzione

Controllo:

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

La documentazione ufficiale fornisce indicazioni systemctl --user --now enable wireplumbersu quando il demone è installato ma non abilitato. Su un desktop Debian già configurato, indaga sul motivo per cui il servizio utente si è arrestato prima di riavviare ripetutamente l'intero stack audio.

Debian 12 contro Debian 13: quali sono le differenze?

Non copiate ciecamente gli esempi di configurazione di WirePlumber 0.5 in un'installazione precedente della versione 0.4. WirePlumber 0.5 ha modificato il suo sistema di configurazione; questo tutorial evita tale passaggio di versione utilizzando operazioni da riga di comando anziché file di policy persistenti.

Lista di controllo per la verifica rapida

• systemctl --user status wireplumbermostra il gestore di sessione in esecuzione.
• wpctl status -nelenca entrambe le uscite previste sotto Sink.
• wpctl inspect @DEFAULT_AUDIO_SINK@restituisce un nodo di riproduzione corrente valido.
• I due modelli di scrittura identificano in modo univoco i destinatari previsti.
• Eseguendo lo script due volte, si alterna l'impostazione predefinita tra i due output.
• Se un'applicazione esistente non viene spostata, è importante comprendere che la selezione predefinita e la migrazione dello stream attivo sono comportamenti distinti.

Riferimenti primari

Per informazioni sulla semantica dei comandi e sul comportamento attuale di WirePlumber, consultare il manuale ufficiale di WirePlumber wpctl e la guida introduttiva ufficiale di WirePlumber . Per informazioni sui pacchetti e sulla configurazione specifici per Debian, consultare la documentazione di PipeWire per Debian , la pagina del pacchetto WirePlumber per Debian 12 e la pagina del pacchetto WirePlumber per Debian 13 .