Desenvolvimento

Desenvolvimento

Requisitos

• JDK 17+ (o JBR do Android Studio serve)
• Android SDK com a plataforma 34
• Android Studio Koala ou mais recente (opcional — o Gradle Wrapper está no repositório)

Compilar e testar

./gradlew assembleDebug        # app/build/outputs/apk/debug/app-debug.apk
./gradlew testDebugUnitTest    # parsers ID3, LRC e leitura da resposta do tradutor
./gradlew installDebug         # instala no aparelho/emulador conectado

Versões principais: AGP 8.5, Kotlin 1.9.24, Compose BOM 2024.06, Media3 1.4, DataStore 1.1, minSdk 26, targetSdk 34.

Há um workflow do GitHub Actions pronto em ferramentas/ci/android.yml (testes + APK de debug a cada push). Para ativá-lo, siga o ferramentas/ci/LEIAME.md — é preciso autorizar o escopo workflow no gh.

Build de release assinado

O app/build.gradle.kts lê a assinatura de um keystore.properties na raiz do projeto — ele e o .jks ficam fora do git (.gitignore).

storeFile=songv-release.jks
storePassword=********
keyAlias=songv
keyPassword=********

./gradlew assembleRelease      # app/build/outputs/apk/release/app-release.apk (R8 + shrink, ~3 MB)

⚠️ Guarde o songv-release.jks e as senhas. Sem eles não é possível publicar atualizações que instalem por cima das versões anteriores.

Sem keystore.properties, o release sai sem assinatura (útil para CI); o debug funciona sempre.

Biblioteca de demonstração

Para testar sem usar músicas próprias — e para as capturas desta wiki — há um gerador de faixas 100% sintéticas (acordes gerados, capas desenhadas, letras e artistas fictícios) no mesmo formato do agente:

pip install mutagen pillow        # e ffmpeg no PATH
python ferramentas/biblioteca_demo.py saida/
adb push saida/. "/sdcard/Music/SongV Demo/"
adb shell content call --method scan_volume --uri content://media --arg external_primary

Ela inclui letras sincronizadas em português, inglês e coreano (para testar tradução e romanização), trechos instrumentais, uma letra sem sincronia, faixas sem letra, sem capa e sem álbum.

Estilo do código

• Nomes em português, como o resto do projeto (tocarAseguir, CapaRepository…).
• Comentários explicam o porquê — especialmente quando corrigem um comportamento da versão anterior.
• Sem dependências novas para o que poucas linhas resolvem (HTTP, cache de imagem, JSON).

Publicando uma versão

1. Atualize versionCode / versionName em app/build.gradle.kts e o CHANGELOG.md.
2. ./gradlew assembleRelease
3. gh release create vX.Y.Z app/build/outputs/apk/release/app-release.apk#SongV-X.Y.Z.apk --notes-file ...