{"id":13438227,"url":"https://github.com/Arkq/bluez-alsa","last_synced_at":"2025-03-19T18:32:27.846Z","repository":{"id":37251906,"uuid":"66030180","full_name":"arkq/bluez-alsa","owner":"arkq","description":"Bluetooth Audio ALSA Backend","archived":false,"fork":false,"pushed_at":"2024-09-16T16:41:56.000Z","size":3133,"stargazers_count":853,"open_issues_count":16,"forks_count":188,"subscribers_count":44,"default_branch":"master","last_synced_at":"2024-09-17T18:39:40.052Z","etag":null,"topics":["a2dp","alsa","audio","ble-midi","bluetooth","bluez","hfp","hsp","linux","ofono"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/arkq.png","metadata":{"files":{"readme":"README.md","changelog":"NEWS","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS","dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-08-18T20:56:32.000Z","updated_at":"2024-09-16T23:56:49.000Z","dependencies_parsed_at":"2023-10-20T17:37:23.028Z","dependency_job_id":"47b6d3a2-59e3-432a-a4e6-944c148ef688","html_url":"https://github.com/arkq/bluez-alsa","commit_stats":{"total_commits":987,"total_committers":27,"mean_commits":36.55555555555556,"dds":"0.15805471124620063","last_synced_commit":"adf9334e30553c9ce7f4f868b75ff6da92d4d857"},"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arkq%2Fbluez-alsa","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arkq%2Fbluez-alsa/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arkq%2Fbluez-alsa/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arkq%2Fbluez-alsa/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/arkq","download_url":"https://codeload.github.com/arkq/bluez-alsa/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244483584,"owners_count":20460142,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["a2dp","alsa","audio","ble-midi","bluetooth","bluez","hfp","hsp","linux","ofono"],"created_at":"2024-07-31T03:01:03.837Z","updated_at":"2025-03-19T18:32:27.841Z","avatar_url":"https://github.com/arkq.png","language":"C","readme":"# Bluetooth Audio ALSA Backend\n\n\u003e [!WARNING]\n\u003e The latest source uses new names for some core components:\n\u003e\n\u003e * The `bluealsa` daemon is now called `bluealsad`\n\u003e * The `bluealsa-cli` utility is now called `bluealsactl`\n\u003e\n\u003e See the wiki guide [Migrating from release 4.3.1 or earlier](https://github.com/arkq/bluez-alsa/wiki/Migrating-from-release-4.3.1-or-earlier)\n\u003e for more information.\n\n[![Build Status](https://github.com/arkq/bluez-alsa/actions/workflows/build-and-test.yaml/badge.svg)](https://github.com/arkq/bluez-alsa/actions/workflows/build-and-test.yaml)\n[![Code Coverage](https://codecov.io/gh/arkq/bluez-alsa/branch/master/graph/badge.svg)](https://app.codecov.io/gh/arkq/bluez-alsa)\n\n## About BlueALSA\n\nThis project is a rebirth of a direct integration between [BlueZ][] and\n[ALSA][]. Since BlueZ \u003e= 5, the built-in integration has been removed in favor\nof 3rd party audio applications. From now on, BlueZ acts as a middleware\nbetween an audio application, which implements Bluetooth audio profile, and a\nBluetooth audio device.\n\nThe current status quo is, that in order to stream audio from/to a Bluetooth\ndevice, one has to install a general-purpose audio server such as [PipeWire][]\nor [PulseAudio][], or use BlueZ version 4 which is deprecated and unmaintained.\n\n[BlueZ]: http://www.bluez.org/\n[ALSA]: https://www.alsa-project.org/\n[PipeWire]: https://pipewire.org/\n[PulseAudio]: https://www.freedesktop.org/wiki/Software/PulseAudio\n\nThis project created and maintains a product called BlueALSA, with which one\ncan achieve the same Bluetooth audio profile support as with PulseAudio, but\nwith fewer dependencies and at a lower level in the software stack.  BlueALSA\nregisters all known Bluetooth audio profiles in BlueZ, so in theory every\nBluetooth device (with audio capabilities) can be connected.\n\nBlueALSA is designed specifically for use on small, low-powered, dedicated\naudio or audio/visual systems where the high-level audio management features of\nPulseAudio or PipeWire are not required. The target system must be able to\nfunction correctly with all its audio applications interfacing directly with\nALSA, with only one application at a time using each Bluetooth audio stream.\nIn such systems BlueALSA adds Bluetooth audio support to the existing\nALSA sound card support. Note this means that the applications are constrained\nby the capabilities of the ALSA API, and the higher-level audio processing\nfeatures of audio servers such as PulseAudio and PipeWire are not available.\n\nBlueALSA consists of the daemon `bluealsad`, ALSA plug-ins, and a number of\nutilities. The basic context is shown in this diagram:\n\n```mermaid\nflowchart TD\nclassDef external fill:#eee,stroke:#333,stroke-width:4px,color:black;\nclassDef bluealsa fill:#bbf,stroke:#333,stroke-width:4px,color:black;\n\nA[Bluetooth Adapter] \u003c--\u003e B((bluetoothd\u003cbr/\u003edaemon))\nA \u003c--\u003e C((bluealsad daemon))\nB \u003c-- dbus --\u003e C\nC \u003c-- dbus --\u003e G((bluealsactl))\nC \u003c-- dbus --\u003e D((bluealsa-aplay))\nD --\u003e E([ALSA libasound])\nE --\u003e K[Speakers]\nC \u003c-- dbus --\u003e F((bluealsa\u003cbr/\u003eALSA plug-ins))\nF \u003c--\u003e H([ALSA libasound])\nH \u003c--\u003e I((ALSA\u003cbr/\u003eapplications))\nC \u003c-- dbus --\u003e J((\"other D-Bus\u003cbr/\u003eclients\"))\nC \u003c--\u003e L((ALSA MIDI\u003cbr/\u003esequencer))\nL \u003c--\u003e M([ALSA libasound])\nM \u003c--\u003e N((ALSA MIDI\u003cbr/\u003eapplication))\n\nclass A,B,E,H,I,J,K,L,M,N external;\nclass C,D,F,G bluealsa;\n```\n\nThe heart of BlueALSA is the daemon `bluealsad` which interfaces with the BlueZ\nBluetooth daemon `bluetoothd` and the local Bluetooth adapter. It handles the\nprofile connection and configuration logic for A2DP, HFP and HSP and presents\nthe resulting audio streams to applications via D-Bus.\n\nBlueALSA includes ALSA plug-ins which hide all the D-Bus specifics and permit\napplications to use the ALSA PCM and mixer interfaces, so that existing ALSA\napplications can access Bluetooth audio devices in the same way as they use\nsound card PCMs and mixers.\n\nIn case of BLE MIDI, the daemon creates a simple MIDI port directly in ALSA\nMIDI sequencer, so that ALSA MIDI application can connect to the remote BLE\nMIDI device in the same way as it would connect to a local MIDI device.\n\nBlueALSA also includes a number of utility applications. Of particular note\nare:\n\n* bluealsactl\\\n   an application to allow command-line management of the BlueALSA system.\n\n* bluealsa-aplay\\\n   an application to simplify the task of building a Bluetooth speaker using\n   BlueALSA.\n\n* bluealsa-rfcomm\\\n   a command-line application which provides access to the RFCOMM terminal for\n   HFP/HSP devices.\n\n## Installation\n\nBuild and install instructions are included in the file\n[INSTALL.md](INSTALL.md) and more detailed guidance is available in the\n[wiki](https://github.com/arkq/bluez-alsa/wiki/Installation-from-source).\n\n## Usage\n\n### bluealsad daemon\n\nThe main component of BlueALSA is a program called `bluealsad`. By default,\nthis program shall be run as a root during system startup. It will register\n`org.bluealsa` service in the D-Bus system bus, which can be used for accessing\nconfigured audio devices. In general, BlueALSA acts as a proxy between BlueZ\nand ALSA.\n\nThe `bluealsad` daemon must be running in order to pair, connect, and use\nremote Bluetooth audio devices. In order to stream audio to e.g. a Bluetooth\nheadset, firstly one has to connect the device. If you are not familiar with\nthe Bluetooth pairing and connecting procedures on Linux, there is a basic\nguide in the wiki:\n[Bluetooth pairing and connecting](https://github.com/arkq/bluez-alsa/wiki/Bluetooth-Pairing-And-Connecting).\n\nFor details of command-line options to `bluealsad`, consult the [bluealsad\nmanual page](doc/bluealsad.8.rst).\n\n### ALSA plug-ins\n\nWhen a Bluetooth audio device is connected one can use the `bluealsa`\nvirtual PCM device with ALSA applications just like any other PCM device:\n\n```sh\naplay -D bluealsa Bourree_in_E_minor.wav\n```\n\nIf there is more than one Bluetooth device connected, the target one can be\nspecified as a parameter to the PCM:\n\n```sh\naplay -D bluealsa:XX:XX:XX:XX:XX:XX, Bourree_in_E_minor.wav\n```\n\nPlease note that this PCM device is based on the [ALSA software PCM I/O\nplug-in][] - it has no associated sound card, and it will not be available in\nthe [ALSA Kernel proc interface][].\n\n[ALSA software PCM I/O plug-in]: https://www.alsa-project.org/alsa-doc/alsa-lib/pcm_external_plugins.html\n[ALSA Kernel proc interface]: https://www.kernel.org/doc/html/latest/sound/designs/procfile.html\n\nSetup parameters of the `bluealsa` PCM device can be set in the local\n`.asoundrc` configuration file like this:\n\n```sh\ncat ~/.asoundrc\ndefaults.bluealsa.service \"org.bluealsa\"\ndefaults.bluealsa.device \"XX:XX:XX:XX:XX:XX\"\ndefaults.bluealsa.profile \"a2dp\"\ndefaults.bluealsa.delay 10000\n```\n\nBlueALSA also allows to capture audio from the connected Bluetooth device. To\ndo so, one has to use the capture PCM device, e.g.:\n\n```sh\narecord -D bluealsa -f s16_le -c 2 -r 48000 capture.wav\n```\n\nIn addition to A2DP profile, used for high quality audio, BlueALSA also allows\nto use phone audio connection via SCO link. One can use either built-in HSP/HFP\nsupport, which implements only audio related part of the specification, or use\n[oFono][] service as a back-end. In order to open SCO audio connection one\nshall switch to `sco` profile like follows:\n\n[oFono]: https://01.org/ofono\n\n```sh\naplay -D bluealsa:DEV=XX:XX:XX:XX:XX:XX,PROFILE=sco Bourree_in_E_minor.wav\n```\n\nIn order to control input or output audio level, one can use provided\n`bluealsa` control plug-in. This plug-in allows adjusting the volume of the\naudio stream or simply mute/unmute it, e.g.:\n\n```sh\namixer -D bluealsa sset '\u003ccontrol name\u003e' 70%\n```\n\nwhere the control name is the name of a connected Bluetooth device with a\ncontrol element suffix, e.g.:\n\n```sh\namixer -D bluealsa sset 'Jabra MOVE v2.3.0 A2DP' 50%\n```\n\nFor full details of the BlueALSA ALSA PCM device and mixer device consult the\n[BlueALSA plug-ins manual page](doc/bluealsa-plugins.7.rst).\n\nThere are also a number of articles on the [bluez-alsa project wiki][] giving\nmore examples of using these plug-ins.\n\n[bluez-alsa project wiki]: https://github.com/arkq/bluez-alsa/wiki\n\nFor more advanced ALSA configuration, consult the [asoundrc on-line\ndocumentation][] provided by the AlsaProject wiki page.\n\n[asoundrc on-line documentation]: https://www.alsa-project.org/main/index.php/Asoundrc\n\n### bluealsa-aplay\n\nIt is possible to create Bluetooth-powered speaker using BlueALSA. For this it\nis required to forward the audio signal from the BlueALSA capture PCM to some\nother playback PCM (e.g. built-in audio card).  In order to simplify this task,\nBlueALSA includes a program called `bluealsa-aplay`, which acts as a simple\nBlueALSA player. Connect your Bluetooth device (e.g. smartphone) and do as\nfollows:\n\n```sh\nbluealsa-aplay XX:XX:XX:XX:XX:XX\n```\n\nFor details of command-line options to `bluealsa-aplay`, consult the\n[bluealsa-aplay manual page](doc/bluealsa-aplay.1.rst). There are also some\narticles on the [bluez-alsa project wiki][] giving examples of its use.\n\nThe list of available BlueALSA PCMs (provided by connected Bluetooth devices\nwith audio capabilities) can be obtained directly from [BlueALSA D-Bus\nAPI](doc/org.bluealsa.PCM1.7.rst) or using `bluealsa-aplay` as a convenient\nwrapper as follows:\n\n```sh\nbluealsa-aplay -L\n```\n\n## Release Policy\n\nThe bluez-alsa project does not create nor distribute release software\npackages. However, at irregular intervals, when an important new feature or fix\nis considered stable then the `master` branch is tagged with a release version\nnumber. These tags are included only to mark reference baselines; their main\npurpose is to help Linux distribution package maintainers to relate their own\npackage versioning schemes to the original codebase.\n\nA release tag is formed as `vN.N.N` where the first number indicates a change\nthat is **not** backwards compatible (often a change to the D-Bus API), the\nsecond a feature addition that **is** backwards compatible, and the third a\nbackwards compatible bug-fix or internal change. This scheme complies with the\nrules of [Semantic Versioning]. The most significant changes included in each\ntag are listed in the [NEWS] file. For more detail on the changes please\nconsult the [commit history].\n\nAll changes are applied only to the `master` branch. There are no release\nbranches and no support for old release tags. Distributions are expected to\nmaintain their own patches if they need to support a package based on a release\ntag without upgrading to the latest `master` branch source.\n\n## Contributing\n\nThis project welcomes contributions of code, documentation and testing.\n\nPlease see the [CONTRIBUTING] guide for details.\n\n## Bug reports, feature requests, and requests for help\n\nThe most commonly encountered errors are discussed in the\n[TROUBLESHOOTING] guide. Please check that file to see if there is already a\nsolution for your issue.\n\nIf you are unable to find a solution in that document or by reading the\n[manual pages][], then please search [previous issues][] (both open and\nclosed), and consult the [wiki][] before raising a new issue. Unfortunately\nthe wiki is not indexed by web search engines, so searching on-line for your\nissue will not discover the information in there.\n\nIf reporting a problem as a new issue, please use the appropriate\n[bluez-alsa GitHub issue reporting template][] and complete each section of\nthe template as fully as possible. Note that the `Bug report` template should\nbe used for all questions relating to a specific installation of BlueALSA, even\nif you are not sure that it is a bug. In this way readers will\nbe given specific information about the context of the problem which will make\nit easier to find a solution.\n\n[NEWS]: NEWS\n[CONTRIBUTING]: CONTRIBUTING.md\n[TROUBLESHOOTING]: TROUBLESHOOTING.md\n[manual pages]: doc/\n[commit history]: https://github.com/arkq/bluez-alsa/commits/master/\n[previous issues]: https://github.com/arkq/bluez-alsa/issues\n[wiki]: https://github.com/arkq/bluez-alsa/wiki\n[bluez-alsa GitHub issue reporting template]: https://github.com/arkq/bluez-alsa/issues/new/choose\n[Semantic Versioning]: https://semver.org/\n\n## License\n\nBlueALSA is licensed under the terms of the MIT license. See the [LICENSE\nfile](LICENSE) for details.\n\n## Resources\n\n1. [Bluetooth Adopted Specifications](https://www.bluetooth.com/specifications/adopted-specifications)\n1. [Bluetooth LE MIDI Specification](https://www.midi.org/specifications-old/item/bluetooth-le-midi)\n1. [Bluetooth Design Guidelines](https://developer.apple.com/hardwaredrivers/BluetoothDesignGuidelines.pdf)\n1. [RTP Payload Format for MPEG-4](https://tools.ietf.org/html/rfc6416)\n1. [Coding of MPEG-4 Audio](https://www.iso.org/standard/42739.html)\n1. [ALSA project library reference](https://www.alsa-project.org/alsa-doc/alsa-lib/index.html)\n","funding_links":[],"categories":["C"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FArkq%2Fbluez-alsa","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FArkq%2Fbluez-alsa","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FArkq%2Fbluez-alsa/lists"}