FAQ and troubleshooting

Answers to the most common questions and step-by-step fixes for common problems.

This page answers the most common questions about Spatial9, grouped by topic, and ends with step-by-step fixes for common problems. It covers the product, input and output formats, Eclipsa Audio on YouTube, AI assistants and the MCP server, the A2A agent, automation and enterprise pipelines, and limits.

It is for artists, engineers, developers and operations teams. Each answer is short and links to the reference page that covers the topic in depth.

General

What is Spatial9

Spatial9 is an AI-powered platform that transforms stereo audio into immersive spatial audio for streaming platforms such as Apple Music, YouTube, Amazon Music and Tidal. You can use it in the browser, from an AI assistant through the MCP server, from other agents through the A2A agent, or from your own code through the REST API. See Introduction.

Can I start with a finished song or video

Yes. Bring a completed stereo song or a finished video, and Spatial9 produces an immersive version from it. Original stems help but are not required.

Do I need stems or audio engineering experience

No. If you have stems, you can supply them, but Spatial9 can separate an existing mix. You do not need to operate a mixer or position sources yourself. For Eclipsa Audio, stereo files are processed directly. For ADM BWF, stems give better results but are not required. See Stereo vs stems.

How do the Music and Video workflows differ

Music is available now. Video production is in early access, and you can request an invite. See Choosing a workflow.

What is included in Enterprise

Enterprise plans include custom processing volumes, dedicated support, white-label options, custom training on your catalog and SLA guarantees. See /pricing and Enterprise data platforms.

Files and formats

What input formats are supported

Spatial9 accepts WAV, MP3, FLAC and AIFF. The converter also accepts ADM BWF masters, and AC-3, E-AC-3 and TrueHD files, whose speaker channels are decoded up to 7.1 and converted to Eclipsa Audio.

What quality should my input files be

For best results, use 24-bit WAV files at 48 kHz or higher. Files up to a 96 kHz sample rate are accepted.

What files will I receive

Deliverables depend on your plan and the request. They include immersive formats such as ADM BWF, Eclipsa Audio (IAMF), binaural and Ambisonics, as well as standard stereo. Through an AI assistant you can also receive Eclipsa Audio in MP4, a YouTube-ready MP4 video, a binaural headphone WAV, separate instrument tracks and short vertical clips. See Formats overview.

Which platforms support spatial audio

Many VR and AR platforms also support spatial audio. See Publishing and delivery.

Will my Dolby Atmos objects stay as objects in Eclipsa Audio

No. Eclipsa Audio stores channel layouts and Ambisonics, so objects are rendered into the scene, for example as third-order Ambisonics. Their position and movement remain, but the ability to edit them separately does not. See Eclipsa Audio and IAMF.

Eclipsa Audio and YouTube

Can I convert Dolby Atmos to Eclipsa Audio for free

Yes. The Spatial9 ADM to Eclipsa converter is free with an account, accepts ADM BWF masters (WAV or BWF) and adds no watermark. It also scores how well the conversion kept your mix. The open-source iamf-tools encoder from the Alliance for Open Media is also free. See ADM to Eclipsa and /adm-to-eclipsa.

Does YouTube support Eclipsa Audio uploads

Yes. YouTube's recommended upload settings list Eclipsa Audio with a channel layout of "Stereo + Eclipsa Audio" at 48 kHz. Upload a video MP4 that contains the IAMF track.

How do I know YouTube is playing Eclipsa Audio

Right-click the player and open Stats for nerds. opus (773) means the Eclipsa Audio stream is playing; opus (251) means you are hearing stereo.

How can I listen to Eclipsa Audio on my computer

Use Chrome 153 or later, set your audio device to its full speaker layout and open the video through YouTube's TV interface. On headphones, use the Spatial9 binaural version, the iamf-tools web demo or the libiamf decoder. See Binaural and headphones.

AI assistants and MCP

What is the Spatial9 MCP server

It is a remote Model Context Protocol server at https://spatial9.ai/mcp that gives AI assistants 37 tools for immersive audio. Assistants can create Eclipsa Audio from songs, stems and videos, convert Dolby files, remix in 3D, make social clips and publish to YouTube. See MCP server.

Which AI assistants work with Spatial9

Any assistant that supports remote MCP servers, including ChatGPT (paid plans with Developer mode), Claude, Gemini (app and CLI), Grok, coding tools such as Claude Code, Codex, Cursor, VS Code and Windsurf, and agent builders that support remote MCP servers for models such as Qwen, Kimi and DeepSeek.

How do I add Spatial9 to my AI assistant

Open /connect, choose your assistant, paste the Spatial9 server address into its connector settings and approve the Spatial9 sign-in. In Claude, use Settings, then Connectors. In the Gemini app, use Settings, then Apps, or run gemini mcp add in Gemini CLI. In Grok, use Connectors on grok.com.

Do I need an account to try Spatial9 in my assistant

No. Add https://spatial9.ai/mcp/free as a connector to get three chorus previews, one video in spatial audio, one ADM to Eclipsa Audio conversion and one stem split without an account. A full 3D song render needs a free Spatial9 account.

What should I say to my assistant

Ask in plain words, for example "Turn my song into 3D audio, start with a free chorus preview" or "Give my video spatial audio for YouTube". If you have no link to the file, the assistant gives you an upload link.

Can my assistant make my song sound like a specific room or stadium

Yes, with a Spatial9 account. Name the place in plain words, such as "intimate studio", "cathedral", "small jazz club" or "packed domed stadium from the back". Spatial9 has 6,700 ready-made spaces, including 40 kinds of stadium and arena in different sizes, empty or packed, heard up close or from far away. See Acoustic digital twin.

Can an agent publish to my YouTube channel

Yes, with your permission. You connect your channel once, the agent confirms the title, description and privacy with you, and then calls publish_to_youtube. Uploading as private or unlisted first is the safest way to check the result.

Is my audio safe when an agent uses Spatial9

Connections use OAuth with a single spatial_audio scope and short-lived tokens, or a personal key you can revoke. Your renders stay in your Spatial9 account. Streaming pages cannot be used as input, so the agent works only with files you provide.

What are Spatial9 Agent Skills

They are free instruction packs in the open SKILL.md format that teach AI agents to use Spatial9: immersive mixes, stem splits, Dolby and ADM to Eclipsa Audio conversion, free chorus previews, remixing by voice, YouTube publishing and governed enterprise catalog renders. They work in any agent that reads the Agent Skills standard. See Agent Skills and /agents/skills.

What is the difference between the MCP server and the REST API

The MCP server is for AI assistants and agents that work through conversation. The REST API at https://api.spatializer.spatial9.ai/api/v0.0.1 is for your own code: you send files with tus resumable uploads, choose Dolby Atmos or Eclipsa Audio output, poll status and download. Both use the same Spatial9 engine. See REST API.

A2A agent

What is the Spatial9 A2A agent

It is an Agent2Agent (A2A) protocol endpoint at https://spatial9.ai/a2a, implementing A2A 0.3.0. Other AI agents read its Agent Card, send it a task with a song or video, and receive immersive audio files when the render finishes. It uses the same Spatial9 account, key and plan as the MCP connector. See A2A agent.

How does A2A differ from the MCP connector

MCP connects an AI assistant to tools, so the assistant calls Spatial9 directly. A2A connects agents to agents, so your agent hands a whole task to the Spatial9 agent and follows it until the files are ready. Both use the same account and plan.

How does an agent sign in

With a personal Spatial9 key that starts with s9_, sent as Authorization: Bearer or X-API-Key, or with OAuth 2.1 and PKCE using the spatial_audio scope. Create a key at /connect.

Does the agent support streaming and push notifications

Yes. message/stream and tasks/resubscribe send live status and artifact updates, and tasks/pushNotificationConfig sets webhooks that receive the task whenever its state changes. Push notifications carry your token in the X-A2A-Notification-Token header. Polling tasks/get also works.

Which agent frameworks can use it

Any client that speaks A2A 0.3.0 over JSON-RPC, for example an agent built with Google ADK, or a plain HTTP request from a workflow tool. See Agent frameworks.

Automation and enterprise

Can I automate a catalog or integrate Spatial9

Yes. Teams can submit in batches, track job status and integrate through the API and webhooks. The Agent Skills repository includes Python, Node.js, GitHub Actions and Apache Airflow examples. See Workflow automation.

Can I use Spatial9 with n8n

Yes. Use the MCP Client Tool node with an AI Agent node when a model should choose the steps, or HTTP Request nodes for a fixed workflow that starts a render, waits, checks the status and collects the downloads.

Can I use Spatial9 with Zapier or Make

Yes. Start a render with a custom HTTP request to https://spatial9.ai/a2a and include a webhook address. Spatial9 calls that webhook, such as a Zapier catch hook or a Make custom webhook, whenever the task changes, so the flow continues when the render is complete.

Which enterprise platforms are supported

The Agent Skills repository includes recipes for Databricks, Snowflake, Google Cloud with Vertex AI, and AWS with Amazon Bedrock, plus a shared Python MCP client and A2A client for any runtime. See Enterprise data platforms.

What is the Databricks Solutions Accelerator

A free, deployable Databricks Asset Bundle with six notebooks that takes a music catalog from a Unity Catalog Volume to finished immersive files. It routes each track through the MCP server, the A2A agent or the Spatializer REST API, respects the render limits, retries safely with idempotency keys and writes an audit table and gold views. See Databricks Solutions Accelerator.

When should I use MCP, A2A or the REST API

Can I build a pipeline with only open-source tools

Yes. MinIO, Apache Kafka, PostgreSQL, FFmpeg, Dagster, FastAPI, Valkey, Prometheus and Grafana cover storage, events, state, audio checks, scheduling, real time and monitoring. Spatial9 is reached over MCP and A2A on HTTPS, so no proprietary SDK is needed. See Open-source real-time pipeline.

Limits and billing

What limits apply

Each render uses one project from your plan. Chorus previews are free. See Limits and quotas.

How long does a render take

Processing time varies with file length and complexity. A full song usually takes 10 to 20 minutes, a stem split 4 to 8 minutes, a short video a few minutes and a free chorus preview under two minutes. A remix of a finished song reuses the separated stems and usually takes 3 to 6 minutes. You can close the chat; Spatial9 emails the links when the job finishes.

How do I avoid paying twice when a workflow retries

Send the same idempotency_key with every retry of the same song, or reuse the same A2A messageId. Spatial9 returns the original job instead of starting a new one.

What happens when a render fails

A failed render refunds its project automatically. Cancelling an A2A task with tasks/cancel is refunded if paid processing had not started.

Troubleshooting

My link is rejected as a source

Links must download the file directly. YouTube, Spotify and other streaming pages cannot be used as input.

1. Check that the URL returns the audio file itself over https.
2. If it does not, ask your assistant for an upload link, or call create_upload_link.
3. Upload the file to the returned link within 2 hours; files can be up to 2 GB.

I receive HTTP 401 or "Spatial9 rejected the key"

The key is wrong, missing or revoked.

1. Confirm that the header is Authorization: Bearer s9_... with no extra spaces or quotes.
2. Confirm that the secret store or credential holds the current key.
3. If the key leaked or was revoked, create a new one at /connect and update every secret that uses it.

A render will not start because of a limit

You have 3 renders running or have started 20 in the last 24 hours.

1. Wait for a running render to finish, or for the 24-hour window to move.
2. Queue the extra work instead of retrying in a loop.
3. In pipelines, count running jobs before starting new ones.

A retry started a second render

The idempotency key or messageId changed between attempts.

1. Build the key from stable values only, such as the track ID and version or the ISRC.
2. Never include timestamps or random values in the key.

My job seems stuck

1. Poll get_job_status or tasks/get every 30 to 60 seconds; songs usually take 10 to 20 minutes.
2. If you use webhooks, also poll tasks that have had no update for several minutes.
3. If an A2A task is in input-required, Spatial9 needs a file; check the source path or link.

My webhook never receives updates

1. Confirm that the URL is https, on a public host and on port 443.
2. Confirm that your endpoint accepts the push and checks X-A2A-Notification-Token against the token you registered.
3. Re-read the task with tasks/get instead of trusting the posted body.

A download link does not work

Download links are temporary and signed.

1. Use only links returned by get_downloads or A2A task artifacts; never build URLs yourself.
2. Request the links again with get_downloads if they have expired.
3. Copy the files into your own storage if you need them long term.

YouTube plays my video in stereo

1. Check Stats for nerds: opus (251) means stereo.
2. Confirm that you uploaded an MP4 containing the IAMF track, at 48 kHz.
3. To hear Eclipsa Audio on a computer, use Chrome 153 or later with the full speaker layout and YouTube's TV interface, or use the binaural version on headphones.

My file is rejected as unreadable or too short

1. Confirm that the file is real audio in a supported format: WAV, MP3, FLAC or AIFF.
2. The open-source reference pipeline rejects files shorter than 30 seconds in its FFmpeg check.
3. Re-export the file as 24-bit WAV at 48 kHz if problems persist.

Next steps

• Quickstart: render your first immersive track.
• Limits and quotas: the complete list of limits and how they are counted.
• MCP server: connect an AI assistant and see every tool.
• Formats overview: compare Eclipsa Audio, ADM BWF, Ambisonics and binaural.