bluealsa-plugins

package: bluez-alsa

title: bluealsa-plugins(7)

summary: Bluetooth Audio ALSA Plugins

text:
# bluealsa-plugins(7)

## NAME
bluealsa-plugins - Bluetooth Audio ALSA Plugins

## DESCRIPTION
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.

## PCM PLUGIN
The BlueALSA ALSA PCM plugin communicates with the bluealsa(8) service. It can be used to define ALSA PCMs in your own configuration file (e.g. ~/.asoundrc), or you can use the predefined bluealsa PCM.

### The Predefined bluealsa PCM
The simplest way to use the PCM plugin is with the predefined ALSA PCM device bluealsa. The definition of this PCM device is of type plug 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:

```
bluealsa:DEV=01:23:45:67:89:AB,PROFILE=a2dp,CODEC=aac,VOL=60,SOFTVOL=no,DELAY=0,SRV=org.bluealsa
```

### PCM Parameters
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 00:00:00:00:00:00 which selects the most recently connected device of the chosen profile.

PROFILE

May be either a2dp or sco. sco selects either Hands-Free (HFP) or Headset (HSP) profile, whichever is connected on the selected device. The default is a2dp.

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 unchanged which causes the PCM to use its existing codec setting. The codec name is case insensitive; so for example aptX, aptx, and APTX are all accepted. If the specified codec is not available the plugin issues a warning and uses the default value instead. BlueALSA does not support changing the HFP codec from a HFP-HF node, only the HFP-AG node can change the HFP codec.

oFono does not permit the audio agent to select the codec, so this parameter has no effect when BlueALSA is used with oFono for HFP support.

For the A2DP profile it is possible to also specify a "configuration" for the codec by appending the configuration as a hex string separated from the codec name by a colon. For example:

```
CODEC=aptx:4f0000000100ff
```

VOL

Specifies the initial volume for the PCM when opened. The default value is unchanged 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 '-' to mute the sound or '+' 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:

```
VOL=80+
```

SOFTVOL

Enables or disables BlueALSA's software volume feature for this PCM. See the bluealsa(8) manual page for more information on software volume. This is a boolean option (values on or off), but also accepts the special value unchanged which causes the PCM to use its existing softvol value. The default value is unchanged.

DELAY

An integer number which is added to the reported delay (latency) value in order to manually adjust the audio synchronization. It is not normally required and defaults to 0. See the EXT parameter of the CTL plugin in the CTL Parameters section below for a more flexible and convenient method of manually adjusting the reported delay by using a mixer control.

SRV

The D-Bus service name of the BlueALSA daemon. Defaults to org.bluealsa. See bluealsa(8) for more information. Not normally required.

### Setting Different Defaults
The defaults can be overridden by defining the ones you want to change in your own configuration (e.g. in ~/.asoundrc.conf) for example:

```
defaults.bluealsa.device "00:11:22:33:44:55"
defaults.bluealsa.profile "sco"
defaults.bluealsa.codec "cvsd"
defaults.bluealsa.volume "50+"
defaults.bluealsa.softvol off
defaults.bluealsa.delay 5000
defaults.bluealsa.service "org.bluealsa.source"
```

Note that volume takes a string value and so the default must be enclosed in quotation marks.

### Positional Parameters
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 - DEV, PROFILE, CODEC, VOL, SOFTVOL, DELAY, SRV. For example:

```
bluealsa:01:23:45:67:89:AB,a2dp,unchanged,unchanged,unchanged,0,org.bluealsa
```

When using positional parameters defaults can only be implied at the end of the id string, so

```
bluealsa:01:23:45:67:89:AB
```

is equivalent to the full form above, but

```
bluealsa:01:23:45:67:89:AB,a2dp,,80+
```

is not permitted.

### Defining BlueALSA PCMs
You can define your own ALSA PCM in the ALSA configuration. To do this, create an ALSA configuration node defining a PCM with type bluealsa. The configuration node has the following fields:

```
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's software volume

  [delay INT]       # Extra delay (frames) to be reported (default 0)

  [service STR]     # DBus name of service (default org.bluealsa)
}
```

The device and profile 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 defaults.bluealsa.* in a PCM defined this way; however the configuration defaults can be referenced by use of @func refer (see the ALSA configuration file syntax documentation for more information).

When choosing a name for your PCM definition, the name pcm.bluealsa is predefined by the bluez-alsa installation (see section The Predefined bluealsa PCM 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.

Note that the volume field is of type string, so the value must be enclosed in double-quotes. See the PCM Parameters section above for more information on each field.

Do not confuse the PCM type bluealsa with the PCM named bluealsa. The type does not perform any audio conversions, you will have to wrap your own defined PCMs with type plug to achieve that; whereas the predefined PCM pcm.bluealsa is of type plug.

### Name Hints
Applications that follow ALSA guidelines will obtain the list of defined PCMs by using the alsa-lib namehints API. To make BlueALSA PCMs visible via that API it is necessary to add a "hint" section to the ALSA configuration. If you have defined a new PCM, then the hint goes into the PCM configuration entry as follows:

```
pcm.bt-headphones {

    type plug

    slave.pcm {

        type bluealsa

        device "00:11:22:33:44:55"

        profile "a2dp"

    }

    hint {

        show on

        description "My Bluetooth headphones"

    }
}
```

Now using aplay -L will include the following in its output:

```
# aplay -L
bt-headphones

    My Bluetooth headphones
#
```

If you are using the predefined bluealsa PCM, then you can create a "namehint" entry in your ~/.asoundrc file like this:

```
namehint.pcm {

    mybluealsadevice "bluealsa:DEV=00:11:22:33:44:55,PROFILE=a2dp|My Bluetooth headphones"
}
```

Then aplay -L shows

```
# aplay -L
bluealsa:DEV=00:11:22:33:44:55,PROFILE=a2dp

    My Bluetooth headphones
```

For alsa-lib versions before v1.2.3.2, a bug in the namehint parser means that a namehint.pcm entry has to be written as

```
namehint.pcm {

    mybluealsadevice "bluealsa:DEV=00:11:22:33:44:55,PROFILE=a2dp|DESCMy Bluetooth headphones"
}
```

(note the keyword DESC after the pipe symbol and before the description text.)

With that hint in place, the PCM will be listed as both a Capture and Playback device. So arecord -L 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.

If the hint.description value ends with |IOIDInput the PCM will only show in listings of Capture devices; if it ends with |IOIDOutput the PCM will only show in listings of Playback devices.

So we can modify our example above to:

```
pcm.bt-headphones {

    type plug

    slave.pcm {

        type bluealsa

        device "00:11:22:33:44:55"

        profile "a2dp"

    }

    hint {

        show on

        description "My Bluetooth headphones|IOIDOutput"

    }
}
```

or

```
namehint.pcm {

    mybluealsadevice "bluealsa:DEV=00:11:22:33:44:55,PROFILE=a2dp|My Bluetooth headphones|IOIDOutput"
}
```

Now the aplay -L output will be exactly the same as before, but arecord -L will not include bt-headphones in its output.

When using the namehint.pcm method, the key (mybluealsadevice 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 aplay -D ...). The next section, after the pipe symbol, is the description that will be presented to the user. The optional |IOID section is not included in the description given to the application.

## CTL PLUGIN
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 predefined configuration that is included in the bluez-alsa project.

A BlueALSA CTL device has no associated soundcard, so alsamixer will not list it in its F6 menu. It can be selected either by starting alsamixer with

```
alsamixer -D bluealsa
```

or by selecting "enter device name .." on the F6 menu then typing out "bluealsa" in the "Device Name" box.

The CTL has two operating modes, Default mode and Single Device mode.

### Default Mode
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. alsamixer(1) will show these changes dynamically.

Control names are constructed by combining the device Bluetooth alias with either the profile type ('A2DP' or 'SCO') of the controlled PCM or the word "Battery" 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.

The Bluetooth "alias" of a device is by default the same as its "name". The name is a string defined by the device manufacturer and embedded in its firmware. Typically two identical devices will have identical names. The "alias" is created by BlueZ and stored locally on the host computer. So the alias can be changed using a tool such as bluetoothctl(1) 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 "nickname" to a device.

Although this default mode works well with alsamixer, there are some limitations that may make it unsuitable for some applications. In particular:

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

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

### Single Device Mode
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 ('A2DP' or 'SCO') or the word "Battery". There is never any need for index suffixes or device alias. Immediately this overcomes the two main issues of the default mode.

Single device mode is achieved by including the device Bluetooth address as an argument to the ALSA device id, for example:

```
alsamixer -D bluealsa:00:11:22:33:44:55
```

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.

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.

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.

In single device mode when its device disconnects then the mixer will close. The alsamixer 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.

As a special case, a single device mixer can be opened with the address 00:00:00:00:00:00. 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.

### The Predefined bluealsa CTL
The bluealsa CTL has parameters DEV, EXT, BTT, DYN, and SRV. All the parameters have defaults.

### CTL Parameters
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 FF:FF:FF:FF:FF:FF which selects controls from all connected devices (see Default Mode above). Also accepts the special address 00:00:00:00:00:00 which selects the most recently connected device.

EXT

Causes the plugin to include extra controls. These are the controls for Bluetooth codec selection, volume mode selection, delay adjustment (sync) and/or battery level indicator. If the value is yes then all of these additional controls are included; if the value is no then none of them are included. The default is no. This parameter can also select individual controls by using a colon (':') separated list of control names. The control names are codec, mode, sync and battery. For example:

```
EXT=codec
EXT=mode:battery
```

See Codec switching in the NOTES section below for more information on the codec selection control.

The volume mode controls take values "software" and "pass-through"; the playback control has index 0 and capture control has index 1. See the Volume control section in the bluealsa(8) for more information on the software volume setting.

The delay adjustment controls are called "Sync". They can be used to apply a fixed adjustment to the delay reported by the associated PCM to the application, and may be useful with applications that need to synchronize the bluetooth audio stream with some some other stream, such as a video. The values are in milliseconds from -3275 ms to +3275 ms in steps of 25 ms. The playback control has index 0 and the capture control has index 1. Each codec supported by a PCM has its own delay adjustment value. Note that this control changes only the delay value reported to the application by ALSA, it does not affect the actual delay (latency) of the PCM stream. Values set by this control type are saved in the BlueALSA persistent state files, and so are remembered and automatically applied each time the PCM is used.

The read-only battery level indicator will be shown only if the device supports battery level reporting.

BTT

Appends Bluetooth transport type (e.g. "-SNK" or "-HFP-AG") to the control element names. When using with the Default Mode this will reduce the number of available characters for Bluetooth device name, so the default value is no. In some rare circumstances, when more than one A2DP or HFP/HSP profile is connected with a single Bluetooth device, it might happen that the control element names for such device will not be unique. This might be problematic for control applications which use ALSA High Level Control Interface, e.g. amixer or alsamixer. Such applications will report error or simply crash. This can be avoided by setting the BTT parameter to yes.

DYN

Enables "dynamic" operation. The plugin will add and remove controls as profiles are connected or disconnected. This is the normal behavior, so the default value is "yes". This argument is ignored in default mode; in that mode operation is always dynamic. There are some applications that are not programmed to handle dynamic addition or removal of controls, and can fail when such events occur. Setting this argument to no in single device mode with such applications can protect them from such failures. When dynamic operation is disabled, the plugin never adds or removes any controls. If a single profile is disconnected, then its associated volume control is put into an inactive state, i.e.: read-only with its value and playback/capture switch set to 0.

SRV

The D-Bus service name of the BlueALSA daemon. Defaults to org.bluealsa. See bluealsa(8) for more information.

The default values can be overridden in the ALSA configuration, for example:

```
defaults.bluealsa.ctl.device "00:11:22:33:44:55"
defaults.bluealsa.ctl.bttransport "no"
defaults.bluealsa.ctl.dynamic "yes"
defaults.bluealsa.ctl.extended "no"
```

### Defining BlueALSA CTLs
You can define your own ALSA CTL in the ALSA configuration. To do this, create an ALSA configuration node defining a CTL with type bluealsa. The configuration node has the following fields:

```
ctl.name {

  type bluealsa     # Bluetooth PCM

  [device STR]      # Device address (default "FF:FF:FF:FF:FF:FF")

  [extended STR]    # Include additional controls (default no)

  [bttransport STR] # Append BT transport to element names (yes/no, default no)

  [dynamic STR]     # Enable dynamic operation (yes/no, default yes)

  [service STR]     # D-Bus name of service (default "org.bluealsa")
}
```

All the fields (except type) are optional. See the CTL Parameters section above for more information on each field. 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 defaults.bluealsa. settings.

## NOTES

### Codec selection
When used on a HFP gateway node, there may be a brief delay with HFP PCMs after connection until the codec is selected. This delay is typically less than two seconds. During this time interval it is not possible to open the PCM plugin, it will fail with "Resource temporarily unavailable" (EAGAIN).

### Codec switching
Changing the codec used by a BlueALSA transport causes the PCM(s) running on that transport to terminate. Therefore using a Codec control can have undesirable consequences. Unfortunately the alsamixer(1) UI does not present a separate pick-list for enumerated types, so merely browsing the list of codecs using this control actually issues a Codec change request every time a different codec is displayed. This is not ideal, so the use of this control type with alsamixer(1) is not recommended. The control type does however work well with other mixer applications such as amixer(1).

Note that BlueALSA does not support changing the HFP codec from a HFP-HF node, only the HFP-AG node can change the HFP codec.

### Transport acquisition
The audio connection of a profile is not established immediately that a device connects. The A2DP source device, or HFP/HSP gateway device, must first "acquire" the profile transport.

When the BlueALSA PCM plugin is used on a source A2DP or gateway HFP/HSP node, then bluealsa(8) will automatically acquire the transport and begin audio transfer when the plugin starts the PCM.

When used on an A2DP sink or HFP/HSP HF/HS node then bluealsa(8) must wait for the remote device to acquire the transport. During this waiting time the PCM plugin behaves as if the device "clock" is stopped, it does not generate any poll() events, and the application will be blocked when writing or reading to/from the PCM. For applications playing audio from a file or recording audio to a file this is not normally an issue; but when streaming between some other device and a BlueALSA device this may lead to very large latency (delay) or trigger underruns or overruns in the other device.

### PCM drain and non-blocking operation
The BlueALSA PCM plugin does not support draining of capture PCMs. For a capture PCM snd_pcm_drain() has the same effect as snd_pcm_drop(). This is a limitation of the ALSA ioplug external plugin API.

For playback PCMs, BlueALSA has support for the drain operation in both blocking and non-blocking modes. In blocking mode the drain operation will wait until the BlueALSA server has played out the final audio frame. In non-blocking mode the plugin will inform the application of drain completion as soon as the ALSA ring buffer has been flushed; this means that some audio frames at the end of the stream may be lost in non-blocking mode as the PCM may stop before the server has had time to encode and play out all the frames.

## FILES
/etc/alsa/conf.d/20-bluealsa.conf

BlueALSA device configuration file. ALSA additional configuration, defines the bluealsa PCM and CTL devices.

## COPYRIGHT
Copyright (c) 2016-2023 Arkadiusz Bokowy.

The bluez-alsa project is licensed under the terms of the MIT license.

## SEE ALSO
alsamixer(1), amixer(1), aplay(1), bluetoothctl(1), bluealsa(8), bluetoothd(8)

Project web site

https://github.com/arkq/bluez-alsa

ALSA configuration file syntax

https://www.alsa-project.org/alsa-doc/alsa-lib/conf.html

ALSA built-in PCM plugins reference

https://www.alsa-project.org/alsa-doc/alsa-lib/pcm_plugins.html


title: org.bluealsa.Manager1(7)

summary: Bluetooth Audio Manager D-Bus API

text:
# org.bluealsa.Manager1(7)

## NAME
org.bluealsa.Manager1 - Bluetooth Audio Manager D-Bus API

## SYNOPSIS
Service

org.bluealsa[.unique ID]

Interface

org.bluealsa.Manager1

Object path

[variable prefix]/

## DESCRIPTION
This page describes the D-Bus Manager interface of the bluealsa(8) service. The Manager interface exposes some of the run-time properties of the service daemon.

### Properties
string Version [readonly]

Version of BlueALSA service.

array{string} Adapters [readonly]

Used HCI adapters. The device names ("hci0", etc.) of Bluetooth adapters that the BlueALSA service is using.

array{string} Profiles [readonly]

Used (enabled) Bluetooth profiles.

array{string} Codecs [readonly]

Used (enabled) Bluetooth audio codecs. The Bluetooth audio codec names are in the format: "<profile-name>:<codec-name>"

## COPYRIGHT
Copyright (c) 2016-2023 Arkadiusz Bokowy.

The bluez-alsa project is licensed under the terms of the MIT license.

## SEE ALSO
bluealsa-cli(1), bluealsa(8)

Project web site

https://github.com/arkq/bluez-alsa


title: org.bluealsa.PCM1(7)

summary: Bluetooth Audio PCM D-Bus API

text:
# org.bluealsa.PCM1(7)

## NAME
org.bluealsa.PCM1 - Bluetooth Audio PCM D-Bus API

## SYNOPSIS
Service

org.bluealsa[.unique ID]

Interface

org.bluealsa.PCM1

Object path

[variable prefix]/{hci0,...}/dev_XX_XX_XX_XX_XX_XX/[type]/[mode]

## DESCRIPTION
This page describes the D-Bus PCM interface of the bluealsa(8) service. The PCM interface gives access to individual PCM objects created by this service.

### Methods
fd, fd Open()

Open BlueALSA PCM stream. This method returns two file descriptors, respectively PCM stream PIPE and PCM controller SEQPACKET socket. Controller socket commands: "Drain", "Drop", "Pause", "Resume"

Possible Errors:

```
dbus.Error.InvalidArguments
dbus.Error.NotSupported
dbus.Error.Failed
```

array{string, dict} GetCodecs()

Return the array of additional PCM codecs. Client can switch to one of these codecs with the SelectCodec() D-Bus method call.

void SelectCodec(string codec, dict props)

Select PCM codec. This call shall be made before PCM stream opening for given transport type, otherwise the ongoing stream (or PCM counterpart: sink, source) will be terminated. For A2DP codecs, client can override built-in logic for selecting codec configuration by providing the configuration blob via the "Configuration" property. Provided configuration must be valid for given codec in respect to BlueALSA and peer device capabilities. Otherwise, the call will fail. It is possible to override this validation by setting the "NonConformant" property to true.

Possible Errors:

```
dbus.Error.InvalidArguments
dbus.Error.NotSupported
dbus.Error.Failed
```

void SetDelayAdjustment(string codec, int16 adjustment)

Set an arbitrary adjustment (+/-) to the reported Delay in 1/10 of millisecond for a specific codec. This adjustment is applied to the Delay property when that codec is selected, and can be used to compensate for devices that do not report accurate Delay values. Possible Errors:

```
dbus.Error.InvalidArguments
```

array{string, int16} GetDelayAdjustments()

Return the array of currently set delay adjustments. Each entry of the array gives the name of a codec and the adjustment that the PCM will apply to the Delay property when that codec is selected.

### Properties
object Device [readonly]

BlueZ device object path.

uint32 Sequence [readonly]

This property indicates the sequence in which devices connected. The larger the value, the later the device was connected.

string Transport [readonly]

Underlying Bluetooth transport type. Possible values:

```
"A2DP-sink"
"A2DP-source"
"HFP-AG"
"HFP-HF"
"HSP-AG"
"HSP-HS"
```

string Mode [readonly]

PCM stream operation mode (direction). Possible values:

```
"sink"
"source"
```

boolean Running [readonly]

This property is true when the Bluetooth transport for this PCM is acquired and able to transfer audio samples.

uint16 Format [readonly]

Stream format identifier. The highest two bits of the 16-bit identifier determine the signedness and the endianness. Next 6 bits determine the physical width of a sample in bytes. The lowest 8 bits are used to store the actual sample bit-width. Examples:

```
0x4210 - unsigned 16-bit 2 bytes big-endian
0x8418 - signed 24-bit 4 bytes little-endian
```

byte Channels [readonly]

Number of audio channels.

uint32 Sampling [readonly]

Sampling frequency.

string Codec [readonly]

Bluetooth transport codec. This property is available only when transport codec is selected.

array{byte} CodecConfiguration [readonly]

Optional. Bluetooth transport codec configuration blob. This property is available only for transports which support codec configuration (e.g. A2DP).

uint16 Delay [readonly]

Approximate PCM delay in 1/10 of millisecond.

int16 DelayAdjustment [readonly]

An adjustment (+/-) included within the reported Delay in 1/10 of millisecond to compensate for devices that do not report accurate delay values.

boolean SoftVolume [readwrite]

This property determines whether BlueALSA will make volume control internally or will delegate this task to BlueALSA PCM client or connected Bluetooth device respectively for PCM sink or PCM source.

uint16 Volume [readwrite]

This property holds volume (loudness) value and mute information for channel 1 (left) and 2 (right). Data for channel 1 is stored in the upper byte, channel 2 is stored in the lower byte. The highest bit of both bytes determines whether channel is muted. Possible values:

```
A2DP: 0-127
SCO:  0-15
```

## COPYRIGHT
Copyright (c) 2016-2023 Arkadiusz Bokowy.

The bluez-alsa project is licensed under the terms of the MIT license.

## SEE ALSO
bluealsa-cli(1), bluealsa-plugins(5), bluealsa(8)

Project web site

https://github.com/arkq/bluez-alsa


title: org.bluealsa.RFCOMM1(7)

summary: Bluetooth Audio RFCOMM D-Bus API

text:
# org.bluealsa.RFCOMM1(7)

## NAME
org.bluealsa.RFCOMM1 - Bluetooth Audio RFCOMM D-Bus API

## SYNOPSIS
Service

org.bluealsa[.unique ID]

Interface

org.bluealsa.RFCOMM1

Object path

[variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX/rfcomm

## DESCRIPTION
This page describes the D-Bus RFCOMM interface of the bluealsa(8) service. The RFCOMM interface gives access to the RFCOMM terminal objects created by this service.

### Methods
fd Open()

Open RFCOMM socket for dispatching AT commands not handled internally by BlueALSA. This method returns a SEQPACKET socket. Possible Errors:

```
dbus.Error.NotSupported
dbus.Error.Failed
```

### Properties
string Transport [readonly]

HFP/HSP transport type. Possible values: "HFP-AG", "HFP-HF", "HSP-AG" or "HSP-HS"

array{string} Features [readonly]

List of features supported by the remote device.

byte Battery [readonly]

Remote device battery level. Possible values: 0-100 or -1

## COPYRIGHT
Copyright (c) 2016-2023 Arkadiusz Bokowy.

The bluez-alsa project is licensed under the terms of the MIT license.

## SEE ALSO
bluealsa-rfcomm(1), bluealsa(8)

Project web site

https://github.com/arkq/bluez-alsa


calf

package: calf

title: calf(7)

summary: audio plugin library

text:
# calf(7)

## NAME
Calf_Studio_Gear - audio plugin library

## SYNOPSIS
calfjackhost plugin ! [ plugin ! ] [...]

## DESCRIPTION
The Calf project aims at providing a set of high quality open source audio plugins for musicians which can be used as LV2 plug-ins or standalone.

Currently available plugins:

* Instruments and Tone Generators:

Organ, Monosynth, Fluidsynth, Wavetable

* Modulation Effects:

Multi Chorus, Phaser, Flanger, Rotary Speaker, Pulsator, Ring Modulator

* Delay Effects:

Reverb, Vintage Delay, Compensation Delay Line, Reverse Delay (experimental)

* Dynamic Processors:

Compressor, Sidechain Compressor, Multiband Compressor, Deesser, Gate, Sidechain Gate, Multiband Gate, Limiter, Multiband Limiter, Sidechain Limiter, Transient Designer

* Filters and Equalizers:

Filter, Filterclavier, Envelope Filter, Emphasis, Vocoder, Equalizer 5 Band, Equalizer 8 Band, Equalizer 12 Band, Equalizer 30 Band

* Distortion and Enhancement:

Saturator, Exciter, Bass Enhancer, Tape Simulator, Vinyl, Crusher

* Tools:

Mono Input, Stereo Tools, Hass Stereo Enhancer, Multi Spread, X-Over 2 Band, X-Over 3 Band, X-Over 4 Band

## OPTIONS
How to use Calf plugins:

* LV2 plugins

Calf is installed as calf.lv2 library in your LV2 directory (typically /usr/lib/lv2). It means that typical LV2 hosts should be able to find Calf's plugins.

* JACK client application

You can also use Calf plugins as one or more separate applications, connecting to other applications using JACK Audio Connection Kit (version 0.103 or newer is required). To run the client, type:

calfjackhost monosynth !

(! means "connect", last "!" means "connect to output")

Other examples:

calfjackhost monosynth ! vintagedelay ! flanger !

(runs monosynth into vintagedelay and vintagedelay into flanger, then to output)

calfjackhost ! reverb !

(takes signal from system:capture_1 and _2, puts it through reverb, and then sends to system:playback_1 and _2)

## SEE ALSO
calfjackhost(1)

## AUTHOR
Krzysztof Foltman, Markus Schmidt, Christian Holschuh, Thor Harald Johansen, Damien Zammit, Tom Szilagyi, Hans Baier and others

Website: http://calf.sourceforge.net/


ccze-plugin

package: ccze

title: ccze-plugin(7)

text:
# ccze-plugin(7)

## NAME
ccze - A robust log colorizer, plugin infrastructure

## SYNOPSIS
\#include <ccze.h>

/* Plugin support */

typedef void (*ccze_plugin_startup_t) (void);

typedef void (*ccze_plugin_shutdown_t) (void);

typedef int (*ccze_plugin_handle_t) (const char *str, size_t length, char **rest);

CCZE_DEFINE_PLUGIN (name, type, desc);

CCZE_DEFINE_PLUGINS (plugins...);

/* Display */

void ccze_addstr (ccze_color_t col, const char *str);

void ccze_newline (void);

void ccze_space (void);

void ccze_wordcolor_process_one (char *word, int slookup);

/* Helpers */

ccze_color_t ccze_http_action (const char *method);

void ccze_print_date (const char *date);

/* Command line */

char **ccze_plugin_argv_get (const char *name);

const char *ccze_plugin_name_get (void);

## DESCRIPTION
This manual page attempts to outline the internals of CCZE plugins: how they work, how they are implemented, and how to add new ones.

There are four required entry points in a plugin: a startup, a shutdown and a handler routine (more on these later), and an informational structure.

The startup function must be of type ccze_plugin_startup_t. This is called right after the module is loaded. Its purpose is to initialise all kinds of module-specific global variables, such as the regular expressions.

The shutdown function is its counterpart: this is used to deallocate any memory reserved by the startup code.

The core part of a plugin is the handler, of type ccze_plugin_handle_t. This does the actual coloring. The string to process is passed in the str argument, its length in length. The third argument, rest is a pointer to a string. Unlike the first two, this argument is used only for output.

When a handler processed a string, it must return a non-zero value, in case it could not process it, the handler must return with zero. If the string could be processed only partially, the part which was deemed unknown by the handler must be passed back in the rest variable.

The fourth part, although the smallest part, is the most important. Without this, the module is useless, it cannot be loaded. This part tells CCZE what the startup, shutdown and handler functions are called.

To encourage good style, the little details of this structure will not be disclosed in this manual page. Instead, the helper macro, CCZE_DEFINE_PLUGIN will be explained.

CCZE_DEFINE_PLUGIN is the macro to use if one wants to make the plugin loadable. Its first argument is an unquoted string: the name of the plugin. The second part is the type of the plugin, it can be FULL, PARTIAL or ANY. The last argument is a short description of the plugin.

It is assumed that the three functions mentioned earlier are called ccze_name_setup, ccze_name_shutdown and ccze_name_handle, respectively.

A FULL plugin is one that accepts raw input, untouched by any other plugin before, and processes it. On the other hand, a PARTIAL plugin relies on previous ones preprocessing the input. For example, syslog is a full plugin, on which ulogd, a partial plugin relies. The syslog plugin processes the raw input from the logfile, adds colour to most of it, save the actual message sent by a process, that is left to subsequent plugins, like ulogd. An ANY plugin is one can act as both other types.

With CCZE_DEFINE_PLUGINS one can place more than one plugin into one shared object.

There are two other helper functions, ccze_plugin_argv_get and ccze_plugin_name_get. One can pass arguments to CCZE plugins, and these is the function to retrieve them. While ccze_plugin_name_get returns the name of the current plugin, ccze_plugin_argv_get returns a NULL-terminated array, with each entry containing an argument.

## DISPLAY METHODS
The so-called display methods are the only supported interface to emit something to the display. These handle both the normal, ncurses-based, and the HTML output. This is a kind of abstraction so plugins will not have to worry about the differences between the output formats.

The most important one is ccze_addstr, which takes a color (see ccze.h for a list of supported color tags) and a string, and displays it appropriately. The ccze_space and ccze_newline functions emit a space and a newline, respectively.

Our last function, ccze_wordcolor_process_one passes word to the word colourising engine. If the second argument, slookup is non-zero, the engine will perform service lookups (like getent and friends).

## HELPER METHODS
We only have two helper methods: ccze_print_date, which simply prints out the date in the appropriate colour, and ccze_http_action, which given a HTTP method, returns the associated colour, in a format suitable for ccze_addstr.

## EXAMPLE

```
#include <ccze.h>
#include <stddef.h>
#include <string.h>
static char **ccze_foo_argv;
static int
ccze_foo_handle (const char *str, size_t length, char **rest)
{

  int i = 1;

  if (strstr (str, "foo"))

    {

      ccze_addstr (CCZE_COLOR_GOODWORD, str);

      return 1;

    }

  while (ccze_foo_argv[i])

    {

      if (strstr (str, ccze_foo_argv[i]))

        {

          ccze_addstr (CCZE_COLOR_GOODWORD, str);

          return 1;

        }

      i++;

    }

  return 0;
}
static void
ccze_foo_startup (void)
{

  ccze_foo_argv = ccze_plugin_argv_get (ccze_plugin_name_get ());
}
static void
ccze_foo_shutdown (void)
{
}
CCZE_DEFINE_PLUGIN (foo, PARTIAL, "Partial FOO coloriser.");
```

## SEE ALSO
ccze(1)

## AUTHOR
ccze was written by Gergely Nagy <algernon@bonehunter.rulez.org>, based on colorize by Istvan Karaszi <colorize@spam.raszi.hu>.