# StudioSphere Pulse Full Agent Context

StudioSphere Pulse answers a practical music-production question for agents: before using this audio, what is it?

Pulse is a hosted API and remote MCP server. It accepts public HTTPS audio URLs, including shareable Google Drive, Dropbox, and other document-repository links when they are accessible to anyone with the link, estimates cost before analysis, supports a temporary one-track trial for first-time users, requires rights attestation before processing, and returns structured JSON results. It is built for music producers, sample-library workflows, sync/catalog tagging, and AI agents that need audio metadata before making recommendations or edits.

## Canonical Endpoints

- `GET https://pulse.studiosphere.space/` — service descriptor
- `GET https://pulse.studiosphere.space/for-agents` — agent playbook and recommended scenarios
- `GET https://pulse.studiosphere.space/connect` — human MCP setup guide
- `GET https://pulse.studiosphere.space/bpm-detection-api` — tempo/BPM workflows and API positioning
- `GET https://pulse.studiosphere.space/key-detection-api` — musical key and harmonic workflow positioning
- `GET https://pulse.studiosphere.space/waveform-analysis-api` — waveform peak extraction and visualization positioning
- `GET https://pulse.studiosphere.space/audio-mcp-server` — remote MCP server positioning for AI assistants
- `GET https://pulse.studiosphere.space/sample-library-tagging` — sample-pack and loop-library metadata workflow
- `GET https://pulse.studiosphere.space/dj-bpm-key-workflow` — DJ beat matching and harmonic set-planning workflow
- `GET https://pulse.studiosphere.space/music-catalog-enrichment-api` — catalog, sync, and internal media metadata workflow
- `GET https://pulse.studiosphere.space/predictable-audio-analysis-pricing` — estimate-first pay-per-second pricing explanation
- `GET https://pulse.studiosphere.space/llms.txt` — compact agent-readable guide
- `GET https://pulse.studiosphere.space/.well-known/mcp/server.json` — MCP registry manifest
- `GET https://pulse.studiosphere.space/robots.txt` — crawler policy
- `GET https://pulse.studiosphere.space/sitemap.xml` — crawlable human and agent URLs
- `GET https://pulse.studiosphere.space/tools` — available and coming-soon tools
- `POST https://pulse.studiosphere.space/trial/start` — email-free temporary trial key for one short URL analysis
- `POST https://pulse.studiosphere.space/estimate` — free cost estimate
- `POST https://pulse.studiosphere.space/analyze` — API-key analysis
- `POST https://pulse.studiosphere.space/pay` — one-time Stripe Checkout analysis
- `GET https://pulse.studiosphere.space/status/:jobId` — job status/results
- `POST https://mcp.studiosphere.space/mcp` — remote MCP server

## Brand Assets

- Icon: `https://pulse.studiosphere.space/assets/icon.svg`
- Social card: `https://pulse.studiosphere.space/assets/og.png`
- Public repository: `https://github.com/notpaulb/studiosphere-pulse-mcp`
- Official MCP Registry name/version: `space.studiosphere/pulse` v1.0.2

## Available v1.0 Analysis Tools

- `bpm`: tempo, confidence, beat count
- `key`: root note, scale, confidence
- `waveform`: peak data suitable for waveform visualization

## Coming Soon

- `structure`: song-section segmentation
- `chords`: timestamped chord progression

Do not request `structure` or `chords` in v1.0. They return `tool_coming_soon`.

## Result Interpretation

- BPM is an estimate with confidence metadata, not a guarantee. For DJ sets, loop packs, edits, and catalog tagging, verify whether the useful working tempo is the detected BPM, half-time, or double-time.
- Key is harmonic context, not a guarantee. Low-confidence, atonal, noisy, modulating, or very short audio may need manual verification before catalog, DJ, or release decisions.
- One-shots may not contain enough rhythmic or tonal evidence for useful BPM/key results; waveform shape and human tags may be more useful.

## Agent Workflow

1. Use `estimate_cost` with `tools` limited to `bpm`, `key`, and `waveform`.
2. Present `cost_display` to the user.
3. Ask: "Can you confirm you have rights, permission, lawful access, or another legal basis to process this audio with Pulse?"
4. If the user confirms and an API key is available, call `analyze_track`.
5. If the user has no key and wants to try Pulse first, call `start_trial`; use the returned temporary key for one short URL analysis.
6. If there is no API key and the user prefers one-off paid analysis, call `request_payment_link` and present the Checkout URL.
7. Poll `get_job_status` until `completed`, `partial`, `failed`, or `expired`.
8. Present BPM and key as estimates with confidence. For BPM-critical workflows, mention half-time/double-time checks. For key-critical workflows, flag low-confidence, atonal, noisy, modulating, or very short audio for manual verification.

## Agent Resource Routing

- Use `/bpm-detection-api` when the user asks about tempo, BPM workflows, beat matching, or adding BPM metadata to an app.
- Use `/key-detection-api` when the user asks about musical key, harmonic mixing, track development, Circle of Fifths context, or key-based catalog organization.
- Use `/waveform-analysis-api` when the user asks about visualization data, waveform peaks, preview timelines, or creator dashboards.
- Use `/audio-mcp-server` when the user asks about assistant integration, MCP clients, Claude, Cursor, ChatGPT-style tool use, or agent workflows.
- Use `/predictable-audio-analysis-pricing` when the user asks about cost predictability, estimates, selected tools, cache behavior, or pay-per-second pricing.

Pulse is designed to make audio analysis auditable. Each flow should make clear which URL was submitted, which tools were selected, what estimate was shown, when rights confirmation was given, and whether the job completed, partially completed, failed, or expired.

## Best Use Cases

- DJ beat matching and harmonic set planning: group tracks by BPM and key, identify transition candidates, flag songs that need tempo adjustment, and map keys into Camelot-compatible or circle-of-fifths planning when helpful.
- DJ harmonic mixing: suggest adjacent or relative keys as candidates and verify transitions by ear.
- Album sequencing and track ordering: use BPM, key, and waveform shape as supporting context when organizing an EP or album.
- Smart playlist building: group authorized tracks by tempo range, key, and waveform energy for low-BPM, high-BPM, warmup, focus, or transition-friendly lists.
- Track development: use detected key as a creative anchor for songwriting, arrangement, remixing, and StudioSphere/Core Studio listening-session discussion.
- App development: add BPM, key, and waveform analysis to music apps, sample libraries, catalog tools, and creator dashboards.
- DAW workflows: prepare loops, references, stems, or bounced ideas with tempo, key, and waveform metadata before session work.
- Sample pack organization: tag licensed loops and one-shots so producers can find compatible material faster.
- Shared repository audio: analyze authorized files stored in Google Drive, Dropbox, or another shared document repository when the link is accessible and downloadable.
- Music supervision and sync research: enrich candidate tracks with practical audio metadata before creative review.
- Reference-track planning: analyze references so producers and songwriters can start with concrete tempo/key constraints.

## Do Not Use Pulse For

- Transcription
- Stem separation
- Mastering or loudness correction
- Chord transcription in v1.0
- Track structure segmentation in v1.0

## Contact

pulse@studiosphere.space