Comment configurer un script de commutation de sortie audio PipeWire sous Debian

La méthode la plus simple et fiable pour basculer entre les sorties PipeWire depuis un script sous Debian consiste à utiliser wpctll'outil en ligne de commande WirePlumber : identifiez les deux nœuds de destination souhaités, examinez le nœud de destination par défaut actuel et sélectionnez wpctl set-default IDl'autre. Cette méthode est préférable à l'utilisation d'un identifiant numérique de nœud codé en dur, car les identifiants d'objets PipeWire peuvent changer lors de la déconnexion, de la reconnexion ou du redémarrage de la session.

Ce guide utilise une bascule entre deux périphériques (par exemple, haut-parleurs d'ordinateur portable et casque Bluetooth) et a été conçu pour être compatible avec les distributions Debian 13 (Trixie) et Debian 12 (Bookworm). En octobre 2026, les pages de paquets Debian indiquaient que WirePlumber était disponible en version 0.5.8 pour Debian 13 et en version 0.4.13 pour Debian 12. Les versions plus récentes de WirePlumber offrent des fonctionnalités supplémentaires, mais les commandes `listing`, ` wpctl status -nlisting` wpctl inspectet ` wpctl set-defaultsudo` restent indispensables.

Lorsque cette méthode convient

Utilisez cette méthode lorsque PipeWire gère déjà l'audio du bureau et que vous souhaitez un raccourci clavier, un lanceur, un alias de terminal ou une touche de raccourci pour alterner entre deux sorties. Elle fonctionne bien avec une sortie analogique intégrée et un convertisseur numérique-analogique USB, un moniteur HDMI, un casque Bluetooth ou tout autre périphérique de sortie figurant dans la section « Sorties »wpctl status .

Cet outil ne convient pas à tous les problèmes de routage. wpctl set-defaultIl modifie la cible par défaut utilisée pour les flux nécessitant une connexion automatique. Il ne garantit pas que chaque application déjà en cours d'exécution migrera immédiatement un flux existant. Certaines applications adopteront automatiquement la nouvelle cible par défaut ; d'autres peuvent nécessiter un déplacement de flux séparé ou un redémarrage de l'application.

Avant d'écrire le scénario

Vérifiez que la session PipeWire et WirePlumber au niveau utilisateur fonctionne correctement. La documentation officielle de WirePlumber recommande de vérifier le démon avec la commande `ls` systemctl --user status wireplumber. Debian recommande également le pipewire-audiométapaquet `ls` sur Debian 12 et versions ultérieures lors de la configuration d'une pile audio PipeWire complète.

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

S'il wpctlest absent, installez WirePlumber et les composants audio PipeWire standard plutôt que d'essayer de les remplacer par un utilitaire de mixage non compatible :

sudo apt update
sudo apt install pipewire-audio wireplumber

Ne pas exécuter wpctlavec sudo. PipeWire et WirePlumber fonctionnent normalement dans la session de votre utilisateur de bureau ; la commande doit donc se connecter au graphe média de cet utilisateur.

Étape 1 : Trouver les noms des récepteurs de sortie

Courir:

wpctl status -n

Cette -noption permet wpctld'afficher les noms des objets plutôt que des descriptions explicites. Sous Audio → Sorties , notez les noms des deux sorties que vous souhaitez activer/désactiver. Un appareil peut afficher une sortie intégrée ressemblant à «  » alsa_output.pci-0000_00_1f.3.analog-stereoet une sortie Bluetooth commençant par «  » bluez_output..

Choisissez un fragment suffisamment distinctif pour correspondre uniquement à la sortie prévue. Pour une carte intégrée, le alsa_output...nom complet du nœud est généralement un choix judicieux. Pour un périphérique Bluetooth, un bluez_output.fragment plus court est pratique uniquement si vous n'utilisez habituellement qu'une seule sortie audio Bluetooth. Si vous connectez fréquemment plusieurs sorties Bluetooth, utilisez un fragment plus long, unique pour chaque périphérique.

Étape 2 : Vérifier un évier avec wpctl inspect

Avant de programmer le commutateur, examinez l'un des ID affichés par wpctl status -n:

wpctl inspect 45

Remplacez 45par l'identifiant actuel de votre système. Recherchez des propriétés telles que node.nameet media.class. Pour une sortie de lecture, media.classdoit identifier un périphérique de sortie audio. L'identifiant numérique est utile pour l'inspection et pour la set-defaultcommande immédiate, mais le script ci-dessous génère un nouvel identifiant à chaque exécution.

Vous pouvez également demander à WirePlumber quel évier est actuellement l'évier par défaut sans connaître son identifiant numérique :

wpctl inspect @DEFAULT_AUDIO_SINK@

Cet identifiant spécial @DEFAULT_AUDIO_SINK@est documenté par WirePlumber et se résout lors de l'exécution en un nœud de lecture par défaut actuel.

Étape 3 : Créer un script de bascule à deux sorties

Créez un répertoire exécutable personnel si nécessaire, puis ouvrez le script :

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

Collez le code suivant et remplacez `<script>` SINK_Aet ` SINK_B<script>` par des fragments de votre propre wpctl status -nsortie :

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

Pourquoi le script résout-il les identifiants à chaque fois ?

Les identifiants d'objets PipeWire étant des objets de session, les utiliser comme 45identifiants permanents de périphérique s'avère risqué. Le script stocke plutôt des fragments de nom de nœud reconnaissables, analyse la section Sinks actuelle et extrait l'identifiant numérique uniquement lors du changement de périphérique.

Pourquoi utilise-t-il wpctl inspect pour la valeur par défaut actuelle ?

Le script demande @DEFAULT_AUDIO_SINK@son nom node.name. Cela évite de dépendre de l'emplacement visuel d'un astérisque dans le nom du périphérique wpctl statuspour déterminer quel périphérique est actuellement sélectionné. Il compare ensuite ce nom avec les noms du périphérique SINK_Aet du périphérique SINK_B.

Étape 4 : Rendez le script exécutable et testez-le.

Enregistrez le fichier, puis exécutez :

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

Si le récepteur cible est disponible, le script doit afficher l'identifiant sélectionné. Exécutez-le à nouveau ; il devrait alors choisir l'autre récepteur configuré. Vérifiez le résultat en wpctl status -nconsultant le fichier `.gitignore` @DEFAULT_AUDIO_SINK@.

La documentation de WirePlumber wpctl set-default IDindique comment définir une source ou un récepteur comme cible par défaut. Dans les versions récentes de WirePlumber, ce choix est mémorisé et peut primer sur la sélection automatique basée sur les priorités. Si vous souhaitez ultérieurement que WirePlumber rétablisse la sélection par défaut automatique, utilisez :

wpctl clear-default

Ajouter le script à un raccourci clavier

Une fois le test du terminal validé, associez-le /home/YOUR_USER/.local/bin/toggle-audio-outputà un raccourci clavier. Utilisez le chemin absolu, car ~certains gestionnaires de raccourcis ne développent pas les raccourcis du shell. L'interface du raccourci dépend de l'environnement de bureau ; il est donc essentiel de vérifier que le script fonctionne correctement depuis un terminal utilisateur standard.

Si un raccourci s'exécute mais wpctlsignale une erreur de connexion, il se peut que le lanceur n'hérite pas de l'environnement de session utilisateur attendu. Vérifiez la même commande depuis un terminal dans la session graphique, puis consultez les règles d'exécution des raccourcis de l'environnement de bureau. Ne résolvez pas ce problème en préfixant le script par un point sudo.

Dépannage des pannes courantes

« Aucun évier correspondant disponible »

La cible est probablement déconnectée, son nom de nœud a changé ou votre modèle est trop spécifique. Relancez le script wpctl status -net mettez à jour la valeur correspondante SINK_A. SINK_BPour le Bluetooth, vérifiez que le casque est connecté et qu'une sortie audio est disponible avant d'exécuter le script.

Le script modifie le lecteur audio par défaut, mais le son existant continue d'être diffusé ailleurs.

Cela peut être normal. La documentation en amont décrit cette procédure set-defaultcomme la sélection de la cible pour les nouveaux flux nécessitant une connexion automatique. Si le flux existant d'une application reste sur l'ancien récepteur, arrêtez et redémarrez la lecture ou rouvrez l'application. Si vous devez migrer des flux existants, traitez cette opération comme une tâche de routage distincte plutôt que de supposer set-defaultqu'elle est garantie.

Le mauvais périphérique Bluetooth a été sélectionné.

Soyez SINK_Bplus précis. Un modèle générique comme bluez_output.celui-ci ne convient que lorsqu'un seul récepteur Bluetooth compatible est présent. Utilisez le nom complet du nœud ou un fragment central unique lorsque plusieurs sorties sans fil peuvent être connectées simultanément.

WirePlumber ne fonctionne pas.

Vérifier:

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

La documentation officielle recommande de procéder comme suit systemctl --user --now enable wireplumberlorsque le démon est installé mais non activé : sur un ordinateur Debian déjà configuré, il convient d’identifier la cause de l’arrêt du service utilisateur avant de redémarrer plusieurs fois l’ensemble du système audio.

Debian 12 contre Debian 13 : quels changements ?

Ne copiez pas aveuglément les exemples de configuration de WirePlumber 0.5 dans une installation 0.4 plus ancienne. WirePlumber 0.5 a modifié son système de configuration ; ce tutoriel contourne cette limitation de version en utilisant des opérations en ligne de commande plutôt que des fichiers de stratégie persistants.

Liste de vérification rapide

• systemctl --user status wireplumberaffiche le gestionnaire de session en cours d'exécution.
• wpctl status -nliste les deux sorties prévues sous Sinks.
• wpctl inspect @DEFAULT_AUDIO_SINK@renvoie un nœud de lecture courant valide.
• Les deux modèles de script identifient de manière unique les cibles visées.
• L'exécution du script deux fois alterne la valeur par défaut entre les deux sorties.
• Si une application existante ne migre pas, vous comprenez que la sélection par défaut et la migration du flux actif sont des comportements distincts.

Références primaires

Pour connaître la sémantique des commandes et le comportement actuel de WirePlumber, consultez le manuel officiel de WirePlumber wpctl et le guide de démarrage officiel de WirePlumber . Pour obtenir des informations sur les paquets et l'installation spécifiques à Debian, consultez la documentation Debian PipeWire , la page du paquet WirePlumber pour Debian 12 et la page du paquet WirePlumber pour Debian 13 .