Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.patchline.ai/llms.txt

Use this file to discover all available pages before exploring further.

Catalog import is the fastest way to get your music into Patchline. Paste a streaming URL — Spotify, Apple Music, YouTube, SoundCloud — and Patchline pulls the metadata, cover art, ISRC, and queues sonic analysis. This is the most common first action for new users with already-released music.   Limits per tier: Free 10 lifetime · Starter 100 · Pro 500 · Scale + Enterprise unlimited.

​
What’s the difference between import and upload?

ModeUse whenAudio file in Patchline?
Import (this page)Track is already released on a streaming platformNo — Patchline references the canonical streaming version, runs sonic analysis from that
UploadTrack is unreleased or you want the master in PatchlineYes — your file is stored in encrypted cloud storage, sonic analysis runs on your master
If you’ve released through Distrokid, Tunecore, or a label, import is faster and cheaper — no upload time, no storage cost, sonic analysis still runs.

​
How to import

​
Option A — Paste a URL into Aria

Easiest path. Aria’s analyze_url tool resolves any supported streaming URL to its canonical identity and either imports it or asks for confirmation.

​
Option B — Use the Catalog UI

Sidebar → Catalog → Import button (top right) → paste the URL into the dialog → click Import. The track appears in the catalog list within ~3 seconds. Sonic analysis runs in the background — see Sonic analysis.

​
Option C — MCP tool call (for AI agents)

# Aria's analyze_url is the universal dispatcher — it figures out whether
# the URL is a track, album, EP, artist, or playlist, and returns the
# canonical identity plus a ranked list of follow-up tool calls.

​
What gets imported

For a single track URL:
FieldSource
TitleStreaming platform metadata
Artist(s)Streaming platform metadata
ISRCStreaming platform metadata (Spotify, Apple)
Cover artSpotify oEmbed fallback if not embedded
Release dateStreaming platform
DurationStreaming platform
BPM, key, mood, energy, valenceRuns after import (5 credits/track)
Sonic genres, instrumentsRuns after import
For an album/EP URL, Patchline imports every track in the release (counts as several catalog imports against your tier limit).

​
Supported URL types

PlatformTrack URLAlbum URLArtist URLPlaylist URL
Spotify✅✅✅ (via add_artist)⚠️ for analysis only, not imported
Apple Music✅✅✅—
YouTube✅—✅ (channel URL)✅ (read-only)
SoundCloud✅✅✅—
TikTok⚠️ artist-only—✅—
Instagram⚠️ artist-only—✅—
Artist URLs add the artist to your roster and trigger an artist-intelligence refresh — they don’t import all of the artist’s catalog automatically (that would blow through your import limit).

​
Deduplication

Patchline deduplicates by ISRC first, then by its internal catalog identity. If you import the same track twice — once via Spotify URL, once via Apple URL — Patchline merges them into a single catalog entry and updates the metadata with whatever was missing. If you’ve already uploaded a track via file and then import the same track via streaming URL, Patchline keeps the master audio (from the upload) and augments it with the streaming-platform identifiers.
Catalog import never overwrites master audio. If you’ve uploaded a WAV master and the import resolves to the same ISRC, your master stays. Streaming-platform metadata is added but the master remains the source of truth.

​
Import limits

TierCatalog importsWhat counts
10 lifetimeEach track imported = 1. Album with 12 tracks = 12.
100 lifetimeSame
500 lifetimeSame
Unlimitedn/a
Unlimitedn/a
Lifetime caps mean if you’ve used 8/10 on Free, you have 2 imports left ever — until you upgrade. The cap is generous for paid tiers and most users never hit it.

​
Examples

​
Import a single

You: Import this track for me.
https://open.spotify.com/track/4iV5W9uYEdYUVa79Axb7Rh

Aria: Done. "Bohemian Rhapsody" by Queen added to your catalog.
ISRC GBUM71029604. Sonic analysis is running — should finish in 30 seconds.

​
Import an album

You: Import this album.
https://open.spotify.com/album/4LH4d3cOWNNsVw41Gqt2kv

Aria: Imported 12 tracks from "The Dark Side of the Moon" by Pink Floyd.
That used 12/500 of your Pro catalog imports. Sonic analysis is queued for
all 12 — they'll be ready in ~3 minutes. Want me to start a release
plan or playlist matching once they're ready?

​
Import all of an artist’s catalog (advanced)

You: Import every release by Mira on Spotify.
https://open.spotify.com/artist/...

Aria: Mira has 24 releases (3 albums, 2 EPs, 19 singles) = 47 tracks
total. That's a big chunk of your import allowance — Pro tier has 500
lifetime. Want me to:
  1. Import everything (uses 47/500)
  2. Import just the 3 albums (uses 36/500)
  3. Import just the most recent 12 singles (uses 12/500)

​
How it works

  1. Aria’s analyze_url tool inspects the URL pattern and resolves it against the right platform API (Spotify Web API for open.spotify.com, Apple Music API for music.apple.com, etc.).
  2. Track metadata is fetched, normalized to Patchline’s schema, and saved to your workspace catalog.
  3. Patchline updates the user-scoped search view used by catalog search. Deduplication runs before the track appears in your catalog.
  4. Sonic analysis is queued when the track can be analyzed. Results such as BPM, key, mood, and genre are written back to the catalog row.
  5. The catalog UI polls for updates and renders the feature panel once analysis completes.

​
FAQ

No. Import references the streaming version. Your master stays wherever you uploaded it (Distrokid, Tunecore, etc.). If you want Patchline to hold your master, upload it instead.
Most labels distribute the same ISRC to both. If they don’t (rare), Patchline treats them as separate catalog entries until you manually merge them in the UI.
Not from the dashboard UI today. From Aria: paste a list and ask “import these all.” For Enterprise customers with thousands of URLs, the REST API supports batch import — contact support.
The catalog entry stays, but sonic re-analysis can’t run. We mark the track with a streaming_unavailable flag and surface it in the catalog UI.
Yes. Catalog list → track row → ⋯ → Delete. Lifetime import counter does NOT refund (it’s a hard cap to prevent abuse). Free tier users: plan accordingly.
Only if the unreleased track has a private streaming URL (very uncommon). For unreleased work, upload the file instead — that’s the canonical path.