{"id":23739084,"url":"https://github.com/pschatzmann/ESP32-A2DP","last_synced_at":"2025-09-04T13:33:15.268Z","repository":{"id":37832067,"uuid":"250600247","full_name":"pschatzmann/ESP32-A2DP","owner":"pschatzmann","description":"A Simple ESP32 Bluetooth A2DP Library (to implement a Music Receiver or Sender) that supports Arduino, PlatformIO and Espressif IDF","archived":false,"fork":false,"pushed_at":"2024-10-26T06:14:27.000Z","size":5828,"stargazers_count":1700,"open_issues_count":4,"forks_count":275,"subscribers_count":43,"default_branch":"main","last_synced_at":"2024-10-29T17:12:12.108Z","etag":null,"topics":["a2dp-sink","a2dp-source","arduino-library","audio","bluetooth","bluetooth-speaker","esp32","esp32-arduino","pcm-data"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pschatzmann.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":null,"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"lfx_crowdfunding":null,"polar":null,"buy_me_a_coffee":"philschatzh","custom":["https://www.paypal.com/paypalme/pschatzmann?country.x=CH\u0026locale.x=en_US"]}},"created_at":"2020-03-27T17:30:08.000Z","updated_at":"2024-10-28T11:01:06.000Z","dependencies_parsed_at":"2024-11-15T11:26:37.394Z","dependency_job_id":"9d9072a9-f985-40bc-9b0c-2f347bd72463","html_url":"https://github.com/pschatzmann/ESP32-A2DP","commit_stats":{"total_commits":439,"total_committers":31,"mean_commits":"14.161290322580646","dds":"0.21184510250569477","last_synced_commit":"3624fe3f23c8a4d181f891910f5b62dc87a51105"},"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pschatzmann%2FESP32-A2DP","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pschatzmann%2FESP32-A2DP/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pschatzmann%2FESP32-A2DP/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pschatzmann%2FESP32-A2DP/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pschatzmann","download_url":"https://codeload.github.com/pschatzmann/ESP32-A2DP/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":231965456,"owners_count":18453087,"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-sink","a2dp-source","arduino-library","audio","bluetooth","bluetooth-speaker","esp32","esp32-arduino","pcm-data"],"created_at":"2024-12-31T09:02:35.188Z","updated_at":"2025-09-04T13:33:15.223Z","avatar_url":"https://github.com/pschatzmann.png","language":"C++","funding_links":["https://buymeacoffee.com/philschatzh","https://www.paypal.com/paypalme/pschatzmann?country.x=CH\u0026locale.x=en_US","https://www.buymeacoffee.com/philschatzh","https://paypal.me/pschatzmann?country.x=CH\u0026locale.x=en_US"],"categories":["C++","硬件_其他"],"sub_categories":["资源传输下载"],"readme":"# A Simple Arduino Bluetooth Music Receiver and Sender for the ESP32\n\nThe ESP32 is a microcontroller that provides an API for Bluetooth A2DP which can be used to receive sound data e.g. from your Mobile Phone and makes it available via a callback method. The output is a PCM data stream, decoded from SBC format. The documentation can be found [here](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/peripherals/i2s.html). \n\n![esp32](https://pschatzmann.github.io/ESP32-A2DP/img/esp32.jpeg)\n\nI2S is an electrical serial bus interface standard used for connecting digital audio devices together. It is used to communicate PCM audio data between integrated circuits in an electronic device.\n\nSo we can just feed the input from Bluetooth to the I2S output: An example for this from Espressif can be found on [Github](https://github.com/espressif/esp-idf/tree/master/examples/bluetooth/bluedroid/classic_bt/a2dp_sink).\n\nUnfortunately this example did not make me happy so I decided to convert it into a simple __Arduino Library__ that is very easy to use from an Arduino Software IDE.\n\n## Supported Bluetooth Protocols\n\nAs the name of this library implies, it supports the A2DP [Bluetooth protocol](https://en.wikipedia.org/wiki/List_of_Bluetooth_profiles) which only provides audio streaming! \n\nIt also supports Audio/Video Remote Control Profile (AVRCP) together with A2DP.\n\nThe Hands-Free Profile (HFP), Headset Profile (HSP) and standalone AVRCP without A2DP are __not__ supported!\n\n## I2S API / Dependencies\n\nEspressif is retiring the legacy I2S API: So with Arduino v3.0.0 (IDF v5) [my old I2S integration](https://github.com/pschatzmann/ESP32-A2DP/wiki/Legacy-I2S-API) will not be available any more. The legacy syntax is still working as long as you don't upgrade.  \n\nIn order to support a unique output API which is version independent, it is recommended to install and use the [AudioTools](https://github.com/pschatzmann/arduino-audio-tools) library. So the documentation and all the examples have been updated to use this new approach.\n\nHowever you can also output to any other class which inherits from Arduino Print: e.g. the [Arduino ESP32 I2SClass](https://github.com/pschatzmann/ESP32-A2DP?tab=readme-ov-file#output-using-the-esp32-i2s-api) or you can use the [data callback](https://github.com/pschatzmann/ESP32-A2DP?tab=readme-ov-file#accessing-the-sink-data-stream-with-callbacks) described below. \n\n\n## A2DP Sink (Music Receiver)\n\nThis can be used e.g. to build your own Bluetooth Speaker.\n\n### A Simple I2S Example (A2DS Sink) using default Pins\nHere is the simplest example which just uses the proper default settings:\n\n```cpp\n#include \"AudioTools.h\"\n#include \"BluetoothA2DPSink.h\"\n\nI2SStream i2s;\nBluetoothA2DPSink a2dp_sink(i2s);\n\nvoid setup() {\n    a2dp_sink.start(\"MyMusic\");\n}\n\nvoid loop() {\n}\n```\nThis creates a new Bluetooth device with the name “MyMusic” and the output will be sent to the following default I2S pins which need to be connected to an external DAC:\n\n- bck_io_num = 14\n- ws_io_num = 15\n- data_out_num = 22\n\nPlease note that these default pins have changed compared to the legacy API!\n\n### Defining Pins\n\nYou can define your own pins easily before the ```start```.\n\n```cpp\n#include \"AudioTools.h\"\n#include \"BluetoothA2DPSink.h\"\n\nI2SStream i2s;\nBluetoothA2DPSink a2dp_sink(i2s);\n\nvoid setup() {\n    auto cfg = i2s.defaultConfig();\n    cfg.pin_bck = 14;\n    cfg.pin_ws = 15;\n    cfg.pin_data = 22;\n    i2s.begin(cfg);\n\n    a2dp_sink.start(\"MyMusic\");\n}\n\nvoid loop() {\n}\n```\n\n### Output Using the ESP32 I2S API\n\nYou can also use the Arduino ESP32 I2S API: You do not need to install any additional library for this. \n\n```cpp\n#include \"ESP_I2S.h\"\n#include \"BluetoothA2DPSink.h\"\n\nconst uint8_t I2S_SCK = 5;       /* Audio data bit clock */\nconst uint8_t I2S_WS = 25;       /* Audio data left and right clock */\nconst uint8_t I2S_SDOUT = 26;    /* ESP32 audio data output (to speakers) */\nI2SClass i2s;\n\nBluetoothA2DPSink a2dp_sink(i2s);\n\nvoid setup() {\n    i2s.setPins(I2S_SCK, I2S_WS, I2S_SDOUT);\n    if (!i2s.begin(I2S_MODE_STD, 44100, I2S_DATA_BIT_WIDTH_16BIT, I2S_SLOT_MODE_STEREO, I2S_STD_SLOT_BOTH)) {\n      Serial.println(\"Failed to initialize I2S!\");\n      while (1); // do nothing\n    }\n\n    a2dp_sink.start(\"MyMusic\");\n}\nvoid loop() {}\n```\nPlease note, that this API also depends on the installed version: The example above is for ESP32 \u003e= 3.0.0! \n\n### Output to the Internal DAC\n\nYou can also send the output directly to the internal DAC of the ESP32 by using the AnalogAudioStream from the AudioTools:\n\n```cpp\n#include \"AudioTools.h\"\n#include \"BluetoothA2DPSink.h\"\n\nAnalogAudioStream out;\nBluetoothA2DPSink a2dp_sink(out);\n\nvoid setup() {\n    a2dp_sink.start(\"MyMusic\");\n}\n\nvoid loop() {\n}\n```\n\nThe output goes now to the DAC pins GPIO25 (Channel 1) and GPIO26 (Channel 2).\n\n### Accessing the Sink Data Stream with Callbacks\n\nYou can be notified when a packet is received. The API is using PCM data normally formatted as 44.1kHz sampling rate, two-channel 16-bit sample data. \n\n\n```cpp\n// In the setup function:\na2dp_sink.set_on_data_received(data_received_callback);\n\n\n// Then somewhere in your sketch:\nvoid data_received_callback() {\n  Serial.println(\"Data packet received\");\n}\n```\n\nOr you can access the packet:\n\n```cpp\n// In the setup function:\na2dp_sink.set_stream_reader(read_data_stream);\n\n// Then somewhere in your sketch:\nvoid read_data_stream(const uint8_t *data, uint32_t length)\n{\n  int16_t *samples = (int16_t*) data;\n  uint32_t sample_count = length/2;\n  // Do something with the data packet\n}\n```\nIn the ```a2dp_sink.set_stream_reader()``` method you can provide an optional parameter that defines if you want the output to I2S to be active or deactive - So you can use this method to e.g. to switch off I2S just by calling ```a2dp_sink.set_stream_reader(read_data_stream, false)```\n\n### Support for Metadata\n\nYou can register a method which will be called when the system receives any AVRC metadata (`esp_avrc_md_attr_mask_t`). Here is an example\n```cpp\nvoid avrc_metadata_callback(uint8_t data1, const uint8_t *data2) {\n  Serial.printf(\"AVRC metadata rsp: attribute id 0x%x, %s\\n\", data1, data2);\n}\na2dp_sink.set_avrc_metadata_callback(avrc_metadata_callback);\na2dp_sink.start(\"BT\");\n```\nBy default you should get the most important information, however you can adjust this by calling the ```set_avrc_metadata_attribute_mask``` method e.g if you just need the title and playing time you can call:\n```cpp\nset_avrc_metadata_attribute_mask(ESP_AVRC_MD_ATTR_TITLE | ESP_AVRC_MD_ATTR_PLAYING_TIME);\n```\nbefore you start the A2DP sink. Note that data2 is actually a char* string, so even though `ESP_AVRC_MD_ATTR_PLAYING_TIME` is documented as the milliseconds of media duration you'll need to parse it before doing math on it. See the metadata example for more.\n\n### Support for Notifications\n\nSimilarly to the `avrc_metadata_callback`, ESP IDF v4+ supports selected `esp_avrc_rn_param_t` callbacks like `set_avrc_rn_playstatus_callback`, `set_avrc_rn_play_pos_callback` and `set_avrc_rn_track_change_callback` which can be used to obtain `esp_avrc_playback_stat_t playback` playback status,`uint32_t play_pos` playback position and `uint8_t elm_id` track change flag respectively. See the playing_status_callbacks example for more details.\n\n### Support for AVRC Commands\n\nI have added the following AVRC commands, that you can use to 'control' your A2DP Source:\n\n- play();\n- pause();\n- stop();\n- next();\n- previous();\n- fast_forward();\n- rewind();\n\n\n## A2DP Source (Music Sender)\n\nThis can be used to feed e.g. your Bluetooth Speaker with your audio data.\n\n\n### Sending Data from a A2DS Data Source with a Callback\n\nWe can also generate sound and send it e.g. to a Bluetooth Speaker.  \n\nThe supported audio codec in ESP32 A2DP is SBC: The API is using PCM data normally formatted as 44.1kHz sampling rate, two-channel 16-bit sample data. \n\nWhen you start the BluetoothA2DPSource, you need to pass the Bluetooth name that you want to connect to and a 'call back function' that provides the sound data:\n\n```cpp\n#include \"BluetoothA2DPSource.h\"\n\nBluetoothA2DPSource a2dp_source;\n\n// callback \nint32_t get_sound_data(uint8 *data, int32_t byteCount) {\n    // generate your sound data \n    // return the effective length in bytes\n    return byteCount;\n}\n\nvoid setup() {\n  a2dp_source.set_data_callback(get_sound_data)\n  a2dp_source.start(\"MyMusic\");  \n}\n\nvoid loop() {}\n\n```\nInstead of the ```set_data_callback callback``` method you can also use ```set_data_callback_in_frames``` which uses frames instead of bytes. In Arduino you can also provide a Stream (e.g a File) as data source or a callback which provides streams.\n\nIn the examples you can find an implementation that generates sound with the help of the sin() function.\n\nYou can also indicate multiple alternative Bluetooth names. The system just connects to the first one which is available:\n\n```cpp\nvoid setup() {\n  static std::vector\u003cchar*\u003e bt_names = {\"MyMusic\",\"RadioPlayer\",\"MusicPlayer\"};\n  a2dp_source.set_data_callback(get_sound_data)\n  a2dp_source.start(bt_names); \n} \n\n```\n\nFurther information can be found in the [related class documentation](https://pschatzmann.github.io/ESP32-A2DP/html/class_bluetooth_a2_d_p_source.html)!\n\n\n## Logging\n\nThis library uses the ESP32 logger that you can activate in Arduino in - Tools - Core Debug Log.\n\n## Architecture / Dependencies \n\nThe current code is purely dependent on the ESP-IDF (which is also provided by the Arduino ESP32 core). There are no other dependencies and this includes the Arduino API! \n\nTherefore we support:\n\n- Arduino\n- [PlatformIO](https://github.com/pschatzmann/ESP32-A2DP/wiki/PlatformIO)\n- [Espressif IDF](https://github.com/pschatzmann/ESP32-A2DP/wiki/Espressif-IDF-as-a-Component)\n\nThis restriction limits however the provided examples. \n\nBefore you clone the project, please read the following information which can be found in the [Wiki](https://github.com/pschatzmann/ESP32-A2DP/wiki/Design-Overview).\n\n## Digital Sound Processing\n\nYou can use this library standalone, but it is part of my [audio-tools](https://github.com/pschatzmann/arduino-audio-tools) project. So you can easily enhance this functionality with sound effects, use filters or an equilizer, use alternative audio sinks or audio sources, do FFT etc. Here is a [simple example](https://github.com/pschatzmann/arduino-audio-tools/blob/main/examples/examples-communication/a2dp/basic-a2dp-fft/basic-a2dp-fft.ino) how you can analyse the audio data with FFT.\n\n## Documentation\n\n- The [class documentation can be found here](https://pschatzmann.github.io/ESP32-A2DP/html/group__a2dp.html)\n- You can also find further information in the [Wiki](https://github.com/pschatzmann/ESP32-A2DP/wiki)\n\n## Support\n\nI spent a lot of time to provide a comprehensive and complete documentation.\nSo please read the documentation first and check the issues and discussions before posting any new ones on Github.\n\nOpen __issues only for bugs__ and if it is not a bug, use a discussion: Provide enough information about \n- the selected scenario/sketch \n- what exactly you are trying to do\n- your hardware\n- your software versions\n  - ESP32 version from the Board Manager\n  - version of the ESP32-A2DP library\n\nto enable others to understand and reproduce your issue.\n\nFinally above all __don't__ send me any e-mails or post questions on my personal website! \n\n## Show and Tell\n\nGet some inspiration [from projects that were using this library](https://github.com/pschatzmann/ESP32-A2DP/discussions/categories/show-and-tell) and share your projects with the community.\n\n## Installation\n\nFor Arduino you can download the library as zip and call include Library -\u003e zip library. Or you can git clone this project into the Arduino libraries folder e.g. with\n```bash\ncd  ~/Documents/Arduino/libraries\ngit clone https://github.com/pschatzmann/ESP32-A2DP.git\ngit clone https://github.com/pschatzmann/arduino-audio-tools.git\n```\nFor the provided examples, you will need to install the [audio-tools library](https://github.com/pschatzmann/arduino-audio-tools) as well. \n\nFor other frameworks [see the Wiki](https://github.com/pschatzmann/ESP32-A2DP/wiki)\n\n## Change History\n\nThe [Change History can be found in the Wiki](https://github.com/pschatzmann/ESP32-A2DP/wiki/Change-History)\n\n\n## Sponsor Me\n\nThis software is totally free, but you can make me happy by rewarding me with a treat\n\n- [Buy me a coffee](https://www.buymeacoffee.com/philschatzh)\n- [Paypal me](https://paypal.me/pschatzmann?country.x=CH\u0026locale.x=en_US)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpschatzmann%2FESP32-A2DP","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpschatzmann%2FESP32-A2DP","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpschatzmann%2FESP32-A2DP/lists"}