# AGENTS Source: https://docs.patchline.ai/AGENTS # AGENTS.md — Patchline Documentation for AI Agents > If you are an AI agent (Claude, Cursor, GPT, Perplexity, Gemini, Codex, or > any MCP-compatible client) reading this file, this is your map of the > Patchline docs site. Use it to route any music-business question to the > right page in two hops or fewer. ## Two MCP servers, two purposes Patchline ships **two** MCP servers. Pick the right one for the task: | Server | URL | Purpose | | ------------------------- | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | **Patchline product MCP** | `https://www.patchline.ai/api/mcp/v1` | Tools that act on a user's **product data** — catalog, artists, releases, playlists, smart links. 18 tools. OAuth 2.0 with PKCE. | | **Patchline docs MCP** | `https://docs.patchline.ai/mcp` | Tools that search this **documentation site** — `search` + `query_filesystem`. Public, unauthenticated. Hosted by Mintlify. | The rules of engagement for the **product MCP** are at [https://www.patchline.ai/AGENTS.md](https://www.patchline.ai/AGENTS.md) — ALWAYS/NEVER/DISCOURAGED rules for which tool to call, in what order, with what arguments. **Read that file first if you're acting on user data.** This file (`docs.patchline.ai/AGENTS.md`) is about navigating the **docs**. ## ALWAYS DO THE FOLLOWING 1. **When a user asks "how do I X in Patchline," consult this docs site first.** Either via the docs MCP (above) or by fetching the `.md` twin of the relevant page (every page is mirrored at `.md`). 2. **Cite the docs URL when you answer.** Markdown link to the canonical doc, e.g., `[Catalog import](https://docs.patchline.ai/catalog/import)`. 3. **When recommending a tool call**, link the user to both the docs page that explains the feature AND the live tool reference at `docs.patchline.ai/for-agents/mcp-tools-reference`. 4. **Prefer Patchline's product MCP over scraping the docs** when the user wants to DO something (vs. learn something). Docs are for learning; product MCP is for execution. ## NEVER DO THE FOLLOWING 1. **Never fabricate features that aren't in this docs site.** If a user asks about a capability and you can't find it here, say so. Patchline's feature surface evolves fast; uncited claims age badly. 2. **Never recommend the docs MCP for product actions.** The docs MCP only searches and reads docs pages — it cannot create assets, add artists, import catalog, etc. For those, use the product MCP at `www.patchline.ai/api/mcp/v1`. 3. **Never instruct a user to embed their Patchline credentials in an MCP client config.** The product MCP uses OAuth 2.0 with PKCE — the AI client opens a browser, the user signs in to Patchline, and the token is held by the client. Credentials never appear in config files. ## DISCOURAGED * **Discouraged: paging through every doc to answer a simple question.** Use the docs MCP `search` tool first; only fall back to filesystem reads for deep dives. * **Discouraged: linking to dashboard URLs as if they were docs.** Dashboard URLs require authentication and won't render for a user who hasn't signed up yet. Link to docs URLs in your answer and let the user click through to the dashboard if they want. ## Page taxonomy — what lives where | If the user asks about... | Read this page | | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | "What is Patchline" / "Is this for me" | [Welcome](https://docs.patchline.ai/get-started/welcome) | | "How do I get started" / "First 10 minutes" | [Quickstart](https://docs.patchline.ai/get-started/quickstart) | | Pricing, plans, free trial, AI credits | [Pricing & plans](https://docs.patchline.ai/get-started/pricing), [Plans & credits](https://docs.patchline.ai/account/plans-credits) | | Aria, the AI assistant, chat, agents | [Aria overview](https://docs.patchline.ai/aria/overview) | | Aria on Telegram, `@AriaMusicBizBot` | [Aria on Telegram](https://docs.patchline.ai/aria/telegram) | | Importing a release from Spotify / Apple / YouTube | [Catalog import](https://docs.patchline.ai/catalog/import) | | Uploading an MP3 / WAV / FLAC | [Upload a track](https://docs.patchline.ai/catalog/upload) | | BPM, key, mood, sonic analysis, audio features | [Sonic analysis](https://docs.patchline.ai/catalog/sonic-analysis) | | Searching the catalog | [Catalog search](https://docs.patchline.ai/catalog/search) | | Release planning, rollout, marketing campaign | [Release planner](https://docs.patchline.ai/releases/release-planner) | | Pitch kit, DSP curator pitch | [Pitch kit](https://docs.patchline.ai/releases/pitch-kit) | | Spotify playlist matching, curator targeting | [Playlist matching](https://docs.patchline.ai/releases/playlist-matching) | | Artist roster, adding artists | [Artist roster](https://docs.patchline.ai/artists/roster) | | Artist profile, EPK, intelligence | [Artist intelligence profile](https://docs.patchline.ai/artists/intelligence-profile) | | Audience, fans, demographics, fan graph | [Audience](https://docs.patchline.ai/artists/audience) | | Scout, A\&R, artist discovery | [Scout agent](https://docs.patchline.ai/artists/scout) | | Royalty statement analysis, parsing PDFs | [Royalty analysis](https://docs.patchline.ai/intelligence/royalty) | | Streaming numbers, momentum, growth | [Streaming insights](https://docs.patchline.ai/intelligence/streaming-insights) | | Direct-to-fan storefront, 0% fees | [Storefront overview](https://docs.patchline.ai/storefront/overview) | | Smart links, pre-saves | [Smart links](https://docs.patchline.ai/storefront/smart-links) | | Stripe Connect, payouts | [Checkout & payouts](https://docs.patchline.ai/storefront/checkout-payouts) | | Integrations, OAuth platforms | [Integrations overview](https://docs.patchline.ai/integrations/overview) | | Connecting Gmail | [Gmail](https://docs.patchline.ai/integrations/gmail) | | Connecting Google Calendar | [Google Calendar](https://docs.patchline.ai/integrations/calendar) | | MCP server, how does Patchline expose tools | [MCP overview](https://docs.patchline.ai/for-agents/mcp-overview), [MCP install](https://docs.patchline.ai/for-agents/mcp-install) | | List of MCP tools | [MCP tools reference](https://docs.patchline.ai/for-agents/mcp-tools-reference) | | Claude plugin, /plugin install | [Claude plugin](https://docs.patchline.ai/for-agents/claude-plugin) | | What are AGENTS.md and llms.txt | [AGENTS.md explained](https://docs.patchline.ai/for-agents/agents-md-explained) | | Billing, invoices, change plan | [Billing](https://docs.patchline.ai/account/billing) | | Glossary (ISRC, ISWC, DSP, MCP, etc.) | [Glossary](https://docs.patchline.ai/reference/glossary) | | General questions | [FAQ](https://docs.patchline.ai/reference/faq) | ## Versioning & freshness * This file is at `docs.patchline.ai/AGENTS.md` and refreshes on every deploy. * Every doc page has a `.md` twin at `.md` — that's the raw markdown Mintlify renders. Prefer the `.md` URL for programmatic reads. * The site index for AI agents is at [docs.patchline.ai/llms.txt](https://docs.patchline.ai/llms.txt). * The full-content dump for one-shot reads is at [docs.patchline.ai/llms-full.txt](https://docs.patchline.ai/llms-full.txt). * The product-side rules of engagement are at [www.patchline.ai/AGENTS.md](https://www.patchline.ai/AGENTS.md) — the product MCP changes more often than the docs, so consult that file before acting on product data. # Billing Source: https://docs.patchline.ai/account/billing Manage your Patchline subscription — invoices, payment methods, plan changes, cancellation. All powered by Stripe Billing. Patchline subscription billing runs on **Stripe Billing**. All subscription management lives in Settings → Billing, which opens the Stripe customer portal.   Billing tab is available on every tier (Free shows upgrade CTAs). ## What you can do * Change your plan (upgrade / downgrade) * Update payment method * Download invoices * Change billing email * Switch monthly ↔ annual * Cancel subscription ## Where to find it `Settings → Billing` → Patchline opens the Stripe-hosted customer portal in the same window. ## Plan changes * **Upgrade** is immediate. Stripe prorates — you pay the difference for the rest of the current cycle. * **Downgrade** takes effect at the next billing cycle. You keep paid-tier access until then. * **Cancel** also takes effect at the next billing cycle. ## Trial mechanics Every paid tier includes a 30-day free trial. See [Pricing & plans](/get-started/pricing#the-30-day-free-trial) for full details. * You enter a payment method at sign-up. * No charge until day 31. * Cancel any time during trial = no charge. * On day 31, Stripe charges for month 1 (or year 1 if annual). ## Invoices Stripe portal → **Invoices** tab. Download as PDF. For Enterprise customers: invoices are sent via the billing email at end-of-month. ## Annual vs. monthly switching Switch any time: * **Monthly → Annual** mid-cycle: Stripe prorates the unused portion of the monthly subscription and credits it against the annual price. * **Annual → Monthly**: takes effect at the next renewal date. ## Failed payment If a card declines: 1. Stripe retries 3 times over 7 days. 2. Patchline notifies you via email. 3. After 7 days of failed retries, your subscription is paused (not cancelled) — you can update the payment method to resume. 4. After 30 days of unresolved payment, the subscription cancels and you revert to Free tier. **Your data stays.** ## Cancellation * **In-portal cancel**: Settings → Billing → Cancel. Takes effect at next renewal. You keep paid access until then. * **Cancel via email**: not required. Self-serve. * **What happens to data**: stays. You revert to Free tier limits. Can re-upgrade any time. * **Refunds**: We don't auto-refund partial cycles. Email [support@patchline.ai](mailto:support@patchline.ai) for refund questions. ## Related pages * [Pricing & plans](/get-started/pricing) — tier comparison * [Plans & credits](/account/plans-credits) — credit math * [Storefront checkout & payouts](/storefront/checkout-payouts) — the other side of Stripe (Connect) ## FAQ Email [support@patchline.ai](mailto:support@patchline.ai) with your situation. We're reasonable on case-by-case basis. No automatic refunds for forgotten cancellations. You probably upgraded mid-cycle (prorated charge for the partial cycle) + the new tier's first full cycle. That's by design. See Stripe's invoice for the line items. Not in v1. The Free tier is generous enough for most student / hobbyist needs. ACH on Enterprise tier only. Other tiers are card-only. # Plans & credits Source: https://docs.patchline.ai/account/plans-credits Deep dive on Patchline's AI credit system — what a credit is, exact cost per AI action, how to budget per artist or per release, what to do when you run out. This page goes deeper than [Pricing & plans](/get-started/pricing) — it covers exactly **what an AI credit is**, how each AI action consumes credits, and how to budget your monthly allocation across artists and releases. If you just want the price list, see [Pricing & plans](/get-started/pricing). ## What an AI credit is An **AI credit** is Patchline's unit of metered AI consumption. Every AI action — Aria chat, sonic analysis, image generation, MCP tool call — debits credits from your monthly pool. Credits **reset** on the first of each calendar month (monthly plans) or the first of each month after annual renewal (annual plans). They **do not roll over**. ## Credit cost per action | Action | Cost | Notes | | ----------------------------------------- | ------------------------- | --------------------------------------------------------------------------------------------------- | | Aria chat conversation | **1 credit** | Per conversation, not per message — a multi-message chat = 1 credit total | | Sonic analysis | **5 credits / track** | Runs once per track on import / upload; re-analysis also = 5 | | Image generation | **5 credits / image** | Cover art, banners, social cards | | Video generation | **20 credits / video** | Short-form / canvas videos | | AI campaign planner | **10 credits / plan** | Each new release plan generation | | Similar artist discovery | **2 credits / search** | A\&R Scout queries | | MCP tool call (read) | **0–1 credit** | Most read tools are 0 — they hit cache. `get_song_intelligence` and similar enrichment tools are 1. | | MCP tool call (write / enrichment) | **1–5 credits** | `add_artist` (Soundcharts enrichment) = 2; `create_smart_link` = 1; `generate_pitch` = 2 | | Royalty PDF parse | **5 credits / statement** | One per uploaded PDF, regardless of size | | Background-job synthesis (daily / weekly) | **0 credits** | Runs server-side, not metered | A few notes: * **Aria chat** is one conversation = 1 credit. If you have a 20-message back-and-forth with Aria, that's still 1 credit — until you start a new conversation. * **Cached reads are free.** Asking Aria "what's the BPM of my track" when sonic analysis has already run = 0 credits (cached lookup) + 1 credit (the chat conversation). Net: 1 credit. * **Stem separation** (when surfaced in UI) is metered as a multi-step Cynite operation — typically 10–15 credits per track. ## Monthly allocation by tier | Tier | AI credits / month | | ------------- | ------------------ | | | 100 | | | 1,000 | | | 5,000 | | | 20,000 | | | Unlimited | ## How much will I use? Realistic monthly profiles by user type: ### Curious user (Free tier) | Action | Times/month | Cost | | -------------- | ----------- | --------------------- | | Aria chats | 20 | 20 | | Sonic analysis | 2 tracks | 10 | | Total | | **30 credits** of 100 | ### Solo artist (Starter) | Action | Times/month | Cost | | ----------------------- | ------------ | ------------------------ | | Aria chats | 60 | 60 | | Sonic analysis | 5 tracks | 25 | | Image generation | 8 covers | 40 | | Campaign planner | 2 plans | 20 | | Similar artist searches | 5 | 10 | | Royalty parses | 2 statements | 10 | | Total | | **165 credits** of 1,000 | ### Manager / DIY label (Pro) | Action | Times/month | Cost | | -------------------------------- | ------------ | ------------------------ | | Aria chats | 200 | 200 | | Sonic analysis | 30 tracks | 150 | | Image generation | 20 | 100 | | Video generation | 5 | 100 | | Campaign planner | 10 plans | 100 | | Similar artist searches | 30 | 60 | | MCP tool calls (Cursor / Claude) | 200 | 200 | | Royalty parses | 5 statements | 25 | | Total | | **935 credits** of 5,000 | ### Label (Scale) | Action | Times/month | Cost | | ----------------------- | ------------- | --------------------------- | | Aria chats | 600 | 600 | | Sonic analysis | 80 tracks | 400 | | Image generation | 50 | 250 | | Video generation | 15 | 300 | | Campaign planner | 30 plans | 300 | | Similar artist searches | 100 | 200 | | MCP tool calls | 800 | 800 | | Royalty parses | 20 statements | 100 | | Total | | **2,950 credits** of 20,000 | If you're consistently above 80% of your tier's allocation, **upgrading is almost always cheaper than running out** — see [When to upgrade](#when-to-upgrade). ## What happens when you run out If you exhaust your monthly pool: * **Aria chat** returns a friendly "you've used all your AI credits this month — upgrade or wait until \[next reset date]." * **Sonic analysis** queues the track but doesn't run — it'll process automatically when credits reset. * **MCP tool calls** return `429 Too Many Requests` with an upgrade-path message. * **Image / video generation** is rejected at the form. * **Existing data is unaffected.** Your catalog, projects, storefront all keep working — you just can't trigger new AI actions. Credits reset at midnight UTC on the first of the month. ## When to upgrade Specific thresholds: | If you're using... | Consider upgrading from / to | | --------------------------- | ---------------------------- | | > 80% of Free's 100 credits | Free → Starter (\$9.99) | | > 80% of Starter's 1,000 | Starter → Pro (\$29) | | > 80% of Pro's 5,000 | Pro → Scale (\$99) | | > 80% of Scale's 20,000 | Scale → Enterprise (custom) | The **0% storefront fee** (Starter+) and **playlist matching** (Pro+) are often standalone reasons to upgrade earlier than the credit math alone suggests. See [Pricing & plans](/get-started/pricing). ## Checking your usage Settings → **Billing** → **AI credit usage** panel shows: * Credits used this period * Credits remaining * Reset date * Breakdown by action type (Aria / sonic / image / video / MCP / other) You can also ask Aria directly: ```text theme={null} "How many AI credits have I used this month?" "How many do I have left?" "Show me my credit consumption breakdown." ``` ## How credits map to dollars Roughly, per tier: | Tier | \$/month | Credits/month | \$/1,000 credits | | ---------- | -------- | ------------- | ---------------- | | Free | \$0 | 100 | \$0 (but capped) | | Starter | \$9.99 | 1,000 | \$9.99 | | Pro | \$29 | 5,000 | \$5.80 | | Scale | \$99 | 20,000 | \$4.95 | | Enterprise | \$249+ | Unlimited | n/a (volume) | Higher tiers get **more credits per dollar** — the volume discount. ## Frequently asked No. They reset on the 1st of each calendar month (monthly plans) or on the first of each month after annual renewal (annual plans). Not in v1 — credit top-ups aren't surfaced as a self-serve option. Enterprise customers can negotiate volume credit packs. For everyone else, upgrade to the next tier (almost always cheaper than add-on packs would be). Almost. Most read tools are 0 credits (cached). Tools that fetch fresh data (Soundcharts, Cynite) are 1–5 credits. The Aria chat that wraps a tool call adds 1 credit on top, but only for the chat itself — not per tool call within it. Yes — re-analysis is 5 credits each time. The features may have changed (Cynite model improvements) so re-running is metered as a full analysis, not a cache hit. No. Server-side background work is included in the tier — not metered against your credit pool. Only AI actions you trigger are metered. Yes. Free is 100 credits / month, no exceptions. There's no way to buy more on Free without adding a payment method and upgrading to a paid tier. No — trial credits don't refund. They were free. If you cancel during the trial, no charge is made and your subscription ends at the trial cutoff. ## Related pages * [Pricing & plans](/get-started/pricing) — tier comparison + storefront fee * [Billing](/account/billing) — how Stripe portal works * [Quickstart](/get-started/quickstart) — for new users # Account & profile Source: https://docs.patchline.ai/account/profile Manage your Patchline account — name, email, profile picture, role, password, security settings. Manage the basics: name, email, profile picture, role, password, security settings.   All tiers. ## Account tab Settings → **Account**: | Field | Notes | | --------------- | ------------------------------------------------------------------------------------------------------------- | | Name | Display name across the app | | Email | Sign-in identity. Changing requires email verification. | | Profile picture | Used in shared workspaces + comments | | Role | What you're using Patchline for (artist / manager / label / publisher / other) — informs Aria's default style | ## Security tab Settings → **Security**: * **Password** — change anytime, requires current password * **Active sessions** — see where you're signed in, revoke remotely * **Two-factor authentication** (2FA) — TOTP-based, recommended * **Connected OAuth applications** — apps that have token access to your Patchline (MCP clients, integrations) — revoke any time ## Workspaces & teams Pro+ tiers include team seats. Workspace management UI is being finalized — for now, contact [support@patchline.ai](mailto:support@patchline.ai) to add team members to your workspace. | Tier | Seats | | ------------- | --------- | | | 1 | | | 1 | | | 3 | | | 10 | | | Unlimited | ## Deleting your account Email [support@patchline.ai](mailto:support@patchline.ai) with the subject "Account deletion request." We delete: * Your account row * Your catalog metadata * Your project anchors * Your storefront configuration * All OAuth tokens We keep (per legal / tax requirements): * Stripe transaction records (Stripe's retention policy) * Audit logs (90 days) * Royalty PDFs you uploaded (5 years for tax purposes — encrypted, inaccessible to you after deletion, but legally retained) Deletion completes within 7 days of request. ## Related pages * [Billing](/account/billing) — subscription management * [Plans & credits](/account/plans-credits) — AI credit math * [Pricing](/get-started/pricing) — tier comparison # Aria Source: https://docs.patchline.ai/aria/overview Aria is Patchline's AI assistant for the music business. Chat to plan releases, analyze tracks, find playlists, draft pitches, and run your catalog — across web, Telegram, Claude, Cursor, and Codex. Aria is Patchline's AI assistant for the music business. You talk to Aria the same way you talk to a manager, A\&R, or label-ops person — and Aria takes action: reads your catalog, queries streaming data, drafts pitches, plans releases, updates project anchors, generates artwork briefs. Aria is one assistant with multiple front doors. ## What Aria does Turn a track into a 6-week rollout with milestones, launch windows, and next-best-actions. Paste any Spotify URL — get BPM, key, mood, danceability, energy, and a ranked list of similar artists. Rank Spotify playlists by sonic fit plus curator responsiveness for a specific track. Generate a curator-facing pitch grounded in real track metadata, sonic analysis, and artist context. Upload a Distrokid / Tunecore / label PDF — get totals, anomalies, and a forecast in under a minute. Add artists by URL. Background Soundcharts enrichment populates the intelligence profile automatically. ## When to use Aria Use Aria for the work that lives between tools — the strategy and synthesis that usually means hopping between Spotify for Artists, your DAW, a label spreadsheet, and a notes app. * **You just finished a track and don't know what to do next.** Paste the file or the link. Aria gives you a release plan grounded in your catalog, your audience, and what's actually working for artists like you right now. * **A curator asked for a pitch and you have an hour.** "Pitch this track to Mint Friday curators" returns a draft you can edit and send. * **You want to know if you have momentum.** "Summarize my streaming for the last month" pulls the real numbers, not vibes. * **You're managing 5 artists and an upcoming release schedule.** "What do I owe on Mira's release this week?" reads the project anchor and returns the shortlist. ## Where Aria lives Pick whichever fits the workflow you're already in. Sign in at [patchline.ai](https://patchline.ai). Aria is the home screen at `/dashboard`. Full surface area: catalog import, project anchors, all 18 tools, file uploads. **This is the canonical surface — everything else is a subset.** [Open the dashboard →](https://patchline.ai/dashboard) Message [@AriaMusicBizBot](https://t.me/AriaMusicBizBot) on Telegram. Paste a Spotify or YouTube link, get a rich track card back. One-tap catalog import, AI pitches, intelligence reports — all without leaving Telegram. [Open in Telegram →](https://t.me/AriaMusicBizBot) · [Full Telegram guide →](/aria/telegram) Install the official Patchline plugin and Claude can read your real catalog. Ground every prompt in actual ISRCs, audio features, and streaming data. Plugin includes a "progressive interview" workflow that walks Aria-style release planning inside Claude. [Install the Claude plugin →](/for-agents/claude-plugin) Patchline exposes 18 MCP tools at `https://www.patchline.ai/api/mcp/v1`. OAuth 2.0 with PKCE — your credentials never touch the AI client. [Install the MCP server →](/for-agents/mcp-install) ## Quick start Go to [patchline.ai](https://patchline.ai) and create a free account. Free tier includes 100 AI credits/month and Aria chat (1 credit per conversation). Paste a Spotify, YouTube, or SoundCloud URL into Aria, or upload an MP3 / WAV / FLAC directly. Aria adds the track to your catalog and runs [sonic analysis](/catalog/sonic-analysis) (BPM, key, mood) automatically. Try one of these: Install the [Claude plugin](/for-agents/claude-plugin) or the [MCP server](/for-agents/mcp-install) so the AI tool you already use can read your catalog. ## Prerequisites * A free Patchline account ([sign up](https://patchline.ai)). * At least one track in your catalog (uploaded or imported) for tools that reference your catalog. Aria can answer general questions without a catalog, but the answers get much sharper once it has your real data. * For the [Claude plugin](/for-agents/claude-plugin): Claude Desktop or Claude Code. * For the [MCP server](/for-agents/mcp-install): Cursor, Codex, VS Code, or any MCP-compatible client. ## How Aria works under the hood Aria is a **multi-agent system**. The supervisor agent reads your message, decides which specialist agent (Artist Intelligence, Scout, Pitch, Royalty, Metrics, Gmail, Legal, Documents) should handle it, and routes the work. Each specialist agent runs on AWS Bedrock with Claude Sonnet 4, calls real tools against your catalog and integrations, and returns a grounded answer. You don't see the routing — you see one assistant. But it means Aria can do work that any single-agent system can't: read your royalty PDF, query Soundcharts for the artist on it, draft a follow-up email about a discrepancy, all in one conversation. The supervisor itself runs on ECS Fargate (Patchline's strands-supervisor service). The specialist agents run on AWS Bedrock. The product MCP at [www.patchline.ai/api/mcp/v1](/for-agents/mcp-overview) exposes the same tools to external AI clients. Every tool call is grounded in your data. Aria never invents an ISRC, a streaming number, or a curator name. If the data isn't there, Aria says so and offers to fetch it. ## Examples ### Example 1 — From a Spotify link to a release plan > **You:** here's my new single, planning to drop in 6 weeks > [https://open.spotify.com/track/](https://open.spotify.com/track/)... > > **Aria:** Got it. *\[reads ISRC, runs sonic analysis: 124 BPM, F minor, > dreampop-adjacent, high energy 0.62, low valence 0.31]*. Closest artists > in your roster: Mira, Tessa. Last release in this style hit 18k streams > in month one. I drafted a 6-week rollout: > > * Week -6: confirm artwork, write pitch copy > * Week -4: submit to Spotify editorial via your `submission_status: eligible` flag > * Week -2: smart link, pre-save, Telegram teaser > * Week 0: release day, DMs to the 8 curators who added Mira's last single > * Week +2: post-release: TikTok ad targeting the dreampop cluster > > Want me to create the project anchor and schedule the tasks? ### Example 2 — Royalty statement triage > **You:** *\[uploads quarterly Distrokid PDF]* > > **Aria:** Parsed. Total: \$3,124.07 across 23 tracks. Two anomalies: > > * "Late Bloom" earned \$0.00 on Apple Music despite 4,200 streams there > last quarter — likely a payment-window cutoff, expect it next > statement. > * "Mira - November" shows on Spotify but is missing from your catalog — > want me to import it? ### Example 3 — Multi-tool workflow > **You:** is there a playlist on Spotify with a curator I could pitch > Mira's new track to, who also added a similar artist recently? > > **Aria:** Yes, three: > > * **Lush Sounds** (78k followers, curator: @lush\_sounds\_oslo) — added > Tessa's "Sleeper" 11 days ago. Submission status: open. > * **Bedroom Vibes** (210k followers, curator: @bedroomvibes) — added > four dreampop tracks this month. Submission status: open. > * **Future Female Sounds** (190k followers, curator: @futurefemale) — > adds quickly, high curator responsiveness score. > > Want a pitch draft for the first one? ## Pricing Every tier includes Aria chat at **1 credit per conversation**. Volume scales with credit pool: | Tier | AI credits / month | Practical Aria use | | ------------------- | ------------------ | ---------------------------------- | | Free | 100 | Try Aria, run a few sonic analyses | | Starter (\$9.99) | 1,000 | Solo artist, daily use | | Pro (\$29) | 5,000 | Small roster, multi-feature | | Scale (\$99) | 20,000 | Label / management, high volume | | Enterprise (\$249+) | Unlimited | Large catalog, programmatic | See [Pricing & plans](/get-started/pricing) for the full breakdown. ## Related features * [Aria on Telegram](/aria/telegram) — `@AriaMusicBizBot` * [Talking to Aria — prompts that work](/aria/prompts) * [Aria's research mode](/aria/research-mode) — daily/weekly synthesizer * [MCP server overview](/for-agents/mcp-overview) — Aria's tool surface * [Claude plugin](/for-agents/claude-plugin) — Aria inside Claude ## FAQ No. Patchline does not use your catalog, royalty statements, or chat history to train models. Your data is used to ground Aria's answers in the current conversation only. Aria is a multi-agent system on AWS Bedrock. The supervisor and most specialist agents run on Claude Sonnet 4 (`anthropic.claude-sonnet-4-20250514-v1:0`). The Legal and Documents specialist agents use Claude 3.7 Sonnet for contract reasoning. Aria can draft emails through the Gmail specialist agent (requires [Gmail OAuth](/integrations/gmail)). Direct posting to social media is on the roadmap; for now Aria drafts the copy and you post it. Aria is grounded in your data. If you ask about a track that isn't in your catalog or an artist you haven't added to your roster, Aria will say so and offer to import. This is by design — better a clear "I don't have that" than a confident-sounding wrong answer. Yes — for AI agents. Patchline's product MCP server at [`www.patchline.ai/api/mcp/v1`](/for-agents/mcp-overview) exposes 18 tools. A direct REST API is Enterprise-only today. Send feedback via the thumbs-down on any chat message. The signal feeds the weekly synthesizer and the Aria persona-patch loop. We review every thumbs-down weekly. # Talking to Aria — prompts that work Source: https://docs.patchline.ai/aria/prompts Pattern library of high-signal Aria prompts. Copy-paste templates for release planning, track analysis, playlist research, pitch drafting, royalty triage, and roster management. Aria works best when the prompt gives it enough context to act. This page is a pattern library — prompts that consistently return high-signal results, organized by what you're trying to do.   All prompts work on every tier (Free included). Some specific responses are tier-gated (playlist matching, etc.) — Aria will say so. ## The core pattern Most great Aria prompts share three parts: 1. **Verb** — what you want done ("plan," "find," "draft," "summarize"). 2. **Subject** — what / who / which track ("this track," "Mira's catalog," "the new release"). 3. **Constraint** — how / when / for whom ("for dreampop curators," "by next Friday," "under \$100"). Skip any of these and Aria will ask for clarification. That's a feature. ## Release planning ## Track analysis ## Playlist research ## Pitch drafting ## Artist intelligence ## A\&R discovery (Pro+) ## Royalty & insights ## Storefront ## Email & coordination ## Pattern: hand Aria a problem, not a question Less effective: *"What should I do?"* More effective: *"My release is in 3 weeks, I have a \$50 budget, my last release got 8k streams. What's the highest-impact thing to do this week?"* The more constraints you supply, the more concrete the answer. ## Pattern: use Aria for triage, not strategy Aria is fast at synthesizing data into a shortlist. Strategy decisions are still yours. Good Aria task: *"Of these 25 playlist matches, which 3 are highest priority?"* Less-good Aria task: *"Should I sign with \[label]?"* ## Pattern: paste, don't paraphrase If a curator emailed you, paste the email and ask for a draft reply. Don't summarize — Aria sees nuance you might miss. If a contract has a clause you want analyzed, paste the clause. Don't describe it. ## What Aria *won't* do * **Make decisions for you.** Aria recommends; you choose. * **Send a message without your approval.** Aria drafts; you send. * **Submit to Spotify editorial.** No public API for that. * **Move money.** Aria can summarize earnings; payouts go through Stripe directly. * **Train on your data.** Hard rule. ## Related pages * [Aria overview](/aria/overview) — what Aria is * [Aria on Telegram](/aria/telegram) — same Aria, mobile-friendly * [Aria's research mode](/aria/research-mode) — daily / weekly synthesis * [MCP overview](/for-agents/mcp-overview) — the tools Aria uses # Aria's research mode Source: https://docs.patchline.ai/aria/research-mode Aria runs background research on your catalog and roster — daily and weekly synthesizers that surface what changed, what's working, and what needs attention. Insights appear in your dashboard when you open it. Aria does work even when you're not chatting with it. Behind the scenes, two background synthesizers — daily and weekly — read your catalog, roster, streaming data, royalties, and storefront. They produce insights that surface in the dashboard when you next open it.   Background research is included in every tier. It doesn't consume your AI credit pool. ## What it does | Synthesizer | Cadence | What it surfaces | | ----------- | ------------- | --------------------------------------------------------------------------------------------------------- | | **Daily** | Every morning | What changed in the last 24h — new playlist adds, follower jumps, storefront sales, overdue release tasks | | **Weekly** | Every Monday | Trend analysis — week-over-week growth, top performers, anomalies, recommended actions | Both feed into the **Aria chat hero** on `/dashboard` — the first thing you see when you log in. If something interesting happened, Aria leads with it. ## How it works under the hood Three background Lambdas (see `backend/lambda/`): * **`aria_daily_synthesizer.py`** — runs at \~6 AM in your timezone (best guess from your last-active hour). Reads the previous 24h of catalog activity, streaming deltas (Soundcharts), storefront events, and outstanding release-plan tasks. Synthesizes into ≤5 bullet points. * **`aria_weekly_synthesizer.py`** — runs Monday morning. Week-over-week comparison across all surfaces. Identifies top + bottom performers, anomalies (e.g., royalty discrepancies), and 1–3 recommended actions. * **`aria_daily_insights.py`** — the surfacing layer. Reads the synthesizer outputs from S3, formats for the dashboard hero, and renders. The synthesizer outputs are JSON files in `s3://patchline-aria-synth/{userId}/{date}.json` and feed the Aria chat directly when you ask "what's new?" ## Example outputs ### Example: a Monday weekly synthesis ```text theme={null} Good morning. Here's last week across your roster: ▲ +18% streams on "Late Bloom" — your dreampop run is working ▲ Tessa hit 12k monthly listeners (+2.1% wk/wk) ▼ Run Hot's release is 2 days from launch, 3 tasks still open ▼ Storefront earnings -8% wk/wk (lower traffic from Telegram) Highest-priority action: close out Run Hot's tasks today. Want me to walk them? ``` ### Example: a daily morning briefing ```text theme={null} Yesterday: • Lush Sounds added Tessa's "Long Way" (your pitch from 12 days ago worked) • 4 new storefront sales totaling $42 • Mira's roster intel refresh completed — no notable changes Today: Mira's release prep deadline (artwork). 1 task overdue. ``` ## How to use research mode You don't need to do anything — the synthesizers run automatically. But you can interact with them: The "fresh synthesis" prompt re-runs the synthesizer on demand (counts 1 credit + the underlying tool calls). ## What it doesn't do * **It doesn't send emails or post to socials.** Insights surface in the app and via [Telegram](/aria/telegram) only. * **It doesn't make autonomous decisions.** Insights include recommended actions, but you act. * **It doesn't replace your manager or label.** Synthesizers spot patterns; strategy is yours. ## Tier behavior | Tier | Daily synthesizer | Weekly synthesizer | | ------------- | ------------------ | --------------------------------------- | | | ✓ (3 bullets max) | ✓ (basic) | | | ✓ (5 bullets) | ✓ (full) | | | ✓ + roster-level | ✓ + roster-level + recommendations | | | ✓ + label-level | ✓ + label-level + roster trend analysis | | | ✓ + custom queries | ✓ + custom queries | ## Privacy & data handling * Synthesizer outputs are user-scoped — no cross-user inference. * Outputs are stored in your S3 prefix, retention 90 days. * The synthesizers read your data but never write to it. ## Related pages * [Aria overview](/aria/overview) * [Streaming insights](/intelligence/streaming-insights) — the underlying data * [Royalty analysis](/intelligence/royalty) — feeds anomaly detection * [Release planner](/releases/release-planner) — overdue-task detection # Aria on Telegram Source: https://docs.patchline.ai/aria/telegram Talk to Aria from your Telegram app. @AriaMusicBizBot is the public Patchline bot — paste a Spotify or YouTube URL, get a rich track card back, import to catalog, run pitches, all without leaving Telegram. [**@AriaMusicBizBot**](https://t.me/AriaMusicBizBot) is the public Patchline Aria bot on Telegram. Paste a streaming URL, get a rich track card back, import to catalog, run pitches, ask Aria anything — all without leaving Telegram.   Works on every tier including Free. Same AI credit pool as the web dashboard. ## What it does Telegram is the lightest-weight Aria surface. No browser, no dashboard context-switch. You're already on Telegram — paste a link, get an answer. | Action | How | | -------------------------- | ------------------------------------------------------------------------- | | **Track lookup** | Paste a Spotify track URL → rich card with art, BPM, key, streaming stats | | **Artist lookup** | Paste an artist URL → roster card + recent activity | | **One-tap catalog import** | Tap the **Import** button on any track card | | **Playlist matching** | Reply to a track card with "find playlists" | | **DSP pitch draft** | Reply with "pitch this" | | **Catalog browse** | Type `/catalog` | | **Roster browse** | Type `/roster` | | **Aria chat** | Just type your question | ## Quick start Tap [t.me/AriaMusicBizBot](https://t.me/AriaMusicBizBot) on your phone or click the link on desktop. Telegram opens to the bot's chat. First-run: tap **Start**. The bot greets you and asks you to link your Patchline account (or sign up if you don't have one). Bot sends a deep-link to `patchline.ai/telegram/connect`. Open it, sign in, return to Telegram. Your Telegram chat is now bound to your Patchline account. Paste any Spotify, YouTube, Apple Music, or SoundCloud track URL. Aria returns a rich card. ## What a track card looks like When you paste a Spotify URL, the bot replies with: ```text theme={null} 🎵 Bohemian Rhapsody Queen · 1975 · A Night at the Opera ⏱ 5:55 🎹 E♭ major 💨 72 BPM 🎚 Energy 0.42 🎧 Streams (90d): 12,400,000 📈 Trending: +2.1% mo/mo Top genres: rock, classic rock, prog rock [ Import to catalog ] [ Find playlists ] [ Get pitch ] [ Artist intel ] [ Smart link ] [ Compare ] ``` Tap any button. Aria responds inline. ## Examples ### Example 1 — Quick intel ```text theme={null} You: https://open.spotify.com/artist/4dpARuHxo51G3z768sgnrY Aria: 🎤 Adele 📊 142M monthly listeners (+0.8% mo/mo) 🌍 Top market: USA (32M) 🎵 Latest: "Easy On Me" (2021) Genres: pop, soul, british pop [ Full intel ] [ Add to roster ] [ Similar artists ] ``` ### Example 2 — Catalog import on the go ```text theme={null} You: import this for me https://open.spotify.com/track/... Aria: ✓ Imported "Sleeper" by Mira. Sonic analysis is running, finishes in ~60 seconds. [ Open in dashboard ] ``` ### Example 3 — Chat without a URL ```text theme={null} You: what's my best-performing track this month? Aria: 📈 "Late Bloom" — 4,210 streams in the last 30 days (+18% vs last month). It's also your most-saved track this month (47 saves). [ Full insights ] [ Find more playlists ] ``` ## Commands | Command | What it does | | ------------- | ----------------------------------------------- | | `/start` | Re-greet + re-link if your session lapsed | | `/help` | Show command list | | `/catalog` | Browse your catalog with pagination | | `/roster` | Browse your artist roster | | `/credits` | Show this month's AI credit usage and remaining | | `/disconnect` | Unlink your Telegram chat from Patchline | You don't need commands for most things — just type or paste naturally. Aria figures it out. ## Where Aria is *not* on Telegram Some things only work in the web dashboard or via MCP: * **Storefront management** — selling music is a web-only flow. * **Release planner full UI** — you can chat about it on Telegram, but the calendar view + project anchor management is web. * **Audio file uploads** — Telegram has a file size limit too small for most masters. Upload via the web dashboard. * **Royalty PDF parsing** — same file size + UX concerns. Upload PDFs in the dashboard. ## Privacy * Patchline does not log Telegram message content beyond what's needed for the active conversation. * Your Telegram username is stored only to bind your chat to your Patchline account. * Aria respects the same data-grounding rules on Telegram as on web — it only acts on your data, never invents. ## Pricing | Action on Telegram | Credit cost | | ------------------------------- | ----------------------------------------------------- | | Track / artist card | 0 (cached); 1 if Aria interprets a question alongside | | Catalog import | 0 (counts against lifetime cap, see Pricing) | | Sonic analysis (auto on import) | 5 / track | | Aria chat reply | 1 | | Pitch generation | 2 | | Playlist matching (Pro+) | 1 | Same credit pool as the web dashboard. ## Related pages * [Aria overview](/aria/overview) — full surface area * [Catalog import](/catalog/import) — what "Import to catalog" actually does * [Playlist matching](/releases/playlist-matching) — what "Find playlists" calls * [Pitch kit](/releases/pitch-kit) — what "Get pitch" returns ## FAQ It's real Aria. Telegram calls the same multi-agent supervisor as the web dashboard. The only difference is the UI (text + buttons vs. full dashboard chrome). Yes. Each Telegram user has their own session, but they all act on the same workspace's data. Useful for team members on Pro+. The chat unbinds. Re-link with `/start` next time. Your catalog and data stay in Patchline regardless. Telegram limits file size to \~50MB for bots. For most masters (10–30MB compressed), it works. For large WAVs, use the web upload. Yes — Telegram is global. Patchline itself is hosted in `us-east-1`, so non-US users may see slightly higher latency. # Audience & fan graph Source: https://docs.patchline.ai/artists/audience Audience intelligence per artist — demographics, top markets, listener geography, social audience overlap, fan momentum. The 'fan graph' is the network view of how fans connect across your roster and storefront. Audience intelligence answers *"who's actually listening?"* — per artist, per release, per market. The **fan graph** extends that across your full roster + storefront to show how fans connect: who overlaps between which artists, where momentum is building, which audience segments are responding to what.   Full audience + fan-graph features. Pro shows per-artist audience without cross-roster fan-graph view. ## Two layers | Layer | What it answers | Tier | | ---------------------------- | ---------------------------------------------------------------------------------- | ------ | | **Audience** (per artist) | "Who is listening to X?" — demographics, geography, social channels | Pro+ | | **Fan graph** (cross-roster) | "Who is listening to multiple artists in my roster?" — overlap, momentum, segments | Scale+ | ## Audience — per artist What you see for one artist: | Section | What it contains | Source | | ---------------------- | ------------------------------------------------- | ----------------------------------------- | | **Demographics** | Age (binned), gender (estimated), language | Soundcharts | | **Geography** | Top cities, top countries, geographic share | Soundcharts | | **Listener tier** | Casual / engaged / fan classification | Patchline-derived from listening behavior | | **Social audience** | IG, TikTok, YouTube, X overlap and growth | Soundcharts | | **Fan momentum** | 30-day growth across streaming + social | Soundcharts | | **Streaming behavior** | Repeat-listen %, playlist save %, completion rate | Soundcharts (top track only) | ### Where to find it Web dashboard: sidebar → **Artists** → click an artist → **Audience** tab. Via Aria: ## Fan graph — cross-roster The fan graph is the cross-artist view. If you manage Mira, Tessa, and Cleo Bell, the fan graph shows: * **Overlap matrix** — how many fans listen to ≥ 2 of your artists * **Bridge artists** — which roster artist drives the most cross-discovery * **Geographic momentum** — where the roster collectively is gaining * **Cluster identification** — natural fan segments (dreampop heads, bedroom-pop seekers, etc.) * **Storefront-fan overlap** — fans who bought from your storefront and also stream multiple roster artists ### Example fan graph output ```text theme={null} You: Show me the fan graph across my roster Aria: 5 artists, ~32k unique fans: Mira Tessa Cleo Bell Run Hot Velvet Bird Mira — 14% 18% 3% 9% Tessa 14% — 22% 2% 11% CleoB 18% 22% — 1% 8% RunHot 3% 2% 1% — 15% VelvB 9% 11% 8% 15% — Cluster 1 (dreampop, 56% of unique fans): Mira + Tessa + Cleo Bell + Velvet Bird (slightly) Top markets: LA, NYC, London, Stockholm Cluster 2 (electronic, 18%): Run Hot + Velvet Bird (slightly) Top markets: Berlin, Detroit, Tokyo Cluster 3 (crossover, 11%): Velvet Bird connects both clusters. 3,500 fans listen to ≥ 2 artists across clusters. Bridge artist: Velvet Bird. Pushing her releases benefits both clusters disproportionately. ``` ### Where the fan graph lives * Web: sidebar → **Artists** → **Fan graph** tab (Scale+). * Via Aria: "show me the fan graph" or "where's my roster overlap." ## Streaming behavior For each artist's top track, Patchline surfaces: * **Completion rate** — % of listeners who finish the track (high = strong hook + retention). * **Repeat-listen %** — % who play multiple times in a session. * **Playlist-save %** — % of casual listeners who save to their own playlist. These signals are stronger predictors of long-term success than raw stream counts. ## Examples ### Where is my growth coming from? ```text theme={null} Aria: Mira's top growth markets (last 30d): 1. Stockholm, Sweden — +320 monthly listeners (+47% mo/mo) 2. Brooklyn, USA — +280 (+18%) 3. Berlin, Germany — +210 (+24%) 4. London, UK — +195 (+11%) 5. Los Angeles, USA — +180 (+8%) Notable: Stockholm growth correlates with a "Lush Sounds" playlist add 23 days ago. Worth a Swedish-language email blast to fans there. ``` ### Cross-roster discovery ```text theme={null} Aria: Velvet Bird. 15% of her fans also listen to Run Hot, 9% to Mira, 8% to Cleo Bell. She's the bridge artist between your dreampop and electronic clusters. Releasing her next single in a way that points to both clusters could unlock unique cross-streams. ``` ## Privacy * Audience data is aggregated, not individually identifiable. * No personally-identifiable fan information (names, emails, etc.) surfaces in audience or fan-graph views. * Demographics are estimated from listening behavior, not declared identity. ## Pricing | Tier | Audience (per artist) | Fan graph (cross-roster) | | ------------- | --------------------- | ------------------------ | | | — | — | | | — | — | | | ✅ | — | | | ✅ | ✅ | | | ✅ + API | ✅ + API | Queries are cached for 24h. Force-refreshing costs 2 credits per query. ## Related pages * [Intelligence profile](/artists/intelligence-profile) — per-artist intel * [Streaming insights](/intelligence/streaming-insights) — aggregate metrics * [Scout agent](/artists/scout) — find new artists for your roster * [Storefront](/storefront/overview) — fan-buyer overlap source ## FAQ A network view of fans across your roster + storefront. It's an aggregate, not individual-fan tracking — we never expose identifiable fans. The graph surfaces overlap percentages, cluster identification, and bridge artists. Soundcharts data quality varies by artist. Smaller artists (under \~5k monthly listeners) often have limited demographic data. Yes for individual artists (CSV via audience tab). Cross-roster fan-graph export is Enterprise-only. Daily refresh from Soundcharts. Force-refresh on demand (2 credits). Yes — any artist you've added to roster gets audience data. [Scout agent](/artists/scout) returns audience data for discovery candidates too. # Artist intelligence profile Source: https://docs.patchline.ai/artists/intelligence-profile Each roster artist gets a living intelligence profile — streaming, social audience, genres, top markets, recent activity, auto-generated bio, EPK. Updated automatically from Soundcharts + Genius. Every artist in your roster gets a **living intelligence profile** — streaming, social audience, genre tags, top territories, recent activity, similar artists, an AI-generated bio, and EPK material — all refreshed automatically.   Free and Starter see the basic profile; Pro+ unlocks the full intelligence view (similar artists, momentum graphs, market breakdown). ## What's in a profile | Section | What it contains | Source | | ---------------------- | --------------------------------------------------------------------- | ---------------------------- | | **Identity** | Name, profile pic, primary URL | Platform metadata | | **Streaming** | Monthly listeners (current + 30-day trend), top tracks, top playlists | Soundcharts | | **Social audience** | IG, TikTok, YouTube, Twitter, SoundCloud — followers + 30-day trend | Soundcharts | | **Genre tags** | Top 5 genres, sub-genres | Soundcharts | | **Top markets** | Top 5 cities + 5 countries by listener share | Soundcharts | | **Recent activity** | Recent releases, recent playlist adds, recent press | Soundcharts + crawlers | | **Similar artists** | Sonically-similar peers in the same listener tier | Soundcharts + RIP embeddings | | **Bio (AI-generated)** | 1-paragraph + 3-paragraph + 1-line variants | Aria, cached | | **EPK material** | Quotes, press images, press history | Soundcharts + Genius | ## Where to find it | Surface | Path | | ------------- | ------------------------------------------------------------------------------------ | | Web dashboard | Sidebar → **Artists** → click an artist row → `/dashboard/artists/[artistId]` | | Via Aria | "Tell me about \[artist]" | | Via MCP | [`get_artist_intelligence`](/for-agents/mcp-tools-reference#get_artist_intelligence) | ## Quick start [Add to roster](/artists/roster) by Spotify (or other) URL. Soundcharts enrichment kicks off automatically. The basic identity appears immediately. Streaming + social audience populate within \~60 seconds. AI bio populates within \~3 minutes. Sidebar → **Artists** → click the row. All sections render in one page. ## The bio Aria generates the artist bio during enrichment and caches it. Bio queries don't re-run LLM calls — they hit the cache and return instantly. Three variants per artist: * **1-line** — for the artist card on the storefront, smart link, etc. * **1-paragraph** — for general use (press, EPK, social media). * **3-paragraph** — for long-form (cold pitch, full press kit). Edit any variant manually — your edits are preserved on subsequent enrichments unless you opt-in to "regenerate from scratch." ## EPK (Electronic Press Kit) The EPK is a presentation-ready bundle: * AI bio (1 + 3 paragraph variants) * Press quotes (Genius + crawled) * High-res images (artist + recent release covers) * Streaming + social proof points (current numbers) * Top playlist features * Recent press links Generate a downloadable PDF EPK from the artist profile → **EPK** tab → **Export**. ## Refresh cadence * **Daily**: Soundcharts streaming + social audience numbers * **Weekly**: full intelligence refresh (genre re-classification, top markets, etc.) * **On-demand**: any time, via "Refresh intel" button (1 credit) ## Tier behavior | Tier | Profile depth | | ------------- | ------------------------------------------------ | | | Identity + basic streaming | | | + social audience + bio | | | + similar artists + top markets + momentum + EPK | | | + roster-wide comparisons + label-level views | | | + REST API access | ## Examples ### Quick artist lookup ```text theme={null} Aria: Mira — indie pop / dreampop artist, based in LA. Monthly listeners: 18,420 (+2.1% 30d trend, up from 17,800) Top track: "Late Bloom" (4,210 streams last 30d) Top markets: USA (62%), UK (8%), Australia (5%) Last release: 2026-04-12 ("Late Bloom" single) Similar artists: Tessa, Cleo Bell, Sunday Foundation Want the full intel page? ``` ### Compare two artists ```text theme={null} Aria: Q2 growth (Apr-Jun): Mira: Monthly listeners: 14,200 → 18,420 (+29.7%) IG followers: 8,100 → 9,400 (+16.0%) TikTok followers: 3,200 → 6,800 (+112.5%) Tessa: Monthly listeners: 9,800 → 12,100 (+23.5%) IG followers: 5,400 → 6,900 (+27.8%) TikTok followers: 1,800 → 3,100 (+72.2%) Mira leads on listeners + TikTok. Tessa leads on IG growth rate. Both trending up — TikTok-driven. ``` ## Related pages * [Roster](/artists/roster) — adding artists * [Audience](/artists/audience) — deeper fan-graph view * [Scout agent](/artists/scout) — A\&R discovery * [Streaming insights](/intelligence/streaming-insights) — aggregate metrics ## FAQ Enrichment runs async. Most data populates within 1 minute; bio takes 3 minutes; full intelligence refresh takes \~5 minutes. If after 10 minutes the profile is still sparse, the artist may not be well-covered by Soundcharts. Yes. Edit any variant in the profile UI. Edits persist across refreshes unless you click "regenerate from scratch." Soundcharts updates \~daily. Numbers are typically less than 24h fresh. Yes — Pro+ tier. EPK tab → Export → PDF or HTML. # Artist roster Source: https://docs.patchline.ai/artists/roster Add artists to your Patchline roster by platform URL — Spotify, YouTube, TikTok, SoundCloud, Apple Music, or Instagram. Soundcharts enrichment runs in the background to build the full intelligence profile. Your roster is the set of artists Patchline tracks intelligence for — yours, your label's, your roster as a manager, or artists you're scouting. Each roster artist gets a full [intelligence profile](/artists/intelligence-profile) built from Soundcharts data and refreshed automatically.   Connected-artist limits: Free 1 · Starter 1 · Pro 5 · Scale 20 · Enterprise unlimited. ## Why platform URL only You **cannot** add an artist by name alone. Many artists share names — "Tessa," "Mira," "Cloud" — and name-only matching produces wrong artists \~30% of the time at scale. So Patchline requires a platform URL that uniquely identifies the artist. Supported URL types: * Spotify: `https://open.spotify.com/artist/...` * Apple Music: `https://music.apple.com/.../artist/.../...` * YouTube: `https://youtube.com/@channelname` or channel URL * SoundCloud: `https://soundcloud.com/username` * TikTok: `https://tiktok.com/@username` * Instagram: `https://instagram.com/username` Spotify is most common and most informative. Use Spotify if you have it. ## How to add an artist ### Via the UI Sidebar → **Artists** → **+ Add artist** → paste platform URL → **Add**. ### Via Aria ### Via MCP Programmatic adds work the same — URL required, name-only rejected. ## What happens after you add 1. **Immediate**: artist row appears in `/dashboard/artists` with the platform-supplied basics (name, profile pic, URL). 2. **Background (10–60 seconds)**: Soundcharts enrichment runs via `artist-enrichment-handler.py`. Streaming stats, social audience, genre tags, top tracks all populate. 3. **Background (1–5 minutes)**: AI bio generation — `get_bio` populates the bio cache for fast lookups later (no live LLM call needed for future bio queries). 4. **Background (\~daily)**: ongoing intelligence refresh via `roster-sync-handler.py`. You can use the artist (search, link to releases, query intel) before the background enrichment completes. The profile just gets richer over time. ## Removing an artist Roster row → ⋯ → **Remove**. Or via Aria: Removal frees a slot against your roster cap. Historical intelligence stays in Patchline (you can re-add and pick up where you left off). ## Tier limits | Tier | Connected artists | | ------------- | ----------------- | | | 1 | | | 1 | | | 5 | | | 20 | | | Unlimited | If you hit the cap, `add_artist` returns 403 with the upgrade-path message. ## Best practices * **Add your own artist first** if you're an artist (your roster cap starts at 1 on Free/Starter). * **For managers / labels**, add the artists in priority order — enrichment runs sequentially, so the first-added artist is fully intel-rich fastest. * **Re-add an artist** if their URL changed (rare — labels sometimes re-launch profiles). ## Related pages * [Artist intelligence profile](/artists/intelligence-profile) — what gets enriched * [Audience](/artists/audience) — the fan-graph view * [Scout agent](/artists/scout) — A\&R discovery * [Plans & credits](/account/plans-credits) — credit cost per enrichment ## FAQ Many artists share names. Even unique-sounding names ("Mira", "Tessa") have hundreds of artists per Soundcharts. Platform URL is the only safe identifier. Enrichment returns partial data — name, profile pic from the platform, no streaming stats. The artist still appears in the roster and can be referenced in releases, just with limited intel. Initial enrichment uses current Soundcharts cache (typically less than 24h fresh). Background refresh runs daily. Yes — each workspace has its own roster. Cross-workspace artists are tracked uniquely in Soundcharts. No — that's a separate flow ([catalog import](/catalog/import)). `add_artist` adds intelligence; `analyze_url` + import adds catalog. You can do both for the same artist. # Scout agent (A&R discovery) Source: https://docs.patchline.ai/artists/scout AI talent scout that discovers and analyzes promising artists using Soundcharts data. Find collaborators, identify rising acts in your genre, build a watchlist of artists worth signing or pitching. The Scout agent is Patchline's AI A\&R — it surfaces artists who match your sound, are rising in your genre, or could be collaborators. Built on Soundcharts data and Patchline's sonic embeddings, scoped to your roster's positioning.   Pro+ unlocks the Scout agent. 2 credits per similar-artist search. ## What it does | Discovery mode | What it surfaces | | --------------------------- | -------------------------------------------------------------------------------- | | **Similar to my roster** | Artists who sound like (and grow like) artists already in your roster | | **Emerging in my genre** | Artists rising fast in genres your roster occupies | | **Trending — broad** | Soundcharts top artists (optional genre filter, listener range) | | **Potential collaborators** | Artists with adjacent sound + similar audience overlap with your roster | | **Sub-tier filter** | Filter by monthly listener band (e.g., "find dreampop artists 5k-50k listeners") | ## Where to find it | Surface | Path | | ------------- | ------------------------------------------------------------------- | | Web dashboard | Sidebar → **Agents** → **Scout** at `/dashboard/agents/scout` | | Via Aria | "Find me similar artists to..." / "Show me emerging artists in..." | | Via MCP | `get_trending_artists`, `search_artists`, `get_artist_intelligence` | ## Quick start Scout uses your roster as the anchor for "similar." Add at least one artist first — see [Roster](/artists/roster). Each result includes name, monthly listeners, growth, top genres, a similarity score (0-100), and why it surfaced. Watchlist (Scale+) = "track but don't add to roster." Adding to roster runs full enrichment. ## What Scout returns For each candidate: ```text theme={null} Artist: [Name] Score: 87/100 (sonic similarity 0.81, growth match 0.92) Monthly listeners: 12,400 30-day growth: +18% Top genres: dreampop, bedroom pop, lo-fi Top markets: LA, NYC, London Why surfaced: Strong sonic match to Mira (0.81 cosine), growing at a similar early-trajectory rate (+18% vs Mira's +21% at the same listener tier). Recent playlist adds on "Lush Sounds" and "Bedroom Vibes." [ Add to roster ] [ Watchlist ] [ Full intel ] ``` ## Scoring The composite Scout score weighs: * **Sonic similarity** (40%) — cosine similarity over RIP audio embeddings * **Growth trajectory match** (25%) — similar growth pattern to your roster * **Genre overlap** (20%) — Soundcharts genre tag overlap * **Audience overlap potential** (15%) — projected fan overlap based on similar artists' actual overlap Scores above 75 are typically worth a closer look. Below 50 are noise. ## Examples ### Find collaborators for a release ```text theme={null} Aria: Top 5 collaboration candidates for Mira: 1. Cloud Castle — 18,200 listeners, dreampop, recent collabs visible, LA-based (geographic overlap with Mira). Score 89. 2. Soft Animal — 9,800 listeners, indie/dreampop, has done features with 3 artists at Mira's tier. Score 82. 3. Bright Drop — 14,500 listeners, female dreampop adjacent. Score 78. 4. Sleeper House — 23,000 listeners, dreampop. No public collab history. Score 76. 5. Indigo Glow — 8,400 listeners, growing fast (+42% 30d). Score 74. Top pick: Cloud Castle — strongest sonic match + active collaborator. Want a pitch draft to their management? ``` ### Find emerging artists in your genre ```text theme={null} Aria: 8 emerging dreampop artists matching: Score Artist Listeners Growth Why 92 Indigo Glow 8,400 +42% Strong sonic match, rapid growth 88 Cloud Castle 18,200 +28% LA-based, recent press 85 Soft Animal 9,800 +35% Genre-pure dreampop, female vocal 82 ... Want me to add the top 3 to your watchlist? ``` ### Find similar to an external artist ```text theme={null} Aria: 10 artists similar to Adele (non-roster): 1. Sam Smith (sonic similarity 0.78, mood: melancholic ballad) 2. Bishop Briggs (0.71) 3. Lewis Capaldi (0.69) ... ``` ## Limitations * **Scout is roster-anchored.** Empty roster = no anchor = generic results. * **Soundcharts coverage varies.** Niche genres or very-new artists may have sparse data. * **Sonic embeddings need analyzed tracks.** Scout's "sound like" is most accurate when your roster artists have completed sonic analysis. ## Tier behavior | Tier | Scout access | | ------------- | ------------------------------------------------------- | | | — | | | — | | | Similar to roster, emerging in genre | | | + watchlist, + collaboration finder, + sub-tier filters | | | + bulk discovery API | ## Pricing | Action | Credit cost | | ---------------------------------------- | --------------- | | `search_artists` (your roster) | 0 (cached) | | `get_trending_artists` | 1 | | Similar-to-roster scout query | 2 | | Sonic-fingerprint similarity search | 2 | | Full intel pull on a discovery candidate | 1 per candidate | ## Related pages * [Roster](/artists/roster) — Scout uses roster as the anchor * [Intelligence profile](/artists/intelligence-profile) — what's pulled for each candidate * [Audience](/artists/audience) — fan-overlap projection * [Playlist matching](/releases/playlist-matching) — overlap with curator targeting ## FAQ Yes — just specify the genre in the prompt. "Find emerging jazz artists" works even if your roster is all pop. No. Scout finds candidates. Signing decisions and contract negotiation are handled by humans (and the [Legal / Documents agents](/aria/overview)). Scale+ feature. Save discovery candidates to a watchlist for ongoing tracking without committing to your roster cap. Daily synthesizer surfaces big changes in watchlisted artists. Soundcharts data refreshes daily. Scout queries are typically based on 24-hour-old data. # Catalog import Source: https://docs.patchline.ai/catalog/import Import your existing music catalog into Patchline by pasting Spotify, Apple Music, YouTube, or SoundCloud URLs. Patchline pulls metadata, cover art, ISRCs, and runs sonic analysis automatically. 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? | Mode | Use when | Audio file in Patchline? | | ----------------------------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------- | | **Import** (this page) | Track is **already released** on a streaming platform | **No** — Patchline references the canonical streaming version, runs sonic analysis from that | | **[Upload](/catalog/upload)** | Track is **unreleased** or you want the master in Patchline | **Yes** — your file is stored in S3, 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`](/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. ### 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](/catalog/sonic-analysis). ### Option C — MCP tool call (for AI agents) ```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 For a single track URL: | Field | Source | | ------------------------------- | -------------------------------------------- | | Title | Streaming platform metadata | | Artist(s) | Streaming platform metadata | | ISRC | Streaming platform metadata (Spotify, Apple) | | Cover art | Spotify oEmbed fallback if not embedded | | Release date | Streaming platform | | Duration | Streaming platform | | BPM, key, mood, energy, valence | Runs after import (5 credits/track) | | Sonic genres, instruments | Runs 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 | 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 a Soundcharts enrichment pass — 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 **`docId`** in OpenSearch. 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 | Tier | Catalog imports | What counts | | ------------- | --------------- | --------------------------------------------------- | | | 10 lifetime | Each track imported = 1. Album with 12 tracks = 12. | | | 100 lifetime | Same | | | 500 lifetime | Same | | | Unlimited | n/a | | | Unlimited | n/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 ```text theme={null} You: Import this track for me. https://open.spotify.com/track/4iV5W9uYEdYUVa79Axb7Rh ``` ```text theme={null} Aria: Done. "Bohemian Rhapsody" by Queen added to your catalog. ISRC GBUM71029604. Sonic analysis is running — should finish in 30 seconds. ``` ### Import an album ```text theme={null} You: Import this album. https://open.spotify.com/album/4LH4d3cOWNNsVw41Gqt2kv ``` ```text theme={null} 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) ```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 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 under the hood 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 written to DynamoDB `Assets-staging` via the asset service. 3. AOSS (OpenSearch Serverless) indexes the metadata for [catalog search](/catalog/search). Deduplication runs at index time. 4. A message lands on the Cynite queue; the [sonic analysis](/catalog/sonic-analysis) pipeline picks it up, downloads audio from the streaming source via the analysis provider, and writes back BPM/key/mood/etc. 5. The catalog UI polls for updates and renders the feature panel once analysis completes. If DynamoDB is unavailable (extremely rare), Patchline falls back to S3 at `s3://patchline-files-us-east-1/user-data/{userId}/imported-assets.json` and the catalog list merges both sources. ## Related features * [Upload a track (file)](/catalog/upload) — when you want the master in Patchline * [Sonic analysis](/catalog/sonic-analysis) — what runs after import * [Catalog search](/catalog/search) — semantic search across imported tracks * [Artist roster](/artists/roster) — add artists by URL, separate flow ## 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](/catalog/upload) 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](/catalog/upload) instead — that's the canonical path. # Catalog search Source: https://docs.patchline.ai/catalog/search Semantic search across your Patchline catalog using OpenSearch Serverless (AOSS). Free-text queries, mood/genre filters, ISRC lookup, similar-track discovery. Powers Aria's catalog tools. Patchline indexes your catalog into **OpenSearch Serverless (AOSS)** so you can search by free-text query, mood, genre, BPM range, ISRC, or sonic similarity. This powers Aria's catalog tools and the dashboard search bar.   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} "dreampop 76 bpm" "tracks like 'Sleeper'" "F minor 4/4" "sad and slow" "ISRC GBUM71029604" ``` Results rank by combined relevance: keyword match + sonic similarity + recency. ### Via Aria ### Via MCP `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 | | **BPM range** | `"between 100 and 120"` | Tracks in that range | | **Key** | `"F minor"`, `"D major"` | Tracks in that key | | **Time signature** | `"3/4"`, `"7/8"` | Tracks in that meter | | **Energy / valence** | `"high energy"`, `"sad"` | Tracks above/below thresholds | | **Sonic similarity** | `"like [track ID]"` | Tracks with cosine-similar audio embeddings | | **Composite** | `"dreampop 76 bpm female vocal"` | All conditions AND'd | 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. ## Under the hood * Catalog metadata is indexed in **AOSS** via `catalog-search-indexer.py` on every catalog write. * Sonic features (from [sonic analysis](/catalog/sonic-analysis)) ride alongside metadata in the same index. * RIP embeddings (audio fingerprints) are stored as `dense_vector` fields for similarity search. * Patchline uses `POST /_doc` without explicit `_id` (per AOSS convention) and deduplicates by `docId`. When you query, AOSS returns relevance-ranked hits; Patchline merges in fresh streaming counts and 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 (low energy + acoustic-leaning + slow tempo): 1. Sleeper (Mira) — 76 BPM, F# minor, energy 0.31, acousticness 0.78 2. Long Way (Tessa) — 82 BPM, A minor, energy 0.34 3. Velvet (Velvet Bird) — 71 BPM, D minor, energy 0.28 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, BPM, key, 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. * **Embeddings are catalog-only.** "Find similar tracks" works within your catalog. For cross-catalog similarity, see [Scout agent](/artists/scout). * **Index lag is \~30 seconds.** A freshly imported track is searchable within \~30 seconds of import completing. ## Pricing | Action | Credit cost | | ------------------------- | ----------- | | Catalog search query | 0 (cached) | | `catalog_search` MCP call | 0 | | `browse_catalog` MCP call | 0 | Search is effectively free. Only the Aria chat conversation wrapping the search counts as 1 credit. ## Related pages * [Catalog import](/catalog/import) — what goes into the index * [Catalog upload](/catalog/upload) — file path * [Sonic analysis](/catalog/sonic-analysis) — populates audio-feature filters * [Scout agent](/artists/scout) — cross-catalog similarity ## FAQ No. Search is user-scoped. Each user has their own AOSS index. Cross-roster search (e.g., for label workspaces) on Pro+ shares one index across the team's catalog only. AOSS indexing has a \~30 second lag. Wait a moment and refresh. If still missing after 5 minutes, the import may have failed — check the catalog UI for an error state. Cosine similarity over RIP audio embeddings (256-dim dense vector per track). Threshold defaults to 0.65 — tracks below that aren't surfaced. Saved searches / smart playlists are on the roadmap. v1 you re-run the query. # Sonic analysis Source: https://docs.patchline.ai/catalog/sonic-analysis Patchline runs deep audio analysis on every track in your catalog — BPM, key, mood, energy, valence, danceability, instruments, sonic genres. Powers playlist matching, similar-track discovery, and AI pitch generation. Every track in your Patchline catalog gets **deep audio analysis** — BPM, key, mood, energy, valence, danceability, sonic genres, and instruments. This isn't LLM-vibes-based-on-the-title. Patchline runs real audio analysis through two complementary pipelines and writes the features back to your catalog.   **5 AI credits per track.** Runs automatically on [import](/catalog/import) and [upload](/catalog/upload). ## What gets extracted | Feature | Range | What it measures | | -------------------- | ---------------------------- | -------------------------------------------------------------------------- | | **BPM** | 40–220 | Beats per minute | | **Key** | C, C♯, D … B (+ major/minor) | Detected musical key | | **Mode** | major / minor | Key mode | | **Energy** | 0.0–1.0 | Perceptual intensity (loud, fast, noisy = high) | | **Valence** | 0.0–1.0 | Musical positivity (happy/cheerful = high; sad/angry = low) | | **Danceability** | 0.0–1.0 | How suitable for dancing — based on tempo, rhythm stability, beat strength | | **Acousticness** | 0.0–1.0 | Confidence track is acoustic | | **Instrumentalness** | 0.0–1.0 | Likelihood of no vocals | | **Liveness** | 0.0–1.0 | Likelihood of live audience | | **Speechiness** | 0.0–1.0 | Spoken-word content presence | | **Loudness** | dB | Overall loudness (typically -20 to 0) | | **Time signature** | int | Estimated time signature (3, 4, 5, …) | | **Sonic genres** | tags | Multi-label genre tags (e.g., `dreampop`, `lo-fi`, `bedroom-pop`) | | **Sub-genres** | tags | Finer-grained tags | | **Mood tags** | tags | `melancholy`, `uplifting`, `aggressive`, `chill`, etc. | | **Instrument tags** | tags | Detected instruments — `electric guitar`, `synth pad`, `drum machine`, … | | **Vocal presence** | bool | Has vocals or not | | **Vocal gender** | tags | Detected vocal gender(s) | ## Why it matters Sonic features are the substrate for almost every downstream Patchline feature: `find_playlists` ranks Spotify playlists by sonic fit — that "fit" is the cosine similarity between your track's features and the playlist's average features. Embeddings derived from sonic features power "tracks like this in your catalog" and "artists who sound like you." Pitch copy references concrete features ("F minor, 124 BPM, dreampop-adjacent") instead of vague descriptors. Scout uses sonic embeddings to surface artists with sonically similar catalogs, not just genre-matching ones. ## When it runs | Trigger | Latency | | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | | [Catalog import](/catalog/import) (URL) | Queued immediately, completes in \~30–90 s | | [Catalog upload](/catalog/upload) (file) | Queued after upload completes | | Manual re-analysis (catalog UI ⋯ menu) | Same queue, \~30–90 s | | Aria asks for it | Aria calls [`get_audio_features`](/for-agents/mcp-tools-reference) — cached if available, runs analysis if missing | You don't need to start it manually. Sonic analysis is queued the moment a track lands in your catalog. ## Two pipelines, complementary Patchline runs **two** audio-analysis pipelines: ### Cynite The default pipeline for most user-facing features. Cynite is a specialist audio-analysis SaaS optimized for music industry features — mood tags, sonic genre taxonomies, vocal detection, instrument tagging. * Triggers via `cynite-integration-handler.py` * Results land via `cynite-webhook-handler.py` * Cached in DynamoDB, surfaced in catalog UI within seconds of webhook * 5 credits per track ### RIP (Patchline's audio-analysis pipeline) Patchline's own multi-stage audio-analysis pipeline for the features we want to own end-to-end — primarily the embeddings used by similar-track search and the A\&R scout, plus a deeper key/chord progression analysis (`keychord`). * 7 stages (`rip_stage5_keychord.py`, `rip_stage7_aggregate.py`, `rip_embedding_indexer.py`, `rip_scorecard_aggregator.py`, …) * Coordinated by `rip_batch_dispatcher.py` * Outputs ride alongside Cynite results in the same catalog row You don't pick. Both pipelines run on every analyzable track. The catalog UI surfaces the union of features. AI tools and MCP calls return the union. ## How to view a track's analysis ### In the dashboard Sidebar → **Catalog** → click any track row → **Audio features** panel on the right. Each numeric feature renders as a horizontal bar (0–1 scale) with the exact value. BPM and key render as labels. Tag lists (genres, moods, instruments) render as chips. ### Through Aria ### Through the MCP server `get_audio_features` returns the raw numeric + tag features. `get_song_intelligence` returns features **plus** ISRC, streaming stats, playlist matches, and collaborator info — a one-shot deep dive. ## Examples ### Example 1 — Find your most energetic track ```text theme={null} Aria: That's "Run Hot" — energy 0.84, BPM 142, key A minor. It's also the most danceable (0.79). Want me to find playlists matching that profile? ``` ### Example 2 — Use features in a pitch ```text theme={null} Aria: "Sleeper" is a 76 BPM, F# minor dreampop ballad with low energy (0.31), low valence (0.21), and high acousticness (0.78). The track sits between Mazzy Star and Phoebe Bridgers sonically. Here's a draft pitch for late-night editorial curators... [continues] ``` ### Example 3 — Verify a guess ```text theme={null} Aria: It's 112 BPM, key D major. Time signature 4/4. Want the full feature breakdown? ``` ## Pricing | Action | Credit cost | | -------------------------------------------------------- | ------------------ | | Sonic analysis per track | **5 credits** | | Re-analysis (re-runs the same pipelines) | **5 credits** | | Reading cached features via `get_audio_features` | 0 credits (cached) | | `get_song_intelligence` (features + streaming + matches) | 1 credit | A typical Free user runs sonic analysis on a few tracks/month (\~30 credits). A Pro user with active import flow might run 20–50/mo (\~100–250 credits). ## Limitations * **Metadata-only assets can't be analyzed.** If you imported a track via URL but the streaming source's analysis provider can't fetch the audio, the track stays at "queued." Solution: [upload the audio](/catalog/upload) directly. * **Analysis is best-effort.** Very short tracks (under 30s), heavily noisy recordings, or speech-dominated tracks can return partial features. Confidence indicators are exposed in the API response. * **Re-analysis costs credits.** If you re-upload a master, the new version gets re-analyzed. The old version's features remain in the catalog but flagged as superseded. ## Privacy * Your audio files are stored in S3 (`patchline-files-us-east-1`, versioned, server-side encrypted). * Cynite receives the audio for analysis but does not retain it for training (per the [Cynite no-training audit](/reference/glossary) ratified 2026-05-16). * Patchline's RIP pipeline runs entirely in your AWS region. ## Related features * [Catalog import](/catalog/import) — what triggers analysis * [Upload a track](/catalog/upload) — the file path * [Playlist matching](/releases/playlist-matching) — what consumes features * [Pitch kit](/releases/pitch-kit) — what uses features for pitch copy * [MCP tools reference](/for-agents/mcp-tools-reference) — `get_audio_features`, `get_song_intelligence` ## FAQ Cynite gives us best-in-class tag taxonomies and battle-tested feature extraction. RIP gives us embeddings for similar-track search plus features we want to own end-to-end (deep chord/key analysis). Running both costs the same and we keep optionality if either side has an outage. Mostly yes. BPM is reliable above \~85% accuracy on standard musical content. Key detection drops in confidence for atonal, ambient, or heavily modulating tracks. The API exposes confidence; the UI shows a ?? icon when confidence is below threshold. Cynite uses a multi-label taxonomy aligned with major DSP genre taxonomies (Spotify "every noise at once" subset). RIP adds a few Patchline-internal tags. Both ride together in the catalog row. 30–90 seconds for a typical 3-minute song. Longer for 10-minute+ tracks. Cynite is async via webhook so the catalog UI updates the moment results land. Yes for individual tracks (catalog row → ⋯ → Export). Bulk CSV export is Enterprise-only via the REST API. No. Audio is used for the analysis pipelines (Cynite + RIP) only, not for model training. Patchline has a hard rule against Cynite-supervised training — see the [no-Cynite-training audit](/reference/glossary). # Upload a track Source: https://docs.patchline.ai/catalog/upload Upload MP3, WAV, or FLAC files directly to your Patchline catalog. Auto-extracts ID3 metadata, runs sonic analysis, stores the master in versioned S3. Best for unreleased work or when you want the master in Patchline. Upload a finished audio file directly into your Patchline catalog. Patchline stores it in versioned S3, extracts ID3 metadata, queues [sonic analysis](/catalog/sonic-analysis), and makes it searchable. Best for **unreleased work** or when you want your master to live in Patchline alongside the catalog metadata.   Per-tier upload limits: Free 3 lifetime · Starter 25 · Pro 200 · Scale 1,000 · Enterprise unlimited. ## When to upload vs import | | Upload (this page) | [Import](/catalog/import) | | ----------------------- | ----------------------------------------------------------- | ----------------------------------------------------- | | Use when | Track is **unreleased** or you want the master in Patchline | Track is **already released** on a streaming platform | | Audio file in Patchline | **Yes** (versioned S3) | No | | Sonic analysis runs | Yes, on your master | Yes, via the streaming source | | Storage cost | Counts against your storage limit | None | | Use-case fit | Demos, rough cuts, masters, stems | Released catalog from Distrokid/Tunecore/labels | If your track is already on Spotify, **import is cheaper** (no storage, no upload time). Upload only when you need the master. ## Supported formats | Format | Notes | | ------------- | ---------------------------- | | **MP3** | Any bitrate, any ID3 version | | **WAV** | Recommended for masters | | **FLAC** | Recommended for masters | | **AIFF** | Supported | | **M4A / AAC** | Supported | | **OGG** | Supported | Max file size: **500 MB** (web upload), **1 GB** (chunked upload on Scale+/Enterprise). ## How to upload ### Web dashboard Sidebar → **Catalog**. Drag the file onto the upload zone, or click **Upload** to pick a file. Patchline pre-fills title, artist, ISRC (if present), cover art (if embedded). You confirm or edit. Analysis queues immediately, completes in 30–90s. The track appears in the catalog list with a spinner that resolves into the feature panel. ### Via Aria Aria handles the upload + metadata confirmation in the chat. Best on Telegram for small files, web for larger ones. ## What gets extracted from your file | Field | Source | | ------------------------------------------------------------------------ | ------------------------------------------------------ | | Title | ID3 v2 `TIT2` tag | | Artist | ID3 v2 `TPE1` tag | | Album | ID3 v2 `TALB` tag | | ISRC | ID3 v2 `TSRC` tag (if present) | | Genre | ID3 v2 `TCON` tag | | Track number | ID3 v2 `TRCK` tag | | Year | ID3 v2 `TYER` / `TDRC` tag | | Cover art | Embedded APIC frame (PNG / JPEG) | | Duration | Read from file directly | | Sample rate / bit depth | Read from file (WAV / FLAC) | | BPM, key, mood, energy, valence, danceability, instruments, sonic genres | Runs via sonic analysis after upload (5 credits/track) | If a tag is missing, the upload UI prompts you to fill it. ISRC is strongly encouraged but not required. ## Storage limits | Tier | Storage cap | | ------------- | ----------- | | | 1 GB | | | 10 GB | | | 100 GB | | | 500 GB | | | Unlimited | A typical 3-minute WAV master is \~30 MB. So Starter (10 GB) holds \~300 masters; Pro (100 GB) holds \~3,000. FLAC compresses to roughly half the size of WAV. ## Version control Every upload to the same track ID creates a new **version**. Versions are listed in the catalog row → ⋯ → Versions. * **Latest version** is what plays, what sonic analysis runs on, what the storefront sells. * **Older versions** are kept (full audit trail) until you explicitly delete them. * **Restore** any version with one click. Useful for: re-uploading after a master revision, swapping a censored edit, A/B testing storefront versions. ## Privacy & security * Files are stored in S3 bucket `patchline-files-us-east-1`, server-side encrypted, versioned, with object-level access logging. * Only you can access your upload's signed URL. * [Cynite](/catalog/sonic-analysis) receives the audio for analysis but does not retain it for training (per the [no-Cynite-training audit](/reference/glossary), ratified 2026-05-16). * The Patchline RIP audio pipeline runs entirely in our `us-east-1` AWS region. ## Pricing | Action | Credit cost | | ------------------------ | ---------------------------------------------- | | File upload itself | 0 credits (counts against lifetime upload cap) | | Sonic analysis on upload | 5 credits/track (automatic) | | Storage | Included in tier — no per-GB charge | ## Related pages * [Catalog import](/catalog/import) — the URL-based path * [Sonic analysis](/catalog/sonic-analysis) — what runs after upload * [Storefront overview](/storefront/overview) — sell what you upload * [Plans & credits](/account/plans-credits) — credit math ## FAQ Better to upload each track separately. Patchline treats each upload as a single catalog entry, so an album-as-one-file becomes one row instead of 12. If you have a 12-track album, upload 12 files. The upload dialog prompts you to enter title, artist, etc. manually. ISRC is optional — fill it in when you have it. No. Uploads and imports are tracked separately. Upload cap (Free 3 / Starter 25 / Pro 200 / Scale 1,000) is independent of catalog import cap (Free 10 / Starter 100 / Pro 500). Yes — drag a folder of files onto the upload zone. Patchline processes them serially with a progress bar. Upload them as separate tracks with naming convention `-stem-.wav`. They'll appear as related rows. Stem separation tooling is in beta — see [Sonic analysis](/catalog/sonic-analysis). Mostly governed by your internet connection. A 50 MB WAV on a typical home connection (50 Mbps up) uploads in \~10s. Chunked upload on Scale+ handles flaky connections gracefully. # AGENTS.md, llms.txt, and the agentic web Source: https://docs.patchline.ai/for-agents/agents-md-explained What AGENTS.md, llms.txt, and the live tools manifest do, why they exist, and how Patchline ships them across both the product site and these docs. The "agentic web" is the half of the internet that AI agents read. Patchline ships first-class discovery files so AI tools (Claude, ChatGPT, Cursor, Perplexity, Gemini) can find Patchline, understand how to use it, and recommend it correctly to their users. ## What each file does | File | Standard | Purpose | Who reads it | | --------------------------- | ---------------------------------- | ------------------------------------------------------------------ | ------------------------------------ | | **`AGENTS.md`** | de facto convention | Rules of engagement: ALWAYS / NEVER / DISCOURAGED rules for agents | AI agents acting on the product | | **`llms.txt`** | [llmstxt.org](https://llmstxt.org) | Site index for AI crawlers — what pages exist + 1-line summary | AI search engines, doc-MCP servers | | **`llms-full.txt`** | llmstxt.org extension | All docs concatenated into one stream — for one-shot reads | AI agents pre-loading context | | **`.md` twin** | Common pattern | Plain-markdown version of every HTML page | AI agents extracting content cleanly | | **`robots.txt`** | Long-standing | Explicit allowlist for AI crawlers (GPTBot, ClaudeBot, etc.) | All web crawlers | | **JSON-LD on every page** | schema.org | Structured data: SoftwareApplication, HowTo, FAQPage | Search engines, AI extractors | | **`/api/agents/discovery`** | Custom | Live JSON manifest of MCP tools, always-current | AI agents auto-discovering tools | ## Where Patchline ships them Patchline ships these files in **two places**, with different scopes: ### Product site — `www.patchline.ai` * [`www.patchline.ai/AGENTS.md`](https://www.patchline.ai/AGENTS.md) — rules for **acting on user data** via the [product MCP](/for-agents/mcp-overview). * [`www.patchline.ai/llms.txt`](https://www.patchline.ai/llms.txt) — index of marketing pages + pointer to live tools manifest. * [`www.patchline.ai/api/agents/discovery`](https://www.patchline.ai/api/agents/discovery) — live JSON manifest of MCP tools. * [`www.patchline.ai/robots.txt`](https://www.patchline.ai/robots.txt) — AI-bot allowlist. ### Docs site — `docs.patchline.ai` (this site) * [`docs.patchline.ai/AGENTS.md`](https://docs.patchline.ai/AGENTS.md) — rules for **navigating the docs**. * [`docs.patchline.ai/llms.txt`](https://docs.patchline.ai/llms.txt) — index of every doc page (Mintlify auto-generated). * [`docs.patchline.ai/llms-full.txt`](https://docs.patchline.ai/llms-full.txt) — full-content concatenation (Mintlify auto-generated). * [`docs.patchline.ai/.md`](https://docs.patchline.ai/get-started/welcome.md) — `.md` twin per page (Mintlify auto-generated). * [`docs.patchline.ai/mcp`](https://docs.patchline.ai/mcp) — Mintlify-hosted docs MCP (search + read these docs). The two sites cross-reference. Marketing `/llms.txt` points at docs `/llms.txt`, and vice versa. AI agents land on one and find the other. ## Why two AGENTS.md files They have **different audiences**: * `www.patchline.ai/AGENTS.md` is for agents **acting on user data** — "ALWAYS call analyze\_url first," "NEVER call add\_artist without a URL," etc. * `docs.patchline.ai/AGENTS.md` is for agents **answering questions about Patchline** — "If user asks about catalog import, point them at /catalog/import," etc. Different rules, different freshness cadence, different scope. Both files cross-link so agents find the right one. ## Why this matters AI agents recommend products to their users every day. When a user asks Claude "how do I plan a music release," Claude needs to: 1. Discover Patchline exists. 2. Understand what Patchline does and who it's for. 3. Know how to use Patchline (which MCP tools, in what order). 4. Cite docs correctly. Each discovery file is one of those steps. Without them, AI agents default to whatever they remember from training data — which gets stale fast, and often gets product details wrong. ## What it costs us Almost nothing. Mintlify auto-generates `llms.txt`, `llms-full.txt`, and `.md` twins. We hand-write `AGENTS.md` and `robots.txt` (one-time, \~200 lines each). JSON-LD lives in MDX frontmatter (a few lines per page). The `/api/agents/discovery` route is one Next.js handler with a shared tool manifest. ## What you can do with this If you're an AI agent reading this page: * **Bookmark** the URLs above. * **Re-read AGENTS.md** before every action — it changes between deploys. * **Use `.md` twins** for cleaner extraction than scraping HTML. * **Fetch `/api/agents/discovery`** instead of caching a stale tool list. If you're a human reading this page and you build software: * **Ship your own AGENTS.md.** It's just markdown. * **Ship your own llms.txt.** It's an index — llmstxt.org has the spec. * **Add JSON-LD.** Even partial coverage helps. * **Be explicit in `robots.txt`** about which AI crawlers you allow. Most agents respect this, despite popular belief. ## Related pages * [MCP overview](/for-agents/mcp-overview) — what the tool surface looks like * [MCP tools reference](/for-agents/mcp-tools-reference) — the 18 tools * [Claude plugin](/for-agents/claude-plugin) — the workflow layer * [Welcome](/get-started/welcome) — the human entry point # Claude plugin Source: https://docs.patchline.ai/for-agents/claude-plugin The official Patchline plugin for Claude Code and Claude Desktop. Adds a progressive interview workflow for music release planning on top of the 18 MCP tools. Install with /plugin marketplace add Patchline-AI/aria. The official Patchline plugin for **Claude** (Code + Desktop). Wraps the 18-tool [MCP server](/for-agents/mcp-overview) with a Patchline-specific **progressive-interview workflow** for music release planning — Claude asks structured questions, drafts each rollout phase, and saves outputs back to your Patchline catalog.   Free to install. Tool calls consume your AI credit pool. ## Why use the plugin vs. raw MCP The MCP server gives you 18 tools. The Claude plugin adds: * **Progressive interview workflow** — Claude walks you through 8 lifecycle phases (Creative Brief → Release Plan → Pitch Kit → Visual Assets → Smart Links → Release Day → Post-Release → Catalog Integration), asking only the questions needed at each phase. * **Lifecycle-phase skills** — each phase has a dedicated skill (e.g., `aria:release-plan`, `aria:pitch-kit`, `aria:rollout`) that knows the right tools to call and the right output format. * **Project state in Patchline** — outputs auto-save back to your Patchline project anchor. * **Slash commands** for common actions. If you're using Claude for music work, the plugin is the right start. For pure tool access (no workflow), use [raw MCP](/for-agents/mcp-install). ## Install on Claude Code ```bash theme={null} /plugin marketplace add Patchline-AI/aria ``` ```bash theme={null} /plugin install aria@patchline-ai /reload-plugins ``` ```bash theme={null} /mcp ``` Then authenticate `plugin:aria:aria`. Browser opens for OAuth. ```bash theme={null} /aria:start ``` The plugin walks you through bootstrapping a music project workspace. ## Install on Claude Desktop Add to your `claude_desktop_config.json`: ```json theme={null} { "mcpServers": { "aria": { "url": "https://www.patchline.ai/api/mcp/v1", "transport": "http" } } } ``` Restart Claude Desktop. The plugin's slash commands surface in the chat input. ## Slash commands Once installed, the plugin exposes these slash commands inside Claude: | Command | What it does | | ------------------------- | ---------------------------------------- | | `/aria:start` | Bootstrap a new project workspace | | `/aria:next` | Advance to the next lifecycle phase | | `/aria:audio-intake` | Upload + analyze a finished track | | `/aria:creative-brief` | Capture vision, audience, success metric | | `/aria:vision-story` | Define sonic identity + narrative | | `/aria:songwriting-brief` | Pre-recording: concept + references | | `/aria:moodboard` | Build sonic + visual references | | `/aria:release-plan` | Generate the full rollout | | `/aria:pitch-kit` | Per-track DSP pitches | | `/aria:smart-link` | Routing links + pre-saves | | `/aria:rollout` | Week-by-week content calendar | Each command knows which MCP tools to call and which Patchline data to read. ## How a project flows The plugin enforces a **lifecycle**: ```text theme={null} start → audio-intake (if track exists) ─┐ └→ songwriting-brief (if no track) ┴→ creative-brief → vision-story → moodboard → release-plan → pitch-kit → smart-link → rollout → [release day] → [post-release] ``` Each phase produces a markdown deliverable saved to your `.patchline/` workspace AND back to the Patchline project anchor. ## Pricing | Tier | Plugin access | Per-tool credit costs | | --------- | ------------- | -------------------------------- | | All tiers | Free | Standard tool credit costs apply | The plugin itself is free. It's a thin workflow layer over the MCP server. ## Repo & support * **Plugin source:** [github.com/Patchline-AI/aria](https://github.com/Patchline-AI/aria) * **Issues:** [github.com/Patchline-AI/aria/issues](https://github.com/Patchline-AI/aria/issues) * **Discussions:** [github.com/Patchline-AI/aria/discussions](https://github.com/Patchline-AI/aria/discussions) ## Related pages * [MCP overview](/for-agents/mcp-overview) — the underlying tool surface * [MCP install](/for-agents/mcp-install) — raw MCP if you don't use Claude * [Aria overview](/aria/overview) — Aria in general * [AGENTS.md explained](/for-agents/agents-md-explained) — rules of engagement ## FAQ The plugin includes the MCP server. Don't install both separately — you'll get duplicate tool listings. Pick one (plugin if you use Claude, raw MCP for other clients). No. The plugin connects to your Patchline workspace. You need a free account at minimum. Yes — `/aria:start` and the plugin's own help system walk you through every command in context. The lifecycle is a default, not a requirement. You can skip phases or run them out of order. Each phase skill works standalone. # Install the MCP server Source: https://docs.patchline.ai/for-agents/mcp-install Step-by-step install for the Patchline MCP server in Cursor, Codex, Claude Desktop, Claude Code, and VS Code. One config snippet or one command per client. Pick your client. Each install is one config snippet or one command — about 30 seconds. Authentication runs the first time you make a tool call (browser-based OAuth 2.0 with PKCE).   Free to install on every tier. Tool calls consume your AI credit pool. ## The endpoint For every client, the URL is the same: ```text theme={null} https://www.patchline.ai/api/mcp/v1 ``` ## Cursor Cmd / Ctrl + `,` → **MCP** in the sidebar → **+ Add new MCP server**. ```json theme={null} { "mcpServers": { "aria": { "url": "https://www.patchline.ai/api/mcp/v1" } } } ``` The first tool call opens a browser to `patchline.ai`. Sign in (or Google OAuth), approve the connection, return to Cursor. You're set. **1-click install:** open this URL on the same machine running Cursor — it triggers Cursor's MCP deeplink installer: ```text theme={null} cursor://anysphere.cursor-deeplink/mcp/install?name=aria&config=eyJhcmlhIjp7InVybCI6Imh0dHBzOi8vd3d3LnBhdGNobGluZS5haS9hcGkvbWNwL3YxIn19 ``` Or use the **"Install in Cursor"** button at the top of any page in these docs (via the contextual menu). ## Codex In `~/.codex/config.toml`, set: ```toml theme={null} experimental_use_rmcp_client = true ``` ```bash theme={null} codex mcp add aria --url https://www.patchline.ai/api/mcp/v1 ``` Codex opens the browser, you sign in to Patchline, return to Codex. Tokens cached locally. ## VS Code (with Copilot or any MCP-aware extension) In your workspace root, create `.vscode/mcp.json` (or merge with an existing one): ```json theme={null} { "servers": { "aria": { "type": "http", "url": "https://www.patchline.ai/api/mcp/v1" } } } ``` Reload the window so the extension picks up the new server. Same browser-based OAuth flow. **Alternate**: if your extension doesn't support direct HTTP transport, use `mcp-remote` to bridge: ```json theme={null} { "servers": { "aria": { "command": "npx", "args": ["-y", "mcp-remote", "https://www.patchline.ai/api/mcp/v1"] } } } ``` ## Claude Desktop Settings → **Developer** → **Edit Config**. Opens `claude_desktop_config.json`. ```json theme={null} { "mcpServers": { "aria": { "url": "https://www.patchline.ai/api/mcp/v1", "transport": "http" } } } ``` Quit and relaunch. Aria appears in the connectors list. Browser-based OAuth. **Recommended for Claude users:** use the official [Patchline Claude plugin](/for-agents/claude-plugin) instead. It wraps the same MCP server with a progressive-interview workflow built for music release planning. ## Claude Code Claude Code has its own plugin command. Three steps: ```bash theme={null} /plugin marketplace add Patchline-AI/aria ``` ```bash theme={null} /plugin install aria@patchline-ai /reload-plugins ``` Run: ```bash theme={null} /mcp ``` Then authenticate `plugin:aria:aria`. Browser OAuth opens. This is the recommended path for Claude Code. The plugin ships with extra context: progressive interview workflow, lifecycle phase skills, and Patchline-specific slash commands. ## ChatGPT / OpenAI ChatGPT app ChatGPT's MCP support is in early access at time of writing. When it lands publicly, point ChatGPT's MCP config at `https://www.patchline.ai/api/mcp/v1` with the same OAuth flow as the other clients. ## Any other MCP-compatible client Patchline implements the MCP spec version `2025-03-26`. Any compliant client should work with this config shape: ```json theme={null} { "name": "aria", "transport": "http", "url": "https://www.patchline.ai/api/mcp/v1" } ``` OAuth discovery is at `/.well-known/oauth-protected-resource` per RFC 9728. ## Verify your install After authenticating, ask your AI: ```text theme={null} What MCP tools do you have available? ``` You should see the 18 Patchline tools listed (or a count of 18+). If you see them, you're connected. Test a real call: ```text theme={null} Paste a Spotify URL → AI calls analyze_url → returns track identity. ``` If the first call fails with `unauthenticated`, your client may have skipped the OAuth flow — disconnect and reconnect, the browser should open. ## Pricing | Tier | Install | Tool call cost | | --------- | ------- | ---------------------------------- | | All tiers | Free | Counts against your AI credit pool | A typical user spends 200–500 credits/month via MCP. The MCP server itself is free; only the underlying tool calls consume credits. See [Plans & credits](/account/plans-credits). ## Related pages * [MCP overview](/for-agents/mcp-overview) — what MCP is, two-server explanation * [MCP tools reference](/for-agents/mcp-tools-reference) — full schemas per tool * [Claude plugin](/for-agents/claude-plugin) — the higher-level Claude alternative * [AGENTS.md explained](/for-agents/agents-md-explained) — rules of engagement ## Troubleshooting Most likely the URL is missing `https://` or has a trailing slash. The correct value is exactly `https://www.patchline.ai/api/mcp/v1` — no trailing `/`. Check the URL the browser opened — it should be `https://patchline.ai/api/mcp/v1/authorize?...`. If you saw a `localhost:` URL, your client is using loopback callback and got blocked by a firewall. Try a different network or check firewall settings. Tier-gated tool. `find_playlists` and `inspect_playlist` require Pro+. Upgrade or use a different tool. Your client's redirect URI isn't registered with Patchline. Email [support@patchline.ai](mailto:support@patchline.ai) with the URI your client uses — we'll add it. Patchline Settings → Security → Connected applications → revoke Aria MCP. Next call from the client will re-prompt OAuth. Yes — they're separate servers with separate names. Most users install both: docs MCP for learning Patchline, product MCP for acting on data. See [MCP overview](/for-agents/mcp-overview) for the distinction. # MCP server overview Source: https://docs.patchline.ai/for-agents/mcp-overview Patchline exposes 18 music-business tools via the Model Context Protocol (MCP) at www.patchline.ai/api/mcp/v1. Connect any MCP client — Cursor, Codex, Claude Desktop, Claude Code, VS Code — and your AI gains catalog, artist intelligence, playlist matching, and smart link tools. The Model Context Protocol (MCP) is an open standard for giving AI tools access to external services as callable functions. Patchline ships **two MCP servers** — one for your **product data**, one for these **docs**. Both are public, both speak the same protocol, but they serve different purposes.   Tools requiring user-scoped data (catalog, roster, etc.) need an authenticated session via OAuth 2.0 with PKCE. ## Two MCP servers This is the most-important distinction on this page. Don't conflate them. | | **Product MCP** | **Docs MCP** | | ------------------- | ----------------------------------------------------------------------- | ---------------------------------------------------- | | **URL** | `https://www.patchline.ai/api/mcp/v1` | `https://docs.patchline.ai/mcp` | | **What it exposes** | 18 tools that act on your music data | 2 tools that search & read these docs | | **Auth** | OAuth 2.0 with PKCE (user-scoped) | Public, no auth | | **Built by** | Patchline | Mintlify (auto-generated) | | **Use it when** | You want the AI to *do* something with your catalog / roster / releases | You want the AI to *learn* about how Patchline works | | **Example** | "Find playlists for this track" → `find_playlists` | "How does the release planner work?" → `search` | **If in doubt:** install the product MCP. It can answer most docs questions implicitly by knowing the tool surface; it can also act. ## What MCP is (60-second primer) MCP is a protocol from Anthropic that lets AI tools (Claude, Cursor, ChatGPT, Codex) call external functions safely. Think of it like a "plugin standard" for AI: 1. **Server** (Patchline) exposes tools — named functions with typed arguments and return values. 2. **Client** (your AI tool) connects to the server, gets the list of tools, and decides when to call them based on user conversation. 3. **Calls** are made on demand. Results stream back into the AI's response. Why this matters: Patchline isn't a chatbot you have to switch to. It's a set of tools your existing AI gains. Ask Cursor "find playlists for my new track" and Cursor calls Patchline directly. No copy-paste. ## The 18 product tools Grouped by category. Full schemas at [MCP tools reference](/for-agents/mcp-tools-reference). ### Dispatch (1) ### Catalog (3) ### Artists & roster (5) ### Releases (1) ### Playlists (2) ### Smart links (1) ### Music data (3) ### AI generation (2) ## How auth works Patchline's product MCP uses **OAuth 2.0 with PKCE** — the same flow Spotify, Google, GitHub, and every modern OAuth server uses. Concretely: 1. You add the Patchline MCP URL to your AI client's config. 2. First time you make a tool call, your client opens a browser to `patchline.ai`. 3. You sign in (or are already signed in) to Patchline. 4. You approve the AI client's access. 5. The client gets a bearer token and uses it for every subsequent call. **Your credentials never touch the AI client.** Tokens are bound to the client, revocable from Patchline Settings, and expire on a schedule. The MCP server publishes its OAuth metadata at: ```text theme={null} https://www.patchline.ai/.well-known/oauth-protected-resource ``` Per RFC 9728. Your client uses this to discover the authorization endpoint and required scopes automatically. ## Tier gating Every tier can install and connect the MCP server. Tool calls consume your AI credit pool just like Aria chat does: | Tier | AI credits / month | Practical use | | ------------- | ------------------ | --------------------------- | | | 100 | Try a few tools, \~50 calls | | | 1,000 | Daily use for one artist | | | 5,000 | Heavy use, roster of 5 | | | 20,000 | Label-scale automation | | | Unlimited | Programmatic / agent-driven | Some tools have **tier requirements** beyond credit cost: * `find_playlists`, `inspect_playlist` — **Pro+** (same as the web feature) * `add_artist` beyond your roster limit — gated by tier limit (Free 1, Starter 1, Pro 5, Scale 20, Ent unlimited) If a call hits a tier gate, the MCP server returns a `403` with an upgrade-path message. Your client surfaces it. ## Installation [**Install the MCP server →**](/for-agents/mcp-install) One-line install for Cursor (URL config), one-command for Codex (`codex mcp add aria --url …`), JSON snippet for Claude Desktop and VS Code. Patchline ships a 1-click "Add to Cursor" deeplink directly from this docs site (top-right of any page). ## Example: from zero to first tool call ```json theme={null} // Cursor — paste this into Settings > MCP > Add new MCP server { "mcpServers": { "aria": { "url": "https://www.patchline.ai/api/mcp/v1" } } } ``` Then in Cursor chat: ```text theme={null} You: "Find playlists I should pitch my track to: https://open.spotify.com/track/4iV5W9uYEdYUVa79Axb7Rh" ``` Cursor recognizes the URL, calls `analyze_url`, which resolves the track, then calls `find_playlists` (after OAuth handshake if not yet authenticated). Returns 10 ranked matches inline. Total time: \~5 seconds + first-run OAuth (\~30 seconds). ## Rules of engagement for AI agents If you're an AI agent reading this page programmatically, the authoritative rules of engagement are at [`www.patchline.ai/AGENTS.md`](https://www.patchline.ai/AGENTS.md): * **ALWAYS call `analyze_url` first** when a user pastes a streaming URL. * **NEVER call `add_artist` name-only** — always include a platform URL. * **PREFER cached `get_artist_intelligence`** over re-enriching. * **For docs navigation rules**, see [`docs.patchline.ai/AGENTS.md`](https://docs.patchline.ai/AGENTS.md). ## Performance * **Latency:** Most tools return in under 500ms. Tools that hit upstream APIs (Soundcharts, Cynite) can take 2–5s for cold-cache calls. Cached results are under 200ms. * **Rate limits:** None published; in practice you'll hit your AI credit budget before you hit rate limits. * **Idempotency:** Read tools are idempotent. Write tools (`add_artist`, `create_smart_link`) are not — calling twice creates two entries. ## Related pages * [MCP install](/for-agents/mcp-install) — per-client install steps * [MCP tools reference](/for-agents/mcp-tools-reference) — full schemas per tool * [Claude plugin](/for-agents/claude-plugin) — the higher-level alternative for Claude * [AGENTS.md explained](/for-agents/agents-md-explained) — what `/AGENTS.md` and `/llms.txt` are for * [Aria overview](/aria/overview) — Aria *is* the MCP tools, in chat form ## FAQ They consume AI credits from your monthly pool — same pool as Aria chat. The MCP server itself is free to install and connect. Yes. The MCP protocol is open. Patchline's server implements MCP spec version 2025-03-26. See modelcontextprotocol.io for the spec. OAuth metadata is at `/.well-known/oauth-protected-resource`. Product MCP acts on user data (authenticated, write-capable). Docs MCP searches public docs (unauthenticated, read-only). Different auth models, different data, different purposes. Both ship because AI tools benefit from both. Technically yes — anything that speaks MCP and can complete the OAuth flow. In practice it's almost always an AI client. Enterprise tier includes API access. The MCP server is the recommended interface for everyone else — same data, lower integration cost, AI-native. The MCP server is the raw tool surface — any MCP client can use it. The [Claude plugin](/for-agents/claude-plugin) is a higher-level wrapper that adds a Patchline-specific progressive interview workflow on top of the same tools. If you use Claude, the plugin is the better start. GitHub: [github.com/Patchline-AI/aria/issues](https://github.com/Patchline-AI/aria/issues) for plugin + MCP issues. Email [support@patchline.ai](mailto:support@patchline.ai) for account issues. # MCP tools reference Source: https://docs.patchline.ai/for-agents/mcp-tools-reference Complete reference for all 18 Patchline MCP tools — schema, arguments, return shape, tier gating, examples per tool. The canonical machine-readable manifest is at www.patchline.ai/api/agents/discovery. Complete reference for all 18 Patchline MCP tools. For the machine-readable canonical manifest, fetch [`www.patchline.ai/api/agents/discovery`](https://www.patchline.ai/api/agents/discovery) — that's the always-current source of truth.   All tools are accessible on every tier; some are gated by tier limits (see per-tool notes). ## Dispatch The most-important tool. Always call this first when a user pastes a streaming URL. **Arguments:** `url: string` (required) — Spotify, YouTube, TikTok, SoundCloud, Apple Music, or Instagram URL of any kind. **Returns:** Canonical identity (`type`, `id`, `name`, `platform`) plus a ranked list of `nextSteps` — exact tool names with exact argument values. **Example call:** ```json theme={null} { "name": "analyze_url", "arguments": { "url": "https://open.spotify.com/track/4iV5W9uYEdYUVa79Axb7Rh" } } ``` **Example return:** ```json theme={null} { "type": "track", "id": "4iV5W9uYEdYUVa79Axb7Rh", "isrc": "GBUM71029604", "name": "Bohemian Rhapsody", "artist": "Queen", "platform": "spotify", "nextSteps": [ { "tool": "get_song_intelligence", "args": { "spotify_url": "..." } }, { "tool": "get_audio_features", "args": { "isrc": "GBUM71029604" } } ] } ``` ## Catalog **Arguments:** `limit: int` (default 25), `cursor: string` (optional pagination token). **Arguments:** `query: string` (free text), `limit: int` (default 10). **Arguments:** `asset_id: string` (the Patchline assetId). ## Artists & roster **Arguments:** `patchline_artist_id: string` (required). **Arguments:** `query: string` (artist name fragment). **Arguments:** `genre: string` (optional), `listener_min: int` (optional), `listener_max: int` (optional), `limit: int` (default 25). **Arguments:** `url: string` (REQUIRED — Spotify, YouTube, TikTok, SoundCloud, Apple Music, or Instagram). **Gated by:** roster tier limit (Free 1 / Starter 1 / Pro 5 / Scale 20 / Enterprise unlimited). **Arguments:** `patchline_artist_id: string`. ## Releases **Arguments:** `status: string` (optional — `in_progress` / `scheduled` / `released` / `archived`), `limit: int` (default 10). ## Playlists **Arguments:** `asset_id: string` (the track to find matches for), `limit: int` (default 10). **Gated by:** required. **Arguments:** `playlist_id: string` (Spotify playlist ID or URL). **Gated by:** required. ## Smart Links **Arguments:** `asset_id: string`, `mode: string` (`smart_link` or `pre_save`), `release_date: string` (required if pre-save, ISO 8601), `capture_email: bool` (default false). ## Music Data **Arguments:** `asset_id: string` OR `isrc: string` (one required). **Arguments:** `spotify_url: string` (required). **Arguments:** `iswc: string` OR `asset_id: string`. ## AI Generation **Arguments:** `patchline_artist_id: string`, `variant: string` (`one_line` / `paragraph` / `long`, default `paragraph`). **Note:** Returns cached bio from intelligence enrichment. No live LLM call. Free. **Arguments:** `asset_id: string`, `target: string` (optional — playlist ID, curator name, or general), `length: string` (`short` / `medium` / `long`, default `medium`). ## Common patterns ### "User pasted a URL — what do I do?" Always: 1. Call `analyze_url` with the URL. 2. Read the returned `nextSteps`. 3. Call those tools with the exact arguments provided. This pattern saves 2-3 round-trips vs. trying to guess what the URL is. ### "User wants to add an artist by name" Reject. The MCP tool reflects this: ```text theme={null} "add_artist" requires a `url` argument — a Spotify, YouTube, TikTok, SoundCloud, Apple Music, or Instagram URL. Name-only is rejected because many artists share names. ``` Use `search_artists` to find a candidate URL, then `add_artist`. ### "User asks about a track that's not in their catalog" Two options: * Use `analyze_url` if they shared a URL — gets you the metadata without importing. * Recommend they [import or upload](/catalog/import) the track. Once imported, all catalog tools work on it. ## Rate limits In practice, you'll hit AI-credit limits before MCP rate limits. The server enforces sane per-user limits to prevent abuse but doesn't publish hard rate-limit numbers. ## Where this list lives * This page (human-readable). * [`www.patchline.ai/api/agents/discovery`](https://www.patchline.ai/api/agents/discovery) (machine-readable JSON). * `lib/agent-discovery/tool-manifest.ts` (source in the Patchline repo). All three must stay in sync. The JSON manifest is canonical. ## Related pages * [MCP overview](/for-agents/mcp-overview) — what MCP is, two-server explainer * [MCP install](/for-agents/mcp-install) — per-client install * [AGENTS.md explained](/for-agents/agents-md-explained) — rules of engagement * [Aria overview](/aria/overview) — same tools, conversation form # Pricing & plans Source: https://docs.patchline.ai/get-started/pricing Five tiers from Free to Enterprise. Storefront platform fee is 0% on every paid tier. Every paid tier includes a 30-day free trial. AI credits are pooled monthly and used per AI action. Patchline has **5 tiers** — Free, Starter, Pro, Scale, Enterprise. Every paid tier includes a **30-day free trial**. Annual plans get **2 months free** (roughly 17% discount). Stripe handles billing. The live, always-current price page is at **[patchline.ai/pricing](https://patchline.ai/pricing)** — start there if you're about to sign up. This page explains how the tiers map to features and how AI credits work. ## At a glance | Plan | Monthly | Yearly | Track uploads | Catalog imports | AI credits / month | Connected artists | Storage | | -------------- | ------- | -------- | -------------- | --------------- | ------------------ | ----------------- | --------- | | **Free** | \$0 | \$0 | 3 lifetime | 10 lifetime | 100 | 1 | 1 GB | | **Starter** | \$9.99 | \$99 | 25 lifetime | 100 lifetime | 1,000 | 1 | 10 GB | | **Pro** | \$29 | \$290 | 200 lifetime | 500 lifetime | 5,000 | 5 | 100 GB | | **Scale** | \$99 | \$990 | 1,000 lifetime | Unlimited | 20,000 | 20 | 500 GB | | **Enterprise** | \$249+ | \$2,490+ | Unlimited | Unlimited | Unlimited | Unlimited | Unlimited | **Music storefront platform fee:** | Plan | Platform fee on music sales | | ---------------------------------- | --------------------------- | | Free | 10% | | Starter / Pro / Scale / Enterprise | **0%** | Stripe payment processing (typically 2.9% + \$0.30 per transaction) applies on all tiers, separate from Patchline's platform fee. ## Plan details ### Free **\$0 forever.** Good for evaluation, side projects, or curious artists. * 3 lifetime track uploads * 10 lifetime catalog imports (e.g., one EP via URL counts as several) * 100 AI credits per month * 1 GB storage * Aria agent chat (web + Telegram) * AI sonic analysis (5 credits/track) * Basic release planning * Music store with **10% platform fee** * 1 connected artist profile [Sign up free →](https://patchline.ai/signup) ### Starter **$9.99/mo or $99/yr** (\$8.25/mo equivalent). 30-day free trial. The entry tier for an artist running their own career. Everything in Free, plus: * **25 lifetime track uploads** (8× Free) * **100 lifetime catalog imports** (10× Free) * **1,000 AI credits / month** (10× Free) * **10 GB storage** * AI Image Generation (5 credits/image) * AI Campaign Planner (10 credits/plan) * Your Artist Profile & EPK * Release & marketing planning * Similar artist discovery (2 credits/search) * **Music Store — 0% platform fee** * Secure file exchange + version control Best for: solo artists, bedroom producers, anyone who's released a single or two. ### Pro **$29/mo or $290/yr.** 30-day free trial. 🔥 **Highlighted tier.** Everything in Starter, plus: * **200 lifetime track uploads** * **500 lifetime catalog imports** * **5,000 AI credits / month** * **100 GB storage** * **5 connected artist profiles** (manage multiple artists) * AI Video Generation (20 credits/video) * **Playlist Targeting** (find\_playlists ranked + inspect\_playlist) * **Artist Intelligence Profiles** (the deep view) * Scout agent (A\&R discovery) * Password-protected sharing * 3 team seats Best for: DIY labels, artist managers running 2–5 artists, producers with a small roster. ### Scale **$99/mo or $990/yr.** 30-day free trial. Everything in Pro, plus: * **1,000 lifetime track uploads** * **Unlimited catalog imports** * **20,000 AI credits / month** * **500 GB storage** * **20 connected artist profiles** * Similar Track Discovery * Release Management * **Demo Submission Portal** (public form for unsigned artists to submit) * Fan agent (audience-focused) * Marketplace agent * Metadata agent (auto-tag entire catalog) * 10 team seats Best for: indie labels, artist management companies, mid-size rosters. ### Enterprise **$249/mo or $2,490/yr starting price.** Custom pricing for larger operations. 30-day free trial. Everything in Scale, plus: * **Unlimited everything** (uploads, imports, credits, storage, artists) * **API Access** * Advanced Document Analysis (Documents + Legal agents) * Education agent * Custom integrations * Dedicated Customer Success Manager * SLA Best for: music publishing companies, large entertainment groups, rights management companies, anyone with catalogs over \~1,000 tracks. [Contact sales →](https://patchline.ai/contact) ## How AI credits work Credits are the unit Patchline charges per AI action. They reset on the first of each calendar month for monthly plans, or on the first of each month after annual renewal. | Action | Cost | | ------------------------------------- | -------------- | | Aria chat conversation | **1 credit** | | Sonic analysis (per track) | **5 credits** | | Image generation (per image) | **5 credits** | | Video generation (per video) | **20 credits** | | AI campaign planner (per plan) | **10 credits** | | Similar artist discovery (per search) | **2 credits** | A typical Free user uses \~30 credits/month: a few Aria conversations + 1 or 2 sonic analyses. A typical Pro user uses \~500–1,500 credits/month running 5–10 artists across releases, pitches, and image generation. Credits **do not roll over** month-to-month. If you consistently exceed your plan, upgrade — it's almost always cheaper than the alternative. ## The 30-day free trial Every paid tier (Starter / Pro / Scale / Enterprise) includes 30 days free. The trial mechanics: * You enter a payment method at sign-up. **No charge until day 31.** * During the trial you get full tier limits — 1,000 AI credits on Starter, 5,000 on Pro, etc. * Cancel any time during the trial with no charge. * On day 31 the card is charged for month 1 (or year 1 if you picked annual). * After the trial ends, downgrading to Free preserves your catalog but reverts you to Free limits — uploads beyond 3 are blocked, AI credits drop to 100/mo. Stripe owns the trial lifecycle. The `subscription_status` becomes `trialing` the moment you sign up for a paid plan, then transitions to `active` on day 31. ## Annual vs monthly Annual = **2 months free** vs paying monthly: | Plan | Monthly × 12 | Annual price | Savings | | ---------- | ------------ | ------------ | ----------------- | | Starter | \$119.88 | \$99 | **\$20.88 (17%)** | | Pro | \$348 | \$290 | **\$58 (17%)** | | Scale | \$1,188 | \$990 | **\$198 (17%)** | | Enterprise | \$2,988 | \$2,490 | **\$498 (17%)** | If you're sure you'll use Patchline for a year, annual is the right call. If you're trying it out, monthly. You can switch from monthly to annual mid-cycle — Stripe prorates. ## Music storefront platform fee This is the most-asked-about pricing detail, so it gets its own section. * **Free tier:** Patchline takes a **10% platform fee** on every storefront sale (in addition to Stripe processing). * **Every paid tier:** Patchline takes **0%**. You keep 100% of revenue after Stripe processing (typically 2.9% + \$0.30 per transaction). So if you're selling music direct-to-fan and earning $50/mo from your store, **upgrading from Free to Starter ($9.99/mo) makes you money\*\* — you save the 10% (\~\$5) and gain everything else Starter includes. See [Storefront overview](/storefront/overview) for the storefront mechanics. ## Team seats | Plan | Seats | | -------------- | ------------ | | Free / Starter | 1 (just you) | | Pro | 3 | | Scale | 10 | | Enterprise | Unlimited | Seats are members of your Patchline workspace — they can sign in, see the catalog, run Aria, plan releases. Roles control what they can do. See [Workspaces & teams](/account/profile) (coming soon). ## FAQ Yes. Free is permanent, no expiration. You can use Patchline at the Free tier indefinitely. The catch: tighter limits (3 lifetime uploads, 100 AI credits/mo, 10% storefront fee). All major credit and debit cards (Visa, Mastercard, Amex, Discover) via Stripe. Apple Pay and Google Pay on supported devices. ACH for Enterprise customers only. Yes. Upgrade is immediate (prorated charge for the partial cycle). Downgrade takes effect at the next renewal. Both via Settings → Billing. Your existing tracks stay. New uploads are blocked once you exceed the Free limit (3 lifetime). You can re-upgrade any time to lift limits. Tool calls through the MCP server count against your AI credit pool. A `find_playlists` call counts the same as Aria using the same tool in chat. We don't separately meter "MCP usage" — it's one pool. Yes. Stripe handles international cards. Patchline itself is cloud-hosted on AWS in `us-east-1`, so non-US users may see slightly higher latency. Most surfaces are async, so it's not perceptible in practice. Settings → Billing → Cancel subscription. Cancellation takes effect at the end of the current billing period — you keep paid-tier access until then. ## What's next Start with Free, upgrade when ready. No card required. Live, always-current comparison table on the marketing site. Deeper dive on credit consumption per action and how to budget. Why the 0% platform fee on paid tiers matters if you sell direct. # Quickstart Source: https://docs.patchline.ai/get-started/quickstart From sign-up to your first Aria conversation grounded in real catalog data in about 10 minutes — covers the Free tier, no payment method required. 10 minutes. Free tier. No credit card. By the end you'll have a Patchline account, at least one track in your catalog, real sonic analysis run on it, and a working conversation with Aria about your own music.   works on every plan, but this guide assumes the Free tier (100 AI credits/month, 3 lifetime track uploads). ## Before you start You'll need: * An email address (Google sign-in also works). * **Either** a finished track file (MP3, WAV, or FLAC) **or** the Spotify / Apple Music / YouTube URL of a track you already released. * Optional: a Telegram account if you want to also try [Aria on Telegram](/aria/telegram) along the way. ## Step 1 — Create a free account Go to [patchline.ai](https://patchline.ai) and click **Get Started**. Use Google (one click) or email + password. Confirm your email if you chose the email path. The first page is the Aria chat hero at `/dashboard`. Don't type anything yet — Aria works better once you have a track loaded. Free tier defaults: **100 AI credits/month**, **3 lifetime track uploads**, **10 lifetime catalog imports**, **1 GB storage**. See [Pricing & plans](/get-started/pricing) for the full matrix. ## Step 2 — Add your first track You have two ways. Both work on Free. ### Option A — Import from a streaming URL (recommended if you've released) Paste a Spotify, Apple Music, or YouTube link directly into Aria or into the **Catalog** section. Patchline pulls the metadata, cover art, and sonic analysis if the track is already analyzable. ```text theme={null} https://open.spotify.com/track/4iV5W9uYEdYUVa79Axb7Rh ``` ### Option B — Upload a file Sidebar → **Catalog** → drag-and-drop your MP3 / WAV / FLAC into the upload zone. Patchline reads the file's ID3 metadata, extracts title, artist, ISRC if present, and cover art. Either way, the track now lives in your catalog at [`patchline.ai/dashboard/catalog`](https://patchline.ai/dashboard/catalog). **No track yet?** Skip this step. Aria can still answer general music-industry questions on the Free tier — just at lower fidelity than it does once it has your real data. ## Step 3 — Wait for sonic analysis Once a track is in your catalog, Patchline runs **sonic analysis** automatically. This extracts BPM, key, mood, danceability, energy, valence, and instruments. It takes 30–90 seconds depending on track length. You can watch progress in the catalog list — the track card shows a spinner that resolves into a feature panel: | Field | Example value | | ------------ | ------------- | | BPM | 124 | | Key | F minor | | Energy | 0.62 | | Valence | 0.31 | | Danceability | 0.71 | | Top genre | dreampop | See [Sonic analysis](/catalog/sonic-analysis) for the full feature list and what each one means. ## Step 4 — Chat with Aria Back to `/dashboard`. Click into the chat input. Try one of these: Aria reads your catalog, calls real tools, and returns a grounded answer. Every Free-tier conversation costs **1 AI credit**. ## What you just did In 10 minutes you: 1. ✅ Created a Patchline account. 2. ✅ Got a track into your catalog (file or URL). 3. ✅ Ran real sonic analysis on it. 4. ✅ Had a grounded conversation with Aria. That's the loop. Everything else in Patchline — release planning, pitch generation, royalty parsing, storefront setup — extends this same pattern. ## What to do next Free tier: 3 lifetime uploads + 10 catalog imports. Import an EP or album via URL to use them efficiently. Message [@AriaMusicBizBot](https://t.me/AriaMusicBizBot). Paste a Spotify link. Get a rich track card without leaving Telegram. Turn your track into a 6-week rollout. Best on Starter+ but you can preview the flow on Free. Wire your catalog into Cursor, Codex, Claude Code, or VS Code as callable tools. ## When to upgrade from Free Starter (\$9.99/mo, 30-day free trial) unlocks 25 lifetime track uploads, 100 catalog imports, 1,000 AI credits/month, and your **0% fee music storefront**. If you're past the first 10 minutes and want to actually run your release through Patchline, Starter is the upgrade. See [Pricing & plans](/get-started/pricing) for the full breakdown. ## Troubleshooting Files larger than 50 MB or longer than 10 minutes can take 2–3 minutes. If you're past that, refresh the page. If still stuck, ping [support@patchline.ai](mailto:support@patchline.ai) with the track ID. Make sure it's a `https://open.spotify.com/track/...` URL (not an artist or playlist URL). For artist/playlist URLs use Aria — it handles all link types via the `analyze_url` tool. Aria is intentionally grounded. If you ask about a track that isn't in your catalog, it will say so and offer to import. That's the right behavior — it's preferable to inventing data. Free tier resets monthly. Each Aria conversation is 1 credit; each sonic analysis is 5 credits per track; each image generation is 5 credits. Upgrade to Starter (1,000 credits/mo) or wait for the next cycle. # Welcome to Patchline Source: https://docs.patchline.ai/get-started/welcome Patchline is the AI command center for the modern music business — your catalog, artists, streaming intelligence, releases, storefront, and royalties wired into AI tools you already use. Patchline is an AI command center for the music business. You drop a track, ask a question, or paste a streaming link — and a multi-agent system reads your catalog, queries streaming data, drafts a pitch, plans a release, parses a royalty PDF, or generates the artwork brief. Same product, many front doors: a web dashboard, Telegram, Claude, Cursor, VS Code, Codex. ## Who Patchline is for Solo artists and bedroom producers running the business between sessions. Free tier + Starter (\$9.99/mo) cover the work. Small teams managing 5–20 artists. Pro ($29/mo) and Scale ($99/mo) add roster intelligence, A\&R scout, and team seats. Enterprise plans for large catalogs, custom integrations, dedicated success management. Built for teams that need API access and high-volume processing. Patchline ships first-class agent surfaces: 18-tool MCP server, Claude plugin, AGENTS.md, llms.txt, JSON-LD on every page. If you're an AI copilot, [start here](/for-agents/mcp-overview). ## What you can do Turn a track into a 6-week rollout with milestones, launch windows, DSP pitches, and a smart link. BPM, key, mood, danceability, energy, instruments — every track in your catalog, automatically. Rank Spotify playlists by sonic fit plus curator responsiveness. Inspect a playlist's history before you pitch. Sell direct to fans with **0% platform fees** on paid tiers. Stripe payouts, smart links, fan stats. Upload a Distrokid / Tunecore / label PDF. Get totals, anomalies, and a forecast in under a minute. A\&R scout finds similar artists, collaborators, and rising acts in your genre using Soundcharts data. ## The fastest path through this site Read the **[Quickstart](/get-started/quickstart)** — 10 minutes from sign-up to first Aria conversation grounded in your real data. Skim the **[Pricing & plans](/get-started/pricing)** page and the **[Aria overview](/aria/overview)**. The Aria page shows what the product actually does in one conversation. Jump straight to **[MCP overview](/for-agents/mcp-overview)** for the tool surface, or **[AGENTS.md](https://docs.patchline.ai/AGENTS.md)** for the rules of engagement. Use the search bar (top of every page) or open the **[FAQ](/reference/faq)**. ## What Patchline is not Setting expectations matters. Patchline is **not**: * **A distributor.** Patchline doesn't ship your music to Spotify, Apple, Tidal, etc. You distribute through Distrokid, Tunecore, CD Baby, or your label. Patchline imports the result and runs intelligence on it. * **A DAW.** No multitrack editor. Patchline reads finished audio and helps you market, plan, and analyze it. * **A replacement for your manager.** Aria handles the busywork — spreadsheets, pitch drafting, data lookup, calendar coordination. The strategy decisions are still yours. * **A general-purpose chatbot.** Aria is grounded in your music data and the music industry. Ask it about your catalog, get a grounded answer. Ask it about quantum physics, it'll politely redirect. ## How Patchline grounds AI answers Generic AI hallucinates ISRCs, invents stream counts, fabricates curator names. Patchline's whole architecture is built to stop that: * **Your catalog is the source of truth.** Aria reads it directly. If it doesn't have data, it says "I don't have that" instead of guessing. * **Streaming numbers come from real APIs** (Soundcharts, Spotify Web API, Apple), not training data. * **Sonic analysis is real audio analysis** — Cynite + Patchline's own RIP pipeline — not LLM-vibes-based-on-the-title. * **Royalty parsing reads the PDF you uploaded**, line by line. You can verify any number Aria gives you. That's the design. ## Where Patchline lives The full surface. `patchline.ai` → sign up → dashboard. Free to start. `@AriaMusicBizBot`. Paste a Spotify link, get a track card. No app install. Official Patchline plugin for Claude Desktop and Claude Code. MCP server. Your catalog as tools your AI editor can call. ## Help & support * **Search** these docs — every page has a `.md` twin at `.md` if you prefer raw markdown. * **Email** [support@patchline.ai](mailto:support@patchline.ai) for account and billing questions. * **[Status & uptime](https://status.patchline.ai)** for live system health. * **[GitHub Discussions](https://github.com/Patchline-AI/aria/discussions)** for plugin and MCP issues. # Google Calendar integration Source: https://docs.patchline.ai/integrations/calendar Connect Google Calendar so Aria can schedule release milestones, fan emails, tour dates, and content drops on your calendar. Aria respects existing events when proposing new ones. Connect Google Calendar so Aria can schedule release campaigns, content drops, fan emails, and tour dates directly on your calendar. Release plans auto-populate calendar events when committed as project anchors.   Free to connect. ## What Aria can do | Action | Default behavior | | --------------------------------------- | --------------------------------------- | | Read your calendar | Yes | | Propose new events around existing ones | Yes | | Add a single event | Asks for confirmation | | Add a release-plan task bundle | Asks for batch confirmation | | Move / reschedule events | Asks for confirmation per move | | Delete events | Asks for confirmation, with undo window | | Read attendee responses | Yes (for meeting scheduling) | ## Connecting Or use the direct OAuth callback: ```text theme={null} https://patchline.ai/api/auth/connect/google ``` Patchline requests: * `calendar` (read + write) * `userinfo.email` * `userinfo.profile` Connection shows in Connected Platforms. ## Examples ### Schedule a release rollout ```text theme={null} Aria: I'll add 28 events from your release plan to your calendar. A few collisions: • June 12 — proposed "Submit to Spotify editorial" conflicts with your "Studio session w/ Mira" 2-4pm. Move to morning? • July 1 — proposed "Pre-save go-live" overlaps with "Family dinner" at 6pm. Move to noon? Approve all, fix collisions, or cancel? ``` ### Add a one-off event ### Check before scheduling ```text theme={null} Aria: Free slots this week (1h+): • Wed 2-4pm • Thu 11am-12pm • Fri 9-11am, 3-5pm Want me to send a meeting proposal to Mira's manager with these times? ``` ## Privacy * OAuth tokens stored encrypted, per-user. * Calendar events are read only when you ask. * New events are created only with your explicit confirmation. ## Pricing | Action | Credit cost | | --------------------- | -------------------------------------------- | | Read calendar | 0 (cached for the conversation) | | Add a single event | 1 (counted as Aria chat) | | Bulk-add release plan | 1 per Aria interaction (the events are free) | | Move / delete | 1 per Aria interaction | ## Related pages * [Integrations overview](/integrations/overview) * [Gmail](/integrations/gmail) — pair with Calendar for full coordination * [Release planner](/releases/release-planner) — auto-populates calendar events ## FAQ No. Aria proposes; you approve. Batch operations (like a 28-event release plan) get one batch-approval prompt, not 28 individual prompts. Google Calendar only in v1. Outlook is on the roadmap. Apple Calendar via CalDAV is not currently planned. Your primary calendar by default. Multi-calendar support (assign release-plan events to a specific calendar) is on the roadmap. # Gmail integration Source: https://docs.patchline.ai/integrations/gmail Connect your Gmail to let Aria read, draft, and (with your approval) send emails. Aria triages curator emails, drafts follow-ups, summarizes inbox threads about your releases. Connect Gmail so Aria can read your inbox, draft replies, summarize threads, and (with explicit approval per send) send messages. Backed by the Gmail specialist agent (`gmail-action-handler.py` Lambda + Bedrock agent `PatchlineEmailAgent`).   Free to connect. Drafts are 1 credit; sends require your explicit approval per message. ## What Aria can do with Gmail | Action | Default behavior | | ------------------------------ | --------------------------------------------------------------------------------------- | | Read recent emails | Yes, when you ask | | Search inbox | Yes ("emails about Mira's release", "from a curator") | | Summarize a thread | Yes (1 credit per chat) | | Draft a reply | Yes (1 credit per draft) | | Send a message | **Requires explicit approval per send** | | Read attachments (PDFs, audio) | Yes — feeds into [royalty](/intelligence/royalty) or [catalog](/catalog/upload) parsing | | Triage unread inbox | Yes — Aria categorizes (fan / curator / business / spam) | ## Connecting UI is being finalized — for now, contact support to enable Gmail in your account, or use the OAuth callback URL directly: ```text theme={null} https://patchline.ai/api/auth/connect/gmail ``` Patchline requests: * `gmail.readonly` (read your inbox) * `gmail.send` (only used when you explicitly approve a send) Connection appears in Settings → Connected Platforms once OAuth completes. ## Examples ### Triage your inbox ```text theme={null} Aria: 12 unread emails. Triaged: CURATOR (3) — respond today • @lush_sounds_oslo confirming track receipt • SubmitHub status update for "Sleeper" • Tessa's manager re: feature on Mira's next BUSINESS (2) • Distrokid: royalty statement for Q2 ready • Stripe: payout completed ($212.40) FAN (5) • 3 download confirmations, 1 question about lossless availability, 1 thank-you note SPAM (2) Want me to draft replies to the curator emails? ``` ### Draft a follow-up ```text theme={null} Aria: Drafted 3 follow-ups (one per curator, personalized to their last add). Review: Subject: Quick check-in — Mira "Sleeper" To: anders@lushsounds.com Hi Anders, Following up on my note from 2 weeks ago about Mira's single "Sleeper." I saw you added Cleo Bell's "Distant" recently — same sonic territory. Sleeper is out and getting traction (now at 4,200 streams in week 1). If you have a moment, listen here: https://... No pressure if it's not a fit. — Mira [Send] [Edit] [Skip] ``` Each draft has explicit Send / Edit / Skip controls. Aria never sends without your action. ### Pull data out of an email ```text theme={null} Aria: Parsed the attached PDF. Q2 royalty statement, $3,124.07 across 23 tracks. Want the full breakdown? (Same flow as [Royalty analysis](/intelligence/royalty)) ``` ## Privacy * Patchline stores OAuth tokens encrypted at rest (per-user). * Email content is read only when you ask — no background scanning. * Drafted replies are stored only until sent (or until you discard). * Patchline does not use your email content for model training. ## Pricing | Action | Credit cost | | --------------------------- | ----------------------------------------------------------------------------------- | | Read / summarize email | 1 (counted as Aria chat) | | Triage inbox | 1 | | Draft a reply | 1 per draft | | Send (with approval) | 0 (sending itself is free, the draft was the credit) | | Read attachment (PDF, etc.) | Per the attachment type — royalty PDF = 5 credits, audio = 5 credits sonic analysis | ## Related pages * [Integrations overview](/integrations/overview) * [Calendar](/integrations/calendar) — pair with Gmail for scheduling * [Aria overview](/aria/overview) — Aria as a whole * [Royalty analysis](/intelligence/royalty) — Aria triggers this from Gmail attachments ## FAQ No. Drafts are stored; sends require explicit Send action per message. We never auto-send. Not in v1. Outlook / Microsoft 365 is on the roadmap. Workarounds: forward relevant emails to a Gmail address you connect. Pro+ tiers (team seats) — each team member connects their own Gmail. Aria scopes inbox queries per-member. Use Gmail filters / labels — Aria respects them. Label something `Aria-Ignore` and triage skips it. # Integrations Source: https://docs.patchline.ai/integrations/overview Patchline connects to your existing tools — Gmail, Google Calendar, Stripe, Spotify, YouTube, Telegram. Some are live today, some coming soon. Composio powers the long-tail of third-party tool access. Patchline integrates with the tools you already use. Some are first-party OAuth connections (Gmail, Calendar, Stripe). Others come through **Composio** — a third-party tool orchestrator that gives Aria access to hundreds of services via a single layer.   Integrations are free to connect. Underlying actions consume AI credits. ## Status matrix | Integration | Status | Read | Write | Notes | | ---------------------------------------------------- | --------------------- | ---- | ---------- | ------------------------------------------------- | | [**Gmail**](/integrations/gmail) | ✅ Live | ✓ | ✓ (drafts) | Aria reads + drafts email; sending optional | | [**Google Calendar**](/integrations/calendar) | ✅ Live | ✓ | ✓ | Schedule releases, events, tour dates | | **Stripe** (Connect + Billing) | ✅ Live | ✓ | ✓ | Powers storefront + subscription billing | | **Telegram** | ✅ Live | ✓ | ✓ | @AriaMusicBizBot is the user-facing surface | | **Spotify** (public API) | ✅ Live (read-only) | ✓ | — | URL imports, playlist intel | | **Apple Music** (public API) | ✅ Live (read-only) | ✓ | — | URL imports | | **YouTube** (public API) | ✅ Live (read-only) | ✓ | — | URL imports, channel intel | | **Soundcharts** | ⚪ Backend only | — | — | Powers artist intelligence; not user-installable | | **Cynite** | ⚪ Backend only | — | — | Powers sonic analysis; not user-installable | | **Discogs / Genius** | ⚪ Backend only | — | — | Enrichment during catalog/artist import | | **Google Drive** | 🔵 Coming soon | — | — | OAuth scaffold exists; UI not yet live | | **Spotify for Artists (OAuth)** | 🔵 Coming soon | — | — | Read-only public API works today; OAuth in flight | | **Instagram** | 🔵 Coming soon | — | — | OAuth scaffold exists; UI not yet live | | **YouTube (OAuth, writes)** | 🔵 Coming soon | — | — | Public API works today; channel writes in flight | | **SoundCloud (OAuth)** | 🔵 Coming soon | — | — | | | **TikTok (OAuth)** | 🔵 Coming soon | — | — | | | **Twitter / X (OAuth)** | 🔵 Coming soon | — | — | | | **Composio toolkits** (ClickUp, Notion, Slack, etc.) | ⚪ Operator-only in v1 | — | — | Backend infrastructure; per-user proxy planned | ## How OAuth connections work For first-party OAuth integrations (Gmail, Calendar): Some platforms surfaces are temporarily hidden in the dashboard while we finalize the UI — connections still work via OAuth callback. Browser redirects to the platform's OAuth screen. Approve the requested scopes. Browser returns to Patchline. Aria automatically picks up the connection. Ask Aria to do something — *"draft a follow-up to that curator email"* — and it uses the connection. Disconnect: Settings → **Connected Platforms** → revoke. Patchline deletes the access token within seconds. ## Composio — what it is [Composio](https://composio.dev) is a third-party tool orchestrator that exposes hundreds of SaaS tools (ClickUp, Notion, Slack, Discord, Instagram, etc.) through a single MCP-like layer. Patchline integrates Composio so Aria can act on those tools without us building per-platform OAuth. In v1, Composio is **operator-only** — only Patchline staff configure Composio toolkits manually. Per-user Composio proxy is planned but not shipped. ## Per-integration pricing Most integrations are free to connect. Costs come from underlying actions: | Action | Cost | | -------------------------- | -------------------------------------------------------------- | | Gmail drafted message | 1 credit (counted as Aria chat) | | Calendar event creation | 1 credit | | Stripe-side actions | Stripe's pricing, see [checkout](/storefront/checkout-payouts) | | Telegram message | 1 credit | | Spotify / Apple URL import | 0 (counts against catalog imports cap) | ## Related pages * [Gmail](/integrations/gmail) — full setup * [Google Calendar](/integrations/calendar) — full setup * [Storefront overview](/storefront/overview) — Stripe Connect * [Aria on Telegram](/aria/telegram) — Telegram bot # Royalty statement analysis Source: https://docs.patchline.ai/intelligence/royalty Upload a Distrokid, Tunecore, label, or publisher royalty PDF. Aria parses every line, computes totals, identifies anomalies (missing platforms, unusual deltas), and surfaces opportunities. Royalty statements are PDFs no one wants to read. Patchline's royalty analysis parses them in seconds, computes totals, finds anomalies (missing platforms, unexpected drops, payment-window cutoffs), and forecasts the next period.   Pro+ includes royalty analysis. 5 credits per statement. ## What it does Upload a PDF → Aria returns: * **Total earnings** across all tracks * **Per-track breakdown** with platform mix * **Per-platform totals** (Spotify, Apple, YouTube, Tidal, Amazon, etc.) * **Anomalies** flagged automatically * **Period-over-period comparison** if prior statements exist * **Revenue forecast** for next period ## Supported formats | Source | Status | | ----------------------------------------------------- | ----------------------------------------- | | **Distrokid** | ✓ | | **Tunecore** | ✓ | | **CD Baby** | ✓ | | **Amuse** | ✓ | | **United Masters** | ✓ | | **Label statements** (custom format) | ✓ — parsing improves with each one we see | | **Publishing statements** (ASCAP, BMI, SoundExchange) | ✓ | | **DDEX DSR** | ✓ | If your statement format isn't supported well, send it to [support@patchline.ai](mailto:support@patchline.ai) — every new format makes the parser smarter. ## How to upload ### Web Sidebar → **Royalties** → drag-and-drop PDF → wait 30–60s for parse. ### Via Aria ## What anomaly detection catches Common anomalies the royalty parser flags: | Anomaly | What it means | Example | | ----------------------------------------------- | ---------------------------------------- | -------------------------------------------------------------- | | **Zero earnings on a platform with streams** | Payment-window cutoff or platform glitch | "Late Bloom earned \$0 on Apple despite 4,200 streams" | | **Sudden drop on a previously-strong platform** | Possible removal or playlist drop | "Sleeper dropped from $124 to $12 on Spotify mo/mo" | | **Track in catalog missing from statement** | Distribution gap | "Mira - November shows on Spotify but isn't on this statement" | | **Suspiciously consistent earnings** | Possible stream manipulation flag | "Same \$43.21 every month — worth checking" | | **Currency conversion losses** | Multiple-currency statements | "USD-equivalent dropped 3% from FX, not from performance" | ## Example output ```text theme={null} You: [uploads Distrokid Q2 2026 PDF] Aria: Parsed ✓ (12 sec) Total: $3,124.07 across 23 tracks Period: April-June 2026 Compared to Q1 2026: +18% ($2,647 → $3,124) PER-TRACK TOP 5 1. Late Bloom $1,082 (Spotify $890, Apple $124, YouTube $68) 2. Sleeper $612 (Spotify $510, Apple $74, Amazon $28) 3. Long Way $419 (steady across platforms) 4. Velvet $310 (notable: TikTok $52 — first TikTok earnings) 5. Run Hot $287 PER-PLATFORM Spotify $2,124 (68%) Apple Music $510 (16%) YouTube $284 (9%) Amazon $112 (4%) TikTok $52 (2%) Other $42 (1%) ⚠ ANOMALIES (2) 1. "Late Bloom" earned $0 on Apple Music despite 4,200 streams last quarter. Likely a payment-window cutoff — expect it next statement. 2. "Mira - November" shows on Spotify (1,200 streams) but is missing from this statement. Possible distribution gap — want me to import it to your catalog? Q3 FORECAST: $3,400 ± $200 Based on current run-rate + the TikTok earnings line, expect slight growth. ``` ## Privacy * PDFs are stored encrypted in S3, retention 5 years for tax purposes. * Only you have access — no shared dashboards expose royalty data. * The royalty processor (`royalty-processor.py`) runs in-region. ## Pricing | Action | Credit cost | | ----------------------- | ----------- | | Parse a statement (PDF) | 5 | | Period comparison query | 1 | | Forecast query | 1 | | Anomaly re-scan | 1 | ## Related pages * [Streaming insights](/intelligence/streaming-insights) — the stream-side counterpart * [Aria's research mode](/aria/research-mode) — surfaces royalty anomalies in the weekly synthesis * [Plans & credits](/account/plans-credits) — credit cost ## FAQ No. Royalties come from your distributor (Distrokid, Tunecore, etc.) or label. Patchline reads the statements they send you and finds insights — we don't sit in the money flow. Email it (with permission) to [support@patchline.ai](mailto:support@patchline.ai). Each new format improves the parser. Most major distributors and publishers are already supported. Yes — CSV per statement, or aggregated cross-statement (Scale+). Typically within ±10% if you have 3+ months of prior statements. Less reliable for new releases or seasonal genres. # Streaming insights Source: https://docs.patchline.ai/intelligence/streaming-insights Aggregate streaming metrics across your catalog and roster — monthly listeners, top tracks, playlist features, momentum, and per-artist comparisons. Powered by Soundcharts. Streaming insights aggregates everything that's happening on the streaming side — monthly listeners, top tracks, playlist features, momentum — across your catalog and roster. The Metrics agent (`metrics-action-handler.py`) surfaces it.   Pro+ for full streaming insights. Free/Starter see basic per-artist numbers in the [intelligence profile](/artists/intelligence-profile). ## What you can ask The most common queries: ## What's tracked | Metric | Per artist | Per track | Per roster | | ----------------------------------------------------------- | ---------- | --------- | ----------- | | Monthly listeners | ✓ | — | ✓ aggregate | | Stream counts (30d / 7d / yesterday) | ✓ | ✓ | ✓ | | Top tracks | ✓ | — | ✓ ranked | | Playlist features | ✓ | ✓ | ✓ | | Top markets | ✓ | ✓ | ✓ | | Social audience | ✓ | — | ✓ | | Momentum (week-over-week, month-over-month) | ✓ | ✓ | ✓ | | Streaming source (editorial / algorithmic / user playlists) | — | ✓ | — | ## Where to find it | Surface | Path | | ---------- | ------------------------------------------------------- | | Web | Sidebar → **Insights** at `/dashboard/insights` | | Per artist | Sidebar → **Artists** → click artist → **Insights** tab | | Via Aria | "Summarize my streaming..." / "Compare..." | ## Example: monthly roster recap ```text theme={null} You: Summarize my roster's streaming for May 2026. Aria: ROSTER MAY 2026 Total streams (30d): 142,400 across 5 artists Monthly listeners: 58,200 (combined unique) Growth vs April: +12.3% PER-ARTIST Mira 42,100 streams (top: "Late Bloom" 18,300) Tessa 38,800 streams (top: "Long Way" 16,200) Cleo Bell 28,400 streams (top: "Distant" 11,900) Run Hot 19,200 streams (top: "Run Hot" 8,100) Velvet Bird 13,900 streams (top: "Velvet" 7,400) TOP PLAYLISTS DRIVING STREAMS Lush Sounds 12,400 streams (4 roster artists featured) Bedroom Vibes 8,900 streams (2 roster artists) Future Female Sounds 6,200 streams (3 roster artists) GROWTH WINNERS (mo/mo) Mira +18% (driven by "Late Bloom" playlist adds) Tessa +14% (TikTok lift) Cleo Bell +9% Run Hot +1% Velvet Bird -3% (no new releases, expected drop) NOTABLE Velvet Bird's first TikTok earnings landed ($52 in royalties) suggests TikTok is starting to convert — worth a TikTok ad push. ``` ## Refresh cadence * **Soundcharts data**: refreshes \~daily. * **Aria's daily synthesizer**: runs every morning, surfaces deltas. * **On-demand refresh**: any time, 1 credit. ## Pricing | Action | Credit cost | | ------------------------------ | ----------- | | Insights query (cached) | 0 | | Insights query (force refresh) | 1 | | Cross-artist comparison | 1 | | Cross-period comparison | 1 | ## Related pages * [Intelligence profile](/artists/intelligence-profile) — per-artist streaming * [Audience](/artists/audience) — demographic breakdown * [Royalty](/intelligence/royalty) — the \$ side * [Aria's research mode](/aria/research-mode) — automatic synthesis ## FAQ Soundcharts is the primary source. Spotify Web API supplements for a few specific signals. Apple Music for Artists data isn't accessible via API — those numbers come through Soundcharts' estimate. Monthly listeners are exact (Spotify-supplied via Soundcharts). Daily stream counts are estimates. Growth percentages are reliable for established artists, noisier for very-new artists. YouTube Music numbers come through Soundcharts. TikTok music discovery data is partial — TikTok doesn't expose track-level play counts publicly. # FAQ Source: https://docs.patchline.ai/reference/faq Frequently asked questions about Patchline — across pricing, Aria, catalog, releases, integrations, MCP, security, and roadmap. Per-feature FAQs live on each feature page. Cross-feature questions live here. Per-feature FAQs live on each feature page (e.g., catalog questions at [Catalog import FAQ](/catalog/import#faq)). ## About Patchline Patchline is an AI command center for the music business. You talk to Aria (the assistant) and Aria reads your catalog, queries streaming data, drafts pitches, plans releases, parses royalty PDFs, runs your storefront. Web app + Telegram + Claude plugin + MCP for AI editors. Independent artists, DIY labels, managers, A\&R, music publishers. Plus any AI agent (Claude, Cursor, Codex, Perplexity) that wants real music industry tools instead of generic web search. No. Patchline doesn't ship music to Spotify, Apple, etc. You distribute through Distrokid, Tunecore, CD Baby, or your label. Patchline imports the result and runs intelligence on it. Generic AI doesn't have your catalog, your roster, your royalty statements, your audience data. Patchline is grounded in your real music business — every answer references actual ISRCs, actual streaming numbers, actual curator history. Generic AI hallucinates these details; Patchline doesn't. ## Pricing & plans Yes. 100 AI credits/month, 3 lifetime track uploads, 10 lifetime catalog imports, 1 GB storage. Permanent — no expiration. Starter at $9.99/month ($99/year). 30-day free trial. Unlocks 1,000 AI credits/month + 0% storefront platform fee. Yes — annual = 2 months free (\~17% discount vs monthly). Yes. Upgrade is immediate (prorated). Downgrade takes effect at next billing cycle. ## Aria Aria is a multi-agent system on AWS Bedrock. Most specialist agents run on Claude Sonnet 4 (`anthropic.claude-sonnet-4-20250514-v1:0`). Legal and Documents specialists use Claude 3.7 Sonnet. No. Patchline does not use your catalog, royalty statements, or chat history to train models. Aria drafts. You approve sends. No auto-send. Direct social posting is on the roadmap. Aria is grounded — it doesn't invent. If a track isn't in your catalog or an artist isn't in your roster, Aria offers to import rather than guess. ## Catalog & releases No. [Import via URL](/catalog/import) (Spotify, Apple, YouTube) is cheaper and easier. Upload is for unreleased work or when you want your master in Patchline. Limited in v1. Upload stems as separate tracks with naming convention `-stem-.wav`. Stem separation tooling is in beta. The persistent state for a release campaign — track list, tasks, dates, concurrent-safe storage. Every release plan you commit becomes a project anchor. See [Project anchors](/releases/project-anchors). ## Storefront Yes on every paid tier (Starter / Pro / Scale / Enterprise). Free tier is 10%. Stripe processing (\~2.9% + \$0.30/txn) applies on every tier separately. Stripe Connect — money goes from fan's card to your Stripe account directly. Patchline never holds your funds. Digital products only in v1. Physical merch / vinyl / CDs are on the roadmap. ## MCP & integrations Model Context Protocol. Open standard for giving AI tools access to external services as callable functions. Patchline ships two MCP servers — [overview here](/for-agents/mcp-overview). Cursor, Codex, Claude Desktop, Claude Code, VS Code, plus any MCP-compatible client. ChatGPT support is pending OpenAI's MCP rollout. Tools that act on your data (catalog, roster, releases) need to know who you are. OAuth 2.0 with PKCE — your credentials never touch the AI client. See [MCP overview](/for-agents/mcp-overview). ## Security & privacy AWS `us-east-1`. DynamoDB for metadata, S3 for audio/PDFs (encrypted * versioned), OpenSearch Serverless for catalog search. No. Hard rule. Includes audio (no Cynite-supervised training per the 2026-05-16 audit), catalog metadata, royalty PDFs, chat history. Patchline implements SOC 2 Type II-aligned controls. Formal certification status: contact [support@patchline.ai](mailto:support@patchline.ai) for current attestation status. Yes — email [support@patchline.ai](mailto:support@patchline.ai) with deletion request. Most data deletes within 7 days. Stripe records and royalty PDFs are retained for legal/tax purposes. ## Support & roadmap [support@patchline.ai](mailto:support@patchline.ai). We aim for 24-hour response on weekdays. [github.com/Patchline-AI/aria/issues](https://github.com/Patchline-AI/aria/issues) for plugin / MCP issues. Email for everything else. See [patchline.ai/changelog](https://patchline.ai/changelog) for shipped features. Major items in flight: Aria iOS app, Outlook integration, physical merch on storefront, REST API beyond Enterprise. GitHub Discussions or email. We read every request — though we can't promise every one ships. # Glossary Source: https://docs.patchline.ai/reference/glossary Music industry + Patchline-specific terminology. ISRC, ISWC, DSP, MCP, Bedrock, sonic features, smart link, project anchor, fan graph, and the rest. Music industry + Patchline-specific terminology. Organized alphabetically. ## A **AGENTS.md** — A markdown file with rules of engagement for AI agents using a product. Patchline ships two: one at [www.patchline.ai/AGENTS.md](https://www.patchline.ai/AGENTS.md) (for the product MCP) and one at [docs.patchline.ai/AGENTS.md](https://docs.patchline.ai/AGENTS.md) (for the docs). See [AGENTS.md explained](/for-agents/agents-md-explained). **AOSS** — Amazon OpenSearch Serverless. The search engine powering Patchline's [catalog search](/catalog/search). **AI credit** — Patchline's unit of metered AI consumption. See [Plans & credits](/account/plans-credits). **ASCAP** — American Society of Composers, Authors and Publishers. US performance rights organization (PRO). ## B **Bedrock** — AWS's hosted LLM service. Patchline's Aria agents run on Bedrock with Claude Sonnet 4. **BMI** — Broadcast Music, Inc. US PRO (peer to ASCAP). **BPM** — Beats per minute. Tempo measure from [sonic analysis](/catalog/sonic-analysis). ## C **Catalog** — The set of tracks (yours + your roster's) Patchline holds metadata + intelligence for. See [Catalog](/catalog/import). **Composio** — Third-party tool orchestrator that exposes hundreds of SaaS tools via a single layer. Patchline integrates Composio server-side; operator-only in v1. **Cynite** — Specialist audio-analysis SaaS that powers part of Patchline's [sonic analysis](/catalog/sonic-analysis). **Curator** — A person who runs a Spotify (or other DSP) playlist. Patchline ranks curators by "responsiveness score" — see [Playlist matching](/releases/playlist-matching). ## D **DDEX** — Digital Data Exchange. Music industry standards body. DDEX DSR (Digital Sales Report) is one royalty statement format Patchline [parses](/intelligence/royalty). **DSP** — Digital Service Provider. Streaming platform (Spotify, Apple Music, YouTube Music, etc.). ## E **EPK** — Electronic Press Kit. Bio + photos + press + streaming proof points, exportable from the [artist intelligence profile](/artists/intelligence-profile). ## F **Fan graph** — Patchline's cross-roster + storefront audience network view. Surfaces overlap between artists, cluster identification, bridge artists. See [Audience](/artists/audience). ## I **ISRC** — International Standard Recording Code. 12-character ID that uniquely identifies a recording. Patchline [deduplicates](/catalog/import) by ISRC. **ISWC** — International Standard Musical Work Code. The ID for a musical work (composition), not a specific recording. ## J **JSON-LD** — JavaScript Object Notation for Linked Data. Structured data format Patchline ships on every page so search engines and AI extractors understand page content. See [AGENTS.md explained](/for-agents/agents-md-explained). ## L **llms.txt** — A markdown file convention from [llmstxt.org](https://llmstxt.org) that serves as a site index for AI crawlers. Patchline ships two: marketing + docs. ## M **MCP** — Model Context Protocol. Open standard from Anthropic for giving AI tools access to external services as callable functions. Patchline ships [two MCP servers](/for-agents/mcp-overview). **Mintlify** — The platform hosting these docs. Provides MDX rendering, search, `llms.txt`, `.md` twins, and the hosted docs MCP server. ## O **OAuth 2.0** — Authorization framework Patchline's MCP uses for user-scoped access. ## P **PKCE** — Proof Key for Code Exchange. OAuth 2.0 extension Patchline uses to make the MCP OAuth flow safe for AI clients. **Project anchor** — Patchline's persistent state for a release campaign — track list, status, tasks, dates. Concurrent-write-safe. See [Project anchors](/releases/project-anchors). **PRO** — Performance Rights Organization (ASCAP, BMI, SoundExchange, PRS, etc.). Collects performance royalties. ## R **RIP** — Patchline's own audio-analysis pipeline. Runs alongside Cynite. See [Sonic analysis](/catalog/sonic-analysis). ## S **S4A** — Spotify for Artists. Spotify's artist-facing dashboard. **Smart link** — A routing URL that takes fans to their preferred streaming platform. Patchline [creates](/storefront/smart-links) these via the `create_smart_link` MCP tool. **Sonic features** — The audio characteristics (BPM, key, mood, energy, valence, etc.) that Patchline extracts via [sonic analysis](/catalog/sonic-analysis). **Soundcharts** — Music intelligence data provider. Powers Patchline's artist intelligence, audience, royalty trend, and scout features. **Storefront** — A branded artist page on Patchline at `patchline.ai/store/` where fans buy music direct. See [Storefront](/storefront/overview). ## T **Tier** — Patchline's plan level: Free / Starter / Pro / Scale / Enterprise. See [Pricing & plans](/get-started/pricing). **TikTok**-driven — Audience growth specifically attributable to TikTok. Surfaces in [streaming insights](/intelligence/streaming-insights). ## V **Valence** — Sonic-analysis measure of musical positivity (0 = sad, 1 = happy / cheerful). ## W **Workspace** — A Patchline account container with team seats. Pro+ tiers have multi-seat workspaces. # AI campaign planner Source: https://docs.patchline.ai/releases/campaign-planner Generate a marketing campaign for a release from intake (artist, audience, budget) — Aria assembles channels, content calendar, ad targeting, fan messaging into a deliverable plan you can execute or hand to a marketing team. The AI campaign planner generates the **marketing-layer** of a release: which channels, what content calendar, which ad targeting, what fan messaging, what budget allocation. It's the marketing-strategy counterpart to the [release planner's](/releases/release-planner) operational rollout.   Free shows the layout (no AI generation). Starter+ generates the plan. 10 credits per plan. ## What's in a campaign plan | Section | What it contains | | --------------------- | -------------------------------------------------------------------------------------------------------------- | | **Audience profile** | Who you're marketing to — drawn from existing fan data, similar artists, audience demographics | | **Channel mix** | Spotify, TikTok, Instagram, YouTube, email, paid ads, organic — weighted by what's worked for similar releases | | **Content calendar** | Week-by-week post schedule with topic, channel, asset reference | | **Ad targeting** | If you have a budget — interest tags, lookalikes, geo | | **Fan messaging** | Email/Telegram copy for the fan list at each phase | | **Budget allocation** | Per-channel split of whatever budget you provided | | **Success metrics** | What to measure, what "good" looks like | ## When to use it * **You have a release plan and now need the marketing layer.** The release planner gives you ops; the campaign planner gives you marketing. * **You have ad money to spend and don't know where.** The campaign planner allocates a budget across channels based on signal. * **You want a deliverable to hand to a marketing person.** The output is markdown — clean enough to send. ## Quick start Campaign planner builds on top of a [release plan](/releases/release-planner). Create that first if you haven't. Aria returns a campaign plan in markdown. Edit anything that doesn't fit your audience, budget, or risk tolerance. Say "yes, commit" — the campaign becomes part of the [project anchor](/releases/project-anchors). Tasks land in the release timeline. ## Example output ```text theme={null} 🎯 Marketing campaign: Sleeper — Mira — 6 weeks — $100 budget AUDIENCE Primary: 18-29 dreampop fans, US/UK/AU, female-skewing. Lookalikes from Mira's last release: 4.2k fans, 87% match. Adjacent audiences: Tessa fans (1.1k overlap), Cleo Bell fans (640). CHANNEL MIX TikTok 40% — high virality for the sonic profile Instagram 25% — visual-first content, Reels priority Email 15% — Mira's list (1,247 subscribers, ~24% open rate) Paid ads 15% — TikTok ads to dreampop interest cluster Spotify 5% — Marquee or Showcase if budget permits later WEEKLY CONTENT CALENDAR Week -6: artwork reveal (IG + TikTok), pitch teaser to fan list Week -4: 30-sec preview clip (TikTok), curator DMs Week -2: pre-save go-live, Telegram drop, email blast Week 0: release day post (3 platforms), TikTok ad campaign starts Week +1: behind-the-scenes content, fan story repost Week +2: TikTok ad optimization, lookalike refresh Week +4: post-mortem, learnings doc AD TARGETING (TikTok $40 budget) Interest tags: dreampop, indie pop, lo-fi, bedroom pop Audience: 18-29, female-skewing, US/UK/AU Lookalike: Mira existing fans (1% lookalike) Creative: 30-sec preview video, full-bleed FAN MESSAGING Email pre-release: 1 week before — "New single dropping Friday" Email release day: "Sleeper is out — listen + share" Telegram drop: same-day, exclusive lossless link to fan-Telegram SUCCESS METRICS Streams week 1: target 8k (baseline 5k from last release) Playlist adds: target 3 (last release: 1) Email open rate: target 28% (baseline 24%) Storefront conversion: target 12 sales (baseline 7) ``` ## Prerequisites * A release plan committed as a [project anchor](/releases/project-anchors). * Optionally: a fan list (Telegram, email) for messaging. * Optionally: an ad budget — Aria can plan without budget too (organic-only). * Optionally: historical campaign data (auto-pulled if you've used Patchline for prior releases). ## Pricing | Tier | Campaign planner access | Generation cost | | ------------- | ----------------------- | --------------- | | | Layout only (no AI) | — | | | Full | 10 credits/plan | | | Full + multi-channel | 10 credits/plan | | | Full + roster-level | 10 credits/plan | | | Full + API | 10 credits/plan | ## Related pages * [Release planner](/releases/release-planner) — the operational layer * [Project anchors](/releases/project-anchors) — where the campaign lives * [Pitch kit](/releases/pitch-kit) — DSP-specific output, separate from campaign ## FAQ No. Aria plans the campaign and writes the targeting brief. You run ads through TikTok/Meta/Spotify Ad Studio directly. Patchline doesn't have ad-platform integrations yet. Aria generates organic-only campaigns — content calendar, fan messaging, curator DMs. No ad targeting section. Yes. "Regenerate with \$250 budget" or "more aggressive timeline" — costs another 10 credits per regen. Not automatically. Regenerate when you have meaningfully more data. A small audience delta doesn't change the plan much. # Pitch kit Source: https://docs.patchline.ai/releases/pitch-kit Generate compelling DSP curator pitches grounded in real track metadata, sonic analysis, and artist context. Per-curator personalization, A/B variants, tone control. A **pitch kit** is the per-track package of DSP-curator-facing copy — the message you send when submitting to editorial playlists, pitching to an independent curator, or applying for a Spotify Marquee. Aria generates these grounded in real audio features, artist history, and the specific curator's context.   Generation costs 2 credits per pitch. ## What's in a pitch kit For one track, Aria generates: | Variant | Length | Use | | ---------------------------- | ----------- | ------------------------------------------- | | **Short** | 280 chars | Twitter, DM, in-app message | | **Medium** | \~150 words | Editorial submission form, generic pitch | | **Long** | \~400 words | Cold email to curator, detailed positioning | | **Personalized per curator** | varies | References curator's recent adds + style | Plus: * **One-line hook** — for subject lines, headers * **Sonic positioning statement** — "between \[artist A] and \[artist B]" * **Three social proof points** — relevant numbers (streams, playlists, growth) * **One-paragraph artist bio** — concise, recent, accurate * **Asset references** — links to streaming, smart link, cover art ## Why it matters Generic pitches get ignored. Pitches grounded in the curator's actual recent adds plus your track's actual sonic profile get heard. Aria's pitch kit closes the gap between "I have a track" and "here's why this curator should care." ## How to generate Track must be in your catalog with sonic analysis complete. Or sidebar → **Releases** → project → **Pitch kit** tab → **Generate**. For personalized pitches: Aria fetches the curator's recent adds via [inspect\_playlist](/releases/playlist-matching) and references them. Pitch is markdown. Edit anything that doesn't sound like you. Send via your usual channel (email, DM, S4A, SubmitHub). ## Example: long-form personalized pitch ```text theme={null} Subject: Sleeper — for Lush Sounds curators Hi Anders, I saw you added Tessa's "Long Way" to Lush Sounds 11 days ago — I mention it because Mira (whose track I'm sharing) shares Tessa's mixer and tends to sit sonically adjacent to her work. Sleeper is Mira's third single this year. It's a 76 BPM F# minor dreampop ballad with high acousticness (0.78), low valence (0.21), and prominent reverb-soaked guitar. Closest sonic peers are Mazzy Star and late-period Beach House. A few proof points: • Her last release ("Late Bloom") hit 8.2k streams in week 1 and was added to "Bedroom Vibes" within 4 days of release. • Editorial adds on Mint Friday and Lush Sounds (CA) this year. • 1,247 active fan-list subscribers, 28% open rate. Sleeper releases July 15. Pre-save: patchline.ai/store/mira/sleeper. Lossless version available if you'd prefer that for the playlist. Happy to send the artwork pack or a longer write-up — just ask. — Mira ``` ## Tone control Aria can rewrite in different tones: ## Where pitches get used | Channel | How | | ---------------------------------------------- | ----------------------------------------------------------------- | | **Spotify for Artists (S4A)** | Copy the medium variant into the editorial pitch form | | **SubmitHub** | Use the long form, attach the track | | **Curator DMs (IG, Twitter, email)** | Use the personalized variant | | **Submission portals (Daily Playlists, etc.)** | Use the long form | | **Spotify Marquee / Showcase** | Use the medium + budget block (Aria can add the budget rationale) | ## Pricing | Action | Credit cost | | ------------------------------------------- | ----------- | | Generate pitch kit (all 3 variants) | 2 credits | | Personalized variant for a specific curator | 2 credits | | Tone rewrite | 1 credit | | Translation | 1 credit | ## Related pages * [Playlist matching](/releases/playlist-matching) — find the curators worth pitching * [Release planner](/releases/release-planner) — pitch generation is a task in every release plan * [Sonic analysis](/catalog/sonic-analysis) — supplies the audio features that ground pitches * [Artist intelligence](/artists/intelligence-profile) — the artist context ## FAQ Yes — Aria varies wording across regenerations. The factual content (BPM, key, sonic peers, social proof) stays consistent because those are pulled from your real data. No. There's no public submission API for S4A editorial. You copy the pitch into the S4A form yourself. Aria reminds you when the submission window opens (in the release plan). Run [sonic analysis](/catalog/sonic-analysis) first. Pitches without audio features default to generic genre descriptors — much weaker. Yes — same flow. Released tracks can still be added to playlists. Some curators prefer 30-90 days post-release for "we already validated it" reasons. Pitch-response tracking is on the roadmap. v1 you manually log it in the project anchor activity feed. # Playlist matching & inspector Source: https://docs.patchline.ai/releases/playlist-matching Rank Spotify playlists by sonic fit and curator responsiveness for a specific track. Inspect any playlist's curator identity, recent additions, freshness, and submission status before you pitch. Playlist pitching is half the indie release game. Patchline doesn't ship a generic "submit to 500 playlists" service — it surfaces the **specific playlists with the highest probability of adding your specific track**, ranked by sonic fit and curator responsiveness, and gives you full intelligence on each curator before you pitch.   Free and Starter can browse playlists. Pro+ unlocks ranked matching and the playlist inspector. ## Two tools, one workflow | Tool | Question it answers | | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | **[`find_playlists`](/for-agents/mcp-tools-reference#find_playlists)** | *"What playlists should I pitch this track to?"* | | **[`inspect_playlist`](/for-agents/mcp-tools-reference#inspect_playlist)** | *"Who runs this playlist? Is the curator active? Did they recently add similar artists? Are they accepting submissions?"* | You use them together. `find_playlists` returns a ranked list; you `inspect_playlist` on the top 5 to pick the 1–3 worth pitching seriously. ## What `find_playlists` actually does The Patchline playlist matcher (`playlist-matcher-handler.py`, `playlist_scoring.py`) ranks Spotify playlists by a composite score: | Signal | Weight | What it measures | | -------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------- | | **Sonic fit** | High | Cosine similarity between your track's [audio features](/catalog/sonic-analysis) and the playlist's average features | | **Genre overlap** | High | How many of the playlist's existing tracks share genre/mood tags with yours | | **Curator responsiveness** | High | How quickly the curator has historically added new releases (the "fresh playlist" signal) | | **Track turnover** | Medium | How often the playlist refreshes — high-turnover = open to new music | | **Follower count** | Low | A tiebreaker, not a primary signal | | **Submission status** | Hard filter | Is the curator currently accepting? (We crawl SubmitHub-style signals) | The result is a ranked list of 10–25 playlists with a score (0–100) and a one-line "why this fits" explanation per row. ## What `inspect_playlist` returns Per playlist: * **Curator identity** — name, handle, contact (DM, email if listed) * **Followers** + **monthly listener delta** (growing or stagnant) * **Genre/mood profile** — top tags * **Track count + average track age** — freshness signal * **Recent additions** — last 20 tracks added, with dates * **Submission status** — open / closed / unknown * **Similar artists already in the playlist** — overlap with your roster * **Pitch-history** (if you've pitched before) — when, what you sent ## Where it lives | Surface | Path | | ------------- | ----------------------------------------------------------------------------------------------------- | | Web dashboard | Sidebar → **Playlists** → search or sidebar list. Per-track view at `/dashboard/playlists/[assetId]`. | | Aria chat | *"Find playlists for \[track]"* — returns ranked list inline. | | Telegram | Same as Aria — paste track link, get top matches. | | MCP server | `find_playlists` + `inspect_playlist` tools. | ## Quick start Open the catalog, pick the track you want to pitch. It needs completed [sonic analysis](/catalog/sonic-analysis) — playlist matching uses the audio features. Or sidebar → **Playlists** → click your track → **Find matches**. For each of the top 3–5 matches, click into the inspector. Check: * Followers trend (is it growing?) * Recent adds (did they add a similar artist recently?) * Submission status (are they accepting?) Don't pitch all 25. Pitch the 1–3 where Aria's score is highest AND the inspector confirms an active, relevant curator. Aria can [draft the pitch](/releases/pitch-kit) per playlist. ## The tools, in detail Example response (truncated): ```json theme={null} { "track": "Sleeper — Mira", "matches": [ { "playlist_id": "37i9dQZF1DXa1rZf8gLhyz", "name": "Lush Sounds", "score": 87, "why": "Dreampop-heavy curator, 76 BPM is in median range, recent add of Tessa's 'Long Way' (11 days ago)", "followers": 78000, "curator": "@lush_sounds_oslo", "submission_status": "open" }, { "playlist_id": "37i9dQZF1DX2sUQwD7tbmL", "name": "Bedroom Vibes", "score": 79, "why": "Strong genre overlap (4 dreampop tracks this month), high curator responsiveness score", "followers": 210000, "curator": "@bedroomvibes", "submission_status": "open" } // … 18 more ] } ``` Example response (truncated): ```json theme={null} { "playlist_id": "37i9dQZF1DXa1rZf8gLhyz", "name": "Lush Sounds", "curator": { "handle": "@lush_sounds_oslo", "real_name": "Anders B.", "contact": "lushsounds.curator@gmail.com", "active_since": "2019-03", "responsiveness_score": 0.78 }, "followers": 78000, "follower_trend_30d": "+3.2%", "track_count": 247, "avg_track_age_days": 42, "top_genres": ["dreampop", "shoegaze", "indie folk"], "recent_additions": [ { "track": "Long Way", "artist": "Tessa", "added": "2026-05-15" }, { "track": "Distant", "artist": "Cleo Bell", "added": "2026-05-12" } // … ], "submission_status": "open", "your_pitch_history": [] } ``` ## Examples ### Example 1 — Single-track matching ```text theme={null} Aria: Top 3 by composite score: 1. Hopeful Noise — 14k followers, curator @hopefulnoise (open, 0.81 responsiveness) Why: pop-leaning, 118 BPM median, recent add of a sonically-adjacent artist (Cleo Bell) 4 days ago. 2. Future Female Sounds — 190k followers, curator @futurefemale (open, 0.74) Why: strong female-vocal weight, your valence (0.62) is in their range. 3. Bright Drops — 38k followers, curator @bright_drops (open, 0.68) Why: high-energy pop focus, three recent adds in your BPM range. Want me to inspect any of these or draft a pitch? ``` ### Example 2 — Roster-level matching ```text theme={null} Aria: 5 artists, 10 top picks: Mira / "Sleeper": • Lush Sounds (87) • Bedroom Vibes (79) Tessa / "Long Way": • Lush Sounds (already added!) • Sad Girl Starter Pack (74) Cleo Bell / "Distant": • Lush Sounds (added 12 days ago) • Hopeful Noise (81) Run Hot / "Run Hot": • Indie Dance Hour (89) • 4 AM Club (76) Velvet Bird / "Velvet": • Velvet Underground Throwback (72) • Reverb Forever (68) Want me to draft pitches for the top 5 across the roster? ``` ### Example 3 — Pre-pitch inspection ```text theme={null} Aria: Bedroom Vibes — 210k followers, +1.8% in 30 days (growing). Curator @bedroomvibes, real name not listed, contact via Spotify. Responsiveness 0.69 — replies to ~40% of pitches. Recent adds: 4 dreampop tracks this month, avg track age 28 days (fresh). Submission status: open. They've never added you before. Verdict: solid pitch target. Worth a 60-second personalized message referencing the dreampop adds. Want me to draft the pitch? ``` ## Pricing | Tier | Find playlists | Inspect playlist | | ------------- | ----------------- | ---------------- | | | — | Browse only | | | — | Browse only | | | ✅ ranked matching | ✅ full inspector | | | ✅ | ✅ | | | ✅ + bulk API | ✅ | Each `find_playlists` or `inspect_playlist` call counts against AI credits via the Aria conversation that triggered it. Reading cached inspector results is free. ## Related features * [Sonic analysis](/catalog/sonic-analysis) — the input to playlist matching * [Pitch kit](/releases/pitch-kit) — the next step once you've picked a target * [Release planner](/releases/release-planner) — playlist pitching is a section in every plan * [MCP tools reference](/for-agents/mcp-tools-reference) — full `find_playlists` and `inspect_playlist` schemas ## FAQ No. Patchline finds the best-fit playlists and drafts the pitch. You send it through Spotify for Artists, SubmitHub, or direct curator outreach (DM, email). Most curators are humans who reply to humans, not bots. A 0–1 score that estimates how quickly and how often a curator adds pitched tracks. It's derived from historical signal: time between submission and add, % of new releases added vs ignored, recent activity. Higher = more likely to listen and respond. A few possible reasons: (1) the playlist's audio features don't overlap with your track's, (2) the curator is inactive (no recent adds), (3) the playlist is small enough that we haven't indexed it yet. You can manually `inspect_playlist` with a direct URL. Spotify only for ranked matching today. Apple Music / Tidal playlist intelligence is on the roadmap — not in v1. Patchline records the rejection silently. Future `find_playlists` calls deprioritize curators who've rejected you. No penalty box — just don't waste your future pitches. Curator-recent-adds are refreshed daily. Submission status is refreshed weekly. If you need fresher data, the inspector has a "refresh now" button (Pro+). # Project anchors Source: https://docs.patchline.ai/releases/project-anchors Project anchors are Patchline's persistent state for a release campaign — track list, status, tasks, dates, concurrent-write-safe storage. Every release plan you commit becomes a project anchor. A **project anchor** is a persistent row representing one release campaign. It holds the track list, status, tasks, dates, and any state that needs to survive across sessions, tabs, and team members. When you commit a [release plan](/releases/release-planner), that plan becomes a project anchor.   Free has 1 manual project. Starter+ enables AI-generated plans + multi-project tracking. ## Why anchors matter Without persistent state, every release campaign starts from scratch — no memory of what was decided, who's doing what, what's done, what's overdue. With anchors: * **Aria remembers** the campaign across conversations. * **Your team sees** the same state without trampling each other's edits. * **The daily synthesizer** (see [Research mode](/aria/research-mode)) knows what tasks are overdue. * **Cross-feature surfaces** — storefront, smart link, pitch kit — can all reference the same anchor. ## What lives in an anchor ```text theme={null} Project anchor: "Sleeper — Mira — 2026-07-15" ├── Status: in_progress ├── Target release date: 2026-07-15 ├── Created: 2026-06-03 ├── Last updated: 2026-06-10 (concurrent-write-safe via expectedUpdatedAt) ├── Track list: │ • Sleeper (Mira) — assetId abc-123, ISRC ... ├── Tasks (28): │ • [✓] Finalize artwork (due 2026-06-03) │ • [ ] Submit to Spotify editorial (due 2026-06-17) │ • [ ] ... ├── Linked surfaces: │ • Smart link: patchline.ai/store/mira/sleeper │ • Storefront product: enabled │ • Pitch kit: 3 drafts └── Activity log: 47 events ``` ## How writes stay safe The 2026-05-03 audit revealed that opening the same project in two tabs and saving from a stale tab silently overwrote the other tab's edits. That class of bug is now fixed via a concurrent-safe write pattern. What changed: * **`ProjectService.upsertCampaign` uses `UpdateCommand` with explicit `SET `** — only the fields that changed get written, not the whole row. * **Legacy `PutCommand` full-row replacements use optimistic concurrency** via an `expectedUpdatedAt` parameter and the condition `attribute_not_exists(updatedAt) OR updatedAt = :expectedUpdatedAt`. * **On `ConditionalCheckFailedException`**, the UI surfaces a "project changed elsewhere — refresh" state instead of silently overwriting. If you and a collaborator both edit the same anchor in different tabs, the second-to-save sees a friendly conflict prompt instead of losing their work. ## How to use anchors ### Create one Easiest path: Or sidebar → **Projects** → **+ New project**. ### Update one Click any task to mark complete. Edit the date. Add a new task. All changes use the concurrent-safe write pattern transparently. Via Aria: ### View one Sidebar → **Projects** → click the row. Or `/dashboard/projects/[id]` directly. ### List active anchors Or sidebar → **Projects** for the full list. ## Tier limits | Tier | Active projects | Anchor features | | ------------- | --------------- | ---------------------------- | | | 1 | Manual checklist, no AI plan | | | 1 | AI-generated plans | | | 5 | + multi-artist, team seats | | | 20 | + roster view, label-level | | | Unlimited | + API access | Active = `status: in_progress` or `status: scheduled`. Archived projects don't count. ## Anchor lifecycle ```text theme={null} draft → scheduled → in_progress → released → archived ↘ cancelled ``` * **draft** — created but no target date set * **scheduled** — target date set, prep underway * **in\_progress** — within the rollout window * **released** — past target date, post-release tracking * **archived** — manually archived, no longer counts against active limit * **cancelled** — release pulled, history preserved ## Related pages * [Release planner](/releases/release-planner) — generates the anchor * [AI campaign planner](/releases/campaign-planner) — fills the task list * [Pitch kit](/releases/pitch-kit) — references the anchor for context * [Aria's research mode](/aria/research-mode) — flags overdue tasks ## FAQ Concurrent-safe writes catch the conflict. The second save gets a "project changed elsewhere — refresh and retry" prompt. No silent overwrite. Either user can resolve. Yes — useful for re-releases, remixes, regional rollouts. Just create separate projects with different target dates. Pro+ (team tier). Tasks can be assigned to a workspace member. The daily synthesizer surfaces overdue tasks per assignee. The activity log captures every change. Restore-from-history isn't in v1 but the audit trail is there. Critical fields use optimistic concurrency, so unintended overwrites are blocked. Yes — project → ⋯ → Export as Markdown (or JSON via REST on Enterprise). # Release planner Source: https://docs.patchline.ai/releases/release-planner Turn a track or release into a structured rollout — milestones, launch windows, marketing tasks, DSP pitches, smart link, fan messaging — generated by Aria and grounded in your real catalog and audience data. The release planner turns a finished track (or EP, or album) into a **structured rollout**: milestones, launch windows, marketing tasks, DSP pitches, smart links, fan messaging — all grounded in your catalog, your audience, and what's actually working for artists like you.   Free tier sees basic release planning (manual checklist). Starter+ unlocks the AI-generated plan with project anchors. ## What it does A release plan is a living document. Aria generates the structure; you edit, approve, and mark off tasks as you ship them. Every plan includes: | Section | What it contains | | -------------------------------------------- | -------------------------------------------------------------------------------------------------- | | **Pre-release timeline** (Week -6 to Week 0) | Artwork, pitch copy, DSP submissions, smart link, pre-save, teasers | | **Release day** | DM list, post copy, storefront update, fan-facing announcement | | **Post-release** (Week +1 to +4) | TikTok/ads, follow-up pitches, performance review, momentum capture | | **Project anchor** | The persistent row in DynamoDB that holds your project state, trackList, and concurrent-safe edits | | **Tasks** | Discrete checkable items, each tied to a date and (optionally) an Aria action | ## When to use it * **You've finished a track and don't know where to start.** Open the planner and ask Aria. You'll have a draft plan in 60 seconds. * **You're managing 5 artists with overlapping release schedules.** Project anchors let you track multiple campaigns without losing state. * **Your last release flopped and you want to know why.** Aria can compare the new plan against historical performance — *"the dreampop releases that worked all had X in week -4, yours didn't."* ## Where it lives * **Web:** Sidebar → **Releases** → **+ New project** * **Aria:** "Plan a release for \[track]" — generates the plan, asks if you want to commit it as a project anchor. * **Claude plugin:** Same flow, native to Claude. The plugin includes a progressive interview that walks the planner with you step by step. ## Quick start Already in your catalog? Skip to step 2. If not, [import](/catalog/import) or [upload](/catalog/upload) it first — the planner is much better when it has [sonic analysis](/catalog/sonic-analysis) available. Easiest path: Or sidebar → **Releases** → **+ New project**, pick the track, set the target date, click **Generate plan**. Aria returns a 6-week rollout. Edit anything that doesn't fit. The plan is markdown — change task names, dates, owners, descriptions. Click **Save as project** (or tell Aria *"yes, commit it"*). The rollout is now a persistent project at `/dashboard/projects/[id]` with concurrent-write-safe storage and daily task reminders. As each task ships, check it off. Aria's daily synthesizer surfaces what's coming up next every morning when you open the dashboard. ## What a generated plan looks like A typical 6-week rollout for a dreampop single (Mira's "Sleeper"): ```text theme={null} 🎵 Sleeper — Mira — release plan Target release: 2026-07-15 (in 6 weeks) Sonic: 76 BPM, F# minor, dreampop, low energy 0.31, high acousticness 0.78 ━ WEEK -6 (2026-06-03) ──────────────────────────────────────── □ Finalize artwork (cover + canvas) □ Write 60-second teaser script □ Confirm distribution timeline with [distributor] □ Draft Spotify editorial pitch (Aria can draft) ━ WEEK -4 (2026-06-17) ──────────────────────────────────────── □ Submit to Spotify editorial via S4A (deadline: 4 weeks pre-release) □ Submit to Apple Music for Artists editorial □ Build smart link + pre-save page □ DM-list assembly: 8 dreampop curators who added Tessa's "Long Way" ━ WEEK -2 (2026-07-01) ──────────────────────────────────────── □ Pre-save go-live + Telegram teaser □ Schedule fan email (Mira list: 1,247 subscribers) □ Personal DMs to the 8 priority curators ━ WEEK 0 — RELEASE DAY (2026-07-15) ─────────────────────────── □ Release-day post (3 platforms — drafts in Aria) □ Storefront banner swap (Patchline storefront) □ Fan email send □ TikTok teaser drop ━ WEEK +2 (2026-07-29) ──────────────────────────────────────── □ TikTok ad targeting dreampop cluster ($50 test) □ Follow-up pitch to playlist curators who didn't add (Aria drafts) □ Review week 1 performance ━ WEEK +4 (2026-08-12) ──────────────────────────────────────── □ Post-mortem: streams vs forecast □ Hand momentum to next release planning ``` Each item is an actionable task. Aria can do many of them itself — draft the pitch, assemble the DM list, schedule the smart link — when you ask. ## Prerequisites * A track in your catalog with [sonic analysis](/catalog/sonic-analysis) complete. * Starter+ for the AI-generated plan. Free tier sees a manual checklist. * (Optional) [Gmail connected](/integrations/gmail) for Aria to draft and send curator outreach. * (Optional) A [smart link](/storefront/smart-links) plan if you want Aria to wire the pre-save automatically. ## How it works under the hood 1. The release-planner UI calls Aria with a structured payload: track ID, target date, optional constraints. 2. The supervisor agent routes to the campaign planner specialist (Lambda: `campaign-generator.py`) which assembles the rollout from: * The track's [sonic features](/catalog/sonic-analysis) (genre cluster, energy profile). * Your historical release performance (campaign history table). * Your roster's audience data ([Soundcharts](/artists/audience)). * A baseline 6-week template that adjusts based on tier (Pro/Scale unlock more granular timelines). 3. The plan is rendered in markdown in the chat. If you commit it, the `ProjectService.upsertCampaign` writes to DynamoDB `Releases-staging` using the concurrent-safe `UpdateCommand` pattern (see [project anchors](/releases/project-anchors)). 4. Once committed, `release-strategy-optimizer.py` runs nightly to adjust the plan based on early signal — playlist adds, social engagement, etc. The MCP tool for programmatic access: ## Examples ### Example 1 — Generate a fresh plan ```text theme={null} Aria: Built. "Late Bloom" — pop, 118 BPM, B minor, high valence. Closest roster comp: your "Mira - November" release (hit 8.2k streams in week 1). Generated 28 tasks across 6 weeks. Standout differences from your last release plan: - Editorial submission window starts week -4 (was -3, missed cutoff last time) - DM list includes 11 curators (was 6 last release — added pop-leaning curators we missed) - Week +2 includes a TikTok ad test ($50 budget) — your last 3 releases that did this beat forecast by 2.1× Commit as project? [Yes / Edit first] ``` ### Example 2 — Adjust mid-flight ```text theme={null} Aria: Adjusted. New target: 2026-07-29. All upstream tasks shifted by 14 days. Spotify editorial submission still inside the 4-week window — no risk. Curator DM list re-prioritized based on the new date. ``` ### Example 3 — Roster-level view ```text theme={null} Aria: 4 active campaigns: 1. Mira / "Sleeper" — week -2 (release 7/15). 6 open tasks. ⚠️ 2 overdue. 2. Tessa / "Long Way (acoustic)" — week +1 (released 7/8). 3 tasks. 3. Mira / "Late Bloom" — week -4 (release 7/29). On track. 4. Run Hot / EP rollout — week -6 (release 8/15). Just started. Highest priority: the 2 overdue tasks for Mira/Sleeper. Want me to walk them? ``` ## Pricing | Tier | Release planner access | AI plan generation | | ------------- | ------------------------------------------ | ------------------ | | | Basic (manual checklist) | — | | | Full (AI-generated plan, 1 active project) | 10 credits/plan | | | Full + multi-artist (5 active projects) | 10 credits/plan | | | Full + roster view (20 active projects) | 10 credits/plan | | | Full + API access | 10 credits/plan | ## Related features * [Project anchors](/releases/project-anchors) — the persistent state * [AI campaign planner](/releases/campaign-planner) — deeper marketing * [Pitch kit](/releases/pitch-kit) — the pitches Aria generates for the plan * [Playlist matching](/releases/playlist-matching) — the curator targeting * [Smart links](/storefront/smart-links) — auto-wired pre-saves * [Gmail integration](/integrations/gmail) — for Aria to send pitches ## FAQ Yes. The plan is editable markdown. Click any task to rename, change date, add description, mark complete. You can also ask Aria to revise — "move week -2 stuff earlier", "drop the TikTok ad", "add a storefront launch task in week 0". Aria compresses the plan. Editorial submission moves to ASAP, fewer pre-release weeks, more weight on release-day and post-release. The template adjusts to the timeline you give it. Yes on Pro+ (3+ seats). Pro adds 3 team seats, Scale adds 10. The project anchor uses concurrent-safe writes — your edits and your teammate's edits won't overwrite each other. No. Spotify for Artists doesn't have a public submission API. Aria drafts the pitch copy and reminds you when the window opens; you submit in S4A yourself. Aria flags overdue tasks in the daily synthesizer and suggests recovery actions. If you miss the editorial window, Aria suggests alternative paths (DM curators directly, lean harder on playlist matching, etc.). Starter: 1 active project. Pro: 5. Scale: 20. Enterprise: unlimited. # Checkout & payouts Source: https://docs.patchline.ai/storefront/checkout-payouts How Stripe Connect powers storefront checkout, when payouts arrive in your bank account, how to handle taxes, refunds, and disputes. Patchline storefronts run on **Stripe Connect**. Money flows from the fan's card to your Stripe account; Patchline never touches your funds. This page covers checkout mechanics, payout timing, taxes, refunds, and disputes.   Requires a connected Stripe account. See [storefront setup](/storefront/setup). ## How the money flows ```text theme={null} Fan → Stripe Checkout → Stripe Connect → your Stripe account → your bank ↑ Stripe deducts processing fee Patchline platform fee (0% on paid tiers) ``` Concretely: | Step | What happens | | -------------------------------- | -------------------------------------------------- | | Fan clicks Buy | Stripe Checkout session opens | | Fan completes payment | Card charged, \$X received | | Stripe holds briefly | Risk + fraud checks (seconds to minutes) | | Stripe deducts processing fee | Typically 2.9% + \$0.30/txn | | Patchline platform fee | 0% on Starter+; 10% on Free | | Net lands in your Stripe balance | Available for payout | | Payout to your bank account | Per Stripe's default schedule (2 business days US) | ## Payout timing Stripe defaults: | Country | Standard payout | | -------------------- | ------------------- | | United States | T+2 business days | | United Kingdom | T+3 business days | | EU | T+3-7 business days | | Most other countries | T+5-7 business days | You can configure faster payouts in Stripe (some include a small fee). ## Taxes Sales tax / VAT depends on jurisdiction: * **Stripe Tax** (optional, \~0.5% per transaction) — automatic calculation in 30+ countries. Recommended. * **Without Stripe Tax** — you're responsible for declaring and remitting sales tax / VAT in your jurisdiction. Enable Stripe Tax in your Stripe dashboard → Settings → Tax. Income tax on storefront earnings is **always** your responsibility — Patchline issues no tax forms. Use Stripe's annual reports for documentation. ## Refunds Settings → **Sales** → find the transaction → **Issue refund**. * Stripe processes the refund (T+5-10 business days back to fan's card). * Patchline marks the sale refunded. * The fan's download access is revoked. * The transaction shows refunded in your sales report. You can issue partial refunds. ## Disputes (chargebacks) If a fan disputes a charge with their bank: 1. Stripe notifies you via email + dashboard. 2. You have \~7-21 days to respond with evidence (Stripe template). 3. Stripe's chargeback fee (\~\$15) applies if you lose. Patchline can help draft a chargeback response — paste the dispute into Aria: ```text theme={null} You: Help me respond to this chargeback: [paste Stripe email] Aria: Here's a draft response. Key points to cite: download proof, purchase timestamp, your refund policy. [draft follows] ``` ## Pricing | Cost | Where it goes | | ----------------------------------------------- | ------------------------- | | Stripe processing (typically 2.9% + \$0.30/txn) | Stripe | | Patchline platform fee (Free: 10%) | Patchline | | Patchline platform fee (Starter+: **0%**) | n/a | | Stripe Tax (optional \~0.5%) | Stripe (if enabled) | | Stripe chargeback fee (\~\$15) | Stripe (only if you lose) | ## Related pages * [Storefront overview](/storefront/overview) — 0% fee explainer * [Storefront setup](/storefront/setup) — Stripe Connect step * [Plans & credits](/account/plans-credits) — Patchline subscription side * [Pricing & plans](/get-started/pricing) — tier breakdown ## FAQ By design. Stripe Connect routes funds directly to your account — Patchline only receives our platform fee (0% on paid tiers). This means we can't accidentally hold your funds, can't freeze them, and can't be in the middle if there's ever a payout dispute. Stripe handles international cards by default. Currency conversion happens at Stripe; you receive in your account's home currency. Yes — Settings → **Discount codes** → 100% off code with usage limit. Useful for press / promo. Stripe defaults vary by country — typically \$1 in the US. Most artists never hit a minimum because payouts happen automatically. # Storefront Source: https://docs.patchline.ai/storefront/overview Sell your music direct to fans from a branded storefront. Stripe-powered checkout, instant payouts, 0% platform fee on every paid Patchline tier. Includes smart links, pre-saves, fan stats, and an embeddable widget. Patchline storefronts let you sell music direct to fans from a branded page — `patchline.ai/store/`. Stripe handles the checkout and payouts. Patchline takes a **0% platform fee** on every paid tier; **10% on Free**. You keep 100% of revenue after Stripe processing (typically 2.9% + \$0.30/transaction).   0% platform fee on Starter, Pro, Scale, Enterprise. 10% on Free. ## What's included Branded page at `patchline.ai/store/` with your banner, products, smart links. Mobile + desktop, dark by default. Stripe Connect. Cards, Apple Pay, Google Pay. Instant payouts to your bank account. `/store//embed/` — drop into your website, Linktree, artist site. Looks native. Routing links for fans across DSPs. Pre-save flow for unreleased tracks. Built on the same storefront infrastructure. Sales, conversion, top fans, geographic breakdown. Built into the storefront dashboard. Buyers get download links via email + in-page after purchase. Signed URLs, expiring tokens, anti-leech. ## The 0% platform fee — what it actually means This is the storefront's headline. Specifics: * **Free tier:** Patchline takes **10%** of every storefront sale, before payout. * **Every paid tier (Starter, Pro, Scale, Enterprise):** Patchline takes **0%**. You keep 100% of the sale. * **Stripe processing** (typically 2.9% + \$0.30 per transaction) applies on every tier, separate from Patchline's fee. Worked example — selling an album for \$10: | Tier | Gross sale | Patchline fee | Stripe fee | You keep | | -------- | ---------- | ------------- | ---------- | ---------- | | Free | \$10.00 | \$1.00 (10%) | \$0.59 | **\$8.41** | | Starter+ | \$10.00 | **\$0.00** | \$0.59 | **\$9.41** | If you sell more than \~$100/month direct, **Starter ($9.99/mo) pays for itself just from the dropped platform fee\*\*, ignoring everything else Starter unlocks. ## When to use it * **You have superfans willing to pay direct.** Bandcamp-style audience. * **You want margins streaming can't match.** $10 album direct = $9.41 to you. Same album on streaming = \~\$0.003 × thousands of plays before you net the same. * **You're selling more than music** — merch, signed copies, demos, stems, instrumental versions. The storefront supports any digital product, not just full tracks. * **You want a Bandcamp alternative** that integrates with the rest of your Patchline workflow (release planning, smart links, fan stats). ## Where it lives Storefronts are a **web-first** product. Setup happens in the dashboard; the public store page is a separate route at `patchline.ai/store/`. | Surface | Path | | ------------------------- | ------------------------------------------- | | Artist-side setup | Sidebar → **Store** at `/dashboard/store` | | Public store page | `patchline.ai/store/` | | Single-product page | `patchline.ai/store//` | | Checkout | `patchline.ai/store//checkout` | | Thank-you / download page | `patchline.ai/store//thank-you` | | Embed widget | `patchline.ai/store//embed/` | ## Quick start On Starter+, sidebar → **Store** → **Connect Stripe**. Standard Stripe Connect flow — takes 5 minutes if you already have a Stripe account, longer if not. Storefronts sell **assets** from your catalog. Pick the tracks you want to sell. Add custom products if you're selling merch or bundles. Per-product. Pay-what-you-want supported (with optional minimum). Currency follows your Stripe account default. Banner image (1500×500 recommended). Short bio. Your storefront URL. `patchline.ai/store/`. Drop it in your Linktree, bio, socials, fan email. See [Set up your store](/storefront/setup) for the full setup walkthrough. ## Prerequisites * **Starter+ subscription** (recommended) — Free works but 10% fee. * **Stripe Connect account** — created during setup if you don't have one. Takes 5 minutes. * **At least one asset in your catalog** to sell. ## How fans buy From the fan's side: 1. They click a link (smart link, embed, social, your bio). 2. Land on `patchline.ai/store//` — product page with audio preview, art, price. 3. Click **Buy** → Stripe Checkout. Cards, Apple Pay, Google Pay. 4. Land on the thank-you page with a direct download link + emailed download link (signed URL, 30-day expiration). 5. Fan stats record the purchase: which asset, which country, referrer. Total time fan-side: \~30 seconds. ## What kinds of products you can sell * **Single tracks** from your catalog. * **EPs / albums** as bundles. * **Stems** (separate stem pack — vocals, drums, bass, other). * **Demos / unreleased material** (gated behind purchase). * **Instrumentals** as separate SKUs. * **Lossless masters** (WAV / FLAC at premium price). * **Custom digital products** — exclusive cover art, tab books, etc. What you **cannot** sell (yet): * **Physical merch** — not in v1. Roadmap. * **Vinyl / CDs** — not in v1. Roadmap. * **Subscriptions** — fan club / patreon-style monthly support — not in v1. ## Pricing | Tier | Storefront platform fee | Stripe processing | | ------------- | ----------------------- | ----------------------------------- | | | **10%** | Stripe: typically 2.9% + \$0.30/txn | | | **0%** | Stripe: 2.9% + \$0.30/txn | | | **0%** | Stripe: 2.9% + \$0.30/txn | | | **0%** | Stripe: 2.9% + \$0.30/txn | | | **0%** | Stripe: 2.9% + \$0.30/txn | Stripe rates vary by country and card type — check [stripe.com/pricing](https://stripe.com/pricing) for your jurisdiction. The above is US-standard. ## Related features * [Set up your store](/storefront/setup) — full setup walkthrough * [Smart links & pre-saves](/storefront/smart-links) — routing links + pre-save flow * [Checkout & payouts](/storefront/checkout-payouts) — Stripe Connect, payout schedule, taxes * [Catalog](/catalog/import) — assets are what you sell ## FAQ Yes on paid Patchline tiers. Patchline keeps nothing of the sale. Stripe processing (typically 2.9% + \$0.30) is separate and goes to Stripe, not Patchline. Stripe's standard payout schedule: 2 business days in the US, 5–7 in most other countries. You can configure faster payout schedules in Stripe (some include a small fee). Stripe Tax (optional, \~0.5% per txn) handles sales tax / VAT calculation in most jurisdictions. Without it, you're responsible for declaring and remitting. See [Checkout & payouts](/storefront/checkout-payouts). Yes. Product pages include a 30-second preview by default (full preview optional, configurable per asset). Custom domain for the storefront (`store.your-band.com`) is on the Enterprise tier today. Other tiers use `patchline.ai/store/`. Stripe may hold payouts on new accounts or for high-risk transactions — standard Stripe behavior. You contact Stripe directly to resolve. Patchline can't unlock funds we don't hold. Yes. Settings → Sales → Issue refund. Stripe processes the refund, Patchline marks the sale refunded and revokes download access. Yes — `patchline.ai/marketplace`. It's the cross-store discovery surface. Your storefront is auto-listed by default; you can opt out in Store settings. # Set up your store Source: https://docs.patchline.ai/storefront/setup Step-by-step storefront setup: connect Stripe, choose your slug, add products from your catalog, set pricing, add a banner, share your link. About 15 minutes start-to-finish. 15 minutes from "I want to sell my music" to "I have a working storefront link." Works on every tier — Free gives you the storefront with a 10% platform fee; Starter+ is 0% platform fee.   0% platform fee on Starter+. Stripe processing applies on every tier. ## What you'll need * **A Patchline account** ([sign up](https://patchline.ai)). * **A Stripe account** (or willingness to create one — takes 5 minutes). * **At least one [asset in your catalog](/catalog/import)** to sell. * **A banner image** (1500×500 recommended) — can be added later. ## Step-by-step Sidebar → **Store** → `/dashboard/store`. Click **Connect Stripe**. Standard Stripe Connect flow: * Existing Stripe account: sign in, approve Patchline as a connected app. \~2 min. * New Stripe account: create one through Stripe's flow (business info, bank account, tax info). \~5–10 min. Your storefront URL is `patchline.ai/store/`. Pick something short and brandable — `mira-music`, `runhot`, `velvetbird`. Slugs are unique platform-wide. Inventory → **+ Add product**. For each product: * Pick a track from your catalog (or upload a new one) * Set product type: single track / album / stems / merch (text-only for v1, no shipping) * Set price (fixed or pay-what-you-want with optional minimum) * Optionally add a description, behind-the-scenes asset, signed cover art Storefront → **Customize**: * Banner image (1500×500 recommended, JPG/PNG) * Short bio (under 200 chars) * Profile photo (uses your roster artist photo by default) * Social links (IG, TikTok, YouTube, etc.) **Preview** opens your store URL in a new tab. When it looks right, flip the **Live** toggle. `patchline.ai/store/`. Drop in your Linktree, bio, socials, email signature. The link auto-generates an OG image for social previews. ## Embedding on your own site The embed widget lets you drop a product into any HTML page: ```html theme={null} ``` The embed renders the product card + a buy button that opens checkout in a popup. Works on Squarespace, Webflow, Wix, plain HTML, or anywhere iframes are allowed. ## Reordering products Inventory → drag-and-drop to reorder. The order on your storefront follows the inventory order. ## Pricing modes per product | Mode | Use when | | ---------------------------------- | ------------------------------------------------------- | | **Fixed** | Standard — $5, $10, etc. | | **Pay-what-you-want** | Solidarity / tip jar feel — fan picks the price | | **Pay-what-you-want with minimum** | Soft floor with upside — minimum \$3, fans can pay more | | **Free download** | Lead magnet — collect emails in exchange for music | ## Related pages * [Storefront overview](/storefront/overview) — what storefronts are * [Smart links](/storefront/smart-links) — routing links for fans * [Checkout & payouts](/storefront/checkout-payouts) — Stripe details # Smart links & pre-saves Source: https://docs.patchline.ai/storefront/smart-links One link → fan routes to their preferred platform (Spotify, Apple, YouTube). Pre-save flow for unreleased tracks. Auto-resolves ISRC, DSP URLs, and cover art server-side. A smart link is one URL that routes a fan to their preferred streaming platform — Spotify if they're a Spotify user, Apple if they're Apple, YouTube if they're YouTube. Same link, right destination per fan. Pre-save links extend this to unreleased tracks: fans pre-save before release, and the track auto-adds to their library when it drops.   Starter+ for smart links. 1 credit per smart link created. ## What it does | Feature | Smart link (released) | Pre-save (unreleased) | | ------------------------------------------------ | --------------------- | --------------------- | | Fan opens link → routes to their platform | ✓ | ✓ | | Auto-saves to library on release day | — | ✓ | | Captures fan email (optional) | ✓ | ✓ | | Tracks click + conversion | ✓ | ✓ | | Auto-generates OG image | ✓ | ✓ | | Custom landing page (artwork, bio, "listen" CTA) | ✓ | ✓ | ## How to create ### Via Aria ### Via the storefront UI Sidebar → **Store** → asset → **Smart link** → **Create**. ### Via MCP The smart link tool resolves the ISRC against major DSPs server-side and assembles the routing logic — you don't have to provide every platform URL. ## Where smart links live `patchline.ai/link/` — short, shareable. Custom slug (`patchline.ai/link/mira-sleeper`) on Pro+. Embed in: * Your Linktree / bio * Email signatures * Social bios * Fan list emails * Press release "listen here" links ## Pre-save flow Asset → **Smart link** → **Pre-save** mode → set release date. Same URL you'll use post-release. No need to swap links — same URL transitions from pre-save to smart-link on release day. Each fan picks a platform (Spotify, Apple, etc.) and authenticates. Their authorized save is queued. At release time, the queued saves execute. Each fan's library auto-adds the track. The URL automatically transitions. Late fans get routed normally. ## Pricing | Action | Credit cost | | ------------------ | ----------- | | Create smart link | 1 | | Create pre-save | 1 | | Custom slug (Pro+) | 0 | | Click tracking | 0 | ## Related pages * [Storefront overview](/storefront/overview) * [Storefront setup](/storefront/setup) — connect Stripe first * [Release planner](/releases/release-planner) — smart link is a task in every plan * [MCP tools reference](/for-agents/mcp-tools-reference#create_smart_link) ## FAQ Spotify, Apple Music, YouTube Music, Amazon Music, Tidal, Deezer, Pandora, SoundCloud, Bandcamp. We add new DSPs as they become relevant. Pro+ — duplicate a smart link, set different landing-page copy / art per version, share both. Patchline tracks conversion per variant. Yes. Each link has an auto-generated OG image (track cover + title) that renders on all major platforms. Aggregate stats (clicks, conversions, geo) — yes. Per-fan tracking requires the email-capture variant, which is opt-in for fans.