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

> Search across your Patchline catalog by title, artist, ISRC, mood, genre, metadata, and natural-language descriptions from uploaded tracks.

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>;
};

Patchline builds a user-scoped search view of your catalog so you can
search by free-text query, mood, genre, ISRC, metadata, and
natural-language description similarity where uploaded audio has been
captioned. This powers Aria's catalog tools and the dashboard search bar.

<TierBadge tier="all" />   All tiers can search. Sonic-similarity ranking improves with catalog size and runs across the full catalog regardless of tier.

## How to search

### Web dashboard

Sidebar → **Catalog** → search bar at top. Type any query:

```text theme={null}
"melancholy dreampop for late-night listening"
"tracks like 'Sleeper'"
"sad and slow"
"ISRC GBUM71029604"
```

Results rank by combined relevance: keyword match + sonic similarity +
recency.

### Via Aria

<AriaPromptCard prompt="Search my catalog for melancholy ballads for a late-night playlist" />

<AriaPromptCard prompt="Find tracks similar to 'Sleeper' in my catalog" />

### Via MCP

<MCPToolCard name="catalog_search" />

<MCPToolCard name="browse_catalog" />

`catalog_search` is the semantic search — pass any text query, get
ranked results.
`browse_catalog` is the listing endpoint — paginate through your full
catalog without a query.

## What you can search by

| Query type                | Example                             | What it returns                                |
| ------------------------- | ----------------------------------- | ---------------------------------------------- |
| **Title**                 | `"Sleeper"`                         | Tracks with that title                         |
| **Artist**                | `"Mira"`                            | Tracks by that artist                          |
| **ISRC**                  | `GBUM71029604`                      | The single matching track                      |
| **Genre / mood tags**     | `"dreampop"`, `"melancholy"`        | Tracks tagged with those                       |
| **Natural-language vibe** | `"slow sad ballad"`, `"late-night"` | Tracks whose AI caption matches the feel       |
| **Sonic similarity**      | `"like [track ID]"`                 | Tracks with similar audio to a reference track |

The semantic layer means natural language works — *"slow sad ballads
for late night"* returns the right tracks even if those exact words
aren't in any tag.

## How search works

* Catalog metadata is normalized on every catalog write.
* Sonic features from [sonic analysis](/catalog/sonic-analysis) ride
  alongside title, artist, ISRC, release date, and platform metadata.
* Similarity features are available for tracks with completed audio
  analysis.
* Results are scoped to your workspace and ranked by field match,
  freshness, audio similarity, and requested filters.

When you query, Patchline returns relevance-ranked results and merges in
fresh presentation metadata before rendering.

## Examples

### Find a specific track by ISRC

```text theme={null}
You: GBUM71029604
Aria: That's "Bohemian Rhapsody" by Queen. Already in your catalog
      (imported 2026-04-12). Want full intel or just the audio features?
```

### Find tracks for a playlist

```text theme={null}
You: I'm building a chill playlist — find me 10 tracks in my catalog
     that fit
Aria: 10 best fits (mellow, acoustic-leaning, slow):

  1. Sleeper (Mira) — melancholy dreampop, acoustic, low energy
  2. Long Way (Tessa) — drifting indie folk, soft vocals
  3. Velvet (Velvet Bird) — slow shoegaze, reverb-heavy
  4. ...

  Want me to make a smart link with these 10?
```

### Find similar tracks

```text theme={null}
You: Find tracks in my catalog that sound like 'Late Bloom'
Aria: Top 5 by sonic similarity (cosine 0.7+):

  1. Late Bloom (the query track itself, 1.00)
  2. Bright Drop (Cleo Bell) — 0.81
  3. Soft Rain (Tessa) — 0.79
  4. ...
```

### Browse without a query

```text theme={null}
You: List my catalog
Aria: 47 tracks total. Showing first 10:
  [paginated list with title, artist, metadata, caption snippet if available, last activity]

  Want to filter? "all dreampop", "tracks added this month", etc.
```

## Limitations

* **Search is only as good as the indexed data.** Tracks without
  completed sonic analysis won't match audio-feature queries.
* **Similarity is catalog-only.** "Find similar tracks" works within
  your own catalog.
* **Index lag is \~30 seconds.** A freshly imported track is searchable
  within \~30 seconds of import completing.

## Pricing

Plans, AI credits, and limits live on the [pricing page](https://patchline.ai/pricing) — we keep them there so they're always current.

## Related pages

* [Catalog import](/catalog/import) — what goes into the index
* [Catalog upload](/catalog/upload) — file path
* [AI-discoverable tracks](/catalog/sonic-analysis) — the captions search ranks against
* [Playlists](/playlists/overview) — match tracks to playlist targets

## FAQ

<AccordionGroup>
  <Accordion title="Can I search across other users' catalogs?">
    No. Search is scoped to your Patchline workspace. Enterprise
    customers with multi-user workspace access search the shared
    workspace catalog.
  </Accordion>

  <Accordion title="Why didn't my just-imported track show up?">
    Search can have a \~30 second lag after import. Wait a moment and refresh.
    If still missing after 5 minutes, the import may have failed —
    check the catalog UI for an error state.
  </Accordion>

  <Accordion title="How are similar-track results ranked?">
    Patchline compares audio-similarity features from completed sonic
    analysis and filters out weak matches. Metadata, genre, and audience
    context can also affect the ranking.
  </Accordion>

  <Accordion title="Can I save searches?">
    Saved searches / smart playlists are on the roadmap. v1 you re-run
    the query.
  </Accordion>
</AccordionGroup>

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