{"id":18965517,"url":"https://github.com/celliesprojects/esp32_vs1053_stream","last_synced_at":"2026-04-12T20:00:39.263Z","repository":{"id":45287030,"uuid":"375304112","full_name":"CelliesProjects/ESP32_VS1053_Stream","owner":"CelliesProjects","description":"A streaming library for Arduino esp32 with a vs1053 mp3/aac/ogg/flac decoder. Plays http, https and chunked streams. Stream metadata is parsed. Also plays ogg, mp3 and flac from sdcard.","archived":false,"fork":false,"pushed_at":"2026-03-23T22:33:11.000Z","size":1063,"stargazers_count":101,"open_issues_count":10,"forks_count":16,"subscribers_count":3,"default_branch":"master","last_synced_at":"2026-03-24T06:40:17.361Z","etag":null,"topics":["aac","aacp","arduino-library","audio","esp32","esp32-c3","esp32-s2","esp32-s3","flac","mediaplayer","mp3","ogg","psram","sdcard","stream","vs1053","wav","webradio"],"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/CelliesProjects.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2021-06-09T09:46:48.000Z","updated_at":"2026-03-23T09:55:03.000Z","dependencies_parsed_at":"2024-03-15T16:31:33.786Z","dependency_job_id":"958ac95c-0ec8-46c3-8480-87fcfeadc34f","html_url":"https://github.com/CelliesProjects/ESP32_VS1053_Stream","commit_stats":null,"previous_names":[],"tags_count":24,"template":false,"template_full_name":null,"purl":"pkg:github/CelliesProjects/ESP32_VS1053_Stream","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CelliesProjects%2FESP32_VS1053_Stream","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CelliesProjects%2FESP32_VS1053_Stream/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CelliesProjects%2FESP32_VS1053_Stream/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CelliesProjects%2FESP32_VS1053_Stream/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CelliesProjects","download_url":"https://codeload.github.com/CelliesProjects/ESP32_VS1053_Stream/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CelliesProjects%2FESP32_VS1053_Stream/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31292629,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T21:15:39.731Z","status":"ssl_error","status_checked_at":"2026-04-01T21:15:34.046Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["aac","aacp","arduino-library","audio","esp32","esp32-c3","esp32-s2","esp32-s3","flac","mediaplayer","mp3","ogg","psram","sdcard","stream","vs1053","wav","webradio"],"created_at":"2024-11-08T14:29:48.812Z","updated_at":"2026-04-12T20:00:39.253Z","avatar_url":"https://github.com/CelliesProjects.png","language":"C++","readme":"# ESP32_VS1053_Stream\n\n[![Codacy Badge](https://api.codacy.com/project/badge/Grade/7571166c872e4dc8a899382389b73f8e)](https://app.codacy.com/gh/CelliesProjects/ESP32_VS1053_Stream?utm_source=github.com\u0026utm_medium=referral\u0026utm_content=CelliesProjects/ESP32_VS1053_Stream\u0026utm_campaign=Badge_Grade_Settings)\n\nA streaming library for esp32, esp32-wrover, esp32-c3, esp32-s2 and esp32-s3 with a separate VS1053 codec chip.  \nThis library plays mp3, ogg, aac and flac files and streams.  \n\n- Supported codecs are **mp3**, **ogg**, **aac-adts**, **aac-adif**, **aac-mp4** and **16 bit flac**.\n- Supported stream methods are http and insecure https.  \n- Streams can be chunked.  \n- Also plays **mp3**, **ogg** and **flac** files from sdcard or any mounted filesystem.  \n\nVery lightweight, has a binary footprint of less than 7kB excluding the psram buffer.\n\n[ESP_VS1053_Library](https://github.com/baldram/ESP_VS1053_Library) is used to communicate with the decoder.\n\n## How to install and use\n\nUse the [latest Arduino ESP32 core version](https://github.com/espressif/arduino-esp32/releases/latest) for Arduino IDE or the corresponding [PIOArduino release](https://github.com/pioarduino/platform-espressif32/releases/latest) if you use PlatformIO in VSCode.  \n\n### platformio.ini example\n\n```ini\nplatform = https://github.com/pioarduino/platform-espressif32/releases/download/55.03.37/platform-espressif32.zip\n\nlib_deps =\n    https://github.com/baldram/ESP_VS1053_Library#master\n    https://github.com/CelliesProjects/ESP32_VS1053_Stream@3.0.6\n```\n\n### Arduino IDE setup\n\nThe `ESP_VS1053_Library` library is not available in the Arduino IDE library manager.   \nYou will have to install manually.  \n\nFollow these steps to install the vs1053 library in the Arduino IDE:\n\n- Browse to the [vs1053 repository](https://github.com/baldram/ESP_VS1053_Library) and download the zip file found under the green button marked `\u003c\u003e Code`.\n- In the Arduino IDE go to `Sketch-\u003eInclude Library-\u003eAdd .ZIP library` and select the downloaded zip file to install.\n- Answer `YES` when asked to overwrite the existing library.\n\nThat's it.  \nWith the vs1053 library installed this library can be compiled in the Arduino IDE. \n\n## Example: play a stream\n```c++\n#include \u003cArduino.h\u003e\n#include \u003cWiFi.h\u003e\n#include \u003cWiFiClient.h\u003e\n#include \u003cVS1053.h\u003e               // https://github.com/baldram/ESP_VS1053_Library\n#include \u003cESP32_VS1053_Stream.h\u003e\n\n#define SPI_CLK_PIN 18\n#define SPI_MISO_PIN 19\n#define SPI_MOSI_PIN 23\n\n#define VS1053_CS 5\n#define VS1053_DCS 21\n#define VS1053_DREQ 22\n\nESP32_VS1053_Stream stream;\n\nconst char* SSID = \"xxx\";\nconst char* PSK = \"xxx\";\n\n// Called when codec is detected\nvoid codecCallBack(const char *codec)\n{\n    Serial.printf(\"codec: %s\\n\", codec);\n}\n\n// Called when bitrate is detected (cbr) and changes (vbr)\nvoid bitrateCallback(uint32_t bitrate)\n{\n    Serial.printf(\"bitrate: %lu kbps\\n\", bitrate);\n}\n\n// Called when a stream has an ICY name header set\nvoid stationCallback(const char *name)\n{\n    Serial.printf(\"station: %s\\n\", name);\n}\n\n// Called when stream metadata is available\nvoid infoCallback(const char *info)\n{\n    Serial.printf(\"info: %s\\n\", info);\n}\n\n// Called on end-of-file\nvoid eofCallback(const char *url)\n{\n    Serial.printf(\"eof: %s\\n\", url);\n}\n\nvoid setup() {\n    Serial.begin(115200);\n    Serial.println(\"\\n\\nVS1053 Radio Streaming Example\\n\");\n\n    // Connect to Wi-Fi\n    Serial.printf(\"Connecting to WiFi network: %s\\n\", SSID);\n    WiFi.begin(SSID, PSK);  \n    WiFi.setSleep(false);  // Important to disable sleep to ensure stable connection\n\n    while (!WiFi.isConnected())\n        delay(10);\n\n    Serial.println(\"WiFi connected - starting decoder...\");\n\n    // Start SPI bus\n    SPI.setHwCs(true);\n    SPI.begin(SPI_CLK_PIN, SPI_MISO_PIN, SPI_MOSI_PIN);\n\n    // Initialize the VS1053 decoder\n    if (!stream.startDecoder(VS1053_CS, VS1053_DCS, VS1053_DREQ) || !stream.isChipConnected()) {\n        Serial.println(\"Decoder not running - system halted\");\n        while (1) delay(100);\n    }\n\n    // Set the codec callback\n    stream.setCodecCB(codecCallBack);\n\n    // Set the bitrate callback\n    stream.setBitrateCB(bitrateCallback);   \n\n    // Set the station name callback\n    stream.setStationCB(stationCallback);\n\n    // Set the stream metadata callback\n    stream.setInfoCB(infoCallback);\n\n    // Set the EOF callback\n    stream.setEofCB(eofCallback);    \n\n    Serial.println(\"VS1053 running - starting radio stream\");\n\n    // Connect to the radio stream\n    stream.connectToHost(\"http://icecast.omroep.nl/radio6-bb-mp3\");\n\n    if (!stream.isRunning())\n        Serial.println(\"Stream not running\");\n}\n\nvoid loop() {\n    stream.loop();\n    delay(5);\n}\n\n```\n\n## Example: play from SD card\n```c++\n#include \u003cArduino.h\u003e\n#include \u003cSD.h\u003e\n#include \u003cVS1053.h\u003e               // https://github.com/baldram/ESP_VS1053_Library\n#include \u003cESP32_VS1053_Stream.h\u003e\n\n#define SPI_CLK_PIN 18\n#define SPI_MISO_PIN 19\n#define SPI_MOSI_PIN 23\n\n#define VS1053_CS 5\n#define VS1053_DCS 21\n#define VS1053_DREQ 22\n#define SDREADER_CS 26\n\nESP32_VS1053_Stream stream;\n\n// Called when codec is detected\nvoid codecCallBack(const char *codec)\n{\n    Serial.printf(\"codec: %s\\n\", codec);\n}\n\n// Called when bitrate is detected (cbr) and changes (vbr)\nvoid bitrateCallback(uint32_t bitrate)\n{\n    Serial.printf(\"bitrate: %lu kbps\\n\", bitrate);\n}\n\n// Called on end-of-file\nvoid eofCallback(const char *url)\n{\n    Serial.printf(\"eof: %s\\n\", url);\n}\n\nbool mountSDcard() {\n    if (!SD.begin(SDREADER_CS)) {\n        Serial.println(\"Card mount failed\"); \n        return false;\n    }\n\n    uint8_t cardType = SD.cardType();\n    if (cardType == CARD_NONE) {\n        Serial.println(\"No SD card attached\");\n        return false;\n    }\n\n    uint64_t cardSize = SD.cardSize() / (1024 * 1024);\n    Serial.printf(\"SD Card Size: %lluMB\\n\", cardSize);\n    return true;\n}\n\nvoid setup() {\n    Serial.begin(115200);\n    Serial.println(\"\\n\\nVS1053 SD Card Playback Example\\n\");\n\n    // Start SPI bus\n    SPI.setHwCs(true);\n    SPI.begin(SPI_CLK_PIN, SPI_MISO_PIN, SPI_MOSI_PIN);\n\n    // Mount SD card\n    if (!mountSDcard()) {\n        Serial.println(\"SD card not mounted - system halted\");\n        while (1) delay(100);\n    }\n\n    Serial.println(\"SD card mounted - starting decoder...\");\n\n    // Initialize the VS1053 decoder\n    if (!stream.startDecoder(VS1053_CS, VS1053_DCS, VS1053_DREQ) || !stream.isChipConnected()) {\n        Serial.println(\"Decoder not running - system halted\");\n        while (1) delay(100);\n    }\n\n    // Set the codec callback\n    stream.setCodecCB(codecCallBack);\n\n    // Set the bitrate callback\n    stream.setBitrateCB(bitrateCallback);\n\n    // Set the EOF callback\n    stream.setEofCB(eofCallback);\n\n    Serial.println(\"VS1053 running - starting SD playback\");\n\n    // Start playback from an SD file\n    stream.connectToFile(SD, \"/test.mp3\");\n\n    if (!stream.isRunning())\n        Serial.println(\"No file running\");\n}\n\nvoid loop() {\n    stream.loop();\n    delay(5);\n}\n\n```\n\n## Known issues\n`Ogg` and `flac` files can not be resumed from an offset without first playing a couple of seconds from the start of the file. \n\n## Tips for troublefree streaming\n\n### WiFi setup\n\n- Switch off the BlueTooth radio if unused.  \n- Switch off power save mode.\n\n```c++\n...\nbtStop();\nWiFi.begin(SSID, PSK);\nWiFi.setSleep(false); \n...\n```\n\n### Prevent reboots when used on early esp32\nEarly versions of the esp32 have issues with the external psram cache, resulting in reboots.  \nWorkarounds are possible depending on the hardware revision.\n\n#### Revision V0.0\nNo workarounds are possible for this revision other than not using the psram.\n\n#### Revision V1.0\nOn revision V1.0 psram can be used with the following build flags:\n```bash\n-D BOARD_HAS_PSRAM\n-mfix-esp32-psram-cache-issue\n-mfix-esp32-psram-cache-strategy=memw\n```\n\n#### Revision V3.0\nOn revision V3.0 psram can be used with the following build flag:\n```bash\n-D BOARD_HAS_PSRAM\n```\n\nSource: [esp-idf api guide on external ram](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/external-ram.html#chip-revisions).\n\n#### Find your hardware revision\n\nIn PIO you can find out what hardware revision you have by running `esptool.py flash_id` in a terminal.\n\nIn Arduino IDE go to `File-\u003ePreferences` and find the `Show verbose output during` option. Check the box marked `upload`.  \nYou can now see the hardware revision when you upload a sketch.\n\n# Functions\n### Initialize the VS1053 codec\n\n```c++\nbool startDecoder(CS, DCS, DREQ);\n```\n### Check if VS1053 is responding\n```c++\nbool isChipConnected();\n```\n### Start or resume a stream\n```c++\nbool connectToHost(url);\n```\n```c++\nbool connectToHost(url, offset);\n```\n```c++\nbool connectToHost(url, user, pwd);\n```\n```c++\nbool connectToHost(url, user, pwd, offset);\n```\nNote: When a stream does not start in this library but it does play on your desktop or laptop you can try increasing the connection timeout.  \nYou can do this in `ESP32_VS1053_Stream.h` by increasing these values:  \n```c++\n#define VS1053_CONNECT_TIMEOUT_MS 250\n#define VS1053_CONNECT_TIMEOUT_MS_SSL 750\n```\n### Start or resume a local file\n```c++\nbool connectToFile(filesystem, filename);\n```\n```c++\nbool connectToFile(filesystem, filename, offset);\n```\n`filesystem` has to be mounted.  \n### Stop a running stream\n```c++\nvoid stopSong();\n```\n### Feed the decoder\n```c++\nvoid loop();\n```\nThis function has to called every couple of ms to feed the decoder with data.  \nFor bitrates up to 320kbps somewhere between 2-5 ms is about right.\n### Check if stream is running\n```c++\nbool isRunning();\n```\n### Get the current volume\n```c++\nuint8_t getVolume();\n```\n### Set the volume\n```c++\nvoid setVolume(newVolume);\n```\n`newVolume` should be in the range 0-100.\n### Set bass and treble\n```c++\nuint8_t rtone[4]  = {toneha, tonehf, tonela, tonelf};\nvoid setTone(rtone);\n```\nValues for `rtone`:\n```c++\ntoneha       = \u003c0..15\u003e        // Setting treble gain (0 off, 1.5dB steps)\ntonehf       = \u003c0..15\u003e        // Setting treble frequency lower limit x 1000 Hz\ntonela       = \u003c0..15\u003e        // Setting bass gain (0 = off, 1dB steps)\ntonelf       = \u003c0..15\u003e        // Setting bass frequency lower limit x 10 Hz\n```\n### Get the current stream url\n```c++\nconst char* lastUrl();\n```\nThe current stream url might differ from the request url if the request url points to a playlist.\n### Get the filesize\n```c++\nsize_t size();\n```\nReturns `0` if the stream is a radio stream.\n### Get the current position in the file\n```c++\nsize_t position();\n```\nReturns `0` if the stream is a radio stream.\n### Get the buffer fill status\n```c++\nvoid bufferStatus(size_t \u0026used, size_t \u0026capacity);\n```\n\nNote: A buffer will only be allocated if there is enough free psram.\n\n# Event callback setup\n\nWith event callbacks you can run user defined routines on stream events.  \nCheck out the examples to see how to setup event callbacks. \n\n### Station name callback\n\n```c++\nvoid setStationCB(callback);\n```\nSet a callback on the stream name.  \nNote that not all streams provide a name.\n```c++\nvoid clearStationCB();\n```\nClear the stream name callback.\n### Stream metadata callback\n\n```c++\nvoid setInfoCB(callback);\n```\nSet a callback on stream metadata.  \nNote that not all streams provide metadata.\n```c++\nvoid clearInfoCB();\n```\nClear the metadata callback.\n### End of file callback\n\n```c++\nvoid setEofCB(callback);\n```\nSet a callback on the end-of-file.  \nAlso called if a stream or file times out/errors.\n\nYou can use the eof callback to code a playlist.  \nUse `connectToHost()` or `connectToFile()` inside the eof callback to start the next item.\n```c++\nvoid clearEofCB();\n```\nClear the end-of-file callback.\n### Bitrate callback\n```c++\nvoid setBitrateCB(callback);\n```\nSet a callback on bitrate detection.  \nThis callback will be called multiple times on a vbr stream.\n```c++\nvoid clearBitrateCB();\n```\nClear the bitrate callback.\n\n## License\n\nMIT License\n\nCopyright (c) 2021 Cellie\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcelliesprojects%2Fesp32_vs1053_stream","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcelliesprojects%2Fesp32_vs1053_stream","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcelliesprojects%2Fesp32_vs1053_stream/lists"}