# LyricPatch

> LyricPatch replaces short lyric phrases in existing songs through a web editor, REST API and remote MCP. Authorized x402-capable clients can start a private paid session without a human creating a LyricPatch website account. Existing account-owned API keys still work.

## Start here

- [For Agents](https://lyricpatch.com/agents): Capabilities, signup-free sessions, connection and editing workflow.
- [Agent API guide](https://lyricpatch.com/agents/docs): Bootstrap protocol, permissions, costs, x402, limits and recovery.
- [Agent integrations](https://lyricpatch.com/agents/integrations): Version 1.2.0 resumable CLI, host capability requirements, private wallet/session setup, file upload, preview playback and export approval.
- [Agent demo](https://lyricpatch.com/agents/demo): Real owner-authorized Outlet before/after audio at a known 44–48-second selection. Static playback starts no generation or GPU work; not a demonstration of autonomous phrase discovery.
- [OpenAPI schema](https://api.lyricpatch.com/v1/agent/openapi.json): Current public request and response schemas.
- [Published MCP Registry record](https://registry.modelcontextprotocol.io/v0.1/servers/com.lyricpatch%2Flyricpatch/versions/1.2.0): LyricPatch remote MCP listing.
- [Glama connector listing](https://glama.ai/mcp/connectors/com.lyricpatch/lyricpatch): Live directory listing verified September 14, 2026. Discovery is not installation, private access or payment authorization.
- [Python connector](https://github.com/yaboijbigs/lyricpatch-agent): MIT-licensed client and resumable approved-preview workflow. Pin package installs to v1.2.0; the separately published MCP Registry record above has its own verified version.
- [Account agent access](https://lyricpatch.com/account/agents): Optional human login to create/revoke keys for an existing website account.
- [Pricing](https://lyricpatch.com/pricing): One-time packs and credit costs.
- [Examples](https://lyricpatch.com/examples): Real before/after audio; listening starts no generation.

## Signup-free bootstrap

- API origin: https://api.lyricpatch.com
- Public GET /v1/agent/sessions/offer provides service information before creating a session. Anonymous MCP initialization, tools/list and get_service_info expose public metadata only.
- Public POST /v1/agent/sessions offers 40 non-expiring credits for $1.99 through x402, USDC on Base. No preexisting account or API key is required.
- Before the first request, generate a cryptographically random secret: "lp_session_" + 64 random hex characters. Persist it privately and send it as X-LyricPatch-Session on every session request/retry.
- Without the header the server generates a session_secret; losing that first response can lose access. Generate and save your own first.
- The initial response is HTTP 402 with payment_required, PAYMENT-REQUIRED and the current legal_version.
- Obtain real delegated permission for adult eligibility, current terms, recording/lyrics/voice rights, spending and media processing. Do not assume permission or attest merely because a sample says true.
- An authorized x402-capable wallet client signs the offered payment. Retry the SAME URL and session header with PAYMENT-SIGNATURE and body fields legal_version, adult_attested, terms_accepted, rights_attested, spending_authorized, media_processing_authorized. Each attestation must actually be true.
- HTTP 200 after confirmed funding returns api_key. HTTP 202 means pending, with api_key null: preserve this session and purchase rather than creating another.
- GET /v1/agent/sessions/current with the same X-LyricPatch-Session recovers state/credential. Resume an already-recorded pending proof by POSTing the same session again without a new payment proof.
- The session has an isolated owner, projects and balance. Keep its secret to resume paid credits. Lost session secrets have no email recovery; public payment transactions are not login credentials.
- Bootstrap responses may contain credentials. Do not log them or paste them into an ordinary chat.

## Connect

- Remote MCP: https://api.lyricpatch.com/mcp
- Streamable HTTP transport; Authorization: Bearer <api_key> in secure client configuration.
- Bootstrap over REST first, then use the funded session key with REST/MCP. Existing account-scoped keys remain supported.
- A capable host can obtain and configure the key programmatically; no person needs to create a website account or agent key manually. All private MCP work still requires that funded session key or an existing account key.
- A client must support connection, file transfer and the requested wallet workflow. A natural-language prompt does not automatically install MCP or enable every chat assistant to pay.
- Discover current MCP schemas before use; never invent tools or argument names.
- Store keys and session secrets privately, never in chats, URLs, public code or logs.

## Workflow

The 1.2.0 CLI provides connect, preview and export. It needs Python 3.11+, shell and local file access. Codex/Claude Code recipes are capability-based, not a claim that every host or marketplace has been live-tested. Plugin instructions do not add wallet, file-transfer or playback capabilities to a plain chat host.

Install: python -m pip install 'git+https://github.com/yaboijbigs/lyricpatch-agent.git@v1.2.0'. Signup-free wallet support uses the optional x402 extra and a privately provisioned, limited-funds local wallet; never paste EVM_PRIVATE_KEY or LyricPatch credentials into chat. Follow the integration guide's explicit funding and attestation steps.

Use preview with --song, --original-file, --replacement-file, --start, --end, --max-credits, --state, --output and actual --rights-confirmed. Without --authorize-generation it uploads/prepares and quotes only. The maximum credits is the total run ceiling including the 5-credit export. Choose --format wav on the first preview intent if needed; the default finished export is MP3. Use the same private state on retries. Pass --session-state for a recovered paid session, or privately supply LYRICPATCH_API_KEY.

After generation, play the downloaded preview file. export with --approve-version selects only an owner-approved version and quotes; --authorize-export additionally authorizes the charge. Ask before either paid step. Return the actual downloaded output file, not a logged signed URL. Never delete private state to retry uncertain work.

1. Check capabilities, balance, scopes and limits; obtain the owner's audio, edit, spending and media-sharing authorization.
2. Privately upload the owner's MP3 and wait for preparation.
3. Supply exact phrase timestamps, or have the calling agent supply its own timestamped transcript for local phrase matching. LyricPatch does not scan/transcribe the whole song to find phrases. Confirm ambiguous matches; do not silently pick one.
4. Create the selected 0.1–6-second draft using start_sample/end_sample from prepared sample_rate. Supply the exact approved original and replacement words.
5. Get a generation quote and approval. Preserve work identifiers and poll instead of restarting jobs.
6. Let the user compare original/new audio. Apply only the approved version.
7. Quote the separate export, obtain approval and download before project expiry.

Ordinary optional transcription sends only the selected clip to OpenAI, never the whole song. Any transcription performed by the calling agent is a separate client workflow requiring the owner's permission and review of that client's processing terms.

Local matching: POST /v1/agent/projects/{project_id}/phrase-matches with target_phrase and words: [{text, start_seconds, end_seconds}]. MCP equivalent: match_phrase(project_id, target_phrase, words). Requires the transcribe scope and a prepared project. The synchronous response has source: agent_supplied_transcript, transcript_verified: false, match_status and candidates. Candidate fields include start_sample, end_sample, selection_valid and requires_confirmation. A similarity score is not confidence about the audio. Handle matched, ambiguous, not_found, too_long and too_short explicitly. No separate credits, provider request, transcript persistence or automatic edit creation occurs.

## Costs and approvals

- No free welcome credits. Previously issued credits keep their terms.
- Packs: credits_40 = 40 for $1.99; credits_100 = 100 for $4.99; credits_400 = 400 for $14.99; credits_1000 = 1000 for $29.99. USD, one time, purchased credits never expire.
- Signup-free bootstrap buys the credits_40 pack. A funded key can use the documented credit-purchase API for later packs.
- Generation costs one credit per selected second, rounded up per change. Every successful alternate version costs credits again.
- A newly prepared finished-song MP3 or WAV costs 5 credits. Re-downloading the same ready file costs nothing extra while available.
- Account agents share the owner's website balance. Signup-free sessions have a separate balance.
- A payments-scoped key plus separately authorized wallet can buy credits via x402, USDC on Base. A credit limit is not wallet-spending permission.
- Quote each generation/export and obtain approval. Never generate extra versions, purchase another pack or publish audio without authorization.
- Preserve session secrets, purchase IDs and idempotency keys on retries. A timeout is not evidence of nonpayment.

## Limits, privacy and rights

- Adults 18+; the owner needs rights to the audio, lyrics and identifiable voices.
- MP3 uploads up to 100 MB and 15 minutes.
- Selection length 0.1–6 seconds; it can start at zero. 3–4 seconds is a recommendation.
- Up to 32 non-overlapping changes, subject to credits and key budgets.
- Lyric generation supports English and Chinese. Quality varies; never promise perfect voice preservation.
- Project files expire 24 hours after creation; reopening does not extend storage.
- Projects stay private to their owner and authorized agents. Do not log lyrics, transcripts, audio, secrets or signed file links.
- Failed or confirmed-cancelled unfinished work restores reserved credits. Successful work stays charged.
- Never bypass authorization, eligibility, scope, budget, expiry or account restrictions.

## Policies

- [Terms](https://lyricpatch.com/legal/terms)
- [Acceptable use](https://lyricpatch.com/legal/acceptable-use)
- [Privacy](https://lyricpatch.com/legal/privacy)
- [DMCA](https://lyricpatch.com/legal/dmca)
- [Model licenses](https://lyricpatch.com/about/licenses)
- Support: support@lyricpatch.com