pw-link(1)

📦
version 1.6.11 · 13 versions
, in fedora 44

okay bestie, so this is pw-link, from the General Commands Manual section (section 1, the "you can literally just run this" section ✨). It's the little command that lets you list, create, and destroy links between your PipeWire ports. That's it. That's the whole vibe. It's giving patchbay but make it a CLI. 🎀

🌸 SYNOPSIS 🌸

pw-link [options] -o|-i|-l|-t [out-pattern] [in-pattern]

pw-link [options] output input

pw-link [options] -d output input

pw-link [options] -d link-id

like, pick your fighter. four whole whole entire modes, no cap. 💅

✨ DESCRIPTION ✨

List, create and destroy links between PipeWire ports.

that's literally it. that's the whole thesis statement. you see a port, you link a port, you destroy a port (if you're feeling spicy). main character energy for your audio graph fr fr. 🦋

👑 COMMON OPTIONS 👑

these are the ones that work everywhere, the ride-or-dies, the day-ones:

  • -r | --remote=NAME — the name of the remote instance you wanna monitor. if you don't specify it, it just connects to the default PipeWire instance. so like, if you only have one PipeWire, don't even worry about it bestie. 🙈
  • -h | --help — show help. the classic. when in doubt, ask for help, it's not embarrassing it's self-care. 💖
  • --version — show version information. for when you need to know exactly which build you're beefin with. ⭐

so, give it one of -o, -i or -l and it will list the matching (optional) input and output ports and their links. it's the window shopping of audio routing. you're just looking. no commitment. yet. 😌

  • -o | --output — list output ports. the talkers. the senders. the ones that go out. 🗣️
  • -i | --input — list input ports. the listeners. the receivers. the ones that take it in. 👂
  • -l | --links — list links. the actual connections. the friendships. the relationships. 🫶
  • -t | --latency — list port latencies. for when you just need to know how much delay is in the room. ⏱️
  • -m | --monitor — monitor links and ports. warning bestie: pw-link will not exit — it just sits there and monitors and prints new and destroyed ports or links. it's a watcher. it's camping in your terminal. Ctrl+C when you're done okay?? 🔥
  • -I | --id — list IDs. also lists the unique link and port ids, which you're gonna want for disconnecting or for those port-id specs. super handy, lowkey essential. 💯
  • -v | --verbose — verbose port properties. also lists the port-object-path and the port-alias. this is the "tell me everything, leave nothing out" option and we respect her for it. 💅

💜 CONNECTING PORTS 💜

without any list option (-i, -o or -l), the given ports will be linked. you're not looking anymore, you're DOING. icon behaviour. 🔥

valid port specifications are, and I need you to pay attention bestie, there are four:

  • port-id

as obtained with the -I option when listing ports. just a little number. a lil guy. 🍓

  • node-name:port-name

as obtained when listing ports. colon goes between them, don't forget it, that's the whole plot twist. 🎀

  • port-object-path

as obtained from the first alternative name for the port when listing them with the -v option. first alternative. remember which one is first. 📌

  • port-alias

as obtained from the second alternative name for the ports when listing them with the -v option. second one. yes they're different. this is the whole reason -v exists, no cap. 👑

extra options when linking can be given, and here they are:

  • -L | --linger — linger. will create a link that exists after pw-link is destroyed. and here's the tea: this is the default behaviour, unless the -m option is given. so it's the default... but monitor mode changes that. remember that. write it down. 📝
  • -P | --passive — passive link. a passive link will keep both nodes it links inactive unless another non-passive link is activating the nodes. you can use this to link a sink to a filter and have them both suspended when nothing else is linked to either of them. it's giving "I'll wake up when someone actually needs me." nap queen energy. 😴
  • -p | --props=PROPS — properties as a JSON object. give extra properties when creating the link. (the manpage says "creaing", which is a typo, and I'm telling you because I love you and because the original says it like that. the option is still -p | --props=PROPS.) 🧚

🧚 DISCONNECTING PORTS 🧚

when the -d option is given, an existing link between port is destroyed. rip to that link, you had a good run, thank you for your service. 💀

to disconnect port, a single link-id — as obtained when listing links with the -I option — or two port specifications can be given. see the connecting ports section for valid port specifications. (yes, the same four. you already know them. you're a pro now.) 🏆

  • -d | --disconnect — disconnect ports. the breakup option. mutual and consensual. 🫶

🌈 EXAMPLES 🌈

everybody loves examples, here's the demo reel:

pw-link -iol

list all port and their links. (yes, all of them. it's a lot. it's fine.) ✨

pw-link -lm

list all links and monitor changes until pw-link is stopped. it will not stop on its own. it will never stop on its own. you stop it. Ctrl+C. 💅

pw-link paplay:output_FL alsa_output.pci-0000_00_1b.0.analog-stereo:playback_FL

link the given output port to the input port. note: the original page wraps this line, so it reads alsa_output.pci-0000_00_1b.0.analog- then stereo:playback_FL on the next line — but it's one single port name, so don't you dare put a space in it. 😤

pw-link -lI

list links and their Id. 📋

pw-link -d 89

destroy the link with id 89. gone. reduced to atoms. bye bestie. 👋

⭐ AUTHORS ⭐

The PipeWire Developers

issues go here, they're literally asking you to file them: <https://gitlab.freedesktop.org/pipewire/pipewire/issues>

and PipeWire is available from: <https://pipewire.org> 🌐

(no email, no individual names, just The PipeWire Developers as a collective. mysterious. iconic. slay. 👑)

🎀 SEE ALSO 🎀

go read those next, you're already in the docs folder, might as well. 📚

friendly reminder bestie: -m | --monitor means pw-link will not exit by itself. it just keeps printing new and destroyed ports and links at you forever, and it also changes the -L | --linger default. don't leave it running in a forgotten terminal and then wonder why your tmux tab is screaming. I'm looking at you. 🙈

and that's the whole page!! you understood all of it, I'm so proud, this is your era fr fr 💖✨

pw-link(1), part of PipeWire, version 1.6.11, dated pw-link(1) — okay that last one is literally just the page name again, the footer is PipeWire 1.6.11 pw-link(1) and it's giving "signature at the bottom of a letter". anyway. that's the whole manual page, you're welcome, go link some ports. 💜🦋🌸

📦 where this page comes from