MagicPlaylist
A native Android application that generates music playlists from seed tracks using Shazam similarity data, then exports them directly to Spotify - built with Kotlin, Jetpack Compose, and Material Design 3.
Kotlin Lines
5,666
Native Android code
Source Files
46
Kotlin source files
UI Components
22
Reusable Compose components
Mapping Strategies
5
Shazam-to-Spotify fallback chain
Project Overview
What MagicPlaylist is and why it exists
MagicPlaylist is a native Android application written in Kotlin that automatically generates music playlists from tracks chosen by the user. The app uses the unofficial Shazam API to discover similar tracks, then exports the generated playlists directly to the user's Spotify account.
The concept is simple but powerful: the user enters one or more songs they like, and the application builds a complete playlist of similar tracks by recursively exploring musical similarity relationships via Shazam, then saves the result to Spotify.
This project was built within the ESIEA Master in Software Engineering program as a training project. It addresses a real need among music enthusiasts: the difficulty of discovering new tracks matching a specific musical style and building quality thematic playlists without spending hours searching manually.
B2C - General public, Spotify users looking to enrich their playlists and discover new artists through an intuitive mobile experience.
- Real-time song search with auto-completion via Shazam API
- Multi-seed selection (1-50 tracks) with album artwork display
- Configurable BFS expansion: depth 1-3, up to 10,000 tracks, deduplication
- Predictive estimation of expected tracks and API calls before generation
- Audio preview playback with exclusive single-track mode
- OAuth 2.0 Spotify export with progressive 3-level chunking
- 5-strategy Shazam-to-Spotify mapping (ISRC, exact, fuzzy Levenshtein)
Objectives, Context & Risks
The strategic vision behind the project
The project was driven by five measurable goals:
Modern Android Stack
SDK 36
Jetpack Compose, Material 3, MVVM, Kotlin 2.0.21
API Integration
2 APIs
Shazam (unofficial) + Spotify (official) with error handling
Mapping Accuracy
95%+
Shazam-to-Spotify track matching via 5-strategy fallback
Playlist Scale
10K tracks
Handle large playlists with max 500 API calls budget
Dev Speed
2 days
Full app delivery with AI-assisted development
This project was built as part of the ESIEA Master in Software Engineering program. The technology choices were intentionally bleeding-edge: Kotlin 2.0.21, Compose BOM 2024.12, Android SDK 36, and AGP 8.13. A key architectural decision was to use Shazam's unofficial web API directly rather than a paid wrapper (RapidAPI), bringing flexibility but also fragility risk.
The core value proposition rests on music recommendation quality - the relevance of discovered tracks and the reliability of the Shazam-to-Spotify mapping. The user experience was designed with polished animations, gradient designs, confetti celebrations, and real-time progress feedback during generation.
Shazam Unofficial API Changes
High probability, critical impact. No API contract exists. Mitigated by browser header spoofing, but inherently fragile.
Rate Limiting (Shazam + Spotify)
High probability, medium impact. Mitigated by 3-level progressive chunking, exponential backoff, and circuit breaker patterns.
Shazam Response Variability
Medium probability. Some Shazam responses have incomplete data. Mitigated by fallback handling for missing fields.
Mapping Rate Below 95%
Medium probability. Mitigated by 5 fallback strategies (ISRC, exact, fuzzy, duration matching).
Spotify Token Expiration
Low probability. Mitigated by automatic refresh and token persistence.
Implementation Phases
A chronological walkthrough of the development process
- Android project setup with Gradle Kotlin DSL and SDK 36
- MVVM architecture with Jetpack Compose and StateFlow
- Material 3 theming with dynamic colors
- Home screen with real-time search UI
- Unofficial Shazam API integration (search + similarity endpoints)
- BFS expansion algorithm with mathematical guardrails
- Predictive estimation engine (expected tracks + API call budget)
- Coroutines-based asynchronous API orchestration
- OAuth 2.0 authentication via Spotify Auth SDK 2.1.1
- Deep linking callback (magicplaylist://callback)
- 5-strategy Shazam-to-Spotify mapping (ISRC, exact, fuzzy Levenshtein)
- 3-level progressive chunking (20/10/1 tracks per batch)
- Full scenario test: 2 seeds to 126 discovered tracks to Spotify export
- 15 screenshots documenting the complete user flow
- 6 technical documents (PRD, mapping strategy, chunking, expansion)
- Python beta test scripts for API analysis
Team & Interactions
The human and AI collaboration model
Team size: 1 person + AI assistant
The project was developed by Jose DA COSTA as product owner, functional architect, UI designer, and QA lead. Claude Code (Anthropic) was used intensively as a pair-programming assistant throughout the development.
The collaboration model followed an iterative cycle: Jose specified requirements through ~80 detailed prompts (71 KB of CLAUDE_PROMPTS.md), validated results on the emulator, identified bugs, and directed corrections. Claude Code produced the implementation, chose technical patterns, wrote documentation, and fixed reported issues.
- Product vision and complete user journey design
- Shazam API reverse-engineering (captured curl commands with full headers)
- ~80 detailed functional specifications via structured prompts
- All UI/UX decisions (gradients, colors, border thickness, spacing)
- Manual QA on emulator: identified every bug (crashes, empty playlists, auth failures)
- Non-negotiable standards: English only, zero code comments, Material 3, accessibility
- 100% of 5,666 Kotlin lines across 46 files
- MVVM architecture implementation with StateFlow
- All 6 technical documents (PRD, strategies, guidelines)
- Gradle Kotlin DSL and version catalog configuration
- Bug resolution for every reported issue
- Application icon design (SVG/XML music note variants)
Shazam (Apple)
Music data & similarity - Unofficial API
Spotify
Playlist destination - Official OAuth 2.0 API
ESIEA
Training institution - Master program context
Results & Impact
Concrete outcomes for the developer and the project
Hands-on native Android development with the latest Kotlin/Compose stack
API reverse-engineering methodology (unofficial API consumption patterns)
AI-assisted development workflow: specification-driven pair programming
Advanced algorithmic design: BFS exploration with mathematical constraints
OAuth 2.0 flow implementation on mobile with deep linking
Resilient API integration patterns: chunking, backoff, circuit breaker
Fully functional Android app with 12 features from search to Spotify export
Demonstrated scenario: 2 seeds -> 126 tracks discovered -> 38 exported to Spotify
5,666 lines of clean, well-structured Kotlin code following MVVM
22 reusable Compose UI components with accessibility support
10 technical documents covering architecture, strategies, and setup
15 screenshots documenting the complete user journey
2 seed tracks (Dennis Ferrer) - 126 tracks discovered - 38 exported to Spotify after retry
Project Aftermath
What happened after delivery
The project was delivered as a complete, functional Android application demonstrating end-to-end music discovery and playlist generation. As a training project within the ESIEA Master program, it fulfilled its primary objective: proving the ability to build a native Android application from scratch using modern technologies.
The absence of a Git repository means there is no version history. The application remains on the development machine as a standalone APK. No deployment to the Google Play Store was planned or attempted.
The dependency on Shazam's unofficial API represents the biggest long-term risk. Any changes to the API structure or headers would break the core functionality. For a production scenario, a migration to an official music recommendation API (Spotify Recommendations, Last.fm) would be the natural evolution.
Related journey
Professional experience linked to this achievement
Critical Reflection
An honest retrospective on the project
Functional end-to-end product demonstrated with real screenshots
Bleeding-edge technology stack (Kotlin 2.0.21, SDK 36, Compose 2024.12)
Clean MVVM architecture with proper separation of concerns
Rich technical documentation far exceeding typical training project standards
Advanced error handling: 3-level chunking, 5-strategy mapping, circuit breaker
Accessibility built-in: dedicated components, 48dp targets, 4.5:1 contrast
No Git Repository
A .gitignore exists but no repository was initialized. Critical for traceability and collaboration.
No Unit Tests
Test dependencies are present (JUnit, Espresso, Compose UI Test) but zero test files written. BFS algorithm and mapper deserve thorough testing.
No Local Persistence
Room is referenced in the version catalog but not activated. Generated playlists do not survive app closure.
Unofficial API Dependency
Shazam's unofficial API is fragile. No fallback to alternative recommendation sources is implemented.
Missing Dependency Injection
Hilt is in the version catalog but not used. Services are likely instantiated manually.
AI accelerates but does not replace engineering judgment: the decision not to write tests or initialize git remains the developer's responsibility.
Upfront documentation (PRDs, strategy docs) visibly guided coherent, structured development.
Rate limiting must be an architectural concern from day one when depending on third-party APIs, not an afterthought.
Skills applied
Technical and soft skills applied
Image gallery
Project screenshots and visuals