======================
bluetoothctl-transport
======================

-----------------------
Media Transport Submenu
-----------------------

:Version: BlueZ
:Copyright: Free use of this software is granted under the terms of the GNU
            Lesser General Public Licenses (LGPL).
:Date: November 2022
:Manual section: 1
:Manual group: Linux System Administration

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
