.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "BLUEALSA-PLUGINS" 7 "September 2021" "BlueALSA v4.0.0" "Miscellaneous"
.SH NAME
bluealsa-plugins \- Bluetooth Audio ALSA Plugins
.SH SYNOPSIS
.sp
BlueALSA permits applications to access Bluetooth audio devices using the ALSA alsa\-lib API. Users of those applications can then use Bluetooth speakers, headphones, headsets and hands\-free devices much as if they were local devices. This integration is achieved by two ALSA plugins, one for PCM audio streams and one for CTL volume controls.
.SH PCM PLUGIN
.sp
The BlueALSA ALSA PCM plugin communicates with the \fBbluealsa(8)\fP service. It can be used to define ALSA PCMs in your own configuration file (e.g. ~/.asoundrc), or you can use the pre\-defined \fBbluealsa\fP PCM.
.SS The Predefined \fBbluealsa\fP PCM
.sp
The simplest way to use the PCM plugin is with the predefined ALSA PCM device \fBbluealsa\fP\&. The definition of this PCM device is of type \fBplug\fP so audio format conversion, if required, is done automatically by the PCM. It has parameters DEV, PROFILE, CODEC, VOL, SOFTVOL, DELAY, and SRV. All these parameters have defaults. Parameter values in an ALSA PCM name are specified using the syntax:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
bluealsa:DEV=01:23:45:67:89:AB,PROFILE=a2dp,CODEC=aac,VOL=60,SOFTVOL=no,DELAY=0,SRV=org.bluealsa
.ft P
.fi
.UNINDENT
.UNINDENT
.SS PCM Parameters
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.TP
.B DEV
The device Bluetooth address in the form \fIXX:XX:XX:XX:XX:XX\fP\&. Device names or aliases are not valid here. The default value is \fB00:00:00:00:00:00\fP which selects the most recently connected device of the chosen profile.
.TP
.B PROFILE
May be either \fBa2dp\fP or \fBsco\fP\&. \fBsco\fP selects either Hands\-Free (HFP) or Headset (HSP) profile, whichever is connected on the selected device. The default is \fBa2dp\fP\&.
.TP
.B CODEC
Specifies the codec to be used by the profile. When a connection is established between a device and a host, BlueALSA negotiates the best available codec with the device; this parameter allows the ALSA configuration to override that selection. The default value is \fBunchanged\fP which causes the PCM to use its existing codec setting. The codec name is case insensitive; so for example \fBaptX\fP, \fBaptx\fP, and \fBAPTX\fP are all accepted. If the specified codec is not available the plugin issues a warning and uses the default value instead.
.sp
For the A2DP profile it is possible to also specify a \(dqconfiguration\(dq for the codec by appending the configuration as a hex string separated from the codec name by a colon. For example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
CODEC=aptx:4f0000000100ff
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B VOL
Specifies the initial volume for the PCM when opened. The default value is \fBunchanged\fP which causes the PCM to use its existing volume setting. The value is an integer percentage of the maximum volume [0\-100]. The mute status can also be set by appending the character \(aq\-\(aq to mute the sound or \(aq+\(aq to unmute it. The volume is not restored to its original value when the PCM is closed. For example to set the initial volume to 80% and ensure that mute is disabled for this PCM:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
VOL=80+
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B SOFTVOL
Enables or disables BlueALSA\(aqs software volume feature for this PCM. See the \fBbluealsa(8)\fP manual page for more information on software volume. This is a boolean option (values \fBon\fP or \fBoff\fP), but also accepts the special value \fBunchanged\fP which causes the PCM to use its existing softvol value. The default value is \fBunchanged\fP\&.
.TP
.B DELAY
An integer number which is added to the reported latency value in order to manually adjust the audio synchronization. It is not normally required and defaults to \fB0\fP\&.
.TP
.B SRV
The D\-Bus service name of the BlueALSA daemon. Defaults to \fBorg.bluealsa\fP\&. See \fBbluealsa(8)\fP for more information. Not normally required.
.UNINDENT
.UNINDENT
.UNINDENT
.SS Setting Different Defaults
.sp
The defaults can be overridden by defining the ones you want to change in your own configuration (e.g. in ~/.asoundrc.conf) for example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
defaults.bluealsa.device \(dq00:11:22:33:44:55\(dq
defaults.bluealsa.profile \(dqsco\(dq
defaults.bluealsa.codec \(dqcvsd\(dq
defaults.bluealsa.volume \(dq50+\(dq
defaults.bluealsa.softvol off
defaults.bluealsa.delay 5000
defaults.bluealsa.service \(dqorg.bluealsa.source\(dq
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Positional Parameters
.sp
ALSA permits arguments to be given as positional parameters as an alternative to explicitly naming them. When using positional parameters it is important that the values are given in the correct sequence \- \fIDEV\fP, \fIPROFILE\fP, \fICODEC\fP, \fIVOL\fP, \fISOFTVOL\fP, \fIDELAY\fP, \fISRV\fP\&. For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
bluealsa:01:23:45:67:89:AB,a2dp,unchanged,unchanged,unchanged,0,org.bluealsa
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
When using positional parameters defaults can only be implied at the end of the id string, so
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
bluealsa:01:23:45:67:89:AB
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
is equivalent to the full form above, but
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
bluealsa:01:23:45:67:89:AB,a2dp,,80+
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
is not permitted.
.SS Defining BlueALSA PCMs
.sp
You can define your own ALSA PCM in the ALSA configuration. To do this, create an ALSA configuration node defining a PCM with type \fBbluealsa\fP\&. The configuration node has the following fields:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
pcm.name {
  type bluealsa     # Bluetooth PCM
  device STR        # Device address in format XX:XX:XX:XX:XX:XX
  profile STR       # Profile type (a2dp or sco)
  [codec STR]       # Preferred codec
  [volume STR]      # Initial volume for this PCM
  [softvol BOOLEAN] # Enable/disable BlueALSA\(aqs software volume
  [delay INT]       # Extra delay (frames) to be reported (default 0)
  [service STR]     # DBus name of service (default org.bluealsa)
}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The \fBdevice\fP and \fBprofile\fP fields must be specified so that the plugin can select the correct Bluetooth transport; the other fields are optional. Note that the default values for the optional fields are not overridden automatically by the configuration \fBdefaults.bluealsa.*\fP in a PCM defined this way; however the configuration defaults can be referenced by use of \fB@func refer\fP (see the \fIALSA configuration file syntax\fP documentation for more information).
.sp
When choosing a name for your PCM definition, the name \fBpcm.bluealsa\fP is pre\-defined by the bluez\-alsa installation (see section \fIThe Predefined bluealsa PCM\fP above), so it should not be used as a name for your own PCM devices as doing so will most likely have unexpected or undesirable results.
.sp
Note that the \fBvolume\fP field is of type \fBstring\fP, so the value must be enclosed in double\-quotes. See the \fIPCM Parameters\fP section above for more information on each field.
.sp
Do not confuse the PCM type \fBbluealsa\fP with the PCM named \fBbluealsa\fP\&. The type does not perform any audio conversions, you will have to wrap your own defined PCMs with type \fBplug\fP to achieve that; whereas the predefined PCM \fBpcm.bluealsa\fP \fIis\fP of type \fBplug\fP\&.
.SS Name Hints
.sp
Applications that follow ALSA guidelines will obtain the list of defined PCMs by using the alsa\-lib \fBnamehints\fP API. To make BlueALSA PCMs visible via that API it is necessary to add a \(dqhint\(dq section to the ALSA configuration. If you have defined a new PCM, then the hint goes into the PCM configuration entry as follows:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
pcm.bt\-headphones {
    type plug
    slave.pcm {
        type bluealsa
        device \(dq00:11:22:33:44:55\(dq
        profile \(dqa2dp\(dq
    }
    hint {
        show on
        description \(dqMy Bluetooth headphones\(dq
    }
}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Now using \fBaplay \-L\fP will include the following in its output:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# aplay \-L
bt\-headphones
    My Bluetooth headphones
#
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If you are using the pre\-defined bluealsa PCM, then you can create a \(dqnamehint\(dq entry in your ~/.asoundrc file like this:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
namehint.pcm {
    mybluealsadevice \(dqbluealsa:DEV=00:11:22:33:44:55,PROFILE=a2dp|My Bluetooth headphones\(dq
}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Then \fBaplay \-L\fP shows
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# aplay \-L
bluealsa:DEV=00:11:22:33:44:55,PROFILE=a2dp
    My Bluetooth headphones
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
For alsa\-lib versions before v1.2.3.2, a bug in the namehint parser means that a \fBnamehint.pcm\fP entry has to be written as
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
namehint.pcm {
    mybluealsadevice \(dqbluealsa:DEV=00:11:22:33:44:55,PROFILE=a2dp|DESCMy Bluetooth headphones\(dq
}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
(note the keyword \fBDESC\fP after the pipe symbol and before the description text.)
.sp
With that hint in place, the PCM will be listed as both a Capture and Playback device. So \fBarecord \-L\fP will also list it. That is generally OK for HFP/HSP devices, but an A2DP device most often offers only Capture (e.g. a mobile phone) or only Playback (e.g. a Bluetooth speaker). It is possible to use the hint description to limit the listing to only one direction using an undocumented syntax of ALSA configuration files.
.sp
If the hint.description value ends with \fB|IOIDInput\fP the PCM will only show in listings of Capture devices; if it ends with \fB|IOIDOutput\fP the PCM will only show in listings of Playback devices.
.sp
So we can modify our example above to:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
pcm.bt\-headphones {
    type plug
    slave.pcm {
        type bluealsa
        device \(dq00:11:22:33:44:55\(dq
        profile \(dqa2dp\(dq
    }
    hint {
        show on
        description \(dqMy Bluetooth headphones|IOIDOutput\(dq
    }
}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
or
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
namehint.pcm {
    mybluealsadevice \(dqbluealsa:DEV=00:11:22:33:44:55,PROFILE=a2dp|My Bluetooth headphones|IOIDOutput\(dq
}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Now the \fBaplay \-L\fP output will be exactly the same as before, but \fBarecord \-L\fP will not include bt\-headphones in its output.
.sp
When using the \fBnamehint.pcm\fP method, the key (\fBmybluealsadevice\fP in the above example) must be unique but otherwise is not used. The first part of the value string, before the pipe | symbol, is the string that is to be passed to ALSA applications to identify the PCM (e.g. with \fBaplay \-D ...\fP). The next section, after the pipe symbol, is the description that will be presented to the user. The optional \fB|IOID\fP section is not included in the description given to the application.
.SH CTL PLUGIN
.sp
The BlueALSA ALSA CTL plugin can be used to define ALSA CTLs (mixer devices) in your own configuration file (e.g. ~/.asoundrc), or you can use the pre\-defined configuration that is included in the bluez\-alsa project.
.sp
A BlueALSA CTL device has no associated soundcard, so \fBalsamixer\fP will not list it in its F6 menu. It can be selected either by starting \fBalsamixer\fP with
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
alsamixer \-D bluealsa
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
or by selecting \(dqenter device name ..\(dq on the F6 menu then typing out \(dqbluealsa\(dq in the \(dqDevice Name\(dq box.
.sp
The CTL has two operating modes, \fBDefault\fP mode and \fBSingle Device\fP mode.
.SS Default Mode
.sp
In this mode when a device connects, the mixer will create new controls for it, and when a device disconnects, the mixer will remove its controls. \fBalsamixer(1)\fP will show these changes dynamically.
.sp
Control names are constructed by combining the device Bluetooth alias with either the profile type (\(aqA2DP\(aq or \(aqSCO\(aq) of the controlled PCM or the word \(dqBattery\(dq for battery level indicators. If two or more connected devices have the same alias then an index number is added to the name to make it unique.
.sp
The Bluetooth \(dqalias\(dq of a device is by default the same as its \(dqname\(dq. The name is a string defined by the device manufacturer and embedded in its firmware. Typically two identical devices will have identical names. The \(dqalias\(dq is created by BlueZ and stored locally on the host computer. So the alias can be changed using a tool such as \fBbluetoothctl(1)\fP to make it unique if desired. As manufacturers tend to use long names for their devices the alias can also be useful to give a short \(dqnickname\(dq to a device.
.sp
Although this default mode works well with \fBalsamixer\fP, there are some limitations that may make it unsuitable for some applications. In particular:
.INDENT 0.0
.IP \(bu 2
If device aliases are not unique then the index number associated with each is not easily predictable in advance; so it can be difficult to programmatically associate a PCM with its volume control.
.IP \(bu 2
A consequence of the alsa\-lib implementation of controls is that when one Bluetooth device connects or disconnects it is necessary to remove all controls from all devices in the mixer and create a new set. This invalidates pointers held by applications and can cause application crashes. (Hardware sound cards do not have randomly appearing and disappearing controls, so many, or even most, applications are not programmed correctly to deal with it.)
.UNINDENT
.SS Single Device Mode
.sp
The BlueALSA CTL also implements an alternative mode that presents controls only for one specified device. In this case the control names are simply the profile type of the controlled PCM (\(aqA2DP\(aq or \(aqSCO\(aq) or the word \(dqBattery\(dq. There is never any need for index suffixes or device alias. Immediately this overcomes the two main issues of the default mode.
.sp
Single device mode is achieved by including the device Bluetooth address as an argument to the ALSA device id, for example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
alsamixer \-D bluealsa:00:11:22:33:44:55
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
A notable difference between single\-device mode and the default mode is in the cases of the device not being connected when the mixer is opened, and when the device disconnects while the mixer is open.
.sp
For the default mode, the mixer will still open, even if no devices are connected, but will display no controls. In single device mode the open request will fail with an error message.
.sp
Similarly, in default mode when a device disconnects the mixer remains open but removes the set of controls and creates a new control set without the disconnected device. That new set will be empty if no devices remain. If the device then re\-connects the mixer will again create a new set of controls with the newly connected device included.
.sp
In single device mode when its device disconnects then the mixer will close. The \fBalsamixer\fP application will continue running with no associated device or controls, but will not automatically re\-open the mixer if the device re\-connects. The user can use F6 to open a new device.
.sp
As a special case, a single device mixer can be opened with the address \fB00:00:00:00:00:00\fP\&. This will create a mixer with controls for the most recently connected device at the time the mixer is opened. Once created, that mixer behaves the same as if it had been opened with the actual address of the device: it does not change to a new device if another is subsequently connected.
.SS The Predefined \fBbluealsa\fP CTL
.sp
The \fBbluealsa\fP CTL has parameters DEV, BAT, and SRV. All the parameters have defaults.
.SS CTL Parameters
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.TP
.B DEV
The device Bluetooth address in the form XX:XX:XX:XX:XX:XX. Device names or aliases are not valid here. The default value is \fBFF:FF:FF:FF:FF:FF\fP which selects controls from all connected devices (see \fIDefault Mode\fP above). Also accepts the special address \fB00:00:00:00:00:00\fP which selects the most recently connected device.
.TP
.B BAT
Causes the plugin to include a (read\-only) battery level indicator, provided the device supports this. If the value is \fByes\fP then the battery indicator is enabled, any other value disables it. The default is \fByes\fP
.TP
.B SRV
The D\-Bus service name of the BlueALSA daemon. Defaults to \fBorg.bluealsa\fP\&. See \fBbluealsa(8)\fP for more information.
.UNINDENT
.UNINDENT
.UNINDENT
.sp
The default values can be overridden in the ALSA configuration, for example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
defaults.bluealsa.ctl.device \(dq00:11:22:33:44:55\(dq
defaults.bluealsa.ctl.battery \(dqno\(dq
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Defining BlueALSA CTLs
.sp
You can define your own ALSA CTL in the ALSA configuration. To do this, create an ALSA configuration node defining a CTL with type \fBbluealsa\fP\&. The configuration node has the following fields:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
ctl.name {
  type bluealsa # Bluetooth PCM
  [device STR]  # Device address (default \(dqFF:FF:FF:FF:FF:FF\(dq)
  [battery STR] # Include battery level indicator (yes/no, default no)
  [service STR] # D\-Bus name of service (default \(dqorg.bluealsa\(dq)
}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
All the fields (except \fBtype\fP) are optional. See the \fICTL Parameters\fP section above for more information on each field. Note that the \fBbattery\fP default value is \fBno\fP when used in this way. As for PCM definitions above, the default values for the optional fields are hard\-coded into the plugin; they are not overridden by the configuration \fBdefaults.bluealsa.\fP settings.
.SH FILES
.INDENT 0.0
.TP
.B /etc/alsa/conf.d/20\-bluealsa.conf
BlueALSA device configuration file.
ALSA additional configuration, defines the \fBbluealsa\fP PCM and CTL devices.
.UNINDENT
.SH SEE ALSO
.sp
\fBalsamixer(1)\fP, \fBaplay(1)\fP, \fBbluealsa(8)\fP, \fBbluetoothctl(1)\fP, \fBbluetoothd(8)\fP
.INDENT 0.0
.TP
.B Project web site
\fI\%https://github.com/Arkq/bluez\-alsa\fP
.TP
.B ALSA configuration file syntax
\fI\%https://www.alsa\-project.org/alsa\-doc/alsa\-lib/conf.html\fP
.TP
.B ALSA built\-in PCM plugins reference
\fI\%https://www.alsa\-project.org/alsa\-doc/alsa\-lib/pcm_plugins.html\fP
.UNINDENT
.SH COPYRIGHT
.sp
Copyright (c) 2016\-2021 Arkadiusz Bokowy.
.sp
The bluez\-alsa project is licensed under the terms of the MIT license.
.\" Generated by docutils manpage writer.
.