# AI tools and integrations

You can use EditorBrain's tools or tools you have connected to your agent. They are different access and billing routes.

| Tool | Result | Usual input |
| --- | --- | --- |
| Tempo | Transcription and per-word times | Prepared audio from your video |
| Prism | An image for a scene | Description, quality and format |
| Vox | Narration | Compatible text and language |
| Aura | Instrumental music | Musical intent and a target duration |

In **AI tools**, each card opens the settings for Tempo, Prism, Vox or Aura. Saving changes the tool chosen for the active brand; it does not generate media and it does not charge. The Vox selector lets you listen to samples and save a voice. Switching brands does not silently reuse their settings.

The web configures how you want the agent to use them. Seeing them in the interface does not mean they are all active. **Check `studio catalog` before you quote.**

```sh
editorbrain studio catalog
editorbrain integrations list
editorbrain billing status
```

## Your personal integrations

On [Integrations](https://editorbrain.com/app/integrations), name the tools you want to use from your agent. EditorBrain stores their purpose and your preferences; **it does not store keys and it does not connect those accounts**. The connection is configured in Claude, Codex or the environment where your agent runs.

For example: you connect Higgsfield in Claude, configure it in EditorBrain and choose what you want to use it for. When it prepares an edit, the agent reads that preference and checks whether it really has access to Higgsfield in that session. Installing EditorBrain's MCP does not install or authenticate other applications' connectors.

### Add your tool

You can choose a suggestion from the catalog or **Add tool** for any service of your own. Provide:

- **Name and purpose:** what it is called and what you want to use it for.
- **Capabilities:** images, clips, voice, music, transcription or another function.
- **Method:** MCP, CLI or a tool native to the agent; you can also indicate a configured API, a browser or file delivery.
- **Environment:** Claude, Codex or another. The optional connector or executable name helps find it; it does not run saved instructions.
- **Preferences:** model, language, voice or notes when they apply, and whether the agent should ask about spend or use a budget that is already approved.

Do not paste keys, tokens, passwords, install commands or private access links. Registering a tool means **access you indicated**; its availability, session and balance are checked when the agent is about to use it. You can turn it off without losing the configuration.

### Use it from AI tools

Mark an integration as preferred for images, narration, music or transcription. In **AI tools**, select **My external tool** so that brand uses the preference of the person who is editing.

They are two different decisions: your integration is personal inside the workspace; the tool route is a brand preference. Another member does not receive your connections or private notes: they use their own. Choosing a preferred one also does not replace a concrete provider already chosen for the brand or the video.

If the integration is missing, turned off or absent in that session, the agent explains what is pending and proposes how to continue. It does not automatically switch to a paid tool. Moving from Claude to Codex requires checking the connection in the new environment; a saved preference does not transfer a session.

Preferences are recovered when the project is queried. Saving them on the web does not interrupt or change a generation that is already in progress.

An insufficient EditorBrain balance does not mean your external provider has no balance. The agent must explain the route it will use and its cost; it must never switch to another paid route silently. Your project's constraints still apply.

## Tempo: from MP4 to a transcript

### Choose how to transcribe

In **AI tools → Transcription**, save the option for your brand. The agent respects first what you ask for this edit, then your saved preference. If you have not chosen, it proposes Tempo; you can use another option.

| Option | Advantage | What you need |
| --- | --- | --- |
| EditorBrain Tempo | Integrated, with no extra key to manage | Availability and EditorBrain credits for the authorized job |
| Your AssemblyAI account | Uses your own access and balance | A connection your agent can use and the provider's budget |
| Whisper online | Processes on the service you choose | Identify that service and check its access, formats and cost |
| Whisper local | Transcribes on the agent's machine, with no EditorBrain credits | Engine and model installed; time, memory and disk available |

**You can edit on Free or with zero EditorBrain credits by using your own route or an existing transcript.** External services can have their own costs. The selection does not connect accounts, install models or authorize spend. Configure personal access in Integrations; do not paste keys into preferences. On a cloud agent, "local" means its execution environment.

All four routes serve the same editing flow. The agent keeps the source and the real times of the transcript and adapts them to the cuts. Karaoke needs per-word times; a phrase transcript still works for planning and phrase captions. It does not attribute Whisper to Tempo and it does not change provider without a prior choice or authorization. Premium library, search, storage and render permissions stay independent.

These saved options require CLI/API and web 0.44.0 or later. Your own routes run through the tools available to your agent; they are not transcription adapters hosted by EditorBrain.

```sh
editorbrain studio prepare --file ./recording.mp4 --out .editorbrain-local/studio/audio.wav
editorbrain assets upload .editorbrain-local/studio/audio.wav --project my-project --mime audio/wav --purpose temporary
```

Preparation is local and requires FFmpeg/FFprobe. It extracts 16-bit PCM WAV; if there are several tracks, choose the right one. Use the hash the upload returns as `assetId` in `tempo.json`:

```json
{"tool":"tempo","projectId":"my-project","assetId":"REPLACE_WITH_THE_AUDIO_SHA256","language":"es"}
```

```sh
editorbrain studio quote --file tempo.json
```

The placeholder is not a valid hash: replace it before you send. Tempo allows up to 30 minutes per job. If you split an audio, keep each segment's offset so words can be related to the original video. `tempo` is the recommended request name; older responses may keep `scribe` for compatibility.

### Proper names: your brand glossary

Tempo uses your brand glossary to recognize proper names and technical terms better, such as "Claude", "Claude Code" or your product's name. When it quotes, it takes from the brand's `language.json` the names in `doNotTranslate` and the terms in `glossary`. Each term can be text or an object with `term`, for example `"glossary": ["Claude", "Claude Code", {"term": "HyperFrames", "meaning": "Animation engine"}]` and `"doNotTranslate": ["EditorBrain"]`.

- It sends up to 1000 terms of at most 6 words. If there are more, the rest are omitted.
- The transcript includes `glossary` with the terms used (`terms`) and the omitted ones (`omitted`).
- It helps recognition, but it does not guarantee spelling: review proper names.
- Tempo's credit price does not change. Without a glossary, transcription works as before.
- If you change the glossary, quote again; finished transcripts are not redone.

When your agent manually corrects a badly transcribed word, it proposes adding it to the glossary. It saves it only if you accept.

## Prism: a request example

Save in `image.json`:

```json
{"tool":"prism","projectId":"my-project","prompt":"A clear illustration of a calendar with organized tasks, no text","quality":"essential","resolution":"1K","aspectRatio":"9:16"}
```

```sh
editorbrain studio quote --file image.json
```

Omitting compatible parameters lets saved preferences be inherited. An explicit parameter that contradicts those preferences may need a justified exception; do not invent a reason to skip a constraint.

Aura uses `tool: "music"`, `prompt` and `durationSeconds` (30, 60 or 120). The complete schemas are in the [MCP reference](https://editorbrain.com/en/docs/mcp-tools). The duration you ask Aura for is a generation target, not a promise that the delivered audio will measure exactly that.

## Vox: choose a voice for the brand or the video

Look up the catalog and filter by language, accent, gender or text. Results include public aliases, characteristics and a sample when one is available:

```sh
editorbrain studio voices --language es
editorbrain studio voices --accent american --gender female --query warm
editorbrain studio voice --brand my-brand
editorbrain studio voice --project my-project
```

Catalog languages say which languages the voice can synthesize; the sample has its own `preview.language`. The accent describes the original voice in English and does not guarantee a regional accent when speaking Spanish. Listen to the sample and review the generated narration before you treat that result as confirmed.

The selection read returns `path`, `revision`, the saved voice and the effective voice, including its inheritance. To save, use a catalog alias and the revision you just read. For example, if it returned revision `2`:

```sh
editorbrain studio voice narrator --project my-project --expected-revision 2
```

Choose one scope: `--brand` changes that brand's default voice; `--project` changes that video's voice. A revision of `0` means its audio document does not exist yet. If another session changed it, read it again before you save. The rest of `audio.json` is kept, including music, SFX and loudness. The command saves in the cloud. Before you edit or upload your local copy, review `editorbrain pull --project my-project --dry-run`, reconcile any local change and then pull the project. Do not discard local work to force that update.

In MCP use `list_vox_voices`, `get_vox_voice_selection` and `set_vox_voice_selection`. Samples need authenticated access; looking up their link does not mean you listened to them. Choosing a voice or listening to a sample does not generate a narration and does not spend credits. It also does not change the project's decision to keep the original voice or to skip narration.

Save a request in `vox.json` with the exact text:

```json
{"tool":"vox","projectId":"my-project","text":"This is my video's narration."}
```

```sh
editorbrain studio quote --file vox.json
```

When you omit `voice`, the quote inherits the effective EditorBrain voice that is saved. You can indicate an explicit alias that is compatible with the preferences; an unknown alias produces an error, without replacing it with another voice. Review the voice and language the quote resolved. Narration constraints and spend approval still apply before you run it.

## References for Prism Premium

Available with API 0.43.0 or later. Before you use it, check that `studio catalog` announces `capabilities.referenceImages` for Prism; an example in the documentation does not turn a provider on.

Upload the selected images with `assets upload` and add `"referenceAssetIds":["REAL_SHA256_OF_THE_IMAGE"]` to the request. Up to four PNG, JPEG or WebP files from the workspace are accepted, in the order given, with a maximum of 8 MiB per image and 20 MiB in total. Select `"quality":"premium"`; it is not switched to a more expensive model automatically. Saved preferences still apply.

Quoting does not send the images to the provider. When you authorize the run, those references are transferred; review the amount and the images before you confirm. Keeping a likeness to a logo or a character requires inspecting the result. Do not use external links or images from another workspace.

## Quote, authorize and run

The quote returns `quoteId`, credits and an expiry. It does not start generation. After the user authorizes that job or a budget that covers it:

```sh
editorbrain studio run QUOTE_ID --max-credits AUTHORIZED_LIMIT --user-confirmed
editorbrain studio get JOB_ID
```

Replace the placeholders with real values. `--user-confirmed` records an existing authorization; it does not create one. The server checks permissions, context and balance and reserves the credits before it sends the job.

## Queues, polling and errors

| Status | What to do |
| --- | --- |
| `queued`, `submitting`, `running` | Look up the same ID with a wait; do not create another quote to duplicate it |
| `completed` | Read the result files, download them and inspect them |
| `failed` | Read the error and the recovery; check the balance before a new attempt |
| `needs_attention` | Uncertain or delayed result; review the history and ask for help if it persists |

For automation, use growing, bounded waits (for example 2, 5, 10 and 20 seconds), respect `Retry-After` and stop polling on final or attention states. This is a client guideline, not a provider time guarantee.

```sh
editorbrain studio jobs
editorbrain assets download SHA256 --out ./result.png
```

A confirmed failure can release the reservation; an uncertain result needs reconciliation so you do not duplicate charges or generations. Repeating a command blindly is not recovery. See [errors](https://editorbrain.com/en/docs/errores) and [credits](https://editorbrain.com/en/docs/creditos).
