{"id":50103716,"url":"https://github.com/gf-silva/musicplayer","last_synced_at":"2026-05-23T09:03:50.633Z","repository":{"id":342443552,"uuid":"1082286874","full_name":"GF-Silva/MusicPlayer","owner":"GF-Silva","description":"ESP32 MP3 player with Bluetooth A2DP, microSD support, and modular C architecture","archived":false,"fork":false,"pushed_at":"2026-05-19T21:02:18.000Z","size":351,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-20T00:40:04.511Z","etag":null,"topics":["audio","bluetooth","c-language","embbeded-system","esp32","mp3","music-player"],"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/GF-Silva.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-24T02:39:52.000Z","updated_at":"2026-05-19T21:02:22.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/GF-Silva/MusicPlayer","commit_stats":null,"previous_names":["gf-silva/musicplayer"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/GF-Silva/MusicPlayer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GF-Silva%2FMusicPlayer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GF-Silva%2FMusicPlayer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GF-Silva%2FMusicPlayer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GF-Silva%2FMusicPlayer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GF-Silva","download_url":"https://codeload.github.com/GF-Silva/MusicPlayer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GF-Silva%2FMusicPlayer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33389230,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-23T04:15:53.637Z","status":"ssl_error","status_checked_at":"2026-05-23T04:15:53.242Z","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":["audio","bluetooth","c-language","embbeded-system","esp32","mp3","music-player"],"created_at":"2026-05-23T09:03:32.912Z","updated_at":"2026-05-23T09:03:50.626Z","avatar_url":"https://github.com/GF-Silva.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MusicPlayer\n\nPlayer de MP3 com `ESP32` que lê arquivos de um cartão `microSD`, decodifica em tempo real com `Helix MP3` e transmite o áudio via `Bluetooth Classic A2DP` para uma caixa de som, fone ou TWS.\n\nO projeto foi organizado em módulos para separar bootstrap, Bluetooth, pipeline de áudio, playback, energia e entrada do usuário. Além do fluxo principal de reprodução, ele também trata reconexão automática, pré-buffer, recuperação de falhas de stream e `deep sleep`.\n\n## Visão geral\n\nEste firmware:\n\n- monta o cartão `microSD` via `SDSPI`\n- procura arquivos `.mp3` na raiz do cartão\n- busca um dispositivo Bluetooth alvo por `MAC address`\n- conecta como `A2DP Source`\n- decodifica os frames MP3 com `esp-libhelix-mp3`\n- envia PCM para um buffer circular e transmite o áudio por Bluetooth\n- entra em `deep sleep` por botão ou por inatividade\n\n## Funcionalidades\n\n- Reprodução de arquivos MP3 direto do `microSD`\n- Transmissão sem fio via `Bluetooth Classic A2DP Source`\n- Reconexão automática quando a conexão cai\n- Novo ciclo de discovery quando o Bluetooth fica preso ou falha repetidamente\n- Pré-buffer antes de iniciar o stream para reduzir falhas\n- Recuperação de `decode stall` avançando para outra faixa\n- Seleção aleatória da próxima música\n- Controle de volume por sequência de cliques no botão de power\n- `Deep sleep` com wakeup pelo botão\n- Estrutura modular em C com separação por responsabilidade\n\n## Hardware usado\n\n- `ESP32`\n- Cartão `microSD`\n- Módulo/leitor SD em modo `SPI`\n- Caixa de som, fone ou TWS com `Bluetooth A2DP`\n- 1 botão ligado ao pino de power/wakeup\n- LED de status na placa\n\n## Pinagem atual\n\nConfiguração definida em [`main/main.c`](/home/ferreira/Público/projetos/MusicPlayer/main/main.c):\n\n- `MISO`: GPIO `19`\n- `MOSI`: GPIO `23`\n- `CLK`: GPIO `18`\n- `CS`: GPIO `4`\n- `POWER / WAKE`: GPIO `33`\n- `LED`: GPIO `2`\n\n## Controles\n\nO controle é feito pelo botão conectado ao GPIO `33`:\n\n- Segurar por aproximadamente `2s`: entra em `deep sleep`\n- Clique duplo: aumenta o volume\n- Clique triplo: diminui o volume\n\n## Fluxo de funcionamento\n\n1. O sistema inicia e configura wakeup/LED.\n2. O cartão SD é montado em `/sdcard`.\n3. Os arquivos `.mp3` da raiz do cartão são contados.\n4. Os buffers de áudio e o decoder são preparados.\n5. O ESP32 procura o dispositivo Bluetooth alvo.\n6. Ao conectar, o stream A2DP é iniciado.\n7. As músicas são tocadas e, ao terminar, a próxima faixa é escolhida de forma aleatória.\n\n## Estrutura do projeto\n\n```text\nmain/\n  main.c\n  module/\n    audio/       # buffers, pipeline e callback A2DP\n    bootstrap/   # montagem dos contextos e fachada do app\n    bt/          # init BT, discovery, callbacks A2DP/AVRCP/GAP\n    control/     # fila de comandos e tasks principais\n    input/       # leitura do botão e volume\n    playback/    # biblioteca de mídia e engine de decodificação\n    power/       # LED, wakeup e deep sleep\n    storage/     # montagem do cartão SD\ncomponents/\n  esp-libhelix-mp3/\n```\n\n## Requisitos\n\n- `ESP-IDF 5.4.2`\n- Target `esp32`\n- Toolchain configurado com `idf.py`\n\nO projeto usa a dependência `esp-libhelix-mp3` já incluída no repositório em `components/`.\n\n## Como compilar e gravar\n\n```bash\nidf.py set-target esp32\nidf.py menuconfig\nidf.py build\nidf.py -p /dev/SEU_PORTA flash monitor\n```\n\n## Como usar\n\n1. Coloque arquivos `.mp3` na raiz do cartão `microSD`.\n2. Ajuste no `idf.py menuconfig` o `MAC` do dispositivo Bluetooth alvo.\n3. Grave o firmware no `ESP32`.\n4. Ligue o dispositivo.\n5. Aguarde o discovery e a conexão Bluetooth.\n\n## Configuração importante\n\nO dispositivo Bluetooth alvo agora pode ser ajustado via `idf.py menuconfig`, no menu `MusicPlayer Configuration`.\n\nOs campos mais importantes são:\n\n- nome do dispositivo de referência\n- `MAC address` do alvo\n\nO projeto continua priorizando a conexão por `MAC address`. Antes de publicar, vale deixar claro no seu post qual caixa de som/TWS foi usada nos testes e qual `MAC` foi configurado.\n\n## Configuração via menuconfig\n\nAs principais opções do projeto agora podem ser ajustadas em `idf.py menuconfig`:\n\n- nome do dispositivo Bluetooth de referência\n- `MAC address` do alvo\n- GPIOs do SD, botão e LED\n- volume inicial e passo de volume\n- timeouts de sleep, discovery e recovery\n- tamanhos dos buffers de áudio\n\nAs opções ficam no menu `MusicPlayer Configuration`.\n\n## Comportamento atual e limitações\n\n- Os arquivos `.mp3` são buscados somente na raiz de `/sdcard`\n- A próxima faixa é escolhida de forma aleatória\n- O projeto depende de um dispositivo Bluetooth alvo configurado no `menuconfig`\n- A compatibilidade de amostragem é validada para `44.1 kHz` e `48 kHz`\n- O auto-sleep ocorre após aproximadamente `1 minuto` sem Bluetooth/áudio\n- Não há interface gráfica, display ou menu local\n\n## Arquivos importantes\n\n- Entrada principal: [`main/main.c`](/home/ferreira/Público/projetos/MusicPlayer/main/main.c)\n- Gerência Bluetooth: [`main/module/bt/bt_manager.c`](/home/ferreira/Público/projetos/MusicPlayer/main/module/bt/bt_manager.c)\n- Callbacks Bluetooth: [`main/module/bt/bt_callbacks.c`](/home/ferreira/Público/projetos/MusicPlayer/main/module/bt/bt_callbacks.c)\n- Engine de playback: [`main/module/playback/playback_engine.c`](/home/ferreira/Público/projetos/MusicPlayer/main/module/playback/playback_engine.c)\n- Biblioteca de mídia: [`main/module/playback/media_library.c`](/home/ferreira/Público/projetos/MusicPlayer/main/module/playback/media_library.c)\n- Entrada do usuário: [`main/module/input/input_manager.c`](/home/ferreira/Público/projetos/MusicPlayer/main/module/input/input_manager.c)\n- Energia e sleep: [`main/module/power/sleep_manager.c`](/home/ferreira/Público/projetos/MusicPlayer/main/module/power/sleep_manager.c)\n\n## Ideias para evolução\n\n- Suporte a pastas e playlists\n- Próxima/anterior faixa por botões dedicados\n- Persistência de volume e última faixa\n- Pareamento/configuração sem recompilar\n- Indicadores visuais mais completos\n- Testes automatizados para módulos puros\n\n## Status\n\nProjeto funcional e pronto para testes em hardware real.\n\nSe for publicar no GitHub, Reddit e LinkedIn, adicionar fotos do protótipo, esquema de ligação e um pequeno vídeo do sistema tocando música vai aumentar bastante a credibilidade do projeto.\n\n## Licença\n\nEste repositório está sob a licença `MIT`. Veja [`LICENSE`](/home/ferreira/Público/projetos/MusicPlayer/LICENSE).\n\nDependências de terceiros mantêm suas próprias licenças. Em especial, o decoder incluído em `components/esp-libhelix-mp3/` possui arquivos de licença próprios dentro do componente.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgf-silva%2Fmusicplayer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgf-silva%2Fmusicplayer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgf-silva%2Fmusicplayer/lists"}