bluetoothctl-transport(1)

Name
bluetoothctl-transport - Media Transport Submenu

SYNOPSIS

bluetoothctl [--options] [transport.commands]

This submenu manages media transports for audio streaming using the org.bluez.MediaTransport(5) interface.

Media Transport Commands

  list

List available transports.

    Usage
        > list

    Example Display all available media transports (A2DP, LE Audio, etc.)
        > list

  show

Show transport information.

    Usage
        > show [transport]

    Uses
        org.bluez.MediaTransport(5) properties

    [transport]
        Specific transport object path (optional, shows current if omitted)

    Example Show information for currently selected transport
        > show

    Example Show transport information
        > show /org/bluez/hci0/dev_00_11_22_33_44_55/fd0

    Example Show Broadcast Isochronous Stream transport
        > show /org/bluez/hci0/dev_11_22_33_44_55_66/bis1

  acquire

Acquire transport.

    Usage
        > acquire <transport> [transport1...]

    Uses
        org.bluez.MediaTransport(5) method Acquire

    <transport>
        Media transport object path to acquire for audio streaming

    [transport1...]
        Additional transport paths for multi-stream acquisition (optional)

    Example Acquire transport
        > acquire /org/bluez/hci0/dev_00_11_22_33_44_55/fd0

    Example Acquire multiple transports
        > 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 running the setup with an audio server that has LE Audio support (such as PipeWire) it will automatically acquire transports according to the configured roles.

  select

Select transport. For transports created on a Broadcast Sink device only. This moves the transport to the "broadcasting" state, pending acquire.

    Usage
        > select <transport> [transport1...]

    Uses
        org.bluez.MediaTransport(5) method Select

    <transport>
        Broadcast sink transport path to move to broadcasting state

    [transport1...]
        Additional transport paths for multi-stream selection (optional)

    Example Select 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. They will then be 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.

The select command does not require a local endpoint to be registered beforehand. This is 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.

  unselect

Unselect transport. For transports created on a Broadcast Sink device only. This moves the transport to the "idle" state, pending release by the audio server. If the transport was acquired by bluetoothctl it can be released straight away, without having to be unselected.

    Usage
        > unselect <transport> [transport1...]

    <transport>
        Broadcast sink transport path to move to idle state

    [transport1...]
        Additional transport paths for multi-stream unselection (optional)

    Example Unselect 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 running the setup with an audio server that has LE Audio support (such as PipeWire), it will prompt it to automatically release the transport.

  release

Release 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 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.

  send

Send contents of a file.

    Usage
        > send <transport> <filename> [transport1...]

    <transport>
        Media transport object path to send audio data through

    <filename>
        Path to audio file to transmit (supports WAV, MP3, PCM formats)

    [transport1...]
        Additional transport paths for multi-stream sending (optional)

    Example Send encoded audio file via transport
        > send /org/bluez/hci0/dev_00_11_22_33_44_55/fd0 /home/user/music.<format>

    Example Send to multiple transports simultaneously
        > 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/Set file to receive.

    Usage
        > receive <transport> [filename]

    <transport>
        Media transport object path to receive audio data from

    [filename]
        Path to save received audio data (optional, shows current if omitted)

    Example Show current receive file for transport
        > receive /org/bluez/hci0/dev_00_11_22_33_44_55/fd0

    Example Set file to receive audio data
        > receive /org/bluez/hci0/dev_00_11_22_33_44_55/fd0 /tmp/recorded_audio.wav

    Example Set file for broadcast audio capture (note quotes)
        > receive /org/bluez/hci0/dev_11_22_33_44_55_66/bis1 "/home/user/My Recordings/broadcast.wav"

  volume

Get/Set transport volume.

    Usage
        > volume <transport> [value]

    Uses
        org.bluez.MediaTransport(5) property Volume

    <transport>
        Media transport object path to control volume for

    [value]
        Volume level (0-127, optional, shows current if omitted)

    Example Show current volume level
        > volume /org/bluez/hci0/dev_00_11_22_33_44_55/fd0

    Example Set volume to 100
        > volume /org/bluez/hci0/dev_00_11_22_33_44_55/fd0 100

  metadata

Get/Set Transport Metadata.

    Usage
        > metadata <transport> [value...]

    <transport>
        Media transport object path

    [value...]
        Metadata value as hex string (optional, shows current if omitted)

    Example Show current metadata for transport
        > metadata /org/bluez/hci0/dev_00_11_22_33_44_55/fd0

    Example Set metadata value
        > metadata /org/bluez/hci0/dev_00_11_22_33_44_55/fd0 0x03020100

RESOURCES

<http://www.bluez.org>

REPORTING BUGS

<linux-bluetooth@vger.kernel.org>

Copyright
Free use of this software is granted under the terms of the GNU Lesser General Public Licenses (LGPL).