> ## 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 (metadata)

> Import the metadata of your existing catalog by pasting Spotify, Apple Music, YouTube, or SoundCloud URLs. Patchline pulls title, artist, cover art, ISRC, release date, and duration. AI captioning and the Music Store run when you upload the audio.

export const MCPToolCard = ({name}) => {
  const t = MCP_TOOLS[name];
  if (!t) {
    return <div style={{
      padding: "12px",
      border: "1px dashed #f87171",
      borderRadius: "8px"
    }}>
        Unknown MCP tool: <code>{name}</code>
      </div>;
  }
  const badges = {
    Onboarding: "#00E6E2",
    Dispatch: "#818CF8",
    Catalog: "#22D3EE",
    Audience: "#2DD4BF",
    Artists: "#60A5FA",
    Roster: "#60A5FA",
    Releases: "#C084FC",
    Playlists: "#4ADE80",
    "Smart Links": "#FACC15",
    Storefront: "#F59E0B",
    "Music Data": "#FB923C",
    "AI Generation": "#F472B6",
    "Asset Upload": "#A78BFA",
    Projects: "#E879F9"
  };
  const color = badges[t.category] ?? "#A1A1AA";
  return <div style={{
    padding: "16px",
    borderRadius: "12px",
    border: "1px solid rgba(255,255,255,0.10)",
    background: "rgba(255,255,255,0.03)",
    marginBottom: "12px"
  }}>
      <div style={{
    display: "flex",
    justifyContent: "space-between",
    alignItems: "center",
    gap: "12px",
    marginBottom: "6px"
  }}>
        <code style={{
    fontFamily: "var(--font-family-mono)",
    fontSize: "15px",
    fontWeight: 600
  }}>
          {name}
        </code>
        <span style={{
    fontSize: "11px",
    fontWeight: 600,
    padding: "2px 10px",
    borderRadius: "999px",
    border: `1px solid ${color}40`,
    background: `${color}1A`,
    color: color
  }}>
          {t.category}
        </span>
      </div>
      {t.callFirst && <div style={{
    fontSize: "11px",
    color: "#00E6E2",
    fontWeight: 600,
    marginBottom: "6px"
  }}>
          ★ Call this FIRST
        </div>}
      <div style={{
    fontSize: "14px",
    lineHeight: 1.5,
    color: "inherit"
  }}>{t.summary}</div>
    </div>;
};

export const AriaPromptCard = ({prompt, surface = "web"}) => {
  const surfaces = {
    web: {
      href: "https://patchline.ai/dashboard",
      label: "Try in dashboard"
    },
    telegram: {
      href: "https://t.me/AriaMusicBizBot",
      label: "Try in Telegram"
    },
    claude: {
      href: "https://patchline.ai/claude",
      label: "Try in Claude"
    },
    mcp: {
      href: "https://patchline.ai/mcp",
      label: "Install MCP first"
    }
  };
  const s = surfaces[surface] ?? surfaces.web;
  return <div style={{
    display: "flex",
    justifyContent: "space-between",
    alignItems: "center",
    gap: "16px",
    padding: "12px 16px",
    marginBottom: "12px",
    borderRadius: "10px",
    border: "1px solid rgba(255,255,255,0.10)",
    background: "rgba(255,255,255,0.03)"
  }}>
      <code style={{
    fontFamily: "var(--font-family-mono)",
    fontSize: "14px",
    color: "inherit",
    flex: 1
  }}>
        "{prompt}"
      </code>
      <a href={s.href} target="_blank" rel="noopener noreferrer" style={{
    fontSize: "12px",
    fontWeight: 600,
    padding: "6px 12px",
    borderRadius: "999px",
    background: "linear-gradient(92deg, #00E6E2, #0068FF)",
    color: "#FFFFFF",
    textDecoration: "none",
    whiteSpace: "nowrap"
  }}>
        {s.label} →
      </a>
    </div>;
};

export const TierBadge = ({tier}) => {
  const styles = {
    free: {
      label: "Free",
      color: "#A1A1AA"
    },
    starter: {
      label: "Starter+",
      color: "#00E6E2"
    },
    pro: {
      label: "Pro+",
      color: "#0068FF"
    },
    scale: {
      label: "Scale+",
      color: "#7A5BFF"
    },
    enterprise: {
      label: "Enterprise",
      color: "#FF7A59"
    },
    all: {
      label: "All plans",
      color: "#22C55E"
    }
  };
  const t = styles[tier?.toLowerCase()] ?? styles.all;
  return <span style={{
    display: "inline-flex",
    alignItems: "center",
    gap: "4px",
    padding: "2px 10px",
    borderRadius: "999px",
    border: `1px solid ${t.color}40`,
    background: `${t.color}1A`,
    color: t.color,
    fontSize: "12px",
    fontWeight: 600,
    fontFamily: "var(--font-family-mono)",
    verticalAlign: "middle"
  }}>
      {t.label}
    </span>;
};

export const AICallout = ({page}) => {
  const slug = page ?? "";
  const mdUrl = `https://docs.patchline.ai${slug}.md`;
  return <div style={{
    marginTop: "32px",
    padding: "16px 20px",
    borderRadius: "12px",
    border: "1px solid rgba(0,230,226,0.25)",
    background: "linear-gradient(135deg, rgba(0,230,226,0.08), rgba(0,104,255,0.05))",
    color: "inherit",
    fontSize: "14px",
    lineHeight: 1.6
  }}>
      <strong style={{
    display: "block",
    marginBottom: "6px",
    color: "#00E6E2"
  }}>
        For AI agents reading this page
      </strong>
      The canonical machine-readable version of this page is at{" "}
      <a href={mdUrl}>
        <code>{mdUrl}</code>
      </a>
      . For product actions, connect to{" "}
      <code>www.patchline.ai/api/mcp/v1</code>
      {" "}and call MCP <code>tools/list</code> for the current tool schema.
      Rules for navigating these docs:{" "}
      <a href="https://docs.patchline.ai/AGENTS.md">
        <code>docs.patchline.ai/AGENTS.md</code>
      </a>
      .
    </div>;
};

**Import is the metadata path.** You paste a streaming URL (Spotify,
Apple Music, YouTube, SoundCloud) and Patchline pulls what the
streaming platform exposes — title, artist, cover art, ISRC, release
date, duration. That's it. **Audio doesn't come over via import** —
streaming platforms only give us metadata, not the master file.

<TierBadge tier="all" />   Import limits vary by plan — see [pricing](https://patchline.ai/pricing).

## Import vs upload

| Mode                          | What lands in Patchline                                                                                                           |
| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| **Import** (this page)        | Metadata only — title, artist, cover art, ISRC, release date, duration. **No audio file**, no AI caption.                         |
| **[Upload](/catalog/upload)** | The audio file itself. Unlocks AI captioning, the Music Store, smart links, asset shares, and full Aria reasoning on your master. |

**Import then upload — that's the recommended path.** Import gets the
metadata in fast so Patchline knows your full catalog exists. Upload
the audio for the tracks you want to act on — that's what unlocks
the rest of the product.

If you only want intelligence and don't plan to sell or AI-caption,
import alone is fine.

## How to import

### Option A — Paste a URL into Aria

Easiest path. Aria's [`analyze_url`](/for-agents/mcp-tools-reference#analyze_url)
tool resolves any supported streaming URL to its canonical identity and
either imports it or asks for confirmation.

<AriaPromptCard prompt="Import this track: https://open.spotify.com/track/4iV5W9uYEdYUVa79Axb7Rh" />

<AriaPromptCard prompt="Import this whole album for me: https://open.spotify.com/album/..." />

### Option B — Use the Catalog UI

Sidebar → **Catalog** → **Import** button (top right) → paste the URL
into the dialog → click **Import**.

The track's metadata appears in the catalog list within a few
seconds. To unlock AI captioning, smart links, and the Music Store
for that track, [upload the audio](/catalog/upload) next.

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

<MCPToolCard name="analyze_url" />

```bash theme={null}
# 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

Import pulls **only the metadata** the streaming platform makes
public:

| Field        | Source             |
| ------------ | ------------------ |
| Title        | Streaming platform |
| Artist(s)    | Streaming platform |
| ISRC         | Streaming platform |
| Cover art    | Streaming platform |
| Release date | Streaming platform |
| Duration     | Streaming platform |

**What import does not give you:**

* The audio file
* AI captions
* Music Store listings, smart links, asset shares for the track

For those, [upload the audio](/catalog/upload) once the track is in
your catalog. The metadata import + audio upload paths combine into
one catalog row per ISRC.

For an album/EP URL, Patchline imports the metadata for **every
track** in the release (counts as several catalog imports).

## Supported URL types

| Platform    | Track URL      | Album URL | Artist URL                              | Playlist URL                       |
| ----------- | -------------- | --------- | --------------------------------------- | ---------------------------------- |
| Spotify     | ✅              | ✅         | ✅ (via [`add_artist`](/artists/roster)) | ⚠️ 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](/artists/roster) and
trigger an artist-intelligence refresh — they don't import all of the
artist's catalog automatically.

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

<Warning>
  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.
</Warning>

## Examples

### Import a single

```text theme={null}
You: Import this track for me.
https://open.spotify.com/track/4iV5W9uYEdYUVa79Axb7Rh
```

```text theme={null}
Aria: Metadata imported. "Bohemian Rhapsody" by Queen — ISRC
GBUM71029604 — added to your catalog. Upload the audio when you're
ready to AI-caption it or list it on your Music Store.
```

### Import an album

```text theme={null}
You: Import this album.
https://open.spotify.com/album/4LH4d3cOWNNsVw41Gqt2kv
```

```text theme={null}
Aria: Imported metadata for 12 tracks from "The Dark Side of the
Moon" by Pink Floyd. It's now in your catalog.
Want me to walk you through uploading the audio for one of them so
you can list it on your Music Store?
```

### Import all of an artist's catalog (advanced)

```text theme={null}
You: Import every release by Mira on Spotify.
https://open.spotify.com/artist/...
```

```text theme={null}
Aria: Mira has 24 releases (3 albums, 2 EPs, 19 singles) = 47 tracks
total. That's a lot of imports. Want me to:
  1. Import everything
  2. Import just the 3 albums
  3. Import just the most recent 12 singles
```

## 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](/catalog/search). Deduplication runs before the
   track appears in your catalog.
4. The track appears in your catalog as a **metadata-only row**. The
   AI-readable caption and Music Store listing are not generated on
   import — they run only when you [upload the audio](/catalog/upload).

## Related features

* [Upload a track (file)](/catalog/upload) — when you want the master in Patchline
* [AI-discoverable tracks](/catalog/sonic-analysis) — what runs after you upload the audio
* [Catalog search](/catalog/search) — semantic search across imported tracks
* [Artist roster](/artists/roster) — add artists by URL, separate flow

## FAQ

<AccordionGroup>
  <Accordion title="Does importing a track actually move my audio?">
    No. Import references the streaming version. Your master stays
    wherever you originally distributed it. If you want
    Patchline to hold your master, [upload it](/catalog/upload) instead.
  </Accordion>

  <Accordion title="What if the same track is on Spotify with one ISRC and on Apple with a different one?">
    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.
  </Accordion>

  <Accordion title="Can I bulk-import a CSV of URLs?">
    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.
  </Accordion>

  <Accordion title="What happens if the streaming URL goes 404?">
    The catalog entry stays. Patchline marks the source as unavailable
    and keeps the metadata already imported.
  </Accordion>

  <Accordion title="Can I undo an import?">
    Yes. Catalog list → track row → ⋯ → Delete. Lifetime import usage
    does not reset after deletion.
  </Accordion>

  <Accordion title="Does import work for unreleased tracks?">
    Only if the unreleased track has an unlisted streaming URL (very
    uncommon). For unreleased work, [upload the file](/catalog/upload)
    instead — that's the canonical path.
  </Accordion>
</AccordionGroup>

<AICallout page="/catalog/import" />