MagicPlaylist
Uma aplicacao Android nativa que gera playlists musicais a partir de faixas selecionadas usando dados de similaridade do Shazam, e depois exporta diretamente para o Spotify - construida com Kotlin, Jetpack Compose e Material Design 3.
Linhas Kotlin
5,666
Codigo Android nativo
Arquivos Fonte
46
Arquivos fonte Kotlin
Componentes UI
22
Componentes Compose reutilizaveis
Estrategias de Mapping
5
Cadeia de fallback Shazam-para-Spotify
Visao Geral do Projeto
O que e MagicPlaylist e por que existe
MagicPlaylist e uma aplicacao Android nativa escrita em Kotlin que gera automaticamente playlists musicais a partir de faixas escolhidas pelo usuario. O app usa a API nao-oficial do Shazam para descobrir faixas similares, e depois exporta as playlists geradas diretamente para a conta Spotify do usuario.
O conceito e simples mas poderoso: o usuario insere uma ou mais musicas que gosta, e a aplicacao constroi uma playlist completa de faixas similares explorando recursivamente as relacoes de similaridade musical via Shazam, e salva o resultado no Spotify.
Este projeto foi construido no contexto do Mestrado em Engenharia de Software na ESIEA como projeto de formacao. Ele responde a uma necessidade real dos entusiastas de musica: a dificuldade de descobrir novas faixas correspondentes a um estilo musical especifico e construir playlists tematicas de qualidade sem passar horas buscando manualmente.
B2C - Publico geral, usuarios do Spotify que desejam enriquecer suas playlists e descobrir novos artistas atraves de uma experiencia mobile intuitiva.
- Busca de musicas em tempo real com auto-complete via API Shazam
- Selecao multi-seeds (1-50 faixas) com exibicao de capas de album
- Expansao BFS configuravel: profundidade 1-3, ate 10.000 faixas, deduplicacao
- Estimativa preditiva de faixas esperadas e chamadas API antes da geracao
- Reproducao de previews de audio com modo exclusivo de faixa unica
- Exportacao OAuth 2.0 para Spotify com chunking progressivo de 3 niveis
- Mapping Shazam-para-Spotify com 5 estrategias (ISRC, exato, fuzzy Levenshtein)
Objetivos, Contexto e Riscos
A visao estrategica por tras do projeto
O projeto foi guiado por cinco objetivos mensuraveis:
Stack Android Moderno
SDK 36
Jetpack Compose, Material 3, MVVM, Kotlin 2.0.21
Integracao API
2 APIs
Shazam (nao-oficial) + Spotify (oficial) com tratamento de erros
Precisao do Mapping
95%+
Correspondencia Shazam-para-Spotify via 5 estrategias de fallback
Escala de Playlists
10K faixas
Gerenciar playlists grandes com orcamento max de 500 chamadas API
Velocidade de Dev
2 dias
Entrega completa com desenvolvimento assistido por IA
Este projeto foi construido como parte do Mestrado em Engenharia de Software na ESIEA. As escolhas tecnologicas foram deliberadamente de ponta: Kotlin 2.0.21, Compose BOM 2024.12, Android SDK 36 e AGP 8.13. Uma decisao arquitetural chave foi usar a API web nao-oficial do Shazam diretamente em vez de um wrapper pago (RapidAPI), trazendo flexibilidade mas tambem risco de fragilidade.
A proposta de valor central repousa na qualidade da recomendacao musical - a relevancia das faixas descobertas e a confiabilidade do mapping Shazam-para-Spotify. A experiencia do usuario foi projetada com animacoes polidas, designs em gradiente, confetes de celebracao e feedback de progresso em tempo real durante a geracao.
Mudancas na API Nao-Oficial do Shazam
Probabilidade alta, impacto critico. Nenhum contrato de API existe. Mitigado por spoofing de headers de navegador, mas intrinsecamente fragil.
Rate Limiting (Shazam + Spotify)
Probabilidade alta, impacto medio. Mitigado por chunking progressivo de 3 niveis, backoff exponencial e patterns circuit breaker.
Variabilidade das Respostas Shazam
Probabilidade media. Algumas respostas Shazam tem dados incompletos. Mitigado por tratamento de fallback para campos ausentes.
Taxa de Mapping < 95%
Probabilidade media. Mitigado por 5 estrategias de fallback (ISRC, exato, fuzzy, correspondencia por duracao).
Expiracao de Tokens Spotify
Probabilidade baixa. Mitigado por refresh automatico e persistencia de tokens.
Fases de Implementacao
Um percurso cronologico do processo de desenvolvimento
- Configuracao do projeto Android com Gradle Kotlin DSL e SDK 36
- Arquitetura MVVM com Jetpack Compose e StateFlow
- Tema Material 3 com cores dinamicas
- Tela inicial com interface de busca em tempo real
- Integracao da API nao-oficial Shazam (busca + similaridade)
- Algoritmo de expansao BFS com protecoes matematicas
- Motor de estimativa preditiva (faixas esperadas + orcamento API)
- Orquestracao API assincrona baseada em coroutines
- Autenticacao OAuth 2.0 via Spotify Auth SDK 2.1.1
- Callback deep linking (magicplaylist://callback)
- Mapping Shazam-para-Spotify com 5 estrategias (ISRC, exato, fuzzy Levenshtein)
- Chunking progressivo de 3 niveis (20/10/1 faixas por batch)
- Teste de cenario completo: 2 seeds -> 126 faixas descobertas -> exportacao Spotify
- 15 capturas de tela documentando o fluxo completo do usuario
- 6 documentos tecnicos (PRD, estrategia de mapping, chunking, expansao)
- Scripts de teste beta em Python para analise das APIs
Equipe e Interacoes
O modelo de colaboracao humano-IA
Tamanho da equipe: 1 pessoa + assistente IA
O projeto foi desenvolvido por Jose DA COSTA como product owner, arquiteto funcional, designer UI e lider de QA. Claude Code (Anthropic) foi usado intensivamente como assistente de pair-programming ao longo do desenvolvimento.
O modelo de colaboracao seguiu um ciclo iterativo: Jose especificava requisitos atraves de ~80 prompts detalhados (71 KB de CLAUDE_PROMPTS.md), validava resultados no emulador, identificava bugs e direcionava correcoes. Claude Code produzia a implementacao, escolhia padroes tecnicos, escrevia documentacao e corrigia problemas reportados.
- Visao de produto e design da jornada completa do usuario
- Reverse-engineering da API Shazam (captura de comandos curl com todos os headers)
- ~80 especificacoes funcionais detalhadas via prompts estruturados
- Todas as decisoes de UI/UX (gradientes, cores, espessura de bordas, espacamentos)
- QA manual no emulador: identificacao de cada bug (crashes, playlists vazias, falhas de auth)
- Padroes nao-negociaveis: ingles obrigatorio, zero comentarios de codigo, Material 3, acessibilidade
- 100% das 5.666 linhas de Kotlin em 46 arquivos
- Implementacao da arquitetura MVVM com StateFlow
- Todos os 6 documentos tecnicos (PRD, estrategias, guidelines)
- Configuracao Gradle Kotlin DSL e version catalog
- Resolucao de bugs para cada problema reportado
- Design do icone do aplicativo (variantes SVG/XML de nota musical)
Shazam (Apple)
Music data & similarity - Unofficial API
Spotify
Playlist destination - Official OAuth 2.0 API
ESIEA
Training institution - Master program context
Resultados e Impacto
Resultados concretos para o desenvolvedor e o projeto
Desenvolvimento Android nativo com o stack Kotlin/Compose mais recente
Metodologia de reverse-engineering de API (padroes de consumo de API nao-oficial)
Workflow de desenvolvimento assistido por IA: pair programming orientado por especificacoes
Design algoritmico avancado: exploracao BFS com restricoes matematicas
Implementacao do fluxo OAuth 2.0 em mobile com deep linking
Padroes resilientes de integracao API: chunking, backoff, circuit breaker
App Android funcional com 12 funcionalidades da busca a exportacao Spotify
Cenario demonstrado: 2 seeds -> 126 faixas descobertas -> 38 exportadas para Spotify
5.666 linhas de codigo Kotlin limpo e bem estruturado seguindo MVVM
22 componentes Compose UI reutilizaveis com suporte a acessibilidade
10 documentos tecnicos cobrindo arquitetura, estrategias e setup
15 capturas de tela documentando a jornada completa do usuario
2 seed tracks (Dennis Ferrer) - 126 tracks discovered - 38 exported to Spotify after retry
Apos o Projeto
O que aconteceu apos a entrega
O projeto foi entregue como uma aplicacao Android completa e funcional demonstrando descoberta musical e geracao de playlists de ponta a ponta. Como projeto de formacao no contexto do Mestrado ESIEA, cumpriu seu objetivo principal: provar a capacidade de construir uma aplicacao Android nativa do zero com tecnologias modernas.
A ausencia de repositorio Git significa que nao ha historico de versoes. A aplicacao permanece na maquina de desenvolvimento como um APK autonomo. Nenhuma publicacao no Google Play Store foi planejada ou tentada.
A dependencia da API nao-oficial do Shazam representa o maior risco a longo prazo. Qualquer mudanca na estrutura da API ou headers quebraria a funcionalidade principal. Para um cenario de producao, uma migracao para uma API de recomendacao musical oficial (Spotify Recommendations, Last.fm) seria a evolucao natural.
Trajetoria relacionada
Experiencia profissional ligada a esta realizacao
Reflexao Critica
Uma retrospectiva honesta sobre o projeto
Produto funcional de ponta a ponta demonstrado com capturas de tela reais
Stack tecnologico de ponta (Kotlin 2.0.21, SDK 36, Compose 2024.12)
Arquitetura MVVM limpa com separacao de responsabilidades
Documentacao tecnica rica superando os padroes habituais de projetos de formacao
Tratamento avancado de erros: chunking 3 niveis, mapping 5 estrategias, circuit breaker
Acessibilidade integrada: componentes dedicados, alvos 48dp, contraste 4.5:1
Sem Repositorio Git
Um .gitignore existe mas nenhum repositorio foi inicializado. Critico para rastreabilidade e colaboracao.
Sem Testes Unitarios
Dependencias de teste estao presentes (JUnit, Espresso, Compose UI Test) mas zero arquivos de teste escritos. O algoritmo BFS e o mapper merecem testes aprofundados.
Sem Persistencia Local
Room e referenciado no version catalog mas nao ativado. Playlists geradas nao sobrevivem ao fechamento do app.
Dependencia de API Nao-Oficial
A API nao-oficial do Shazam e fragil. Nenhum fallback para fontes alternativas de recomendacao esta implementado.
Injecao de Dependencias Ausente
Hilt esta no version catalog mas nao e usado. Servicos sao provavelmente instanciados manualmente.
IA acelera mas nao substitui o julgamento de engenharia: a decisao de nao escrever testes ou inicializar git permanece responsabilidade do desenvolvedor.
Documentacao antecipada (PRDs, documentos de estrategia) visivelmente guiou um desenvolvimento coerente e estruturado.
Rate limiting deve ser uma preocupacao arquitetural desde o primeiro dia ao depender de APIs de terceiros, nao uma correcao posterior.
Competencias aplicadas
Competencias tecnicas e humanas aplicadas
Galeria de imagens
Capturas e visuais do projeto