PokéTunes

Project Overview

Type a Pokémon’s name and PokéTunes hands you back a real Spotify playlist built from what that creature actually is: its type, its stats, its lore. There’s also a “Spirit Pokémon” mode that reads your listening history and tells you which Pokémon you are, musically speaking.

Motivation

Pokémon and music are two things almost everyone grew up with, and nobody had bothered to connect them properly. The question I wanted to answer: can a Pokémon’s type, stats, and lore actually translate into a musical identity? Fire types should sound like distorted guitars and heavy drums. Water types should feel like smooth R&B and late-night lo-fi. PokéTunes makes that translation real.

Features

Search that knows every Pokémon

• Autocomplete across all 1,025 Pokémon in the National Pokédex
• PokéAPI responses cache locally for 24 hours, so repeat searches don’t hammer the network
• Each lookup pulls from both the pokemon and pokemon-species endpoints in parallel, so you get the full picture: stats, types, legendary and mythical status, and flavor text

Playlist Generation

• A Pokémon’s attributes go to a serverless edge function that authenticates with Spotify using client credentials
• The function turns the type-to-genre mapping into keyword search queries and pulls matching tracks
• Those results get aggregated, deduplicated, and returned as a finished playlist

Type-to-Genre Mapping

Each of the 18 Pokémon types maps to a set of genres and keywords:

Type	Genres / Keywords
Fire	Rock, Metal, Hard Rock
Water	Chill, R&B, Lo-fi
Grass	Folk, Acoustic, Indie Folk
Electric	EDM, Synthwave, Electro
Psychic	Dream Pop, Ambient, Shoegaze
Ghost	Darkwave, Gothic, Post-Punk
Dragon	Epic, Orchestral, Power Metal
Fairy	K-Pop, Bubblegum Pop, Hyperpop
Dark	Trap, Horrorcore, Industrial
…	(and so on for all 18 types)

Speed and attack push the energy and tempo of the tracks that get picked. Legendary and mythical Pokémon skew toward the epic and cinematic end of things.

Spirit Pokémon (needs Spotify sign-in)

1. You sign in to Spotify with OAuth
2. The app pulls your top 50 tracks and the genres of the artists behind them
3. Those genres collapse into a five-dimension audio profile: energy, valence, tempo, acousticness, and instrumentalness
4. That profile gets compared against a pre-computed database of Pokémon profiles using weighted Euclidean distance
5. The nearest match comes back as your Spirit Pokémon, with a match score and a handful of personality traits

Shareable Result Cards

• Drawn entirely in the browser with the Canvas API, no server round-trip
• Two sizes: landscape (1200x630) for Twitter and Facebook link previews, and portrait (1080x1920) for Instagram Stories
• Each card carries the Pokémon sprite, the playlist name, type badges, and a styled background
• Sharing uses the Web Share API where the device supports it, and falls back to copying a link

Tech Stack

Layer	Technology
Frontend	React 18, TypeScript, Vite
Styling	Tailwind CSS, shadcn/ui component library
Backend	Deno edge functions (serverless)
APIs	Spotify Web API, PokéAPI
Database	Cloud-hosted PostgreSQL
Deployment	Lovable Cloud

Architecture

┌──────────────┐       ┌──────────────────┐       ┌─────────────┐
│   React App  │──────▶│  Edge Functions   │──────▶│ Spotify API │
│  (Vite/TS)   │       │  (Deno runtime)   │       └─────────────┘
└──────┬───────┘       └──────────────────┘
       │
       ▼
┌──────────────┐
│   PokéAPI    │
│  (REST, cached locally)
└──────────────┘

1. The frontend pulls Pokémon data straight from PokéAPI, cached locally for 24 hours
2. The edge function takes the Pokémon’s attributes, authenticates with Spotify using client credentials, builds genre-based search queries, and returns a deduplicated playlist
3. The Spirit Pokémon edge function handles the OAuth flow, fetches the user’s listening data, computes the audio profile, and matches it against the pre-computed Pokémon profiles
4. Share cards render entirely on the client with Canvas, so there’s no server-side image generation to pay for

Design

PokéTunes leans into a dark neon, slightly cyberpunk look:

• Typography: Orbitron for headings, Exo 2 for body, both picked for that techy, near-future feel
• Colour: A deep dark background with neon accents that shift to match the selected Pokémon’s type
• Effects: Neon glow shadows, gradient overlays, and type-coloured badges
• Layout: A single page with a centred search that expands into the playlist once you’ve picked something

Challenges & Lessons Learned

Spotify’s Developer Restrictions

Spotify keeps individual developers on a short leash. An app in “development mode” only works for up to 25 manually allowlisted accounts, and getting into “extended quota mode” means passing a formal review. So the features that need a user to sign in (Spirit Pokémon, Save to Spotify) had to be switched off for the public. Only the client-credentials playlist generation works without anyone logging in.

Lesson: When you’re building on someone else’s API, prototype the auth flow first and learn the access tiers before you sink time into features that depend on user-level permissions.

Genre Mappings that Actually Return Good Tracks

Turning 18 types into genres meant balancing the obvious associations (fire = intense) against what Spotify search actually returns, because not every genre keyword pulls back good tracks. The mapping took a few passes, testing which keywords reliably came back with variety and quality.

Lesson: Features built on an API have to be designed around how the API really behaves, not the mapping you drew on paper. There’s no substitute for testing against live data.

Share Cards Drawn in the Browser

Generating the share images entirely client-side meant wrestling the Canvas API’s quirks: cross-origin image loading, fonts that render differently across browsers, and laying everything out pixel by pixel without CSS to lean on. Supporting two aspect ratios (landscape for link previews, portrait for Stories) added to it.

Lesson: Drawing images in the browser saves you the server cost entirely, but you pay for it in careful handling of async asset loading and cross-browser rendering.

Current Status

Live at poketunes.com. Playlist generation works fully: search any Pokémon and get a real Spotify playlist. Spirit Pokémon and Save to Spotify are turned off for public users because of Spotify’s API restrictions for non-approved developers.