🎵 FetchTune

Universal music metadata resolver for Python.

FetchTune is a lightweight Python library and CLI for resolving music URLs into clean, structured metadata.

It provides a unified interface for working with music data across different platforms, including tracks, artists, albums, artwork, release dates, durations, and platform information.

Supported: Spotify · Apple Music · YouTube · SoundCloud

---

✨ Features

Feature	Status
Track metadata	✅
Artist metadata	✅
Album metadata	✅
Artwork & images	✅
Release date	✅
Duration	✅
Explicit status	✅
Platform IDs & URLs	✅
JSON serialization	✅
Cross-provider enrichment	✅
CLI	✅
Interactive URL input	✅
Audio download (optional extra)	✅

---

🧱 Architecture

FetchTune uses a provider-based architecture. Each platform has its own provider responsible for resolving and normalizing platform-specific data.

                         FetchTune
                            │
                         Resolver
                            │
          ┌─────────────────┼─────────────────┐
          │        │        │        │
    SpotifyProvider  AppleProvider  YouTubeProvider  SoundCloudProvider
          │        │        │        │
          └────────┴────────┼────────┴────────┘
                           │
                         Models
                    ┌──────┼──────┐
                    │      │      │
                  Artist  Album  Track

The core models remain platform-independent, making it possible to add new providers without changing the rest of the library.

---

📦 Installation

pip install fetchtune

Optional — enable the downloader (see below):

pip install "fetchtune[downloader]"

---

🚀 Usage

CLI

Pass a supported music URL:

fetchtune "https://open.spotify.com/track/4a0yULThaKQTm0hYPGEMOc"

For JSON output:

fetchtune --json "https://open.spotify.com/track/4a0yULThaKQTm0hYPGEMOc"

Download a track as a tagged audio file (requires the downloader extra and ffmpeg on your PATH):

fetchtune download "https://open.spotify.com/track/4a0yULThaKQTm0hYPGEMOc"
fetchtune download -f flac -o ~/Music "https://music.apple.com/us/album/carefree/1887648284?i=1887648293"

Python

from fetchtune import resolve

track = resolve(
    "https://open.spotify.com/track/4a0yULThaKQTm0hYPGEMOc"
)

print(track.title)
print(track.to_json(indent=2))

---

⬇️ Downloader (optional)

fetchtune[downloader] adds fetchtune download — turn any resolved track URL into a tagged audio file with embedded cover art.

             your URL (spotify / apple / youtube / soundcloud)
                            │
                       FetchTune ─── resolves title, artists, album,
                            │        duration, artwork, release date
              ┌─────────────┴─────────────┐
     youtube/soundcloud links      spotify/apple links
     download the original        search YouTube (fallback
              │                   SoundCloud), score candidates,
              │                   pick the best match
              └─────────────┬─────────────┘
                        yt-dlp + ffmpeg ─── download & convert
                            │
                          mutagen ─── embed metadata + cover art
                            │
                  🎵 "Artist - Title.mp3"

pip install "fetchtune[downloader]"   # + ffmpeg on your PATH

fetchtune download "https://open.spotify.com/track/..."
fetchtune download -f flac -b 320 -o ~/Music url1 url2
fetchtune download --force-search --search-source soundcloud url

Options: -o output dir · -f format (mp3 m4a flac opus ogg wav keep) · -b bitrate · --search-source · --force-search · --no-cover · --no-tags · --overwrite

Python API:

from fetchtune.downloader import Downloader

dl = Downloader(output="downloads", audio_format="mp3")
path = dl.download("https://open.spotify.com/track/...")

Spotify and Apple Music expose no audio streams, so audio for those links is fetched from a streamable platform (YouTube/SoundCloud) identified via FetchTune metadata. Please use it responsibly — only for content you own or that is freely licensed, and respect platform terms of service.

---

🎵 Example

FetchTune resolving a real Spotify track:

Fooroodgah - HEEN's Reinterpretation

Mehrad Hidden · HEEN

Open on Spotify ↗

Metadata

Field	Value
Title	Fooroodgah - HEEN's Reinterpretation
Artists	Mehrad Hidden, HEEN
Platform	Spotify
Track ID	4a0yULThaKQTm0hYPGEMOc
Release Date	2026-08-28
Duration	3:27
Duration (ms)	207875
Explicit	No
Album	null

Artists

Artist	Spotify ID
Mehrad Hidden	0jCVTRvQkILbJvpviTpvd1
HEEN	3dt8LORgsqjLP8hAYsFKdY

Artwork

Size	URL
640 × 640	https://image-cdn-ak.spotifycdn.com/image/ab67616d0000b2739a1801fbe63582bc1b0678d9
300 × 300	https://image-cdn-ak.spotifycdn.com/image/ab67616d00001e029a1801fbe63582bc1b0678d9
64 × 64	https://image-cdn-ak.spotifycdn.com/image/ab67616d000048519a1801fbe63582bc1b0678d9

JSON

{
  "title": "Fooroodgah - HEEN's Reinterpretation",
  "artists": [
    {
      "name": "Mehrad Hidden",
      "id": "0jCVTRvQkILbJvpviTpvd1",
      "url": "https://open.spotify.com/artist/0jCVTRvQkILbJvpviTpvd1"
    },
    {
      "name": "HEEN",
      "id": "3dt8LORgsqjLP8hAYsFKdY",
      "url": "https://open.spotify.com/artist/3dt8LORgsqjLP8hAYsFKdY"
    }
  ],
  "album": null,
  "cover_url": "https://image-cdn-ak.spotifycdn.com/image/ab67616d0000b2739a1801fbe63582bc1b0678d9",
  "images": [
    {
      "url": "https://image-cdn-ak.spotifycdn.com/image/ab67616d00001e029a1801fbe63582bc1b0678d9",
      "width": 300,
      "height": 300
    },
    {
      "url": "https://image-cdn-ak.spotifycdn.com/image/ab67616d000048519a1801fbe63582bc1b0678d9",
      "width": 64,
      "height": 64
    },
    {
      "url": "https://image-cdn-ak.spotifycdn.com/image/ab67616d0000b2739a1801fbe63582bc1b0678d9",
      "width": 640,
      "height": 640
    }
  ],
  "release_date": "2026-08-28T00:00:00Z",
  "duration_ms": 207875,
  "is_explicit": false,
  "platform": "spotify",
  "platform_id": "4a0yULThaKQTm0hYPGEMOc",
  "url": "https://open.spotify.com/track/4a0yULThaKQTm0hYPGEMOc"
}

---

🔄 Album Enrichment

FetchTune can enrich incomplete track metadata using other providers.

For example:

{
  "album": null
}

can potentially become:

{
  "album": {
    "name": "Innerlight EP",
    "id": "1582831419",
    "release_date": "2021-07-30T12:00:00Z",
    "total_tracks": 4
  }
}

This keeps the final Track model useful even when the original platform doesn't provide complete release information.

---

🛠️ Development

git clone https://github.com/momalekiii/fetchtune.git
cd fetchtune

python3 -m venv .venv
source .venv/bin/activate

pip install -e .
pytest

Build the package:

python -m build

Check the distribution:

python -m twine check dist/*

---

📄 License

MIT License

---

FetchTune
<sub>Music metadata, resolved.

© @momalekiii · 2026</sub>