---
title: "MagicPlaylist"
description: "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."
locale: "en"
canonical: "https://portfolio.josedacosta.info/en/achievements/magicplaylist-android-music-discovery"
source: "https://portfolio.josedacosta.info/en/achievements/magicplaylist-android-music-discovery.md"
html_source: "https://portfolio.josedacosta.info/en/achievements/magicplaylist-android-music-discovery"
author: "José DA COSTA"
date: "2025"
type: "achievement"
slug: "magicplaylist-android-music-discovery"
tags: ["Kotlin 2.0.21", "Android SDK 36", "Jetpack Compose", "Material Design 3", "Retrofit 2", "OkHttp 4", "Kotlin Coroutines", "Coil", "Spotify Auth SDK", "Gradle (Kotlin DSL)"]
generated_at: "2026-04-23T15:45:22.155Z"
---

# 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.

**Date:** September 2025  
**Duration:** 2 days (intensive)  
**Role:** Product Owner & Lead Developer  
**Technologies:** Kotlin 2.0.21, Android SDK 36, Jetpack Compose, Material Design 3, Retrofit 2, OkHttp 4, Kotlin Coroutines, Coil, Spotify Auth SDK, Gradle (Kotlin DSL)

### Key Metrics

- Kotlin Lines: **-** - Native Android code
- Source Files: **-** - Kotlin source files
- UI Components: **-** - Reusable Compose components
- Mapping Strategies: **-** - Shazam-to-Spotify fallback chain

## Project Overview

_What MagicPlaylist is and why it exists_

### Target Users

B2C - General public, Spotify users looking to enrich their playlists and discover new artists through an intuitive mobile experience.

- **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.
- 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)

**Target Users:** Target Users

## Objectives, Context & Risks

_The strategic vision behind the project_

**Objectives Intro:** The project was driven by five measurable goals:

**Obj1 Label:** Modern Android Stack

**Obj1 Value:** SDK 36

**Obj1 Desc:** Jetpack Compose, Material 3, MVVM, Kotlin 2.0.21

**Obj2 Label:** API Integration

**Obj2 Value:** 2 APIs

**Obj2 Desc:** Shazam (unofficial) + Spotify (official) with error handling

**Obj3 Label:** Mapping Accuracy

**Obj3 Value:** 95%+

**Obj3 Desc:** Shazam-to-Spotify track matching via 5-strategy fallback

**Obj4 Label:** Playlist Scale

**Obj4 Value:** 10K tracks

**Obj4 Desc:** Handle large playlists with max 500 API calls budget

**Obj5 Label:** Dev Speed

**Obj5 Value:** 2 days

**Obj5 Desc:** Full app delivery with AI-assisted development

**Context Text:** 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.

**Stakes Text:** 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.

**Risk1 Title:** Shazam Unofficial API Changes

**Risk1 Desc:** High probability, critical impact. No API contract exists. Mitigated by browser header spoofing, but inherently fragile.

**Risk2 Title:** Rate Limiting (Shazam + Spotify)

**Risk2 Desc:** High probability, medium impact. Mitigated by 3-level progressive chunking, exponential backoff, and circuit breaker patterns.

**Risk3 Title:** Shazam Response Variability

**Risk3 Desc:** Medium probability. Some Shazam responses have incomplete data. Mitigated by fallback handling for missing fields.

**Risk4 Title:** Mapping Rate Below 95%

**Risk4 Desc:** Medium probability. Mitigated by 5 fallback strategies (ISRC, exact, fuzzy, duration matching).

**Risk5 Title:** Spotify Token Expiration

**Risk5 Desc:** Low probability. Mitigated by automatic refresh and token persistence.

## Implementation Phases

_A chronological walkthrough of the development process_

**Phase1 Title:** Technical Foundation & Base UI

**Phase1 Period:** Sept 8, 2025

**Phase2 Title:** Shazam Integration & Expansion Algorithm

**Phase2 Period:** Sept 8-9, 2025

**Phase3 Title:** Spotify Integration & Export

**Phase3 Period:** Sept 9, 2025

**Phase4 Title:** Real-World Testing & Documentation

**Phase4 Period:** Sept 9, 2025

## Team & Interactions

_The human and AI collaboration model_

- The project was developed by **José 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: José 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.

**Team Size:** Team size: 1 person + AI assistant

**Jose Role:** José DA COSTA - Product Owner & QA

**Ai Role:** Claude Code - Senior Developer

## 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

## 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.

## 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
- 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.

**Improvement1 Title:** No Git Repository

**Improvement1 Desc:** A .gitignore exists but no repository was initialized. Critical for traceability and collaboration.

**Improvement2 Title:** No Unit Tests

**Improvement2 Desc:** Test dependencies are present (JUnit, Espresso, Compose UI Test) but zero test files written. BFS algorithm and mapper deserve thorough testing.

**Improvement3 Title:** No Local Persistence

**Improvement3 Desc:** Room is referenced in the version catalog but not activated. Generated playlists do not survive app closure.

**Improvement4 Title:** Unofficial API Dependency

**Improvement4 Desc:** Shazam's unofficial API is fragile. No fallback to alternative recommendation sources is implemented.

**Improvement5 Title:** Missing Dependency Injection

**Improvement5 Desc:** Hilt is in the version catalog but not used. Services are likely instantiated manually.