{"id":16237675,"url":"https://github.com/pschatzmann/arduino-libhelix","last_synced_at":"2025-04-06T09:09:59.190Z","repository":{"id":113205834,"uuid":"389340968","full_name":"pschatzmann/arduino-libhelix","owner":"pschatzmann","description":"A simple MP3 and AAC Decoder (not only) for Arduino based on libhelix","archived":false,"fork":false,"pushed_at":"2025-03-20T21:13:14.000Z","size":2755,"stargazers_count":91,"open_issues_count":0,"forks_count":22,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-03-30T08:09:55.526Z","etag":null,"topics":["aac","arduino-library","audio","codec","mp3"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.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.txt","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":"2021-07-25T12:21:35.000Z","updated_at":"2025-03-28T16:23:22.000Z","dependencies_parsed_at":"2024-03-30T19:27:09.920Z","dependency_job_id":"9ac2f375-3bb2-499f-af55-026741543924","html_url":"https://github.com/pschatzmann/arduino-libhelix","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pschatzmann%2Farduino-libhelix","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pschatzmann%2Farduino-libhelix/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pschatzmann%2Farduino-libhelix/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pschatzmann%2Farduino-libhelix/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pschatzmann","download_url":"https://codeload.github.com/pschatzmann/arduino-libhelix/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247457803,"owners_count":20941906,"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","arduino-library","audio","codec","mp3"],"created_at":"2024-10-10T13:36:38.022Z","updated_at":"2025-04-06T09:09:59.168Z","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"],"categories":[],"sub_categories":[],"readme":"# A MP3 and AAC Decoder using Helix\n\nI am providing the [Helix MP3 decoder from RealNetworks](https://en.wikipedia.org/wiki/Helix_Universal_Server) as a simple Arduino Library. The Helix decoders are based on 16bits integers, so they are a perfect fit to be used in Microcontrollers.\n\nMP3 is a compressed audio file formats based on PCM. A 2.6 MB wav file can be compressed down to 476 kB MP3.\n\nThis project can be used stand alone or together with the [arduino-audio_tools library](https://github.com/pschatzmann/arduino-audio-tools). It can also be used from non Arduino based systems with the help of cmake.\n\nThe Helix MP3 decoder provides Layer 3 support for MPEG-1, MPEG-2, and MPEG-2.5. It supports variable bit rates, constant bit rates, and stereo and mono audio formats. \n\n## API Example\n\nThe API provides the decoded data to a __Arduino Stream__ or alternatively to a callback function. The platform dependent I2S implementations usually implement I2S as subclass of Stream, so you can just provide the corresponding I2S object to the constructor.\n\nHere is a MP3 example using the callback:\n\n```\n#include \"MP3DecoderHelix.h\"\n#include \"music_mp3.h\"\n\nusing namespace libhelix;\n\nvoid dataCallback(MP3FrameInfo \u0026info, int16_t *pcm_buffer, size_t len, void*) {\n    for (int i=0; i\u003clen; i+=info.nChans){\n        for (int j=0;j\u003cinfo.nChans;j++){\n            Serial.print(pcm_buffer[i+j]);\n            Serial.print(\" \");\n        }\n        Serial.println();\n    }\n}\n\nMP3DecoderHelix mp3(dataCallback);\n\nvoid setup() {\n    Serial.begin(115200);\n    mp3.begin();\n}\n\nvoid loop() {\n    Serial.println(\"writing...\");\n    mp3.write(music_data, music_len);    \n\n    // restart from the beginning\n    delay(2000);\n    mp3.begin();\n}\n\n```\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\n```\ncd  ~/Documents/Arduino/libraries\ngit clone https://github.com/pschatzmann/arduino-libhelix.git\n```\n\nThis project can also be built and executed on your desktop with cmake:\n\n```\ncd arduino-libhelix\nmkdir build\ncd build\ncmake ..\nmake\n```\n\n## Parameters\n\nThe decoder needs to allocate a buffer to store a frame and the decoded data. The following default values have been defined in ConfigHelix.h: \n\n```\n#define MP3_MAX_OUTPUT_SIZE 1024 * 5\n#define MP3_MAX_FRAME_SIZE 1024 * 2 \n#define AAC_MAX_OUTPUT_SIZE 1024 * 8 \n#define AAC_MAX_FRAME_SIZE 2100 \n```\n\nThese values are working with standard bitrates, but in some exceptional cases (with extreme (220kbs) or insane (320kbs) bitrates) you might need to increase these values e.g. to\n```\n#define MP3_MAX_OUTPUT_SIZE 1024 * 10\n#define MP3_MAX_FRAME_SIZE 3200\n```\n\nAlternatively you can set the values in your sketch by calling the following methods:\n```\nsetMaxPCMSize(int size)\nsetMaxFrameSize(int size)\n```\n\n## Memory Management\n\nOn the ESP32 we support PSRAM: just activate it in the Arduino Tools menu and all the memory will be allocated in PSRAM.\n\n## Logging\n\nYou can define the log level as Debug, Info, Warning, Error\n```\nLOGLEVEL_HELIX = LogLevelHelix::Info;\n```\n\n\n\n## Documentation\n\n- The [Class Documentation can be found here](https://pschatzmann.github.io/arduino-libhelix/html/annotated.html)\n- aac [readme.txt](https://github.com/pschatzmann/arduino-libhelix/blob/main/src/libhelix-aac/readme.txt)\n- mp3 [readme.txt](https://github.com/pschatzmann/arduino-libhelix/blob/main/src/libhelix-mp3/readme.txt)\n- I also suggest that you have a look at [my related blogs](https://www.pschatzmann.ch/home/tag/codecs/)\n\nI recommend to use this library together with my [Arduino Audio Tools](https://github.com/pschatzmann/arduino-audio-tools). \nThis is just one of many codecs that I have collected so far: Further details can be found in the [Encoding and Decoding Wiki](https://github.com/pschatzmann/arduino-audio-tools/wiki/Encoding-and-Decoding-of-Audio) of the Audio Tools.\n\n### Final Comments\n\nThis library is based on a adapted version of libhelix from [Earle Phil Hower's ESP8288Audio library](https://github.com/earlephilhower/ESP8266Audio)  \nThe decoder code is from the Helix project and licensed under RealNetwork's [RPSL license](https://github.com/pschatzmann/arduino-libhelix/blob/main/src/libhelix-mp3/RPSL.txt). For commercial use you might still going to need the usual AAC licensing.\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpschatzmann%2Farduino-libhelix","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpschatzmann%2Farduino-libhelix","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpschatzmann%2Farduino-libhelix/lists"}