.\" 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-APLAY" 1 "January 2023" "BlueALSA v4.1.1" "General Commands Manual" .SH NAME bluealsa-aplay \- a simple bluealsa player .SH SYNOPSIS .sp \fBbluealsa\-aplay\fP [\fIOPTION\fP]... [\fIBT\-ADDR\fP]... .SH DESCRIPTION .sp Capture audio streams from Bluetooth devices (via \fBbluealsa(8)\fP) and play them to an ALSA playback device. .sp By default \fBbluealsa\-aplay\fP captures audio from all connected Bluetooth devices. It is possible to select specific Bluetooth devices by providing a list of \fIBT\-ADDR\fP MAC addresses. Using the special MAC address \fB00:00:00:00:00:00\fP will disable device filtering \- the same as the default behavior. .SH OPTIONS .INDENT 0.0 .TP .B \-h\fP,\fB \-\-help Output a usage message and exit. .TP .B \-V\fP,\fB \-\-version Output the version number and exit. .TP .B \-S\fP,\fB \-\-syslog Send output to system logger (\fBsyslogd(8)\fP). By default, log output is sent to stderr. .TP .B \-v\fP,\fB \-\-verbose Make the output more verbose. .TP .B \-l\fP,\fB \-\-list\-devices List connected Bluetooth audio devices. .TP .B \-L\fP,\fB \-\-list\-pcms List available Bluetooth audio PCMs on connected devices. .TP .BI \-B \ NAME\fR,\fB \ \-\-dbus\fB= NAME BlueALSA service name suffix. For more information see \fB\-\-dbus=NAME\fP option of \fBbluealsa(8)\fP service daemon. .TP .BI \-D \ NAME\fR,\fB \ \-\-pcm\fB= NAME Select ALSA playback PCM device to use for audio output. The default is \fBdefault\fP\&. .sp Internally, \fBbluealsa\-aplay\fP does not perform any audio transformations nor streams mixing. If multiple Bluetooth devices are connected it simply opens a new connection to the ALSA PCM device for each stream. Selected hardware parameters like sampling frequency and number of channels are taken from the audio profile of a particular Bluetooth connection. Note, that each connection can have a different setup. .sp If playing multiple streams at the same time is not desired, it is possible to change that behavior by using the \fB\-\-single\-audio\fP option. .sp For more information see the \fI\%EXAMPLES\fP section below. .TP .BI \-\-pcm\-buffer\-time\fB= INT Set the playback PCM buffer duration time to \fIINT\fP microseconds. The default is 500000. It is recommended to choose a buffer time that is an exact multiple of the period time to avoid potential issues with some ALSA plugins (see \-\-pcm\-period\-time option below). ALSA may choose the nearest available alternative if the requested value is not supported. .sp If you experience underruns on the ALSA device then a larger buffer may help. However, a larger buffer will also increase the latency. For reliable performance the buffer time should be at least 3 times the period time. .TP .BI \-\-pcm\-period\-time\fB= INT Set the playback PCM period duration time to \fIINT\fP microseconds. The default is 100000. ALSA may choose the nearest available alternative if the requested value is not supported. .sp The ALSA \fBrate\fP plugin, which may be invoked by \fBplug\fP, does not always produce the exact required effective sample rate because of rounding errors in the conversion between period time and period size. This can have a significant impact on synchronization \(dqdrift\(dq, especially with small period sizes, and can also result in stream underruns (if the effective rate is too fast) or dropped A2DP frames in the \fBbluealsa(8)\fP server (if the effective rate is too slow). This effect is avoided if the selected period time results in an exact integer number of frames for both the source rate (Bluetooth) and sink rate (hardware card). For example, in the case of Bluetooth stream sampled at 44100Hz playing to a hardware device that supports only 48000Hz, choosing a period time that is a multiple of 10000 microseconds will result in zero rounding error. (10000 µs at 44100Hz is 441 frames, and at 48000Hz is 480 frames). .sp See also \fI\%dmix\fP in the \fBNOTES\fP section below for more information on rate calculation rounding errors. .TP .BI \-M \ NAME\fR,\fB \ \-\-mixer\-device\fB= NAME Select ALSA mixer device to use for controlling audio output mute state and volume level. In order to use this feature, BlueALSA PCM can not use software volume. The default is \fBdefault\fP\&. .sp See \fI\%Volume control\fP in the \fBNOTES\fP section below for more information on volume control. .TP .BI \-\-mixer\-name\fB= NAME Set the name of the ALSA simple mixer control to use. The default is \fBMaster\fP\&. .sp To work with \fBbluealsa\-aplay\fP this simple control must provide decibel scaling information for the volume control. Most, but not all, modern sound cards do provide this information. .TP .BI \-\-mixer\-index\fB= NUM Set the index of the ALSA simple mixer control. The default is \fB0\fP\&. .sp This is required only if the simple mixer control name applies to multiple simple controls on the same card. This is most common with HDMI devices which may have many playback ports. .TP .B \-\-profile\-a2dp Use A2DP profile (default). .TP .B \-\-profile\-sco Use SCO profile. .sp Note: Only one of A2DP or SCO can be used. If both are specified, the last one given will be selected. .TP .B \-\-single\-audio Allow only one Bluetooth device to play audio at a time. If multiple devices are connected, only the first to start will play, the others will be paused. When that first device stops, then the next to send audio will be played. .sp Without this option, \fBbluealsa\-aplay\fP plays audio from all selected Bluetooth devices. Please note that playing from all Bluetooth devices at a time requires used PCM to be able to mix audio from multiple sources (i.e., it can be opened more than once; for example the ALSA \fBdmix\fP plugin). .UNINDENT .SH NOTES .SS Volume control .sp If the BlueALSA PCM is using native Bluetooth volume control, then \fBbluealsa\-aplay\fP operates its given ALSA mixer control to implement volume change requests received from the remote Bluetooth device. .sp If the Bluetooth PCM is using soft\-volume volume control, then volume adjustment will have been applied to the PCM stream within the \fBbluealsa\fP daemon; so \fBbluealsa\-aplay\fP does not operate the mixer control in this case. .sp Native Bluetooth volume control for A2DP relies on AVRCP volume control in BlueZ, which has not always been reliably implemented. It is recommended to use BlueZ release 5.65 or later to be certain that native A2DP volume control will always be available with those devices which provide it. .sp See \fBbluealsa(8)\fP for more information on native and soft\-volume volume control. .SS dmix .sp The ALSA \fIdmix\fP plugin will ignore the period and buffer times selected by the application (because it has to allow connections from multiple applications). Instead it will choose its own values, which can lead to rounding errors in the period size calculation when used with the ALSA \fIrate\fP plugin. To avoid this, it is recommended to explicitly define the hardware period size and buffer size for dmix in your ALSA configuration. For example, suppose we want a period time of 100000 µs and a buffer holding 5 periods with an Intel \(aqPCH\(aq card: .INDENT 0.0 .INDENT 3.5 .sp .EX defaults.dmix.PCH.period_time 100000 defaults.dmix.PCH.periods 5 .EE .UNINDENT .UNINDENT .sp Alternatively we can define a PCM with the required setting: .INDENT 0.0 .INDENT 3.5 .sp .EX pcm.dmix_rate_fix { type plug slave.pcm { type dmix ipc_key 12345 slave { pcm \(dqhw:0,0\(dq period_time 100000 periods 5 } } } .EE .UNINDENT .UNINDENT .SH EXAMPLES .sp The simplest usage of \fBbluealsa\-aplay\fP is to run it with no arguments. It will play audio from all connected Bluetooth devices to the \fBdefault\fP ALSA playback PCM. .INDENT 0.0 .INDENT 3.5 .sp .EX bluealsa\-aplay .EE .UNINDENT .UNINDENT .sp If there is more than one sound card attached one can create a setup where the audio of a particular Bluetooth device is played to a specific sound card. The setup below shows how to do this using the \fB\-\-pcm=NAME\fP option and known Bluetooth device addresses. .sp Please note that in the following example we assume that the second card is named \(dqUSB\(dq and the appropriate mixer control is named \(dqSpeaker\(dq. Real names of attached sound cards can be obtained by running \fBaplay \-l\fP\&. A list of control names for a card called \(dqUSB\(dq can be obtained by running \fBamixer \-c USB scontrols\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .EX bluealsa\-aplay \-\-pcm=default 94:B8:6D:AF:CD:EF F8:87:F1:B8:30:85 & bluealsa\-aplay \-\-pcm=default:USB C8:F7:33:66:F0:DE & .EE .UNINDENT .UNINDENT .sp Also, it might be desired to specify ALSA mixer device and/or control element for each ALSA playback PCM device. This will be mostly useful when BlueALSA PCM does not use software volume (for more information see \fB\-\-a2dp\-volume\fP option of \fBbluealsa(8)\fP service daemon). .INDENT 0.0 .INDENT 3.5 .sp .EX bluealsa\-aplay \-\-pcm=default 94:B8:6D:AF:CD:EF F8:87:F1:B8:30:85 & bluealsa\-aplay \-\-pcm=default:USB \-\-mixer\-device=hw:USB \-\-mixer\-name=Speaker C8:F7:33:66:F0:DE & .EE .UNINDENT .UNINDENT .sp Such setup will route \fB94:B8:6D:AF:CD:EF\fP and \fBF8:87:F1:B8:30:85\fP Bluetooth devices to the \fBdefault\fP ALSA playback PCM device and \fBC8:F7:33:66:F0:DE\fP device to the USB sound card. For the USB sound card the \fBSpeaker\fP control element will be used as a hardware volume control knob. .SH COPYRIGHT .sp Copyright (c) 2016\-2023 Arkadiusz Bokowy. .sp The bluez\-alsa project is licensed under the terms of the MIT license. .SH SEE ALSO .sp \fBamixer(1)\fP, \fBaplay(1)\fP, \fBbluealsa\-rfcomm(1)\fP, \fBbluealsa(8)\fP .INDENT 0.0 .TP .B Project web site \fI\%https://github.com/arkq/bluez\-alsa\fP .UNINDENT .\" Generated by docutils manpage writer. .