Skip to content
Content
Agent

tool-surfaces

**Navigation**: [Agents package rules](../AGENTS.md) → **Headless tool surfaces**

From plugin
nodetool
63614 skills14 agents

Claude Code

$ npx -y skills add nodetool-ai/nodetool --agent claude-code

Agent definition

tool-surfaces.md

Headless tool surfaces

**Navigation**: [Agents package rules](../AGENTS.md) → **Headless tool surfaces**

Paths are relative to `packages/agents/` unless they name another package.

Script Voicing Tools (`src/capabilities/scripts.ts`)

The headless path from a written script to voiced takes and an assembled voiceover sequence. The editor voices a line over the chat WebSocket's `generate_media` / `transcribe_audio` RPCs, and the `nodetool.script.*` nodes do it inside a workflow; an agent outside the browser had neither. These call the provider directly, save each take as an asset, and write it back onto the persisted script.

| Tool | Does | |---|---| | `list_scripts` | Scripts newest first, with line and voiced counts | | `get_script` | Cast, lines, and each line's voicing status | | `voice_script_lines` | TTS per line → a take, current on its line | | `assemble_script_timeline` | Voiced takes → a saved `timeline_sequences` row |

`get_script` reports the status the editor's gutter shows — `draft` (never voiced), `stale` (text or voice changed since the take), `voiced`, `no_voice` — and `voice_script_lines` defaults to every line that is draft or stale, so a whole script is one call. Each line uses its own voice (its override, else its speaker's) unless the call passes provider+model+voice to override them all; a half-specified override is an error, not a guess. Lines are voiced concurrently (default 3, max 8, 60 per call) and each take lands through a CAS on the row's `updated_at`.

Synthesis delegates to `GenerateSpeechTool`, so the encoded/streaming-PCM provider split is handled in one place. Word timings come from a best-effort ASR pass (`whisper-1` by default, `transcribe: false` to skip it) and ride into the assembled clips as captions. Take duration is the container's own, probed in process through `@nodetool-ai/runtime/media`, falling back to the last word timing and then to the 3s placeholder. A take stays assemblable without an exact length.

The voice rule (`effectiveVoice`), the staleness rule (`needsVoicing`) and the script → timeline mapping (`buildScriptTimeline`) live in `@nodetool-ai/timeline`; the editor's "Send to timeline" and `nodetool.script.ScriptToTimeline` call the same functions, so the three surfaces cannot drift. Re-assembly rewrites this script's voiceover track in place and keeps clips other surfaces added.

Tests: `tests/script-voice-tools.test.ts` (in-memory DB, fake provider — no network).

Storyboard Render Tools (`src/capabilities/storyboards.ts`)

The headless path from a directed storyboard to rendered media and an assembled cut. The editor has always had this path — the Storyboard surface builds a throwaway `TextToImage → Output` / `ImageToVideo → Output` graph per shot and runs it in the browser — but an agent outside the browser had to author, save, and run a workflow per shot, or drive the `ui_storyboard_*` tools, which only work while that board is open. These call the provider directly, save each result as an asset, and write it back onto the persisted board.

| Tool | Does | |---|---| | `list_storyboards` | Boards newest first, with per-board still/clip counts | | `create_storyboard` | Blank board (then `edit_storyboard` adds shots) | | `get_storyboard` | Shots with ids, status, and whether each has a still/clip | | `direct_storyboard` | Runs the Director over the board's brief/genre/style and writes the screenplay; `redirect` keeps retained shots' ids and media | | `render_storyboard_stills` | `text_to_image` per shot → the shot's keyframe | | `render_storyboard_clips` | the shot's clip: `image_to_video` seeded by the keyframe, or `text_to_video` from the prompt | | `revise_storyboard_clip` | `video_to_video` revision of one shot's clip | | `assemble_storyboard_timeline` | Rendered clips → a saved `timeline_sequences` row | | `derive_shot_from_clip` | Frames of a shot clip → a new reference-to-video shot after its source, and a draft clip following it on a new track above the source clip | | `get_storyboard_one_take` | The creator's one-take prompt, the block compiled from the board, the full prompt, `[Image N]` references and warnings | | `update_storyboard_one_take` | Sets the creator's one-take prompt and shots' `end_state` / `sound` |

`edit_storyboard` is the document half: beside the shot ops it carries the guided flow's `set_setup`, the scene ops (`move_shot`, `duplicate_shot`, `update_scene`, `create_scene`, `merge_scene`), `set_style`, and the version ops (`select_version`, `delete_version`, `add_keyframe_version`). Every one mirrors a `ui_storyboard_*` browser tool and writes the same document shape, so a board edited headlessly and one edited in the editor cannot diverge (PRD § 7.10).

Both render tools take `targets` (shot ids, indexes, or slugs) and default to "whatever still needs this step", so a whole board is one call. `stale_only` narrows that to the shots whose selected version was rendered from inputs the shot no longer has (`isVersionStale`), which is how a style change is re-rendered without re-rendering the board. Shots render concurrently (default 3, max 8, 24 shots per call). Every write is a CAS on the row's `updated_at` with a bounded retry, because concurrent renders all land on the same board document; a conflicting write re-reads and re-applies rather than clobbering.

The provider and model come from the call, else from the board's own `imageModel` / `videoModel`. There is no fallback default — an unset model is an error naming `find_model`, not silent spend on a model nobody chose.

`Shot.render_mode` decides whether a clip needs a still. `"keyframe"` (the default) animates the selected still; `"direct"` renders from the prompt and skips the stills step entirely, for shots where first-frame conditioning is the wrong trade — heavy motion, which I2V renders stiffer than the same model's T2V, and native-audio models, which are weakest on their image path. A direct shot's prompt carries framing and board st

Read more
@nodetool-ai
Ships withnodetool

Open-source AI film studio · agent + node workflows Direct AI films, shot by shot. Start with one sentence. The agent writes the story, draws a still for every shot, and cuts the clips on a timeline.

6361 skill14 agents
Get the whole plugin

Stars on GitHub

Momentum

stars in total
636
Star history of nodetool-ai/nodetool on GitHub, a chart by star-history.com

Other agents on nodetool.

MUTATION_TESTING

MUTATION_TESTING

Agent

The agent package's pure, deterministic core (the chat permission gate, the control-tool plumbing, JSON extraction, and the…

cli

cli

Agent

**Navigation**: [Agents package rules](../AGENTS.md) → **Running Agents from CLI**

More agents from other plugins.

prompt-manager

prompt-manager

Agent

Agent for managing AI prompts on prompts.chat - search, save, improve, and organize your prompt library.

@gh-f@gh-fInstall Agent
humanize-diagnostician

humanize-diagnostician

Agent

정밀(strict) 모드 1단계 진단 에이전트. 글 전체를 한 번에 보고 "가장 지배적인 AI 티 패턴 3~6개"를 taxonomy ID와 함께 진단한다. 불안정한 span 열거(0↔18개로 요동) 대신 "무엇이 이 글을…

@epoko77-ai@epoko77-aiInstall Agent
blog-cluster-curator
Auto-invoked

blog-cluster-curator

Agent

Topic Clusters curator for the Claude Blog Brain. Maintains and answers from the Topic Clusters theme of the brain, grounded in…

@agricidaniel@agricidanielInstall Agent

Questions about tool-surfaces.

Which coding agents can use tool-surfaces?
tool-surfaces installs in Claude Code and Cursor: each loads subagents from .claude/agents, so copy the file there. Flowy's auto-invocation runs in Claude Code only.