.\" Automatically generated by Pandoc 2.9.2.1
.\"
.TH "BLUEALSA" "8" "August 2020" "BlueALSA v3.0.0" "System Manager\[cq]s Manual"
.hy
.SH NAME
.PP
bluealsa - Bluetooth Audio ALSA Backend
.SH SYNOPSIS
.PP
\f[B]bluealsa\f[R] [\f[I]OPTION\f[R]]\&...
.SH DESCRIPTION
.PP
\f[B]bluealsa\f[R] is a Linux daemon to give applications access to
Bluetooth audio streams using the Bluetooth A2DP, HFP and/or HSP
profiles.
It provides a D-Bus API to applications, and can be used by ALSA
applications via libasound plugins.
.SH OPTIONS
.TP
\f[B]-h\f[R], \f[B]--help\f[R]
Output a usage message and exit.
.TP
\f[B]-V\f[R], \f[B]--version\f[R]
Output the version number and exit.
.TP
\f[B]-B\f[R], \f[B]--dbus\f[R]=\f[I]NAME\f[R]
BlueALSA D-Bus service name suffix.
Without this option, \f[B]bluealsa\f[R] registers itself as an
\[lq]org.bluealsa\[rq] D-Bus service.
For more information see the EXAMPLE below.
.TP
\f[B]-S\f[R], \f[B]--syslog\f[R]
Send output to system logger (\f[B]syslogd\f[R](8)).
By default, system output is sent to stderr.
.TP
\f[B]-i\f[R], \f[B]--device\f[R]=\f[I]hciX\f[R]
HCI device to use.
Can be specified multiple times to select more than one HCI.
Because HCI numbering can change after a system reboot, this option also
accepts HCI MAC address for the \f[I]hciX\f[R] value, e.g:
\f[B]--device\f[R]=\f[I]00:11:22:33:44:55\f[R].
.TP
\f[B]-p\f[R], \f[B]--profile\f[R]=\f[I]NAME\f[R]
Enable \f[I]NAME\f[R] Bluetooth profile.
Without this option, \f[B]bluealsa\f[R] enables \f[B]a2dp-source\f[R],
\f[B]hfp-ag\f[R] and \f[B]hsp-ag\f[R].
For the list of supported profiles see the PROFILES section below.
.TP
\f[B]--a2dp-force-mono\f[R]
Force monophonic sound for A2DP profile.
.TP
\f[B]--a2dp-force-audio-cd\f[R]
Force 44.1 kHz sampling frequency for A2DP profile.
Some bluetooth devices can handle streams sampled at either 48kHz or
44.1kHz, in which case they normally default to using 48kHz.
With this option, \f[B]bluealsa\f[R] will request such a device uses
only 44.1 kHz sample rate.
.TP
\f[B]--a2dp-keep-alive\f[R]=\f[I]SEC\f[R]
Keep A2DP transport alive for \f[I]SEC\f[R] number of seconds after
streaming was closed.
This option can be useful when playing short audio files in quick
succession.
It will reduce the gap between playbacks caused by Bluetooth audio
transport acquisition.
.TP
\f[B]--a2dp-volume\f[R]
Enable native A2DP volume control.
By default \f[B]bluealsa\f[R] will use its own internal scaling
algorithm to attenuate the volume.
This option disables that internal scaling and instead passes the volume
change request to the A2DP device.
This feature can also be controlled during runtime via BlueALSA D-Bus
API.
Note that this feature might not work with all Bluetooth headsets.
.TP
\f[B]--sbc-quality\f[R]=\f[I]NB\f[R]
Set SBC encoder quality, where \f[I]NB\f[R] can be one of:
.RS
.IP \[bu] 2
\f[B]0\f[R] - low audio quality (mono: 114 kbps, stereo: 213 kbps)
.IP \[bu] 2
\f[B]1\f[R] - medium audio quality (mono: 132 kbps, stereo: 237 kbps)
.IP \[bu] 2
\f[B]2\f[R] - high audio quality (mono: 198 kbps, stereo: 345 kbps)
(\f[B]default\f[R])
.IP \[bu] 2
\f[B]3\f[R] - SBC Dual Channel HD (SBC XQ) (452 kbps)
.RE
.TP
\f[B]--mp3-quality\f[R]=\f[I]NB\f[R]
Selects LAME encoder internal algorithm.
The \f[I]NB\f[R] can be in the range from \f[B]0\f[R] to \f[B]9\f[R],
where \f[B]0\f[R] is the best quality but requires a lot of CPU power.
Default value is \f[B]5\f[R].
.TP
\f[B]--mp3-vbr-quality\f[R]=\f[I]NB\f[R]
Specifies variable bit rate (VBR) quality, where \f[I]NB\f[R] can be in
the range from \f[B]0\f[R] to \f[B]9\f[R].
For best VBR quality use \f[B]0\f[R].
Default value is \f[B]2\f[R] (hight quality VBR mode).
.TP
\f[B]--aac-afterburner\f[R]
Enables Fraunhofer AAC afterburner feature, which is a type of analysis
by synthesis algorithm.
This feature increases the audio quality at the cost of increased
processing power and overall memory consumption.
.TP
\f[B]--aac-latm-version\f[R]=\f[I]NB\f[R]
Select LATM syntax version used for AAC audio transport.
Default value is \f[B]1\f[R].
.RS
.PP
The \f[I]NB\f[R] can be one of:
.IP \[bu] 2
\f[B]0\f[R] - LATM syntax specified by ISO-IEC 14496-3 (2001), should
work with all older BT devices
.IP \[bu] 2
\f[B]1\f[R] - LATM syntax specified by ISO-IEC 14496-3 (2005), should
work with newer BT devices
.RE
.TP
\f[B]--aac-vbr-mode\f[R]=\f[I]NB\f[R]
Specifies AAC encoder variable bit rate (VBR) quality, or disables it.
The \f[I]NB\f[R] can be one of:
.RS
.IP \[bu] 2
\f[B]0\f[R] - disables variable bit rate mode and uses constant bit rate
specified by the A2DP AAC configuration
.IP \[bu] 2
\f[B]1\f[R] - lowest quality VBR mode (mono: 32 kbps, stereo: 40 kbps)
.IP \[bu] 2
\f[B]2\f[R] - low quality VBR mode (mono: 40 kbps, stereo: 64 kbps)
.IP \[bu] 2
\f[B]3\f[R] - medium quality VBR mode (mono: 56 kbps, stereo: 96 kbps)
.IP \[bu] 2
\f[B]4\f[R] - high quality VBR mode (mono: 72 kbps, stereo: 128 kbps)
(\f[B]default\f[R])
.IP \[bu] 2
\f[B]5\f[R] - highest quality VBR mode (mono: 112 kbps, 192 kbps)
.RE
.TP
\f[B]--ldac-abr\f[R]
Enables LDAC adaptive bit rate, which will dynamically adjust encoder
quality based on the connection stability.
.TP
\f[B]--ldac-eqmid\f[R]=\f[I]NB\f[R]
Specifies LDAC encoder quality, where \f[I]NB\f[R] can be one of:
.RS
.IP \[bu] 2
\f[B]0\f[R] - high quality (44.1 kHz: 909 kbps, 48 kHz: 990 kbps)
.IP \[bu] 2
\f[B]1\f[R] - standard quality (44.1 kHz: 606 kbps, 48 kHz: 660 kbps)
(\f[B]default\f[R])
.IP \[bu] 2
\f[B]2\f[R] - mobile quality (44.1 kHz: 303 kbps, 48 kHz: 330 kbps)
.RE
.SH PROFILES
.PP
BlueALSA provides support for Bluetooth Advanced Audio Distribution
Profile (A2DP), Hands-Free Profile (HFP) and Headset Profile (HFP).
A2DP profile is dedicated for streaming music (i.e.\ stereo, 48 kHz or
more sampling frequency), while HFP and HSP for two-way voice
transmission (mono, 8 kHz or 16 kHz sampling frequency).
With A2DP, BlueALSA includes mandatory SBC codec and various optional
codecs like AAC, aptX, and other.
The full list of available optional codecs, which depends on selected
compilation options, will be shown with \f[B]bluealsa\f[R] command-line
help message.
.PP
The list of profile \f[I]NAME\f[R]s accepted by the
\f[B]--profile\f[R]=\f[I]NAME\f[R] option:
.IP \[bu] 2
\f[B]a2dp-source\f[R] - Advanced Audio Source (streaming audio to
connected device)
.IP \[bu] 2
\f[B]a2dp-sink\f[R] - Advanced Audio Sink (receiving audio from
connected device)
.IP \[bu] 2
\f[B]hfp-ofono\f[R] - Hands-Free handled by oFono
.IP \[bu] 2
\f[B]hfp-hf\f[R] - Hands-Free
.IP \[bu] 2
\f[B]hfp-ag\f[R] - Hands-Free Audio Gateway
.IP \[bu] 2
\f[B]hsp-hs\f[R] - Headset
.IP \[bu] 2
\f[B]hsp-ag\f[R] Headset Audio Gateway
.PP
The \f[B]hfp-ofono\f[R] is available only when \f[B]bluealsa\f[R] was
compiled with oFono support.
Enabling HFP over oFono will automatically disable \f[B]hfp-hf\f[R] and
\f[B]hfp-ag\f[R].
.SH FILES
.TP
/etc/dbus-1/system.d/bluealsa.conf
BlueALSA service D-Bus policy file.
.SH EXAMPLE
.PP
Emulate Bluetooth headset with A2DP and HFP support:
.IP
.nf
\f[C]
bluealsa -p a2dp-sink -p hsp-hs
\f[R]
.fi
.PP
On systems with more than one HCI device, it is possible to expose
different profiles on different HCI devices.
A system with three HCI devices might (for example) use \f[I]hci0\f[R]
for an A2DP sink service named \[lq]org.bluealsa.sink\[rq] and both
\f[I]hci1\f[R] and \f[I]hci2\f[R] for an A2DP source service named
\[lq]org.bluealsa.source\[rq].
Such a setup might be created as follows:
.IP
.nf
\f[C]
bluealsa -B sink -i hci0 -p a2dp-sink &
bluealsa -B source -i hci1 -i hci2 -p a2dp-source &
\f[R]
.fi
.PP
Setup like this will also require a change to the BlueALSA D-Bus
configuration file in order to allow connection with BlueALSA services
with suffixed names.
Please add following lines to the BlueALSA D-Bus policy:
.IP
.nf
\f[C]
\&...
<allow send_destination=\[dq]org.bluealsa.sink\[dq] />
<allow send_destination=\[dq]org.bluealsa.source\[dq] />
\&...
\f[R]
.fi
.SH SEE ALSO
.PP
\f[B]bluetoothd\f[R](8), \f[B]bluealsa-aplay\f[R](1),
\f[B]bluealsa-rfcomm\f[R](1)
.PP
Project web site at https://github.com/Arkq/bluez-alsa
.SH COPYRIGHT
.PP
Copyright (c) 2016-2020 Arkadiusz Bokowy.
.PP
The bluez-alsa project is licensed under the terms of the MIT license.