{"id":13591071,"url":"https://github.com/CelliesProjects/ESP32_VS1053_Stream","last_synced_at":"2025-04-08T14:32:25.610Z","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 (insecure mode) and chunked streams and parses the metadata. Also plays ogg and mp3 from sdcard.","archived":false,"fork":false,"pushed_at":"2025-02-27T12:07:14.000Z","size":183,"stargazers_count":80,"open_issues_count":7,"forks_count":15,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-07T10:21:12.552Z","etag":null,"topics":["aac","aacp","arduino-library","esp32","esp32-c3","esp32-s2","esp32-s3","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}},"created_at":"2021-06-09T09:46:48.000Z","updated_at":"2025-03-28T14:10:35.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":19,"template":false,"template_full_name":null,"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","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247860945,"owners_count":21008390,"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":["aac","aacp","arduino-library","esp32","esp32-c3","esp32-s2","esp32-s3","mediaplayer","mp3","ogg","psram","sdcard","stream","vs1053","wav","webradio"],"created_at":"2024-08-01T16:00:53.276Z","updated_at":"2025-04-08T14:32:25.595Z","avatar_url":"https://github.com/CelliesProjects.png","language":"C++","funding_links":[],"categories":["C++"],"sub_categories":[],"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.\u003cbr\u003e\nThis library plays mp3, ogg, aac, aac+ and \u003cstrike\u003eflac\u003c/strike\u003e files and streams and uses [ESP_VS1053_Library](https://github.com/baldram/ESP_VS1053_Library) to communicate with the decoder.\n\nSupported stream methods are http and insecure https. Streams can be chunked.\u003cbr\u003e\nAlso plays mp3 and ogg files from sdcard or any mounted filesystem.\n\n## How to install and use\n\nInstall [ESP_VS1053_Library](https://github.com/baldram/ESP_VS1053_Library) and this library in your Arduino library folder.\n\nTake care to install the master branch of the VS1053 library or at least a version from commit [ba1803f](https://github.com/baldram/ESP_VS1053_Library/commit/ba1803f75722a36f3e9f539129e885bea3c60f71) or later because the `getChipVersion()` call that is needed is not included in the latest release.\u003cbr\u003eSee https://github.com/CelliesProjects/ESP32_VS1053_Stream/issues/23\n\nUse the [latest Arduino ESP32 core version](https://github.com/espressif/arduino-esp32/releases/latest).\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\nvoid setup() {\n    Serial.begin(115200);\n\n    while (!Serial)\n        delay(10);\n\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    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 - system halted\");\n        while (1) delay(100);\n    }\n\n    Serial.print(\"Codec: \");\n    Serial.println(stream.currentCodec());\n\n    Serial.print(\"Bitrate: \");\n    Serial.print(stream.bitrate());\n    Serial.println(\" kbps\");\n}\n\nvoid loop() {\n    stream.loop();\n    delay(5);\n}\n\nvoid audio_showstation(const char* info) {\n    Serial.printf(\"Station: %s\\n\", info);\n}\n\nvoid audio_showstreamtitle(const char* info) {\n    Serial.printf(\"Stream title: %s\\n\", info);\n}\n\nvoid audio_eof_stream(const char* info) {\n    Serial.printf(\"End of stream: %s\\n\", info);\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\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\n    while (!Serial)\n        delay(10);\n\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    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 - system halted\");\n        while (1) delay(100);\n    }\n\n    Serial.print(\"Codec: \");\n    Serial.println(stream.currentCodec());\n}\n\nvoid loop() {\n    stream.loop();\n    delay(5);\n}\n\nvoid audio_eof_stream(const char* info) {\n    Serial.printf(\"End of file: %s\\n\", info);\n}\n```\n\n## Known issues\nOgg files can not be started with 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\nDo not forget to switch WiFi out of power save mode:\n\n```c++\n...\nWiFi.begin(SSID, PSK);\nWiFi.setSleep(false); \n...\n```\n\n### Prevent reboots while playing\nEarly version of the esp32 have issues with the external psram cache, resulting in reboots.\u003cbr\u003eWorkarounds 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`.\u003cbr\u003eYou 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.\u003cbr\u003e\nYou can do this in \n`ESP32_VS1053_Stream.h` by increasing these values:\u003cbr\u003e\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.\u003cbr\u003eFor bitrates up to 320kbps somewhere between 5-25 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 used codec\n```c++\nconst char* currentCodec()\n```\nReturns `STOPPED` if no stream is running.\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++\nconst char *bufferStatus()\n```\nReturns `0/0` if there is no buffer.\u003cbr\u003eOtherwise returns something like `4096/65536` which means 4kB waiting in a 64kB buffer.\n```c++\nvoid bufferStatus(size_t \u0026used, size_t \u0026capacity)\n```\nThis version takes two `size_t` variables by reference.\u003cbr\u003eWorks the same as the `const char *` version.\n\nNOTE: A buffer will only be allocated if there is enough free psram.\n\n# Event callbacks\n\n### Station name callback.\n\n```c++\nvoid audio_showstation(const char* info)\n```\n### Stream information callback.\n\n```c++\nvoid audio_showstreamtitle(const char* info)\n```\n### End of file callback.\n\n```c++\nvoid audio_eof_stream(const char* info)\n```\nReturns the eof url or path.\u003cbr\u003eAlso called if a stream or file times out/errors.\n\nYou can use this function for coding a playlist.\u003cbr\u003eUse `connecttohost()` or `connecttofile()` inside this function to start the next item.\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","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"}