# Studio productions

> Direct a film from an AI assistant as a studio production, validate the plan for free, generate frames and motion with quotes, and keep editing in Studio.

Source: https://nodaro.ai/docs/mcp/studio-productions

A **studio production** is a film that an AI assistant can direct from a conversation and that you keep editing in the Studio editor at [studio.nodaro.ai](https://studio.nodaro.ai). It is an ordered list of scenes, each with a frame, an optional motion, and the plan, looks, cast and voice that made them. An assistant can draft the film, hand it over, and pick it up again after you moved three scenes around. Studio productions are a Nodaro Cloud feature.

Choose this lane for "make me a film, a scene or a sequence, and let me keep editing it". For a movie written as one JSON document, see [Recast](https://nodaro.ai/docs/mcp/recast); for a workflow on the canvas, see the [Film Director](https://nodaro.ai/docs/mcp/film-director).

## Two vocabularies

The editor and the production document name the same things differently. The person only ever sees the editor, so an assistant speaks the editor's words and keeps the document's names for tool calls.

| The user says | The document says |
| --- | --- |
| **film** | the production |
| **scene**, such as "Scene 3", a card on the timeline | a `shots[]` entry, addressed by `shot_id` |
| a scene's **frame**, whose results are takes | `still` |
| a scene's **motion**, whose results are takes | `clip` |
| the **shots** inside a motion | `beats[]`, set with `set_beats` |

- **"Scene N" is always the N-th entry of `shots[]`.** "Rename scene 3" is `rename_shot` on it, and "delete scene 3" is `remove_shot` on it.
- **"Shot" means a shot inside a motion**, an entry of `beats[]` of the scene the user is looking at, never a `shots[]` entry. When no scene is in view, or its motion has fewer shots than the user named, the assistant asks instead of guessing.
- **A scene's frame is its `still`.** A planned frame is something else: a frame plan the user reviews and accepts, made with `generate_studio_keyframe`. A scene's start frame and end frame are the endpoints of its motion.
- **Receipts use the document's words.** Operation names and the `receipts` of an edit say "shot" where they mean a scene; an assistant should not repeat that wording to the user.

## The loop

### Read the guide

`get_studio_production_skill` returns the guide in four parts: `operating` (the tools, the loop and the operations), `authoring` (the plan format), `catalog` (every picker, model and option) and `schema` (the plan's JSON Schema). It is generated from the live deployment, so it matches the server you use. Free.

### Validate the plan

`validate_studio_plan` checks a plan for free, saves nothing, and matches cast names against your own library. Fix each `errors[].path` until the plan is valid, before anything is spent.

### Create the production

`create_studio_production` creates a new film, with the plan's scenes if you pass one. `import_studio_production` adds a plan's scenes to an existing film. Both are free. For a story without a plan, `describe_studio_production` asks the Director to write the scenes, as an LLM run.

### Read it back

`get_studio_production` returns the film as it stands, and a `pending` block of what is still running. With write permission, the read first lands everything that finished, so a re-read is how a finished generation reaches its scene. Pass `shot_id` for a cheap read of one scene.

### Edit with operations

`edit_studio_production` applies a batch of operations. See [Editing](#editing-with-operations).

### Generate

`generate_studio_still` makes a scene's frame, `generate_studio_clip` its motion, `new_studio_shot_from_frame` takes a frame out of a motion, `voice_studio_shot` speaks a line, `revoice_studio_clip` recasts the voices of a motion, and `score_studio_production` writes the soundtrack.

### Export and share

`plan_studio_export` lists the steps that assemble the film, each with its price. `share_studio_production` opens or closes a share link, and `clone_studio_production` makes a copy.

An abandoned conversation strands nothing. The production is a real film you can open in the editor, and a generation that was still running lands the next time the production is brought up to date, by you, by the editor or by the next assistant.

## Editing with operations

Every change to a production is an **operation**, and `edit_studio_production` is the one tool that applies them. A batch is applied as one step against the newest version of the document.

- **Operations address things by stable keys**: a scene by its id, a cast member by its role slug, a result by its job id or URL. Never by position, because the user may be editing the same film in the browser.
- **A batch composed against a slightly older version still applies**, and the reply says it was rebased. `strict: true` with `expected_version` refuses instead.
- **One bad operation refuses the whole batch** and writes nothing. The error names the operation by its index, counted from 0; fix it and send the batch again.
- **`receipts` has one past-tense line per operation**, which is what to show a user who asks what just happened.
- **Some deletes can be undone.** A removed scene, take or planned frame goes to the production's bin and can be restored. Clearing a cast member, a voice or the soundtrack, deleting a cut, removing a sequence, purging a bin entry and emptying the bin cannot.
- **Sharing is not an operation.** It has its own tool, so an edit batch can never change who can see the work.
- **Deleting a production is not available.** Archiving it is an operation, and it can be undone.

The operation vocabulary is served, not printed here: `get_studio_production_skill` with `part: "operating"` returns what the deployment accepts.

### Preview a batch

`edit_studio_production` with `dry_run: true` answers what the batch would do and writes nothing. Each operation's receipt carries a class: `S` changes the document, `D` deletes, `P` changes who can reach the work, and `$` spends. A delete that would go to the bin is marked `restorable: true`. Show the preview to the user, then send the same batch without `dry_run`.

The tool checks first that the deployment supports previews, and refuses with `studio_preview_unavailable` if not, having sent nothing. The ids in a preview are not the ids of the real change: to undo, read the bin ids from the applied batch's receipts.

## Spending

An assistant that directs a film makes dozens of calls, so two habits matter.

- **Quote first.** `generate_studio_still` and `generate_studio_clip` accept `dry_run: true`, which returns the model and the price and writes nothing. `credits: null` means the price is unknown, not free. Show the price and let the user accept. The other spending tools have no quote: price them from the model, or ask first.
- **Retry safely.** Every spending tool accepts `client_request_id`, 8 to 128 characters of `A-Za-z0-9_.:-`. The same token answers with the jobs of the first call and charges nothing new. Make a new token for each new request, and never retry a spending call without one.

Generation is **run, then poll, then land**:

1. A frame or motion call returns its job ids at once.
2. Wait on those jobs with `get_job`, or watch the production's `pending` block.
3. Read the production again with `get_studio_production`. With write permission, the read lands every finished job before it answers.
4. Show the user what arrived.

With read-only permission, the read lands nothing, and a finished job stays in `pending` until someone who may write brings the production up to date.

## Confirmation marks

A tool that spends credits, or that changes who can see the work, says so in its own definition, in `_meta.nodaro.confirm`. A client can put a confirmation prompt in front of every tool with the mark, instead of keeping its own list.

| Mark | Why to ask first | Tools |
| --- | --- | --- |
| `$` | It costs credits. | `describe_studio_production`, `generate_studio_still`, `generate_studio_keyframe`, `generate_studio_clip`, `new_studio_shot_from_frame`, `voice_studio_shot`, `revoice_studio_clip`, `score_studio_production` |
| `P` | It changes who can see the work. | `share_studio_production` |

`edit_studio_production` has no mark: what a batch does depends on its operations. To confirm before a delete, preview the batch, where every operation is classed.

## Permissions

The seven spending tools need both `workflows:write` and `workflows:execute`. A connection that granted only one of the two sees none of them, without explanation, so grant both for generation. Reading needs `workflows:read`, and creating, editing, sharing and cloning need `workflows:write`. The [tools reference](https://nodaro.ai/docs/mcp/tools/studio-productions) lists each tool's permission and parameters.

## Availability

On a deployment that does not serve studio productions, every tool of the family answers `not_available`, a plain refusal that is not worth retrying. Call `list_studio_productions` to check before you offer the feature.

## Where the plan format is documented

The plan format, `nodaro-studio-production`, has one published home. The studio app serves the same authoring guide, catalog and JSON Schema at [studio.nodaro.ai/skills/studio-production/](https://studio.nodaro.ai/skills/studio-production/), so an assistant reading `get_studio_production_skill` and a person reading that page read the same document.

The same production lane is available over REST, at [Studio productions](https://nodaro.ai/docs/developers/api/studio-productions), and in the SDK as `client.studio.productions`.

## Frequently asked questions

### What is a studio production?

A film made of scenes, each with a frame, an optional motion, and the plan, looks, cast and voice that made them. It opens in the Studio editor at studio.nodaro.ai, so an assistant can draft it and you can keep editing it by hand.

### Why does the assistant call a scene a shot in some places?

The production document's keys call a scene a shot. In conversation, an assistant should always use your words, scene, frame, motion and shot, and keep the document's names only in tool calls.

### When does a finished generation appear in the film?

When the production is read again with get_studio_production by a session that may write. That read lands every job that finished since the last one. get_job and wait_for_job only report the status.

### Can an edit be undone?

Many deletes can. A removed scene, take or planned frame goes to the production's bin and can be restored. Clearing a cast member, a voice or the soundtrack, deleting a cut or emptying the bin cannot be undone. A preview says which deletes are restorable.

### How is this different from the Film Director?

The Film Director builds a workflow on the canvas. A studio production is a film you keep editing scene by scene in the Studio editor, which suits "make me a film and let me keep editing it".