Choose the right workflow
Compare the app, AI assistants (MCP), agents (A2A), the REST API and the Acoustic Digital Twin, and pick the one that fits.
Spatial9 runs one engine behind several entry points: the web app, AI assistants connected through MCP, agents that delegate work over A2A, the REST API, Agent Skills, workflow automation tools and the Acoustic Digital Twin for real-time streams. This page describes each entry point, compares them side by side and gives you a decision procedure for choosing one.
Read this page when you know what you want to produce but not yet how to drive Spatial9. It is written for creators, developers, automation teams, data teams and product owners. Every entry point described here produces the same kind of render and, except for the Acoustic Digital Twin, shares the same account limits.
The entry points at a glance
| Entry point | Who drives it | Interface | Authentication | Best for |
|---|---|---|---|---|
| Web app | A person | Browser at app.spatial9.ai | Spatial9 account | Hands-on mixing, review and export |
| MCP server | An AI assistant or agent | https://spatial9.ai/mcp | OAuth or a personal s9_ key | Working with Spatial9 by conversation |
| A2A agent | Another agent | https://spatial9.ai/a2a | s9_ key or OAuth 2.1 with PKCE | Delegating tasks between agents |
| REST API | Your own code | https://api.spatializer.spatial9.ai/api/v0.0.1 | API key | Embedding renders in a product or backend |
| Agent Skills | A coding or chat agent | SKILL.md files plus the MCP server | Same as MCP | Teaching agents the correct procedure |
| Workflow tools | An event or schedule | n8n, Zapier, Make, Airflow and others | s9_ key in a secret store | Unattended pipelines |
| Acoustic Digital Twin | A device or service | Cloud API, on-prem, native SDK or device builds | Enterprise license | Real-time stereo-to-immersive playback |
Web app
The web app is the direct, human-operated route. You upload a stereo master or stems, Spatial9 generates the spatial arrangement, and you review, adjust and export. The app exposes the full set of mixing controls: the movement library, section staging, effects, the Mix Console and export presets. It is also the home of the ADM to Eclipsa Audio converter at /adm-to-eclipsa.
Choose the web app when you want to listen and make decisions yourself, when you are learning, or when you are working on one release at a time. See Quickstart and Spatializer for Music.
MCP server for AI assistants
The Model Context Protocol (MCP) connects an assistant to tools. Spatial9 is an MCP server: an assistant lists its tools, then calls them with typed arguments. Messages are JSON-RPC 2.0 over HTTP. The server supports protocol versions 2025-06-18, 2025-03-26 and 2024-11-05.
| Detail | Value |
|---|---|
| Address | https://spatial9.ai/mcp |
| Free guest address | https://spatial9.ai/mcp/free, no sign-in |
| Tools | 37, grouped into create, convert, shape, share, learn and manage |
| Clients | ChatGPT, Claude, Gemini, Grok, Claude Code, Codex, Cursor, VS Code and agent builders for open models |
| Sign-in | OAuth inside the assistant (scope spatial_audio), or a personal s9_ key as a Bearer token |
| Typical render | 10 to 20 minutes for a song, a few minutes for a short video |
The assistant handles intent (which song, which style, which privacy setting) and Spatial9 handles the audio. An agent calls get_capabilities first, so it only offers formats and features that exist. The guest address includes three chorus previews, one video in spatial audio, one ADM to Eclipsa conversion and one full stem separation.
Choose MCP when a person wants to work by conversation, for example "make this song immersive and put it on my channel as unlisted", or when you build a single agent with a framework that has an MCP client. Coding tools connect with one command:
claude mcp add --transport http spatial9 https://spatial9.ai/mcpSetup for each assistant is on the connect page. The full reference is MCP server reference.
A2A agent for agent-to-agent work
The Agent2Agent protocol (A2A) connects agents to other agents. Where MCP lets your agent use Spatial9, A2A lets another agent ask Spatial9 to do a job and follow the task through its lifecycle.
| Detail | Value |
|---|---|
| Endpoint | https://spatial9.ai/a2a |
| Agent Card | https://spatial9.ai/.well-known/agent-card.json |
| Protocol | A2A 0.3.0, JSON-RPC 2.0 over HTTP POST |
| Skills | spatial_audio, split_stems, convert_dolby, preview_chorus, upload_link |
| Updates | Streaming with message/stream and tasks/resubscribe, push notification webhooks, or polling tasks/get |
| Idempotency | messageId is the idempotency key |
| Webhook verification | Each delivery carries the X-A2A-Notification-Token header |
Remixing and YouTube publishing stay on the MCP server. If you need them over A2A, build your own specialist agent on the Spatial9 MCP tools and expose it over A2A.
Choose A2A when an enterprise agent studio or an orchestrator should hand spatial audio work to a specialist without handling MCP tools itself, or when you need task states and push notifications for back-end workflows. See A2A agent reference.
| MCP | A2A | |
|---|---|---|
| Connects | An agent to tools and data | An agent to another agent |
| Discovery | tools/list on the server | An Agent Card at a well-known address |
| Unit of work | A tool call with typed arguments | A task with a lifecycle and artifacts |
| Long jobs | The tool returns a job ID; the agent polls | Task states and streamed status updates |
REST API for your own code
The REST API is the route for software that does not involve an agent. You create a music with POST /musics, choose output formats with the formats query parameter (atmos, iamf or both), upload audio with the tus resumable upload protocol, then poll status and download.
curl -H "Authorization: YOUR_API_KEY" \
https://api.spatializer.spatial9.ai/api/v0.0.1/musics/MUSIC_ID/statusBecause one request can produce both Dolby Atmos and Eclipsa Audio, a distributor or platform can serve both ecosystems from a single upload. Choose the REST API when you embed spatial audio in a product for your own users, when you need direct control over uploads and status, or when you run batch jobs from a backend. See REST API reference and the API page.
Agent Skills
An Agent Skill is a folder with a SKILL.md file: a short frontmatter with a name and description, followed by plain-language instructions. The MCP server gives an agent the tools; a skill gives it the procedure, such as which tool to call first, when to offer a free preview, how long to wait and which mistakes to avoid. Agents load only the name and description until a request matches, then read the full instructions.
The Spatial9 skills repository at /agents/skills contains the following skills.
| Skill | Purpose |
|---|---|
spatial9-immersive-mix | Song, stems or video to Eclipsa Audio with a binaural version |
spatial9-stem-split | Separate a song into instrument stems |
spatial9-atmos-to-eclipsa | Convert Dolby or ADM BWF masters to Eclipsa Audio |
spatial9-chorus-preview | Free 30-second headphone preview of the chorus |
spatial9-remix-by-voice | Change a finished mix from plain language |
spatial9-release-publisher | Publish to YouTube and make 9:16 social clips |
spatial9-enterprise-catalog | Governed catalog renders from Databricks, Snowflake, Vertex AI and Bedrock |
Choose Agent Skills in addition to MCP whenever an agent such as Claude Code, Codex, GitHub Copilot, Cursor or Gemini CLI will use Spatial9 repeatedly. See Agent Skills.
Workflow automation tools
Any tool that can send an HTTPS POST can run a render. n8n offers an MCP Client Tool node for AI agents and an HTTP Request node for fixed flows; Zapier, Make, Power Automate, Pipedream, UiPath, GitHub Actions and Airflow use HTTP requests and webhooks. Every pipeline follows the same lifecycle: upload, start the render with an idempotency key, follow status by polling or webhook, collect the files, and let a person approve anything public.
Choose workflow tools when the trigger is an event, such as a new file in a folder, a pushed master or a nightly catalog job, and no model is needed for the normal path. See Workflow automation. For governed catalog pipelines on data platforms, see Enterprise data platforms.
Acoustic Digital Twin
The Acoustic Digital Twin (ADT) is different from every other entry point. It does not render a finished file in a job; it processes a continuous stream of stereo or mono audio in real time and renders it as immersive audio while it plays. ADT is deployed as a cloud API, in a private cloud or on premises, as native C and C++ libraries inside other software, or directly on phones, cars and other devices.
Choose ADT when audio must be spatialized live, for example in a car, on a device system-wide, across a streaming catalog without pre-rendering, or inside a broadcast chain. ADT is an enterprise license. See Acoustic Digital Twin.
Decision procedure
Answer the following questions in order. Stop at the first question that matches your situation.
- Does audio need to become immersive while it plays, on a device or in a live stream? Use the Acoustic Digital Twin.
- Do you want to listen and adjust the mix yourself, one release at a time? Use the web app.
- Do you have a Dolby Atmos ADM BWF master that you want on YouTube? Use the ADM to Eclipsa Audio converter in the app, or the conversion tools over MCP or A2A.
- Will a person work through a chat assistant or a coding agent? Use the MCP server, and install the Agent Skills.
- Will another team's agent or an enterprise agent studio delegate the work? Use the A2A agent.
- Is the work triggered by a file, an event or a schedule, without a model in the loop? Use a workflow tool with the HTTP lifecycle.
- Is the work a governed catalog batch on a data platform? Use the enterprise data platform recipes.
- Are you embedding spatial audio in your own product for your own users? Use the REST API.
Example scenarios
| Scenario | Recommended route | Reason |
|---|---|---|
| An independent artist prepares a release | Web app, or MCP in a chat assistant | Direct listening and approval, optional publishing by conversation |
| A label converts a back catalog | A2A or workflow tools, or a data platform job | Batches, retries and idempotency within the limits |
| A YouTube creator adds spatial sound to videos | MCP with the release publisher skill | Render, clip and publish with human confirmation |
| A post house delivers Atmos mixes to YouTube | ADM to Eclipsa Audio converter | Keeps beds and objects from the ADM BWF master |
| A music school teaches immersive mixing | Web app and the Academy, or MCP learning tools | Lessons, classroom studio and genre guides |
| A platform adds immersive playback to its own app | REST API | Direct uploads and status checks, no agent required |
| A carmaker spatializes radio and alerts | Acoustic Digital Twin on the device | Real time, offline, any speaker layout |
Shared limits and guardrails
The MCP server, the A2A agent and the pipelines and skills built on them run against the same account limits and server-side guardrails.
| Limit or guardrail | Value |
|---|---|
| Concurrent renders | 3 |
| Renders per day | 20 per 24 hours |
| A2A tasks | 120 per hour |
| YouTube publishes | 5 per 24 hours |
| Idempotency | idempotency_key on MCP renders; messageId on A2A |
| Failed renders | Refunded automatically |
| Free previews | preview_chorus and remix_render with preview: true |
| Publishing | Requires explicit confirmation from a person |
Next steps
- MCP server reference: connect an assistant and see the tool groups.
- A2A agent reference: send tasks, stream progress and register webhooks.
- REST API reference: upload, render and download from your own code.
- Acoustic Digital Twin: evaluate real-time deployment options.