BLUETOOTHCTL-TRANSPORT(1)

📦
version 5.87+2.git8750129efca8 · 9 versions
, in centos-stream 9

💅 bluetoothctl-transport — the media transport submenu, bestie edition

okay so real quick: this is bluetoothctl-transport(1) from the Linux System Administration manual, and it's literally the page that explains the little submenu where you manage media transports for audio streaming. You're gonna be living inside org.bluez.MediaTransport(5) energy the whole time, so buckle up 🎀

✨ NAME ✨

bluetoothctl-transport — the Media Transport Submenu, aka where the audio magic happens 🎧

🌸 SYNOPSIS 🌸

bluetoothctl [--options] [transport.commands]

This submenu is the one that manages media transports for audio streaming, and it does it all through the org.bluez.MediaTransport(5) interface. no cap, that's the whole vibe 💜

🦋 MEDIA TRANSPORT COMMANDS 🦋

🍓 list — bestie, show me what we got

Lists all the available transports. That's it. That's the command.

Usage

> list

Example — display every available media transport (A2DP, LE Audio, all of them, the whole lineup ✨)

> list

⭐ show — info dump, but make it cute

Shows you the transport information. It's pulling from the org.bluez.MediaTransport(5) properties, iykyk.

Usage

> show [transport]

Uses — org.bluez.MediaTransport(5) properties

  • [transport] — a specific transport object path (optional, and if you omit it, it just shows the current one, no biggie)

Example — show info for the currently selected transport

> show

Example — show transport information

> show /org/bluez/hci0/dev_00_11_22_33_44_55/fd0

Example — show a Broadcast Isochronous Stream transport 👑

> show /org/bluez/hci0/dev_11_22_33_44_55_66/bis1

🔥 acquire — claim it, it's yours now

Acquires the transport. Like, actually grabs it for audio streaming.

Usage

> acquire <transport> [transport1...]

Uses — org.bluez.MediaTransport(5) method Acquire

  • <transport> — the media transport object path you wanna acquire for audio streaming
  • [transport1...] — extra transport paths for multi-stream acquisition (optional, but slay if you need it)

Example — acquire a transport

> acquire /org/bluez/hci0/dev_00_11_22_33_44_55/fd0

Example — acquire multiple transports at once, main character energy

> acquire /org/bluez/hci0/dev_00_11_22_33_44_55/fd0 /org/bluez/hci0/dev_00_11_22_33_44_55/fd1

Note:

If you're running the setup with an audio server that has LE Audio support (think PipeWire), it will automatically acquire transports according to the configured roles. so you might not even have to lift a finger 💅

🌈 select — for Broadcast Sink devices only, periodt

Selects a transport. Only for transports created on a Broadcast Sink device. This moves the transport into the "broadcasting" state, pending acquire.

Usage

> select <transport> [transport1...]

Uses — org.bluez.MediaTransport(5) method Select

  • <transport> — broadcast sink transport path to move into the broadcasting state
  • [transport1...] — additional transport paths for multi-stream selection (optional)

Example — select a single Broadcast Isochronous Stream

> select /org/bluez/hci0/dev_00_11_22_33_44_55/bis1

Example — select stereo broadcast streams 🎶

> select /org/bluez/hci0/dev_00_11_22_33_44_55/bis1 /org/bluez/hci0/dev_00_11_22_33_44_55/bis2

Note:

If the select command receives a list of transports, they will first be linked using the "Links" MediaTransport property. Then they get selected one by one, by calling the "Select" MediaTransport method. After the first transport is acquired, the Broadcast Sink will create fds for the associated stream and all its links. Each link can then be acquired one by one, setting the fd for the transport and starting to receive audio. iconic behavior fr fr 🫶

The select command does not require a local endpoint to be registered beforehand. Why? Because if the setup runs with an audio server that has LE Audio support (such as PipeWire), the audio server is the one to register endpoints and the transports are created as a result. Once a transport is selected, the audio server will automatically acquire. teamwork makes the dream work ✨

🧚 unselect — nah, put it back

Unselects a transport. Again, only for transports created on a Broadcast Sink device. This moves the transport to the "idle" state, pending release by the audio server. Lowkey important detail: if the transport was acquired by bluetoothctl it can be released straight away, without having to be unselected. handy 🍓

Usage

> unselect <transport> [transport1...]
  • <transport> — broadcast sink transport path to move into the idle state
  • [transport1...] — additional transport paths for multi-stream unselection (optional)

Example — unselect a broadcast stream transport

> unselect /org/bluez/hci0/dev_00_11_22_33_44_55/bis1

Example — unselect multiple broadcast streams

> unselect /org/bluez/hci0/dev_00_11_22_33_44_55/bis1 /org/bluez/hci0/dev_00_11_22_33_44_55/bis2

Note: If you're running the setup with an audio server that has LE Audio support (such as PipeWire), it will prompt it to automatically release the transport. very demure, very mindful 💅

💜 release — letting go (growth)

Releases the transport.

Usage

> release <transport> [transport1...]

Uses — org.bluez.MediaTransport(5) method Release

  • <transport> — media transport object path to release from audio streaming
  • [transport1...] — additional transport paths for multi-stream release (optional)

Example — release a transport

> release /org/bluez/hci0/dev_00_11_22_33_44_55/fd0

Example — release multiple transports

> release /org/bluez/hci0/dev_00_11_22_33_44_55/fd0 /org/bluez/hci0/dev_00_11_22_33_44_55/fd1

Note:

Transports acquired by an audio server can only be released by said audio server. No take-backsies from you, bestie. 😭

🎀 send — file goes brrr

Sends the contents of a file. yes, literally.

Usage

> send <transport> <filename> [transport1...]
  • <transport> — media transport object path to send audio data through
  • <filename> — path to the audio file to transmit (supports WAV, MP3, PCM formats)
  • [transport1...] — additional transport paths for multi-stream sending (optional)

Example — send an encoded audio file via a transport

> send /org/bluez/hci0/dev_00_11_22_33_44_55/fd0 /home/user/music.<format>

Example — send to multiple transports simultaneously, absolute icon behavior

> send /org/bluez/hci0/dev_00_11_22_33_44_55/fd0 /home/user/stereo-left.<format> /org/bluez/hci0/dev_00_11_22_33_44_55/fd1 /home/user/stereo-rigth.<format>

🦄 receive — get it or set it

Get/Set the file to receive.

Usage

> receive <transport> [filename]
  • <transport> — media transport object path to receive audio data from
  • [filename] — path to save the received audio data (optional, shows the current one if you omit it)

Example — show the current receive file for a transport

> receive /org/bluez/hci0/dev_00_11_22_33_44_55/fd0

Example — set the file to receive audio data

> receive /org/bluez/hci0/dev_00_11_22_33_44_55/fd0 /tmp/recorded_audio.wav

Example — set the file for broadcast audio capture (note the quotes, bestie, the space in the path is not playing games) 🙈

> receive /org/bluez/hci0/dev_11_22_33_44_55_66/bis1 "/home/user/My Recordings/broadcast.wav"

🔈 volume — turn it up

Get/Set the transport volume.

Usage

> volume <transport> [value]

Uses — org.bluez.MediaTransport(5) property Volume

  • <transport> — media transport object path to control the volume for
  • [value] — volume level (0-127, optional, shows the current one if omitted)

Example — show the current volume level

> volume /org/bluez/hci0/dev_00_11_22_33_44_55/fd0

Example — set the volume to 100

> volume /org/bluez/hci0/dev_00_11_22_33_44_55/fd0 100

💫 metadata — the details, the lore

Get/Set Transport Metadata.

Usage

> metadata <transport> [value...]
  • <transport> — media transport object path
  • [value...] — metadata value as a hex string (optional, shows the current one if omitted)

Example — show the current metadata for a transport

> metadata /org/bluez/hci0/dev_00_11_22_33_44_55/fd0

Example — set a metadata value

> metadata /org/bluez/hci0/dev_00_11_22_33_44_55/fd0 0x03020100

🌟 RESOURCES 🌟

💀 REPORTING BUGS 💀

Got beef with a bug? Tell the whole class:

  • linux-bluetooth@vger.kernel.org

Free use of this software is granted under the terms of the GNU Lesser General Public Licenses (LGPL). so yes, it's free, go off 💖

and that's the page!! this icon was brought to you by BlueZ, dated November 2022 — go stream some audio, bestie 🎧✨🫶

📦 where this page comes from