Lets an AI agent edit vertical 9:16 video ads from brand footage, reference ads, or text ideas.
Also known as maxbuildog/adanvil
- Stars
- 1
- Tools
- 43
- Downloads, 30 days
- 363
- Latest version
- 0.4.0
- Last commit
- Oct 19, 2026
- License
- MIT
What is AdAnvil MCP?
AdAnvil lets an AI agent edit vertical 9:16 video ads from brand footage, reference ads, or text ideas. It exposes 43 tools, such as project_init, project_read_text, brand_onboard.
Summary generated from the project's README
About AdAnvil MCP server
Creating vertical 9:16 video advertisements from brand footage or text ideas is what AdAnvil enables for developers using AI agents. This MCP server works with clients like Claude Code, Cursor, and Codex to automate the entire editing process, from analyzing reference ads to rendering final products. It allows an agent to act as an editor by judging clip selection, text placement, and overall visual quality.
Users can set up the server via a one-click Claude Desktop extension, a Docker container, or using uvx. The system requires ffmpeg 6.1 or newer and can be configured with a Freesound key for sound design. It manages projects within a specific directory, organizing files into folders for footage, brand assets, music, and references. The server provides specialized tools for indexing footage, decoding reference pacing, and applying nine distinct ad recipes such as talking-head UGC or meme text styles.
What you can do with it
- 1Generate ads from reference videosAn agent can decode the shots, pacing, and text of a reference ad to create a similar edit for a new brand.
- 2Automate talking-head video editingThe server can identify the best takes of specific lines and cut out hesitations or pauses in creator footage.
- 3Search footage using natural languageDevelopers can instruct an agent to find specific clips based on visual content, emotions, or spoken words.
- 4Apply structured advertisement templatesAn AI can follow specific creative structures like 'before and after' or 'customer diary' to ensure consistent ad shapes.
Written from the project's README. Every use case is checked against a quote from it.
How to install AdAnvil MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall AdAnvil MCP in Claude Code
$ claude mcp add adanvil -- uvx adanvil mcpInstall AdAnvil MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"adanvil": {
"command": "uvx",
"args": [
"adanvil",
"mcp"
]
}
}
}Install AdAnvil MCP in VS Code
.vscode/mcp.json
{
"servers": {
"adanvil": {
"type": "stdio",
"command": "uvx",
"args": [
"adanvil",
"mcp"
]
}
}
}Install AdAnvil MCP in VS Code CLI
$ code --add-mcp '{"name":"adanvil","type":"stdio","command":"uvx","args":["adanvil","mcp"]}'Install AdAnvil MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"adanvil": {
"command": "uvx",
"args": [
"adanvil",
"mcp"
]
}
}
}Install AdAnvil MCP in Codex
$ codex mcp add adanvil -- uvx adanvil mcpInstall AdAnvil MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.adanvil] command = "uvx" args = ["adanvil", "mcp"]
Install AdAnvil MCP in Gemini CLI
$ gemini mcp add -s user adanvil uvx -- adanvil mcpInstall AdAnvil MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"adanvil": {
"command": "uvx",
"args": [
"adanvil",
"mcp"
]
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for adanvil 0.4.0 in an isolated container with no network and no keys. It answered and listed 43 tools.
AdAnvil MCP tools 43
Read from the server with tools/listproject_initCreate an AdAnvil project skeleton. Use this first for a new absolute project directory, then inspect the returned folders before adding media.
project_read_textRead a UTF-8 project text file using the project's safe path rules. Only AdAnvil's own files can be read: ``adanvil.json``, ``brand.yaml``, ``catalog.json`` and ``brand_brief.md`` at the top of the project, and the files under ``brand/``, ``reference/``, ``renders/``, ``music/``, ``storyboards/``, ``exports/``, ``cache/``, ``voice/``, ``sfx/`` and ``footage/`` (extensions .txt, .md, .json, .yaml, .yml, .csv). Any other file, and any name that starts with a dot, is refused. ``max_bytes`` (default 65536) is capped at 1 MB; a larger value is clamped and the result ``note`` says so.
brand_onboardRun brand onboarding step one or two. Use without answers to discover site facts and questions, then call with answers to write brand.yaml and brand_brief.md. Use open_questions to decide what the human must answer (a person whose consent is not yet a yes or a no is listed as ``people.<id>.consent``). ``facts`` is a compact summary of the site (title, colours, fonts, headings, prices, guarantee phrases, a few products); the complete facts are saved in ``facts_file`` (brand/site_facts.json): read it with project_read_text only when you need more. ``more`` counts what the summary left out.
brand_getRead the current brand profile and brief. Use this before writing captions or storyboards so copy follows the brand defaults and constraints. ``brand.product_versions`` says how to tell the product versions apart (match it with the ``product_version`` annotation of library entries). ``brand.cta_image`` is the brand's ready-made call-to-action image, to use as the last segment. ``emoji_available`` lists the emoji characters of the brand's emoji folder, or is "all" for twemoji (and empty for none).
library_indexIndex or refresh media under a project-relative folder or file. Use it before selection. ``source`` is a folder or a single media file. Up to 8 new or changed files are indexed in this call; more than 8 run as a detached job and the call returns at once with ``job_id`` (wait with job_status(job_id, wait_seconds=90), progress is per file). The result is compact: counts, one line per new or updated entry (id, path, duration, people, product_visible, ``speech`` when the clip speaks) and errors. Contact sheets are not sent inline: use library_view, or library_search with full=true for entries in full. ``transcribe`` controls the speech of the clips: "auto" (default) transcribes, with word timestamps, the clips that have an audio stream that is not near-silent; true transcribes every clip with an audio stream; false does no speech work. It uses faster-whisper when installed, else the voice environment (adanvil voice-setup); with neither, entries get a clear ``speech`` status ("unavailable: ...") and indexing still succeeds. The model is ADANVIL_SPEECH_MODEL (default base: fast, good enough to search) and the language is the brand language, else auto-detected; the brand name, the product name and ``speech.vocabulary`` of brand.yaml are given to the transcriber. The speech of each file is saved as soon as that file is transcribed, so library_search(text=...) works while the job runs (stage "transcribing"). Words are right about nine times in ten: run speech_refine on the clips you will use before captioning. Audio files (.m4a, .wav, .mp3, .aac) are indexed as ``audio`` entries, with their speech, and can be used as ``audio_from`` sources. A video whose sound is silent gets the speech status ``silent_audio`` and, when audio files with a similar name are nearby, ``separate_audio_candidates``. The result has a ``speech`` count by status. ``vision`` controls the vision pass: with the vision environment installed (``adanvil vision-setup`` or the tool ``vision_setup``) each image and video is also looked at ("auto", default): the frames of its contact sheet are embedded (so ``library_search(query=...)`` can find shots by sentence) and searched for faces, the entry gets ``auto_tags`` (zero-shot labels such as person, bathroom, smiling, never mixed with your ``tags``) and, when ``brand.product_versions`` has reference photos, a guess of the product version per shot. ``true`` redoes every entry; ``false`` skips the pass. Without the environment the result says ``vision: {"unavailable": n}`` and indexing still succeeds. Cuts: the scene change is scored on every frame (threshold 0.15), so a jump cut between two takes of one person in the same room is a shot boundary (``library_view`` shows the shots; each entry keeps the detector it was measured with as ``shots_detector``, for example ``full@0.15``). A source above 1920 px is read at its keyframes only (``keyframes@0.3``): its cuts are only seen at keyframes, so look at its sheet. Catalogs made before 0.4.0 keep their old, coarser shots: pass ``refresh_shots=true`` to measure the shots of the already indexed videos in ``source`` again (annotations, speech, vision and product versions stay as they are; the contact sheet is redrawn when the shots changed, and the per-shot product guesses of such an entry are cleared, run vision=true to compute them again). The result counts ``refreshed`` entries and ``shots_changed`` (the ones whose number of shots changed) and lists them under ``shots_refreshed``. Do it once per old catalog, before choosing segments: a segment placed across a hidden cut shows a flash of another take (``storyboard_validate`` warns ``segment_crosses_cut``).
library_viewReturn one catalogue entry and its contact sheet. Use it when a summary identifies a candidate; LOOK at the image before choosing a shot. An audio entry has no sheet: only its data is returned.
library_annotateMerge annotations into one catalogue entry. Parameters: ``project_dir`` (str, absolute project path), ``entry_id`` (str, catalog entry id), ``description`` (str or null), ``tags`` (list[str] or null), ``people`` (list[str] or null), ``product_visible`` (bool or null), ``product_version`` (short free string such as ``current``, ``old`` or ``v2``, or null), ``emotion`` (list of what the faces express, a clip can show several: none, neutral, worried, frustrated, sad, tired, closed, skeptical, shocked, curious, relaxed, happy, satisfied; the same words as the breakdown, the segments and the search filter, anything else is refused; or null), ``quality`` (int 1-5 or null), ``usable`` (list of ``[start, end, note]``, ``[start, end]``, or objects with ``start``, ``end`` and ``note``; or null), ``notes`` (str or null), ``exclude`` (bool or null), and ``exclude_reason`` (str or null). Example: ``library_annotate('/abs/project', 'clip-a1b2c3', tags=['hero'], quality=5, usable=[[1.2, 3.4, 'clear demo']])``. Use after looking at the contact sheet; search can then filter by tags, people, product version, emotion, quality and exclusion.
library_searchSearch indexed footage using annotations and technical metadata. Use the returned entries to choose clips without rescanning the filesystem. Each result is one compact line (id, path, duration, people, product_visible, version, emotion, quality); ``full=true`` returns the entries in full. ``product_version`` and ``emotion`` (a list: every listed emotion must be on the clip) filter on what was set with library_annotate; without a human ``product_version`` annotation the guess made from the brand's reference photos is used (a human annotation always wins). ``auto_tags`` filters on the automatic tags of the vision pass (English labels such as ``bathroom`` or ``smiling``; common French, Spanish and German words are understood). ``query`` searches by SENTENCE across the whole library, with no sheet to open: ``query="a woman with a sad face touching her jaw"`` (any language) ranks SHOTS by text-image similarity and returns the best ``limit`` (default 12, at most 48) as ``results`` (entry, shot, start, end, time of the best frame, score) plus ONE mosaic image of those frames, numbered like the list. All the other filters apply first. It needs the vision environment (``vision_setup``) and entries indexed with it (``library_index``); ``missing_vision`` counts the entries that have no vision data yet. Look at the mosaic, then library_view the entry to confirm before choosing. The score is a centred match probability: 0.5 and more is a clear match, under 0.1 means nothing in the library looks like it.
vision_setupInstall the optional vision environment (once, several minutes, about 2.5 GB). It makes its own Python environment in the AdAnvil cache folder with a small multilingual image and text embedding model (SigLIP 2, Apache-2.0) and a face detector (YuNet, MIT), both free for commercial use, and downloads their weights. It runs on the CPU. Afterwards ``library_index`` also looks at every image and video (shot search by sentence, automatic tags, product versions, faces for ``focus: "face"``). Without it everything else works as before. The environment is made from the default Python of this machine: to build it from another interpreter, a person runs ``adanvil vision-setup --python <path>`` in a terminal.
speech_viewRead the speech of one indexed clip and get safe cuts for it. Pass ``entry_id`` (from library_index or library_search) or ``source`` (the project-relative path of a video or audio file). Needs the clip to be indexed with speech (library_index transcribes clips with sound). The output is compact: ``phrases`` (split on pauses longer than ``max_pause`` seconds and on sentence punctuation), each with ``start``, ``end``, ``text`` and ``flags`` (``restart``: the next phrase repeats it, a retake; ``filler``: it holds a hesitation; ``uncertain``: the transcriber doubted a word, so it may be misheard); ``fillers`` (euh, heu, hum, bah, ben, um, uh, er, and genre, du coup, like when said alone between pauses; the lists can be replaced in brand.yaml under ``speech.fillers`` and ``speech.isolated_fillers``); ``restarts`` (a phrase that repeats the start of the next one: a retake inside the file); and ``clean_segments``: clip segments ``{source, in, out}`` ready to paste into a storyboard, which keep the speech and drop pauses over ``max_pause`` and the fillers (0.06 s kept before a word, 0.10 s after, never cutting inside a word). Per-word data (start, end, text and ``filler`` for each word) only comes with ``words=true``. At most ``max_phrases`` phrases are returned (default 60) from ``first_phrase``: when there are more, ``note`` and ``next_first_phrase`` tell how to get the next ones, and the other lists are those of the phrases shown. With ``drop_restarts`` true the restart phrases are cut out of the clean segments too (they are only flagged by default, because a deliberate repetition looks the same). ``model`` says which transcription model made the words: if a clip is used in the ad, run speech_refine on it first. A clip whose sound is silent says ``speech_status: silent_audio`` and lists ``separate_audio_candidates``.
speech_refineTranscribe chosen clips again with a stronger model and replace their words. Indexing transcribes fast with a small model, so about one key word per line can be misheard (names, numbers, rare words). Call this on the clips you will use in the ad (before cutting and captioning): ``sources`` lists project paths of indexed clips (a file, or a folder for every clip below it) or catalogue entry ids. It starts a detached job (wait with job_status(job_id, wait_seconds=90); progress counts clips) that transcribes them with ``model`` (one of tiny, base, small, medium, large-v2, large-v3, large-v3-turbo; default medium: slower, much more accurate; a medium model needs about 2 GB of memory) and the brand vocabulary (brand name, product name and ``speech.vocabulary`` of brand.yaml), then replaces the words of each clip in place (``speech_view`` reports the ``model``). A clip that fails keeps its previous words. The language is the brand's, else detected, unless ``language`` is given. The result of the finished job is ``refine`` in job_status (refined ids, skipped clips with the reason, errors). A word that is still wrong afterwards can be shown correctly with ``speech_captions.corrections`` (close spellings only).
speech_takesPick the best take of each line across several recordings of a script. Pass ``source`` (a project folder such as footage/hooks, or one file) and/or ``entry_ids``: the clips to compare, for example HOOK1.mov, HOOK1.1.mov and HOOK1.2.mov. Phrases that say the same line (normalised text similarity of at least 0.6, inside one file or across files) form a line; each take is ranked on fluency (no filler, no restart), a complete ending (last word not cut), a speech rate in the natural band (about 1.9 to 4.2 words per second) and the audio level. Returns ``lines``: for each, the ``best`` take (entry_id, source, start, end, text, score, ``why`` and ready-to-paste ``clean_segments``) and the ``others`` with the ``issues`` that put them behind. ``skipped`` lists clips without a transcript (run library_index with transcribe=true on them).
| project_init | Create an AdAnvil project skeleton. Use this first for a new absolute project directory, then inspect the returned folders before adding media. | |
| project_read_text | Read a UTF-8 project text file using the project's safe path rules. Only AdAnvil's own files can be read: ``adanvil.json``, ``brand.yaml``, ``catalog.json`` and ``brand_brief.md`` at the top of the project, and the files under ``brand/``, ``reference/``, ``renders/``, ``music/``, ``storyboards/``, ``exports/``, ``cache/``, ``voice/``, ``sfx/`` and ``footage/`` (extensions .txt, .md, .json, .yaml, .yml, .csv). Any other file, and any name that starts with a dot, is refused. ``max_bytes`` (default 65536) is capped at 1 MB; a larger value is clamped and the result ``note`` says so. | |
| brand_onboard | Run brand onboarding step one or two. Use without answers to discover site facts and questions, then call with answers to write brand.yaml and brand_brief.md. Use open_questions to decide what the human must answer (a person whose consent is not yet a yes or a no is listed as ``people.<id>.consent``). ``facts`` is a compact summary of the site (title, colours, fonts, headings, prices, guarantee phrases, a few products); the complete facts are saved in ``facts_file`` (brand/site_facts.json): read it with project_read_text only when you need more. ``more`` counts what the summary left out. | |
| brand_get | Read the current brand profile and brief. Use this before writing captions or storyboards so copy follows the brand defaults and constraints. ``brand.product_versions`` says how to tell the product versions apart (match it with the ``product_version`` annotation of library entries). ``brand.cta_image`` is the brand's ready-made call-to-action image, to use as the last segment. ``emoji_available`` lists the emoji characters of the brand's emoji folder, or is "all" for twemoji (and empty for none). | |
| library_index | Index or refresh media under a project-relative folder or file. Use it before selection. ``source`` is a folder or a single media file. Up to 8 new or changed files are indexed in this call; more than 8 run as a detached job and the call returns at once with ``job_id`` (wait with job_status(job_id, wait_seconds=90), progress is per file). The result is compact: counts, one line per new or updated entry (id, path, duration, people, product_visible, ``speech`` when the clip speaks) and errors. Contact sheets are not sent inline: use library_view, or library_search with full=true for entries in full. ``transcribe`` controls the speech of the clips: "auto" (default) transcribes, with word timestamps, the clips that have an audio stream that is not near-silent; true transcribes every clip with an audio stream; false does no speech work. It uses faster-whisper when installed, else the voice environment (adanvil voice-setup); with neither, entries get a clear ``speech`` status ("unavailable: ...") and indexing still succeeds. The model is ADANVIL_SPEECH_MODEL (default base: fast, good enough to search) and the language is the brand language, else auto-detected; the brand name, the product name and ``speech.vocabulary`` of brand.yaml are given to the transcriber. The speech of each file is saved as soon as that file is transcribed, so library_search(text=...) works while the job runs (stage "transcribing"). Words are right about nine times in ten: run speech_refine on the clips you will use before captioning. Audio files (.m4a, .wav, .mp3, .aac) are indexed as ``audio`` entries, with their speech, and can be used as ``audio_from`` sources. A video whose sound is silent gets the speech status ``silent_audio`` and, when audio files with a similar name are nearby, ``separate_audio_candidates``. The result has a ``speech`` count by status. ``vision`` controls the vision pass: with the vision environment installed (``adanvil vision-setup`` or the tool ``vision_setup``) each image and video is also looked at ("auto", default): the frames of its contact sheet are embedded (so ``library_search(query=...)`` can find shots by sentence) and searched for faces, the entry gets ``auto_tags`` (zero-shot labels such as person, bathroom, smiling, never mixed with your ``tags``) and, when ``brand.product_versions`` has reference photos, a guess of the product version per shot. ``true`` redoes every entry; ``false`` skips the pass. Without the environment the result says ``vision: {"unavailable": n}`` and indexing still succeeds. Cuts: the scene change is scored on every frame (threshold 0.15), so a jump cut between two takes of one person in the same room is a shot boundary (``library_view`` shows the shots; each entry keeps the detector it was measured with as ``shots_detector``, for example ``full@0.15``). A source above 1920 px is read at its keyframes only (``keyframes@0.3``): its cuts are only seen at keyframes, so look at its sheet. Catalogs made before 0.4.0 keep their old, coarser shots: pass ``refresh_shots=true`` to measure the shots of the already indexed videos in ``source`` again (annotations, speech, vision and product versions stay as they are; the contact sheet is redrawn when the shots changed, and the per-shot product guesses of such an entry are cleared, run vision=true to compute them again). The result counts ``refreshed`` entries and ``shots_changed`` (the ones whose number of shots changed) and lists them under ``shots_refreshed``. Do it once per old catalog, before choosing segments: a segment placed across a hidden cut shows a flash of another take (``storyboard_validate`` warns ``segment_crosses_cut``). | |
| library_view | Return one catalogue entry and its contact sheet. Use it when a summary identifies a candidate; LOOK at the image before choosing a shot. An audio entry has no sheet: only its data is returned. | |
| library_annotate | Merge annotations into one catalogue entry. Parameters: ``project_dir`` (str, absolute project path), ``entry_id`` (str, catalog entry id), ``description`` (str or null), ``tags`` (list[str] or null), ``people`` (list[str] or null), ``product_visible`` (bool or null), ``product_version`` (short free string such as ``current``, ``old`` or ``v2``, or null), ``emotion`` (list of what the faces express, a clip can show several: none, neutral, worried, frustrated, sad, tired, closed, skeptical, shocked, curious, relaxed, happy, satisfied; the same words as the breakdown, the segments and the search filter, anything else is refused; or null), ``quality`` (int 1-5 or null), ``usable`` (list of ``[start, end, note]``, ``[start, end]``, or objects with ``start``, ``end`` and ``note``; or null), ``notes`` (str or null), ``exclude`` (bool or null), and ``exclude_reason`` (str or null). Example: ``library_annotate('/abs/project', 'clip-a1b2c3', tags=['hero'], quality=5, usable=[[1.2, 3.4, 'clear demo']])``. Use after looking at the contact sheet; search can then filter by tags, people, product version, emotion, quality and exclusion. | |
| library_search | Search indexed footage using annotations and technical metadata. Use the returned entries to choose clips without rescanning the filesystem. Each result is one compact line (id, path, duration, people, product_visible, version, emotion, quality); ``full=true`` returns the entries in full. ``product_version`` and ``emotion`` (a list: every listed emotion must be on the clip) filter on what was set with library_annotate; without a human ``product_version`` annotation the guess made from the brand's reference photos is used (a human annotation always wins). ``auto_tags`` filters on the automatic tags of the vision pass (English labels such as ``bathroom`` or ``smiling``; common French, Spanish and German words are understood). ``query`` searches by SENTENCE across the whole library, with no sheet to open: ``query="a woman with a sad face touching her jaw"`` (any language) ranks SHOTS by text-image similarity and returns the best ``limit`` (default 12, at most 48) as ``results`` (entry, shot, start, end, time of the best frame, score) plus ONE mosaic image of those frames, numbered like the list. All the other filters apply first. It needs the vision environment (``vision_setup``) and entries indexed with it (``library_index``); ``missing_vision`` counts the entries that have no vision data yet. Look at the mosaic, then library_view the entry to confirm before choosing. The score is a centred match probability: 0.5 and more is a clear match, under 0.1 means nothing in the library looks like it. | |
| vision_setup | Install the optional vision environment (once, several minutes, about 2.5 GB). It makes its own Python environment in the AdAnvil cache folder with a small multilingual image and text embedding model (SigLIP 2, Apache-2.0) and a face detector (YuNet, MIT), both free for commercial use, and downloads their weights. It runs on the CPU. Afterwards ``library_index`` also looks at every image and video (shot search by sentence, automatic tags, product versions, faces for ``focus: "face"``). Without it everything else works as before. The environment is made from the default Python of this machine: to build it from another interpreter, a person runs ``adanvil vision-setup --python <path>`` in a terminal. | |
| speech_view | Read the speech of one indexed clip and get safe cuts for it. Pass ``entry_id`` (from library_index or library_search) or ``source`` (the project-relative path of a video or audio file). Needs the clip to be indexed with speech (library_index transcribes clips with sound). The output is compact: ``phrases`` (split on pauses longer than ``max_pause`` seconds and on sentence punctuation), each with ``start``, ``end``, ``text`` and ``flags`` (``restart``: the next phrase repeats it, a retake; ``filler``: it holds a hesitation; ``uncertain``: the transcriber doubted a word, so it may be misheard); ``fillers`` (euh, heu, hum, bah, ben, um, uh, er, and genre, du coup, like when said alone between pauses; the lists can be replaced in brand.yaml under ``speech.fillers`` and ``speech.isolated_fillers``); ``restarts`` (a phrase that repeats the start of the next one: a retake inside the file); and ``clean_segments``: clip segments ``{source, in, out}`` ready to paste into a storyboard, which keep the speech and drop pauses over ``max_pause`` and the fillers (0.06 s kept before a word, 0.10 s after, never cutting inside a word). Per-word data (start, end, text and ``filler`` for each word) only comes with ``words=true``. At most ``max_phrases`` phrases are returned (default 60) from ``first_phrase``: when there are more, ``note`` and ``next_first_phrase`` tell how to get the next ones, and the other lists are those of the phrases shown. With ``drop_restarts`` true the restart phrases are cut out of the clean segments too (they are only flagged by default, because a deliberate repetition looks the same). ``model`` says which transcription model made the words: if a clip is used in the ad, run speech_refine on it first. A clip whose sound is silent says ``speech_status: silent_audio`` and lists ``separate_audio_candidates``. | |
| speech_refine | Transcribe chosen clips again with a stronger model and replace their words. Indexing transcribes fast with a small model, so about one key word per line can be misheard (names, numbers, rare words). Call this on the clips you will use in the ad (before cutting and captioning): ``sources`` lists project paths of indexed clips (a file, or a folder for every clip below it) or catalogue entry ids. It starts a detached job (wait with job_status(job_id, wait_seconds=90); progress counts clips) that transcribes them with ``model`` (one of tiny, base, small, medium, large-v2, large-v3, large-v3-turbo; default medium: slower, much more accurate; a medium model needs about 2 GB of memory) and the brand vocabulary (brand name, product name and ``speech.vocabulary`` of brand.yaml), then replaces the words of each clip in place (``speech_view`` reports the ``model``). A clip that fails keeps its previous words. The language is the brand's, else detected, unless ``language`` is given. The result of the finished job is ``refine`` in job_status (refined ids, skipped clips with the reason, errors). A word that is still wrong afterwards can be shown correctly with ``speech_captions.corrections`` (close spellings only). | |
| speech_takes | Pick the best take of each line across several recordings of a script. Pass ``source`` (a project folder such as footage/hooks, or one file) and/or ``entry_ids``: the clips to compare, for example HOOK1.mov, HOOK1.1.mov and HOOK1.2.mov. Phrases that say the same line (normalised text similarity of at least 0.6, inside one file or across files) form a line; each take is ranked on fluency (no filler, no restart), a complete ending (last word not cut), a speech rate in the natural band (about 1.9 to 4.2 words per second) and the audio level. Returns ``lines``: for each, the ``best`` take (entry_id, source, start, end, text, score, ``why`` and ready-to-paste ``clean_segments``) and the ``others`` with the ``issues`` that put them behind. ``skipped`` lists clips without a transcript (run library_index with transcribe=true on them). |
Show all 43 toolsShow fewer tools
reference_decodeDecode a reference video into shots, pacing, text, speech and sheets. ``transcribe`` is true, false or "auto" (default: transcribe when the reference has audible sound and a transcriber is available). Returns the JSON, the overview sheet, then up to 6 shot sheets (one row per shot, three frames each). LOOK at every shot sheet and read the on-screen text, then call reference_breakdown with the filled breakdown_template before choosing footage. The JSON is compact: the per-word transcript and rms_per_second stay in reference.json (see ``files``); each shot has its ``spoken`` text and ``transcript_text`` holds the whole transcript. ``breakdown_vocabularies`` lists the allowed type, scale, role, motion, emotion, text_speaker and text_device values and how to read who speaks in the on-screen text; ``music_profile`` is the tempo and energy of the reference soundtrack (voice included).
reference_breakdownSave the agent's shot-by-shot breakdown of a decoded reference. ``reference`` is the decode folder (reference/<slug>) or its reference.json. ``shots`` follows breakdown_template: one entry per shot, or one entry for consecutive shots (``"shots": [4, 5]``); every decoded shot must be covered exactly once. Controlled values: type, scale, role, motion, emotion, text_speaker, text_device (errors list the allowed ones); ``action`` is free short text: what the person does (for example "wipes the counter and sighs"). For every shot note what the person feels (``emotion``) and does, then pick a library shot with the same emotion and the same kind of action. text_speaker and text_device say who speaks in the on-screen text (an emoji or name, ":" and quotes is a character talking); subject is a short id (person_a, product, diagram), on_screen_text is read verbatim, replacement is a library entry id or "missing: ...". Returns type demand, scale mix, role sequence, repeated patterns, people, text shots, text_devices, dialogue, emotion_by_role (the emotions used for each role), pacing and missing shots. Use it before library_overview.
library_overviewOverview of the footage folders without indexing, plus a mosaic. Lists folders up to ``depth`` with file, video and image counts, total video seconds and first file names. With ``mosaic``, returns a labelled thumbnail mosaic of the media under ``path`` (48 per page, 6 columns); ``pages`` tells how many, call again with ``page`` to see the next ones. Run it on the whole footage tree (B-roll folders included) to find each shot type the reference breakdown needs, before choosing shots.
frame_viewExtract one full-resolution frame from a project video or image. Give the time ``t`` (seconds) or the frame number ``frame`` (video only, counted from 0). Returns the frame ON SCREEN at ``t`` (``floor(t * fps)``): at 2.87 s of a 30 fps video that is the frame starting at 2.867 s, not the next one at 2.900 s. A ``t`` within 1 ms of a frame boundary is that frame (10.9333 s at 30 fps is frame 328), so a time printed to four decimals lands on the right frame. ``frame_t`` is the frame's exact start time and ``frame`` its number (video only). Use it to inspect the exact moment behind a timecode; the saved frame is under cache/frames/.
timeline_exportExport a storyboard as an editable timeline for DaVinci Resolve or Premiere Pro. Writes ``exports/<name>/`` with ``<name>.otio`` (OpenTimelineIO: video tracks, speed as a time warp, stills, captions as markers on V1, overlay pictures, voice, music and one audio track per sound effect), ``<name>.xml`` (Final Cut Pro 7 XML, read by Premiere Pro and Resolve, with the real rate, size and duration of each source, speed as Time Remap, music and sound effect levels and fades), ``<name>.edl`` (CMX 3600, video cuts only, the fallback), ``<name>.srt`` (every caption at its final time), ``overlays/`` (each caption, sticker and card as a full-canvas transparent PNG named after its storyboard overlay index, with its place in ``overlays.json``) and ``README.txt``. ``formats`` is any of ``otio``, ``fcp7xml``, ``edl``, ``srt`` (all by default). Media paths are absolute, as the project sees them; ``relative`` writes ``exports/<name>-relative/`` with paths relative to the folder (and a ``relink.txt``), ``copy_media`` writes ``exports/<name>-portable/`` with the used sources copied into ``media/``; ``media_root`` is the absolute folder a relative export will live in. A folder that holds an export of another media mode is only replaced with ``overwrite=true``. The result lists ``warnings`` (what is approximated) and ``not_exported`` (what no editor format here carries: grading, reframing, pop animations, split layout, loudness, the EDL audio).
recipe_listList available ad recipes with purpose and duration. Use this to shortlist a shape, then read its checklist with recipe_get before writing a storyboard.
recipe_getReturn one complete recipe, including rules and example. Use its checklist as the storyboard acceptance criteria.
editing_guideReturn the editing doctrine for footage, copy, rendering and QC. Read it before the first storyboard and whenever a rule is unclear.
storyboard_schemaReturn the JSON Schema for Storyboard v1. Use it to construct agent-authored storyboards before validation.
storyboard_saveSave a storyboard in the project as ``storyboards/<name>.json`` and return its path. Send the storyboard object once, then pass the returned path (``"storyboards/<name>.json"``) as ``storyboard`` to ``storyboard_validate``, ``render_start`` and ``caption_preview`` instead of repeating the whole object (useful on a remote server). Saving again under the same name replaces the file. The object is stored as sent, not validated: ``storyboard_validate`` checks it.
storyboard_patchEdit a saved storyboard in place: ``changes`` is a list of ``{path, value}``. A path walks the JSON with dots and indexes: ``segments.3.out`` (``segments[3].out`` works too). Setting a missing key of an object adds it; the index just past the end of a list, or ``-``, appends; ``{"path": "overlays.1", "remove": true}`` deletes. The changes apply in order to a copy: if one is wrong, nothing is saved and the error names it. When the changes rename the storyboard (``name``), its ``output.path`` follows if it was the default of the old name (a path set by hand stays). The file ``storyboards/<name>.json`` is rewritten and the result lists the schema problems left (``problems``, empty when the storyboard is valid; run ``storyboard_validate`` for the full check).
caption_previewRender a caption, a comment or an information card over a real 9:16 frame. An ``info_card`` overlay (see the storyboard schema) is drawn, settled, as the render draws it: the result has its image on the real frame, its ``bbox`` (inside the frame when it fits), ``size_used`` (the title size), ``overflow`` and ``lines``. A banned word of the brand in its texts is an error. Use it before rendering to inspect placement; the JSON reports bbox, fitted size, overflow and final lines. ``emoji`` takes the storyboard ``emoji`` values (twemoji, none or a project folder) so the preview matches the render; ``emoji_missing`` lists emoji absent from a folder. For a ``voice_captions`` overlay pass ``manifest``: the ``audio.voice`` path of your storyboard (voice/<name>/manifest.json); ``expanded`` lists the resulting captions once. A ``speech_captions`` overlay is built from the speech of the clips: pass ``chunk_index`` to pick the caption to draw and ``storyboard`` (a project path such as ``storyboards/<name>.json`` or the object) so the timeline is the one of your ad; without it the captions are those of ``source`` played whole. ``expanded`` lists them all. With ``start``/``end`` on a ``voice_captions`` or ``speech_captions`` overlay only the captions inside that window exist (``chunk_index`` counts those); a voice preview takes its offset from the overlay (``offset``), not from the storyboard. An animated caption (``animation`` ``karaoke``, ``word`` or ``pop``) is drawn in one of its states, to check where the highlight lands: put ``chunk_index`` and ``word_index`` in the overlay object to pick the chunk and the lit word, or leave them out to get the state on screen at timeline time ``t``. The result names the ``word_index``, the ``window`` of the state and how many ``states`` the chunk has.
end_cardCompose a clean end card image from a real product photo. Use it only when the brand has no ready-made call-to-action image: when it has one (``brand.cta_image``, a ``cta/`` folder or ``brand/``), use that image as the last segment (``image``, ``zoom_in``, about 3 s) instead. It writes ``brand/endcards/<name>.png`` (1080x1920 unless ``spec.format`` says otherwise) and returns the path, the layout boxes and the image: LOOK at it. ``spec``: ``product_image`` (project path of a photo or a video, with ``t`` for the frame, optional ``crop`` {x,y,w,h} in the source's display pixels, before scaling: on a 1920x1080 frame ``{"x": 600, "y": 100, "w": 700, "h": 700}`` keeps a 700 px square; the result returns ``source_size`` [w, h] to measure it), ``pill``, ``title`` (a string or runs ``{text, accent}``), ``subline``, ``badges`` (up to 3, ``{text, icon: check|star|none}``), ``button`` (``{text, arrow: down|right|none}``), colours ``accent``, ``text``, ``muted``, ``background`` (two colours), ``family``, ``emoji``. Colours default to the brand's. Banned words of the brand on any text are an error. Use the PNG as the last segment: ``type: image``, ``motion: zoom_in``, about 3 s, label ``end_card``, no subtitles on it. It also writes ``brand/endcards/<name>.png.json``, the texts drawn (pill, title, subline, badges, button): ``storyboard_validate`` reads it, so ``cta_text_missing`` is not raised when the button already says the brand's call to action.
storyboard_validateValidate a storyboard object or project-relative JSON file. ``storyboard`` is the object, or the path saved by ``storyboard_save`` (``"storyboards/<name>.json"``). Every schema error is reported at once. The check covers Storyboard v1, its files, brand and recipe. Fix every error path before render_start; warnings are questions to review. With ``reference`` set, ``ref_*`` warnings and a ``reference_comparison`` block compare the edit with the reference breakdown. With ``score_check=true`` it also runs the quick pre-check of ``ad_score`` that needs no pixels, as warnings prefixed ``score_`` (reading time and line length, product too early, call to action, platform safe zones of the overlays); ``summary.score_precheck`` lists what passed and what could not be checked. Warning ``segment_crosses_cut``: a clip segment (or the clip side of a ``split`` panel or a ``reveal``) whose source is indexed has a change of take (a shot boundary of ``library_view``) strictly inside its range, more than 0.12 s from each end as the viewer sees it (``speed`` counts). The viewer would see a flash of another take, or a jump in the middle of the shot: move ``in`` after the cut or ``out`` before it, as the message says. ``summary.cut_check`` counts the segments checked and the ones that cross a cut, and lists under ``old_shots`` the sources measured before 0.4.0, whose shots can hide cuts. Sources that are not indexed, or have one shot, say nothing; run ``library_index`` (``refresh_shots=true`` for catalogs made before 0.4.0) so that the cuts of long clips are known. ``cta_text_missing`` also reads the texts of an end card made with ``end_card`` when it is the last segment, and those of ``info_card`` overlays. Information cards (``info_card`` overlays): each is drawn and checked. Error ``info_card_out_of_frame`` (the card leaves the frame), ``banned_word`` in its texts; warnings ``info_card_overlap`` (two cards on screen together: show one at a time), ``caption_over_info_card`` (a caption overlaps a card while both are on screen: pause the captions with ``start``/``end``), ``text_overflow`` (the title does not fit at its smallest size) and ``emphasis_unmatched``. With ``story: "offer"`` (announcements, lead collection, offers where the product is in hand from the first second) ``product_too_early`` is not raised, and ``summary.skipped`` says so.
render_startValidate and queue a background render. ``storyboard`` is the object or a saved path (``"storyboards/<name>.json"``). Use preview while iterating and final after QC. A rejected storyboard returns validation errors and creates no job.
variants_buildBuild the matrix of variants of one storyboard: hooks x bodies x calls to action. ``base`` is a storyboard (object or ``"storyboards/<name>.json"``). ``variants`` is ``{axis: [{id, changes}]}`` for up to 3 axes (for example ``hook``, ``body``, ``cta``). ``changes`` is a list applied in order, each a ``storyboard_patch`` change (``{path, value}`` or ``{path, remove: true}``) or a SLOT REPLACEMENT ``{replace_label: "hook", segments: [...], overlays: [...]}``: it swaps every segment of that label (they must be next to each other) and shifts everything after it by the difference of duration (overlays, sounds and word times follow). The new ``overlays`` are timed from the start of the slot; the overlays that were on the replaced segments go away. A voice-over (``audio.voice``) laid on the timeline must still match: a change of duration while one is set is refused with the reason, as is an overlay that only partly overlaps the slot. An option with no ``changes`` (or ``[]``) is the control: the base unchanged. Timed sounds follow the slot: an ``sfx`` overlay after it shifts by the difference of duration, one inside it goes away when the new slot brings its own sounds (else it keeps its offset); each variant lists what moved under ``moved``. All the errors of all the variants come back at once (variant, path, message). Makes the cartesian product (at most 24, each validated), saves each as ``storyboards/<name>.json`` (``name_pattern`` uses ``{base}`` and the axis names; the default falls back to the axis ids in order when an axis is not hook or cta) and returns the list with the path, ids, duration and warnings of each, plus a contact sheet: the first 3 s (top row) and the last 3 s (bottom row, the call to action) of every variant (LOOK at it, a hook that does not read at that size will not read in the feed). A base that is itself a variant keeps its ids in the new ones (the manifest keeps ``hook=h2;cta=ca``). Then ``render_batch`` renders them with a shared cache. Vary the hook first; keep everything else identical. A storyboard file that already exists is NEVER overwritten, whoever made it (an earlier ``variants_build`` included, or a file edited by hand since): the error lists every file that would be replaced. ``overwrite=true`` replaces them all. Renders may be replaced; storyboards may not.
render_batchQueue ONE background job that renders several storyboards in order. ``quality``: ``final``, ``preview`` or ``draft`` (an alias of ``preview``: half-size ``*.preview.mp4`` files; the report and the manifest say ``preview``, and the manifest has a ``quality`` column because a preview scores lower than its final). ``storyboards``: objects or saved paths (typically the variants of ``variants_build``). The segment cache is shared, so a segment used by several variants (the body, the end card) is built once: the first render is the slow one. ``formats`` (any of ``"9:16"``, ``"4:5"``, ``"1:1"``) renders each storyboard in those ratios; when omitted each storyboard's own ``formats`` field is used, else it renders as it is. Files go to ``renders/<batch>/`` (``batch`` defaults to ``<first name>_batch``) named ``<name>[_9x16|_4x5|_1x1].mp4``, and ``renders/<batch>/manifest.csv`` lists them for an ads manager (file, variant ids, format, duration, score, hook text, CTA text). ``score`` runs ``ad_score`` on each final render for the manifest (with the safe zones of its placement). ``job_status`` shows the progress per render, each output as it finishes, and at the end ``total_seconds``, ``cache_builds`` and the manifest path. A storyboard that does not validate rejects the whole batch with its errors and no job.
render_formatsRender one storyboard in several formats: ``9:16``, ``4:5``, ``1:1``. ``formats`` defaults to the storyboard's own ``formats`` field, else all three. One detached job (see ``render_batch``), one file per format: ``<name>_9x16.mp4``, ``<name>_4x5.mp4``, ``<name>_1x1.mp4`` in ``renders/<batch>/`` (``batch`` defaults to ``<name>_formats``). Each is the same ad laid out for its placement: the footage is re-cropped (face-aware with ``focus: "face"``, else by ``focus``); a still or an end card that does not fit is shown whole over its blurred copy; captions, stickers and images keep their place by bands (the part the platform leaves free is mapped onto the free part of the new frame, 4:5 and 1:1 being the Feed) and are pushed back inside when a block would leave it. An ``info_card`` is placed like an image card: its ``y`` follows the same bands, its width and text scale with the frame (the title stays at 38 px or more) and it stays inside the frame. ``ad_score`` uses the safe zones of the matching placement (``feed`` for 4:5 and 1:1). LOOK at each format's contact sheet before delivery.
voice_generateQueue a checked voice-over generation job. Poll job_status until it is done, then use each manifest line's ``start`` and ``duration`` to place shots. If a line is ``suspect``, regenerate it with slightly different wording or accept it when the transcript differs only by punctuation; agents cannot listen to audio. ``unmatched_words`` lists the key words (4+ letters) missing from the transcript: two or more make the line suspect, so reword them. When the voice says the end of a line again (2 or more extra words after the whole text) the audio is cut after the last expected word: the line has ``extra_words`` and ``trimmed_extra: true``; extra words that could not be cut make it ``suspect``. A line is a string (said and shown) or ``{"say": ..., "show": ...}`` when captions must display something other than the spoken words (say "forty-nine dollars ninety", show "$49.90"). Calling again with an existing ``name`` replaces that voice (unchanged lines come from the cache); the job summary then has ``replaced: true``. ``language`` in the spec is optional: without it the ``language`` of brand.yaml is used, else ``en``.
sfx_listList the sound effects of the project's ``sfx/`` folder, and build the pack. ``fetch=true`` first builds the missing sounds of the pack (about 18: whoosh short and long, swoosh, swipe, pop, click, tap, ding, chime, notification, cash register, camera shutter, record scratch, typing, riser 1 s and 2 s, impact, boom). Each is downloaded from a pinned CC0 source (checked by SHA-1) or synthesised in code, trimmed and set to one level, with the source and licence in ``sfx/LICENCES.txt``. A download that fails is synthesised instead (``offline=true`` synthesises all of them). The files you drop in ``sfx/`` yourself are listed too. Each sound returns its ``name``, ``path`` (the ``source`` of an ``sfx`` overlay), ``duration`` and ``origin``. Use a sound in an ``sfx`` overlay (``{"type": "sfx", "source": "sfx/pop.wav", "at": 3.2, "volume": 0.8}``) or by name in ``audio.sfx_auto``. A riser is placed so that its end meets the moment it builds towards: ``at`` = that moment minus its duration.
music_beatsBeat times of a music track, as it will play in the ad. ``path`` is a project file (audio, or a video whose soundtrack is the music). ``start`` is the storyboard's ``audio.start``: the times are in seconds from the start of the ad, so beat 0 of the result is the first beat heard. They come from the onset envelope and the estimated tempo, on a regular grid whose phase is aligned to the strongest onsets (within a few milliseconds on a steady beat). ``duration`` limits the analysis (default the first 120 s). A track without a steady beat (a piano, a pad) returns no beats. Cut on these times for a music-led ad, or let ``storyboard_snap`` do it.
storyboard_snapMove the cuts of a storyboard onto the beats of its music. ``storyboard`` is the object or a saved path. Each cut within ``max_shift`` seconds (default 0.2) of a beat of ``audio.music`` (from ``audio.start``) moves to it: the ``out`` of the earlier clip (or the ``duration`` of an image) changes, ``in`` points and segment order never do, no segment ends up under 0.5 s (or shorter than it was), the other cuts and the total duration stay, and the captions, images and sounds that started on a moved cut move with it. With ``audio.clips`` the cuts of talking segments never move. The result lists ``moves``, the cuts ``kept`` with the reason, and how many cuts are on a beat before and after. It returns the new ``storyboard``, or with ``save_as`` (a name) writes ``storyboards/<name>.json`` and returns its path instead. The snapped storyboard has its own identity so a render never overwrites the original: with ``save_as`` its ``name`` is ``save_as``, without it the old name plus ``_snapped``, and ``output.path`` is ``renders/<that name>.mp4`` (the quality is kept). Run ``storyboard_validate`` afterwards: its ``beat_alignment`` info shows the share of cuts on a beat.
music_profileTempo, loudness and energy of the music tracks, to match a reference. Without ``path``, profiles every audio file of ``music/``; with ``path`` (project-relative), one file, which may be a video such as the reference (its soundtrack mixes voice and music). Each track returns its duration, integrated loudness (LUFS), estimated tempo (``tempo_bpm``), ``energy`` (onsets per second and loudness range in LU) and ``feel``: calm, medium or energetic (thresholds in ``feel_thresholds``). Pick the library track whose profile is closest to the reference's: a calm track under a fast reference feels flat.
music_searchFind music whose licence lets an ad use it (commercial use and modification). Searches Openverse (no key; ``source="openverse"``), Freesound (``"freesound"``, only with the ``FREESOUND_API_KEY`` environment variable) or both (``"all"``; without the key the answer says so and still lists Openverse). Kept licences: CC0, PDM, CC BY, CC BY-SA; NC and ND are dropped. Each track returns ``source``, ``id``, ``title``, ``author``, ``licence``, ``duration`` (s), ``source_url``, ``preview_url`` (listen before fetching) and ``attribution_required`` (with the ``attribution_text`` to put in the ad's description). ``mood`` adds words to the query ("calm", "upbeat"). ``min_duration`` and ``max_duration`` filter in seconds. ``fit_to="storyboard"`` with ``storyboard`` (a project path such as ``storyboards/summer.json``) ranks for that ad: tracks at least as long as the ad first, then the wanted feel (``audio.music_feel``, or the ``feel`` argument: calm, medium, energetic) against ``fit.feel_guess``, a guess from the track's OWN title, tags and genres (``unknown`` when they say nothing; never copied from the wanted feel). The real feel, tempo and loudness come from ``music_fetch``: trust that, not the guess. Fetch the best ones, listen, and choose.
music_fetchDownload a track from ``music_search`` into ``music/``, with its licence. ``source`` and ``id`` come from the search result. Writes ``music/<file>``, the record ``music/<file>.licence.json`` (source, id, URL, title, author, licence, licence URL, attribution text, fetch date) and a line in ``music/LICENCES.txt``, then profiles the track: the answer has ``path`` (the ``audio.music`` value), ``duration``, ``tempo_bpm``, ``feel`` and ``loudness_lufs``. A licence that is not CC0, PDM, CC BY or CC BY-SA is refused. An embedded cover picture is removed from the stored file. The render and ``ad_score`` read the record (the sidecar, else the track's line in ``LICENCES.txt``): ``music_licence_unknown`` when a track has neither, ``music_attribution_required`` (with the exact text) when it needs one. Freesound serves its high-quality MP3 preview (the original needs a login).
music_generateMake an instrumental track locally (optional ACE-Step environment), as a job. Needs ``adanvil music-setup`` (about 3 GB of packages, then 8 GB of weights at the first run). ``prompt`` is a list of tags ("upbeat acoustic guitar, warm, 110 bpm, instrumental"); ``duration`` 10 to 120 s. On a CPU a 30 s track takes several minutes: poll ``job_status``; its ``music`` field has the ``path`` (the ``audio.music`` value), tempo, feel and loudness. The model and its weights are Apache-2.0: no attribution; the licence record is written next to the file like for a fetched track.
voice_viewRead a voice manifest and suggest final-timeline shot boundaries. ``offset`` is the intended voice start on the final video timeline. Suspect lines should be regenerated with slightly different wording or accepted only when the transcript difference is punctuation. Each line's ``unmatched_words`` lists key words the transcript lacks. ``extra_words`` lists words heard after the whole text (a repeated end): with ``trimmed_extra`` true the audio was already cut after the last expected word, else the line is ``suspect`` and still ends on them (regenerate it).
job_statusRead a queued, running, completed or failed render, batch, voice, index or refine job. With ``wait_seconds`` greater than zero, wait in this call (up to 600 seconds) instead of polling from the client; if the connection drops, just call again, a restarted server still finds the job. Pass ``project_dir`` when it says "job not found". Completed index jobs carry the compact index summary; completed speech_refine jobs carry ``refine`` (refined clips, skipped clips with the reason, errors). Completed render jobs include the persisted RenderReport JSON; batch jobs (``render_batch``, ``render_formats``) carry ``batch``: one entry per render (status, file, format, duration, score, seconds, error) as they finish, then ``total_seconds``, ``cache_builds`` and the ``manifest`` path; completed voice jobs include each manifest line and its warnings. If a line is ``suspect``, an agent cannot listen to it: regenerate with slightly different wording, or accept it when the transcript differs only in punctuation.
qc_runRun technical QC on a rendered project-relative video. Pass a job id or saved report path when available. Inspect the returned sheet, the end card frame (``end.jpg``) and up to four overlay crops before delivery. ``storyboard`` is the EFFECTIVE storyboard of that render (the one of its format after the re-layout: ``renders/<batch>/_storyboards/<name>.json``, found by itself next to a batch render): the overlay crops are then taken where its overlays really are (a caption moved by ``render_formats`` is not cut in half), and ``caption_on_face`` checks the rendered frames for a caption on a face (needs the vision environment; every format, 9:16 too).
ad_scoreScore a rendered ad out of 100 for creative quality, with findings to fix. ``qc_run`` says the file is technically correct; this says whether the ad is any good: a first second that holds attention (motion or a cut, a face or the product, a text within 0.5 s, audio at once), a pacing without a dip in the middle, captions that can be read (0.25 s per word + 0.6 s, 7 words a line at most, contrast of 3:1 or more on the real frames), the problem before the product, a call to action and an end card in the last 4 s, overlays out of the platform interface (``platforms``: any of ``tiktok``, ``reels``, ``stories``, ``feed``; the first three by default, ``feed`` for a 4:5 or 1:1 video) and a clear loudness, a voice 6 dB over the music and no silence over 0.7 s. Pass the ``storyboard`` it was rendered from (object or saved path) for exact timings, words, roles and overlays; without it the checks that need them are listed in ``skipped``. The result has ``score``, ``sub_scores`` (hook, pacing, reading, story, safe_zones, audio), ``findings`` sorted by ``impact`` (each with ``time``, ``severity``, ``message`` and ``fix``), ``passed``, ``skipped``, the pixel boxes of the ``safe_zones`` and the ``thresholds`` (guidelines, not rules). Images: ``safe_zones_preview.jpg`` (the zones of each platform over a mid-ad frame, red where an overlay falls inside) and the frame of each top finding: LOOK at them. Run it before delivery, fix the top findings, render again, and aim for 80 or more. The texts of an ``info_card`` are read like written captions (0.25 s per word + 0.6 s) and count for the call to action, like the texts of an end card made with ``end_card``; with ``story: "offer"`` in the storyboard ``product_too_early`` is not counted (and ``skipped`` says why).
compare_pairMeasure how different a before and an after look, to rank candidate pairs. ``before`` and ``after`` are project files: images, or clips (the frame at ``before_t`` / ``after_t`` seconds, the middle of the clip by default). ``before_crop`` / ``after_crop`` (``{x, y, w, h}`` in source pixels) cut one half out of a side-by-side composite, the same crop a ``reveal`` side takes. The comparison is made on the face when a skin-region heuristic finds one in both pictures (so a different distance still lines up), else on the whole frame after aligning sizes. ``visible_difference`` is 0 to 100 (under 12 not visible, under 30 subtle, under 55 visible, above that obvious at a glance); ``region`` says what was compared. The preview image shows the two pictures side by side: LOOK at it. Compare every available pair (photos, composites split with ``crop``, frames of before/after clips) and use the one whose difference is obvious; a still pair of the same pose beats moving clips for a reveal.
| reference_decode | Decode a reference video into shots, pacing, text, speech and sheets. ``transcribe`` is true, false or "auto" (default: transcribe when the reference has audible sound and a transcriber is available). Returns the JSON, the overview sheet, then up to 6 shot sheets (one row per shot, three frames each). LOOK at every shot sheet and read the on-screen text, then call reference_breakdown with the filled breakdown_template before choosing footage. The JSON is compact: the per-word transcript and rms_per_second stay in reference.json (see ``files``); each shot has its ``spoken`` text and ``transcript_text`` holds the whole transcript. ``breakdown_vocabularies`` lists the allowed type, scale, role, motion, emotion, text_speaker and text_device values and how to read who speaks in the on-screen text; ``music_profile`` is the tempo and energy of the reference soundtrack (voice included). | |
| reference_breakdown | Save the agent's shot-by-shot breakdown of a decoded reference. ``reference`` is the decode folder (reference/<slug>) or its reference.json. ``shots`` follows breakdown_template: one entry per shot, or one entry for consecutive shots (``"shots": [4, 5]``); every decoded shot must be covered exactly once. Controlled values: type, scale, role, motion, emotion, text_speaker, text_device (errors list the allowed ones); ``action`` is free short text: what the person does (for example "wipes the counter and sighs"). For every shot note what the person feels (``emotion``) and does, then pick a library shot with the same emotion and the same kind of action. text_speaker and text_device say who speaks in the on-screen text (an emoji or name, ":" and quotes is a character talking); subject is a short id (person_a, product, diagram), on_screen_text is read verbatim, replacement is a library entry id or "missing: ...". Returns type demand, scale mix, role sequence, repeated patterns, people, text shots, text_devices, dialogue, emotion_by_role (the emotions used for each role), pacing and missing shots. Use it before library_overview. | |
| library_overview | Overview of the footage folders without indexing, plus a mosaic. Lists folders up to ``depth`` with file, video and image counts, total video seconds and first file names. With ``mosaic``, returns a labelled thumbnail mosaic of the media under ``path`` (48 per page, 6 columns); ``pages`` tells how many, call again with ``page`` to see the next ones. Run it on the whole footage tree (B-roll folders included) to find each shot type the reference breakdown needs, before choosing shots. | |
| frame_view | Extract one full-resolution frame from a project video or image. Give the time ``t`` (seconds) or the frame number ``frame`` (video only, counted from 0). Returns the frame ON SCREEN at ``t`` (``floor(t * fps)``): at 2.87 s of a 30 fps video that is the frame starting at 2.867 s, not the next one at 2.900 s. A ``t`` within 1 ms of a frame boundary is that frame (10.9333 s at 30 fps is frame 328), so a time printed to four decimals lands on the right frame. ``frame_t`` is the frame's exact start time and ``frame`` its number (video only). Use it to inspect the exact moment behind a timecode; the saved frame is under cache/frames/. | |
| timeline_export | Export a storyboard as an editable timeline for DaVinci Resolve or Premiere Pro. Writes ``exports/<name>/`` with ``<name>.otio`` (OpenTimelineIO: video tracks, speed as a time warp, stills, captions as markers on V1, overlay pictures, voice, music and one audio track per sound effect), ``<name>.xml`` (Final Cut Pro 7 XML, read by Premiere Pro and Resolve, with the real rate, size and duration of each source, speed as Time Remap, music and sound effect levels and fades), ``<name>.edl`` (CMX 3600, video cuts only, the fallback), ``<name>.srt`` (every caption at its final time), ``overlays/`` (each caption, sticker and card as a full-canvas transparent PNG named after its storyboard overlay index, with its place in ``overlays.json``) and ``README.txt``. ``formats`` is any of ``otio``, ``fcp7xml``, ``edl``, ``srt`` (all by default). Media paths are absolute, as the project sees them; ``relative`` writes ``exports/<name>-relative/`` with paths relative to the folder (and a ``relink.txt``), ``copy_media`` writes ``exports/<name>-portable/`` with the used sources copied into ``media/``; ``media_root`` is the absolute folder a relative export will live in. A folder that holds an export of another media mode is only replaced with ``overwrite=true``. The result lists ``warnings`` (what is approximated) and ``not_exported`` (what no editor format here carries: grading, reframing, pop animations, split layout, loudness, the EDL audio). | |
| recipe_list | List available ad recipes with purpose and duration. Use this to shortlist a shape, then read its checklist with recipe_get before writing a storyboard. | |
| recipe_get | Return one complete recipe, including rules and example. Use its checklist as the storyboard acceptance criteria. | |
| editing_guide | Return the editing doctrine for footage, copy, rendering and QC. Read it before the first storyboard and whenever a rule is unclear. | |
| storyboard_schema | Return the JSON Schema for Storyboard v1. Use it to construct agent-authored storyboards before validation. | |
| storyboard_save | Save a storyboard in the project as ``storyboards/<name>.json`` and return its path. Send the storyboard object once, then pass the returned path (``"storyboards/<name>.json"``) as ``storyboard`` to ``storyboard_validate``, ``render_start`` and ``caption_preview`` instead of repeating the whole object (useful on a remote server). Saving again under the same name replaces the file. The object is stored as sent, not validated: ``storyboard_validate`` checks it. | |
| storyboard_patch | Edit a saved storyboard in place: ``changes`` is a list of ``{path, value}``. A path walks the JSON with dots and indexes: ``segments.3.out`` (``segments[3].out`` works too). Setting a missing key of an object adds it; the index just past the end of a list, or ``-``, appends; ``{"path": "overlays.1", "remove": true}`` deletes. The changes apply in order to a copy: if one is wrong, nothing is saved and the error names it. When the changes rename the storyboard (``name``), its ``output.path`` follows if it was the default of the old name (a path set by hand stays). The file ``storyboards/<name>.json`` is rewritten and the result lists the schema problems left (``problems``, empty when the storyboard is valid; run ``storyboard_validate`` for the full check). | |
| caption_preview | Render a caption, a comment or an information card over a real 9:16 frame. An ``info_card`` overlay (see the storyboard schema) is drawn, settled, as the render draws it: the result has its image on the real frame, its ``bbox`` (inside the frame when it fits), ``size_used`` (the title size), ``overflow`` and ``lines``. A banned word of the brand in its texts is an error. Use it before rendering to inspect placement; the JSON reports bbox, fitted size, overflow and final lines. ``emoji`` takes the storyboard ``emoji`` values (twemoji, none or a project folder) so the preview matches the render; ``emoji_missing`` lists emoji absent from a folder. For a ``voice_captions`` overlay pass ``manifest``: the ``audio.voice`` path of your storyboard (voice/<name>/manifest.json); ``expanded`` lists the resulting captions once. A ``speech_captions`` overlay is built from the speech of the clips: pass ``chunk_index`` to pick the caption to draw and ``storyboard`` (a project path such as ``storyboards/<name>.json`` or the object) so the timeline is the one of your ad; without it the captions are those of ``source`` played whole. ``expanded`` lists them all. With ``start``/``end`` on a ``voice_captions`` or ``speech_captions`` overlay only the captions inside that window exist (``chunk_index`` counts those); a voice preview takes its offset from the overlay (``offset``), not from the storyboard. An animated caption (``animation`` ``karaoke``, ``word`` or ``pop``) is drawn in one of its states, to check where the highlight lands: put ``chunk_index`` and ``word_index`` in the overlay object to pick the chunk and the lit word, or leave them out to get the state on screen at timeline time ``t``. The result names the ``word_index``, the ``window`` of the state and how many ``states`` the chunk has. | |
| end_card | Compose a clean end card image from a real product photo. Use it only when the brand has no ready-made call-to-action image: when it has one (``brand.cta_image``, a ``cta/`` folder or ``brand/``), use that image as the last segment (``image``, ``zoom_in``, about 3 s) instead. It writes ``brand/endcards/<name>.png`` (1080x1920 unless ``spec.format`` says otherwise) and returns the path, the layout boxes and the image: LOOK at it. ``spec``: ``product_image`` (project path of a photo or a video, with ``t`` for the frame, optional ``crop`` {x,y,w,h} in the source's display pixels, before scaling: on a 1920x1080 frame ``{"x": 600, "y": 100, "w": 700, "h": 700}`` keeps a 700 px square; the result returns ``source_size`` [w, h] to measure it), ``pill``, ``title`` (a string or runs ``{text, accent}``), ``subline``, ``badges`` (up to 3, ``{text, icon: check|star|none}``), ``button`` (``{text, arrow: down|right|none}``), colours ``accent``, ``text``, ``muted``, ``background`` (two colours), ``family``, ``emoji``. Colours default to the brand's. Banned words of the brand on any text are an error. Use the PNG as the last segment: ``type: image``, ``motion: zoom_in``, about 3 s, label ``end_card``, no subtitles on it. It also writes ``brand/endcards/<name>.png.json``, the texts drawn (pill, title, subline, badges, button): ``storyboard_validate`` reads it, so ``cta_text_missing`` is not raised when the button already says the brand's call to action. | |
| storyboard_validate | Validate a storyboard object or project-relative JSON file. ``storyboard`` is the object, or the path saved by ``storyboard_save`` (``"storyboards/<name>.json"``). Every schema error is reported at once. The check covers Storyboard v1, its files, brand and recipe. Fix every error path before render_start; warnings are questions to review. With ``reference`` set, ``ref_*`` warnings and a ``reference_comparison`` block compare the edit with the reference breakdown. With ``score_check=true`` it also runs the quick pre-check of ``ad_score`` that needs no pixels, as warnings prefixed ``score_`` (reading time and line length, product too early, call to action, platform safe zones of the overlays); ``summary.score_precheck`` lists what passed and what could not be checked. Warning ``segment_crosses_cut``: a clip segment (or the clip side of a ``split`` panel or a ``reveal``) whose source is indexed has a change of take (a shot boundary of ``library_view``) strictly inside its range, more than 0.12 s from each end as the viewer sees it (``speed`` counts). The viewer would see a flash of another take, or a jump in the middle of the shot: move ``in`` after the cut or ``out`` before it, as the message says. ``summary.cut_check`` counts the segments checked and the ones that cross a cut, and lists under ``old_shots`` the sources measured before 0.4.0, whose shots can hide cuts. Sources that are not indexed, or have one shot, say nothing; run ``library_index`` (``refresh_shots=true`` for catalogs made before 0.4.0) so that the cuts of long clips are known. ``cta_text_missing`` also reads the texts of an end card made with ``end_card`` when it is the last segment, and those of ``info_card`` overlays. Information cards (``info_card`` overlays): each is drawn and checked. Error ``info_card_out_of_frame`` (the card leaves the frame), ``banned_word`` in its texts; warnings ``info_card_overlap`` (two cards on screen together: show one at a time), ``caption_over_info_card`` (a caption overlaps a card while both are on screen: pause the captions with ``start``/``end``), ``text_overflow`` (the title does not fit at its smallest size) and ``emphasis_unmatched``. With ``story: "offer"`` (announcements, lead collection, offers where the product is in hand from the first second) ``product_too_early`` is not raised, and ``summary.skipped`` says so. | |
| render_start | Validate and queue a background render. ``storyboard`` is the object or a saved path (``"storyboards/<name>.json"``). Use preview while iterating and final after QC. A rejected storyboard returns validation errors and creates no job. | |
| variants_build | Build the matrix of variants of one storyboard: hooks x bodies x calls to action. ``base`` is a storyboard (object or ``"storyboards/<name>.json"``). ``variants`` is ``{axis: [{id, changes}]}`` for up to 3 axes (for example ``hook``, ``body``, ``cta``). ``changes`` is a list applied in order, each a ``storyboard_patch`` change (``{path, value}`` or ``{path, remove: true}``) or a SLOT REPLACEMENT ``{replace_label: "hook", segments: [...], overlays: [...]}``: it swaps every segment of that label (they must be next to each other) and shifts everything after it by the difference of duration (overlays, sounds and word times follow). The new ``overlays`` are timed from the start of the slot; the overlays that were on the replaced segments go away. A voice-over (``audio.voice``) laid on the timeline must still match: a change of duration while one is set is refused with the reason, as is an overlay that only partly overlaps the slot. An option with no ``changes`` (or ``[]``) is the control: the base unchanged. Timed sounds follow the slot: an ``sfx`` overlay after it shifts by the difference of duration, one inside it goes away when the new slot brings its own sounds (else it keeps its offset); each variant lists what moved under ``moved``. All the errors of all the variants come back at once (variant, path, message). Makes the cartesian product (at most 24, each validated), saves each as ``storyboards/<name>.json`` (``name_pattern`` uses ``{base}`` and the axis names; the default falls back to the axis ids in order when an axis is not hook or cta) and returns the list with the path, ids, duration and warnings of each, plus a contact sheet: the first 3 s (top row) and the last 3 s (bottom row, the call to action) of every variant (LOOK at it, a hook that does not read at that size will not read in the feed). A base that is itself a variant keeps its ids in the new ones (the manifest keeps ``hook=h2;cta=ca``). Then ``render_batch`` renders them with a shared cache. Vary the hook first; keep everything else identical. A storyboard file that already exists is NEVER overwritten, whoever made it (an earlier ``variants_build`` included, or a file edited by hand since): the error lists every file that would be replaced. ``overwrite=true`` replaces them all. Renders may be replaced; storyboards may not. | |
| render_batch | Queue ONE background job that renders several storyboards in order. ``quality``: ``final``, ``preview`` or ``draft`` (an alias of ``preview``: half-size ``*.preview.mp4`` files; the report and the manifest say ``preview``, and the manifest has a ``quality`` column because a preview scores lower than its final). ``storyboards``: objects or saved paths (typically the variants of ``variants_build``). The segment cache is shared, so a segment used by several variants (the body, the end card) is built once: the first render is the slow one. ``formats`` (any of ``"9:16"``, ``"4:5"``, ``"1:1"``) renders each storyboard in those ratios; when omitted each storyboard's own ``formats`` field is used, else it renders as it is. Files go to ``renders/<batch>/`` (``batch`` defaults to ``<first name>_batch``) named ``<name>[_9x16|_4x5|_1x1].mp4``, and ``renders/<batch>/manifest.csv`` lists them for an ads manager (file, variant ids, format, duration, score, hook text, CTA text). ``score`` runs ``ad_score`` on each final render for the manifest (with the safe zones of its placement). ``job_status`` shows the progress per render, each output as it finishes, and at the end ``total_seconds``, ``cache_builds`` and the manifest path. A storyboard that does not validate rejects the whole batch with its errors and no job. | |
| render_formats | Render one storyboard in several formats: ``9:16``, ``4:5``, ``1:1``. ``formats`` defaults to the storyboard's own ``formats`` field, else all three. One detached job (see ``render_batch``), one file per format: ``<name>_9x16.mp4``, ``<name>_4x5.mp4``, ``<name>_1x1.mp4`` in ``renders/<batch>/`` (``batch`` defaults to ``<name>_formats``). Each is the same ad laid out for its placement: the footage is re-cropped (face-aware with ``focus: "face"``, else by ``focus``); a still or an end card that does not fit is shown whole over its blurred copy; captions, stickers and images keep their place by bands (the part the platform leaves free is mapped onto the free part of the new frame, 4:5 and 1:1 being the Feed) and are pushed back inside when a block would leave it. An ``info_card`` is placed like an image card: its ``y`` follows the same bands, its width and text scale with the frame (the title stays at 38 px or more) and it stays inside the frame. ``ad_score`` uses the safe zones of the matching placement (``feed`` for 4:5 and 1:1). LOOK at each format's contact sheet before delivery. | |
| voice_generate | Queue a checked voice-over generation job. Poll job_status until it is done, then use each manifest line's ``start`` and ``duration`` to place shots. If a line is ``suspect``, regenerate it with slightly different wording or accept it when the transcript differs only by punctuation; agents cannot listen to audio. ``unmatched_words`` lists the key words (4+ letters) missing from the transcript: two or more make the line suspect, so reword them. When the voice says the end of a line again (2 or more extra words after the whole text) the audio is cut after the last expected word: the line has ``extra_words`` and ``trimmed_extra: true``; extra words that could not be cut make it ``suspect``. A line is a string (said and shown) or ``{"say": ..., "show": ...}`` when captions must display something other than the spoken words (say "forty-nine dollars ninety", show "$49.90"). Calling again with an existing ``name`` replaces that voice (unchanged lines come from the cache); the job summary then has ``replaced: true``. ``language`` in the spec is optional: without it the ``language`` of brand.yaml is used, else ``en``. | |
| sfx_list | List the sound effects of the project's ``sfx/`` folder, and build the pack. ``fetch=true`` first builds the missing sounds of the pack (about 18: whoosh short and long, swoosh, swipe, pop, click, tap, ding, chime, notification, cash register, camera shutter, record scratch, typing, riser 1 s and 2 s, impact, boom). Each is downloaded from a pinned CC0 source (checked by SHA-1) or synthesised in code, trimmed and set to one level, with the source and licence in ``sfx/LICENCES.txt``. A download that fails is synthesised instead (``offline=true`` synthesises all of them). The files you drop in ``sfx/`` yourself are listed too. Each sound returns its ``name``, ``path`` (the ``source`` of an ``sfx`` overlay), ``duration`` and ``origin``. Use a sound in an ``sfx`` overlay (``{"type": "sfx", "source": "sfx/pop.wav", "at": 3.2, "volume": 0.8}``) or by name in ``audio.sfx_auto``. A riser is placed so that its end meets the moment it builds towards: ``at`` = that moment minus its duration. | |
| music_beats | Beat times of a music track, as it will play in the ad. ``path`` is a project file (audio, or a video whose soundtrack is the music). ``start`` is the storyboard's ``audio.start``: the times are in seconds from the start of the ad, so beat 0 of the result is the first beat heard. They come from the onset envelope and the estimated tempo, on a regular grid whose phase is aligned to the strongest onsets (within a few milliseconds on a steady beat). ``duration`` limits the analysis (default the first 120 s). A track without a steady beat (a piano, a pad) returns no beats. Cut on these times for a music-led ad, or let ``storyboard_snap`` do it. | |
| storyboard_snap | Move the cuts of a storyboard onto the beats of its music. ``storyboard`` is the object or a saved path. Each cut within ``max_shift`` seconds (default 0.2) of a beat of ``audio.music`` (from ``audio.start``) moves to it: the ``out`` of the earlier clip (or the ``duration`` of an image) changes, ``in`` points and segment order never do, no segment ends up under 0.5 s (or shorter than it was), the other cuts and the total duration stay, and the captions, images and sounds that started on a moved cut move with it. With ``audio.clips`` the cuts of talking segments never move. The result lists ``moves``, the cuts ``kept`` with the reason, and how many cuts are on a beat before and after. It returns the new ``storyboard``, or with ``save_as`` (a name) writes ``storyboards/<name>.json`` and returns its path instead. The snapped storyboard has its own identity so a render never overwrites the original: with ``save_as`` its ``name`` is ``save_as``, without it the old name plus ``_snapped``, and ``output.path`` is ``renders/<that name>.mp4`` (the quality is kept). Run ``storyboard_validate`` afterwards: its ``beat_alignment`` info shows the share of cuts on a beat. | |
| music_profile | Tempo, loudness and energy of the music tracks, to match a reference. Without ``path``, profiles every audio file of ``music/``; with ``path`` (project-relative), one file, which may be a video such as the reference (its soundtrack mixes voice and music). Each track returns its duration, integrated loudness (LUFS), estimated tempo (``tempo_bpm``), ``energy`` (onsets per second and loudness range in LU) and ``feel``: calm, medium or energetic (thresholds in ``feel_thresholds``). Pick the library track whose profile is closest to the reference's: a calm track under a fast reference feels flat. | |
| music_search | Find music whose licence lets an ad use it (commercial use and modification). Searches Openverse (no key; ``source="openverse"``), Freesound (``"freesound"``, only with the ``FREESOUND_API_KEY`` environment variable) or both (``"all"``; without the key the answer says so and still lists Openverse). Kept licences: CC0, PDM, CC BY, CC BY-SA; NC and ND are dropped. Each track returns ``source``, ``id``, ``title``, ``author``, ``licence``, ``duration`` (s), ``source_url``, ``preview_url`` (listen before fetching) and ``attribution_required`` (with the ``attribution_text`` to put in the ad's description). ``mood`` adds words to the query ("calm", "upbeat"). ``min_duration`` and ``max_duration`` filter in seconds. ``fit_to="storyboard"`` with ``storyboard`` (a project path such as ``storyboards/summer.json``) ranks for that ad: tracks at least as long as the ad first, then the wanted feel (``audio.music_feel``, or the ``feel`` argument: calm, medium, energetic) against ``fit.feel_guess``, a guess from the track's OWN title, tags and genres (``unknown`` when they say nothing; never copied from the wanted feel). The real feel, tempo and loudness come from ``music_fetch``: trust that, not the guess. Fetch the best ones, listen, and choose. | |
| music_fetch | Download a track from ``music_search`` into ``music/``, with its licence. ``source`` and ``id`` come from the search result. Writes ``music/<file>``, the record ``music/<file>.licence.json`` (source, id, URL, title, author, licence, licence URL, attribution text, fetch date) and a line in ``music/LICENCES.txt``, then profiles the track: the answer has ``path`` (the ``audio.music`` value), ``duration``, ``tempo_bpm``, ``feel`` and ``loudness_lufs``. A licence that is not CC0, PDM, CC BY or CC BY-SA is refused. An embedded cover picture is removed from the stored file. The render and ``ad_score`` read the record (the sidecar, else the track's line in ``LICENCES.txt``): ``music_licence_unknown`` when a track has neither, ``music_attribution_required`` (with the exact text) when it needs one. Freesound serves its high-quality MP3 preview (the original needs a login). | |
| music_generate | Make an instrumental track locally (optional ACE-Step environment), as a job. Needs ``adanvil music-setup`` (about 3 GB of packages, then 8 GB of weights at the first run). ``prompt`` is a list of tags ("upbeat acoustic guitar, warm, 110 bpm, instrumental"); ``duration`` 10 to 120 s. On a CPU a 30 s track takes several minutes: poll ``job_status``; its ``music`` field has the ``path`` (the ``audio.music`` value), tempo, feel and loudness. The model and its weights are Apache-2.0: no attribution; the licence record is written next to the file like for a fetched track. | |
| voice_view | Read a voice manifest and suggest final-timeline shot boundaries. ``offset`` is the intended voice start on the final video timeline. Suspect lines should be regenerated with slightly different wording or accepted only when the transcript difference is punctuation. Each line's ``unmatched_words`` lists key words the transcript lacks. ``extra_words`` lists words heard after the whole text (a repeated end): with ``trimmed_extra`` true the audio was already cut after the last expected word, else the line is ``suspect`` and still ends on them (regenerate it). | |
| job_status | Read a queued, running, completed or failed render, batch, voice, index or refine job. With ``wait_seconds`` greater than zero, wait in this call (up to 600 seconds) instead of polling from the client; if the connection drops, just call again, a restarted server still finds the job. Pass ``project_dir`` when it says "job not found". Completed index jobs carry the compact index summary; completed speech_refine jobs carry ``refine`` (refined clips, skipped clips with the reason, errors). Completed render jobs include the persisted RenderReport JSON; batch jobs (``render_batch``, ``render_formats``) carry ``batch``: one entry per render (status, file, format, duration, score, seconds, error) as they finish, then ``total_seconds``, ``cache_builds`` and the ``manifest`` path; completed voice jobs include each manifest line and its warnings. If a line is ``suspect``, an agent cannot listen to it: regenerate with slightly different wording, or accept it when the transcript differs only in punctuation. | |
| qc_run | Run technical QC on a rendered project-relative video. Pass a job id or saved report path when available. Inspect the returned sheet, the end card frame (``end.jpg``) and up to four overlay crops before delivery. ``storyboard`` is the EFFECTIVE storyboard of that render (the one of its format after the re-layout: ``renders/<batch>/_storyboards/<name>.json``, found by itself next to a batch render): the overlay crops are then taken where its overlays really are (a caption moved by ``render_formats`` is not cut in half), and ``caption_on_face`` checks the rendered frames for a caption on a face (needs the vision environment; every format, 9:16 too). | |
| ad_score | Score a rendered ad out of 100 for creative quality, with findings to fix. ``qc_run`` says the file is technically correct; this says whether the ad is any good: a first second that holds attention (motion or a cut, a face or the product, a text within 0.5 s, audio at once), a pacing without a dip in the middle, captions that can be read (0.25 s per word + 0.6 s, 7 words a line at most, contrast of 3:1 or more on the real frames), the problem before the product, a call to action and an end card in the last 4 s, overlays out of the platform interface (``platforms``: any of ``tiktok``, ``reels``, ``stories``, ``feed``; the first three by default, ``feed`` for a 4:5 or 1:1 video) and a clear loudness, a voice 6 dB over the music and no silence over 0.7 s. Pass the ``storyboard`` it was rendered from (object or saved path) for exact timings, words, roles and overlays; without it the checks that need them are listed in ``skipped``. The result has ``score``, ``sub_scores`` (hook, pacing, reading, story, safe_zones, audio), ``findings`` sorted by ``impact`` (each with ``time``, ``severity``, ``message`` and ``fix``), ``passed``, ``skipped``, the pixel boxes of the ``safe_zones`` and the ``thresholds`` (guidelines, not rules). Images: ``safe_zones_preview.jpg`` (the zones of each platform over a mid-ad frame, red where an overlay falls inside) and the frame of each top finding: LOOK at them. Run it before delivery, fix the top findings, render again, and aim for 80 or more. The texts of an ``info_card`` are read like written captions (0.25 s per word + 0.6 s) and count for the call to action, like the texts of an end card made with ``end_card``; with ``story: "offer"`` in the storyboard ``product_too_early`` is not counted (and ``skipped`` says why). | |
| compare_pair | Measure how different a before and an after look, to rank candidate pairs. ``before`` and ``after`` are project files: images, or clips (the frame at ``before_t`` / ``after_t`` seconds, the middle of the clip by default). ``before_crop`` / ``after_crop`` (``{x, y, w, h}`` in source pixels) cut one half out of a side-by-side composite, the same crop a ``reveal`` side takes. The comparison is made on the face when a skin-region heuristic finds one in both pictures (so a different distance still lines up), else on the whole frame after aligning sizes. ``visible_difference`` is 0 to 100 (under 12 not visible, under 30 subtle, under 55 visible, above that obvious at a glance); ``region`` says what was compared. The preview image shows the two pictures side by side: LOOK at it. Compare every available pair (photos, composites split with ``crop``, frames of before/after clips) and use the one whose difference is obvious; a still pair of the same pose beats moving clips for a reveal. |
Configuration
ADANVIL_PROJECTS_DIR
| Name | Description | |
|---|---|---|
| ADANVIL_PROJECTS_DIR | — |
Automated checks
Ran Nov 13, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packagePass
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledPass
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesPass
README
View on GitHubAdAnvil
An MCP server that lets an AI agent edit vertical 9:16 video ads.
AdAnvil works with Claude Code, Codex, Cursor or any MCP client. It builds ads from a brand's own footage, from a reference ad, or from an idea. The agent judges (which clips, what the text says, whether the result looks right). AdAnvil renders deterministically and checks the result: the same storyboard always gives the same video.
It is not tied to a niche. The recipes and the editing guide speak in general terms (product, benefit, problem, target customer) with examples from several niches: coffee, fashion, fitness, pets, software, home, beauty.

The demo above was made from the CC0 demo pack in examples/demo/ (four Wikimedia Commons clips, a product still and a fictional brand called Ember & Oak). No footage is stored in this repository: the pack is fetched on demand.
What it does
- Reference decoding: shots, pacing, burnt-in text and speech, plus a shot-by-shot breakdown the agent writes and compares to your edit.
- Footage library: indexing, contact sheets and mosaics so the agent can look at every clip before using it, and the speech of every video and audio file (word timestamps, searchable as soon as each file is done) so a talking creator can be cut on the pauses. Cuts are found on every frame, so the jump cuts between the takes of a long phone clip are separate shots, and the validator warns when a segment crosses one (a flash of one take, then another).
- 9 recipes (YAML) for common ad shapes: text hook, hook plus product, before and after, customer diary, comment reply, meme text, voice-over ad, long remake, talking-head UGC.
- 7 caption styles (
pill,meme,outline,outline_soft,box,label,comment) with emoji support. - Removal of burnt-in text from reference footage.
- HDR (HLG and PQ) to SDR tone-mapping.
- Music matching and loudness control.
- Optional open-source voice-over (Chatterbox) with captions synced to the spoken words, paused with
start/endwindows; a sentence end the voice repeats is cut and flagged. - Talking-head UGC: best take of each line across several recordings, cuts on the pauses without hesitations, the creator's own sound kept (with B-roll laid over the voice), captions built from the speech.
- Visual devices: a before/after reveal (a divider sweeps one picture away to show the other), split screens, picture cards (a photo or a screenshot that comes in over the video), video insets (picture-in-picture), stickers and arrows, a progress bar and punch-in zooms, and information cards drawn by AdAnvil (one idea per card, one card at a time, on screen while the voice says it).
- Sound design: a pack of about 18 sound effects (CC0 or synthesised, never stored in the repository),
sfxoverlays andaudio.sfx_autoat the cuts and captions, and cuts that snap to the beat of the music. - End cards composed from a real product photo, and offer storyboards (
story: "offer") for announcements and lead-collection ads that show the product from the first second. - Quality control with images: automatic checks, contact sheet of the result, full-resolution frames.
- Detached background jobs for indexing, voice and rendering, so long work survives a dropped connection.
Install
Pick one path. The first is the simplest.
1. Claude Desktop extension (one click)
Download adanvil-<version>.mcpb from the latest release, double-click it, and click Install in Claude Desktop. It asks for a projects folder and, optionally, a Freesound key (stored securely). You still need ffmpeg 6.1 or newer on your computer (brew install ffmpeg, winget install Gyan.FFmpeg, sudo apt install ffmpeg); if it is missing, the extension says so with the command for your system.
2. Docker (no Python, no ffmpeg to install)
git clone https://github.com/maxbuildog/adanvil && cd adanvil
docker build -t adanvil .
The image has ffmpeg 6.1, runs as a non-root user and speaks MCP over stdio. Mount the folder that holds your projects at /projects; the agent must give tool calls paths under /projects (for example /projects/my-ad): the image sets ADANVIL_PROJECTS_DIR=/projects, so any other folder, and /projects itself, is refused.
# Claude Code
claude mcp add adanvil -- docker run -i --rm -v "$PWD:/projects" adanvil
On Linux add --user "$(id -u):$(id -g)" so the files written to the folder belong to you.
Codex, in ~/.codex/config.toml:
[mcp_servers.adanvil]
command = "docker"
args = ["run", "-i", "--rm", "-v", "/home/you/ads:/projects", "adanvil"]
tool_timeout_sec = 900
default_tools_approval_mode = "approve" # needed with approval_policy = "never" (codex exec)
Cursor, in .cursor/mcp.json:
{
"mcpServers": {
"adanvil": {
"command": "docker",
"args": ["run", "-i", "--rm", "-v", "/home/you/ads:/projects", "adanvil"]
}
}
}
The image holds the base package only. Transcription is available with docker build --build-arg EXTRAS=transcribe -t adanvil:transcribe .. The voice, vision and music-generation environments (adanvil voice-setup, vision_setup, music-setup) are not included: they need gigabytes of models, so use the uvx path for them.
3. uvx
Requirements: Python 3.11 or newer, uv (it provides uvx), and ffmpeg 6.1 or newer, built with libzimg, on your PATH (check with ffmpeg -version; if it lives elsewhere, set ADANVIL_FFMPEG and ADANVIL_FFPROBE to the full paths).
# 1. Check the install (the first run downloads the package)
uvx --from adanvil adanvil --version
# 2. Register the server in Claude Code
claude mcp add adanvil -e ADANVIL_PROJECTS_DIR="$HOME/AdAnvil" -- uvx --from adanvil adanvil-mcp
# 3. Then ask your agent:
# "Make a 9:16 ad from the footage in ./my-project"
ADANVIL_PROJECTS_DIR (recommended) is the folder that holds your projects: the server then refuses any project outside it. Projects are subfolders of it (for example ~/AdAnvil/summer-ad). See SECURITY.md.
The package is named adanvil. It installs two commands: adanvil (command line) and adanvil-mcp (the MCP server over stdio). uvx adanvil-mcp alone does not work, because uvx looks for a package with that name: always add --from.
The agent creates the project folder and tells you where to drop your files: footage in footage/, the reference ad in reference/, music in music/, logo and end card in brand/. It learns the method from the editing_guide tool and from AGENTS.md.
Codex, in ~/.codex/config.toml:
[mcp_servers.adanvil]
command = "uvx"
args = ["--from", "adanvil", "adanvil-mcp"]
env = { ADANVIL_PROJECTS_DIR = "/home/you/AdAnvil" }
tool_timeout_sec = 900 # indexing long footage can take minutes
default_tools_approval_mode = "approve" # needed with approval_policy = "never" (codex exec)
Without default_tools_approval_mode, a non-interactive codex exec run rejects every AdAnvil tool call with "MCP tool call requires approval".
Cursor, in .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):
{
"mcpServers": {
"adanvil": {
"command": "uvx",
"args": ["--from", "adanvil", "adanvil-mcp"],
"env": { "ADANVIL_PROJECTS_DIR": "/home/you/AdAnvil" }
}
}
}
Any other MCP client (generic stdio entry):
{
"mcpServers": {
"adanvil": {
"type": "stdio",
"command": "uvx",
"args": ["--from", "adanvil", "adanvil-mcp"],
"env": { "ADANVIL_PROJECTS_DIR": "/home/you/AdAnvil" }
}
}
}
Restart the client after editing its config, then ask the agent to call recipe_list. Nine recipes means the server is connected.
Optional: reference transcription needs the transcribe extra (faster-whisper). Use --from "adanvil[transcribe]" in place of the plain --from value above.
Try it with the demo pack
The demo needs a checkout, because the fetch script lives in the repository:
git clone https://github.com/maxbuildog/adanvil
cd adanvil
uv sync
uv run python examples/demo/fetch_demo.py ./demo-project
uv run adanvil index ./demo-project --source footage
Then register the MCP server and ask your agent to make an ad from ./demo-project (give it the absolute path), or follow the command line walkthrough in examples/demo/README.md.
How it works
Everything lives in one project folder: footage/, brand/, music/, reference/, renders/, cache/, plus adanvil.json, brand.yaml and catalog.json. Every tool takes the absolute project_dir; every other path is relative to it and cannot escape it.
- The agent indexes the footage, looks at the contact sheets, and optionally decodes a reference ad.
- It picks a recipe and writes a storyboard (JSON): shots, captions, audio.
storyboard_validatechecks the storyboard against the recipe rules, thenrender_startrenders it in the background.qc_runchecks the file and returns control images that the agent looks at before delivering;ad_scorescores its creative quality (aim for 80 or more).
Details: docs/ARCHITECTURE.md for the pipeline, docs/EDITING_GUIDE.md for the editing doctrine, and AGENTS.md for the step-by-step guide an agent follows (same content as skill/SKILL.md, the Claude Code skill version).
Choosing a model
The result depends on the model that drives AdAnvil. Reference analysis and shot choice are judgement work: use the strongest model you can (for example Claude Opus) for them. Smaller models execute the steps well, but they tend to copy the surface of a reference (same words, same shots) instead of rebuilding its logic for your brand.
Tools (43)
| Tool | What it does |
|---|---|
project_init |
Create an AdAnvil project skeleton. |
project_read_text |
Read one of AdAnvil's own text files in the project (licence notes, JSON, YAML; at most 1 MB). |
brand_onboard |
Read a brand's site, then write the brand profile from the answers. |
brand_get |
Read the brand profile and brief. |
library_index |
Index or refresh footage (long runs become detached jobs; refresh_shots measures the cuts again). |
library_view |
One catalogue entry with its contact sheet. |
library_annotate |
Save what the agent saw in a clip (description, people, emotion, quality, exclusion). |
library_search |
Search the indexed footage by text (including what the clips say), tags, people, emotion, duration, or by sentence (query, with the vision environment). |
speech_view |
Compact phrases (with flags), fillers, restarts and clean cut segments of one clip's speech. |
speech_takes |
The best take of each line across several recordings of a script. |
speech_refine |
Transcribe chosen clips again with a stronger model and the brand vocabulary (detached job). |
library_overview |
Overview of the footage folders without indexing, plus a mosaic. |
frame_view |
The full-resolution frame ON SCREEN at t (floor(t * fps), a t within 1 ms of a frame boundary is that frame) or at frame, with its exact time. |
reference_decode |
Decode a reference video into shots, pacing, text, speech and sheets. |
reference_breakdown |
Save the agent's shot-by-shot breakdown of the reference. |
recipe_list |
List the ad recipes with purpose and duration. |
recipe_get |
One full recipe with its rules and an example. |
editing_guide |
The editing doctrine for footage, copy, rendering and QC. |
storyboard_schema |
The JSON Schema of the storyboard. |
storyboard_save |
Save a storyboard as storyboards/<name>.json once; later tools take that path instead of the object. |
storyboard_patch |
Edit a saved storyboard with a list of {path, value} changes. |
caption_preview |
A caption, comment or information card drawn over a real 9:16 frame. |
end_card |
An end card image composed from a real product photo. |
storyboard_validate |
Validate a storyboard against its schema and recipe rules. |
render_start |
Validate and queue a background render (preview or final). |
voice_generate |
Queue a checked voice-over generation job. |
voice_view |
Read a voice manifest and suggested shot boundaries. |
music_profile |
Tempo, loudness and energy of the music tracks. |
music_search |
Find music whose licence allows an ad (CC0, PDM, CC BY, CC BY-SA) on Openverse and Freesound; fit_to="storyboard" ranks for an ad. |
music_fetch |
Download a found track into music/ with its licence record (.licence.json, LICENCES.txt), then profile it. |
music_generate |
Make a track locally (optional ACE-Step environment, adanvil music-setup), as a job. |
music_beats |
Beat times of a music track as it will play in the ad. |
sfx_list |
List the project's sound effects; fetch=true builds the CC0 sound pack in sfx/. |
storyboard_snap |
Move the cuts of a storyboard onto the beats of its music. |
job_status |
Status of a render, batch, voice or index job, with optional waiting. |
qc_run |
Technical QC on a rendered video, with control images (overlay crops follow the re-laid captions of a format; caption_on_face). Optional storyboard: the effective storyboard of that render. |
ad_score |
Creative score out of 100 of a rendered ad (hook, pacing, reading, story, platform safe zones, audio) with findings to fix and a safe zones preview. |
variants_build |
The matrix of variants of a storyboard (hooks x bodies x calls to action, up to 24): patches or slot replacements, validated and saved, with a contact sheet of the first and last 3 s of each. |
render_batch |
One detached job that renders many storyboards (and formats) with a shared segment cache and writes renders/<batch>/manifest.csv. |
timeline_export |
Export a storyboard as OpenTimelineIO, Final Cut XML, EDL and SRT plus the overlay PNGs (named by storyboard index), the sound effects and the music levels, with the real media descriptors and a not_exported list, to finish it in DaVinci Resolve or Premiere Pro (CLI: adanvil export). |
render_formats |
One storyboard in 9:16, 4:5 and 1:1 (re-cropped footage, captions re-laid out by bands, safe zones of the placement). |
compare_pair |
How different a before and an after look (0 to 100), on the face or the whole frame, with a side-by-side preview, to pick the pair. |
vision_setup |
Install the optional vision environment (search by sentence, automatic tags, product versions, faces). |
CLI commands (adanvil <command> --help): mcp, voice-setup, vision-setup, init, cat, onboard, index, decode, recipes, validate, render, voice, qc, preview-caption, end-card, sfx-fetch. Add --json for machine-readable output.
Smart library (optional)
Finding the right shot is the slowest part of an edit. adanvil vision-setup (or the vision_setup tool) installs, once, a separate environment (about 2.5 GB, CPU only, no GPU needed) with a small multilingual image and text model (SigLIP 2, Apache-2.0) and a face detector (YuNet, MIT); the licences are in THIRD_PARTY.md. Nothing else changes without it, and library_index then says vision: unavailable.
- Index with vision.
library_indexalso embeds the frames of each contact sheet and looks for faces (cache/vision/<file key>.npz), and gives every entryauto_tags(a fixed label list such asperson,bathroom,hands,smiling,text on screen), kept apart from your owntags. - Search by sentence.
library_search(query="a woman with a sad face touching her jaw"), in any language, ranks shots across the whole library, with the usual filters applied first, and returns the best ones with one numbered mosaic: no sheet to open. - Product versions from photos.
brand.yamllistsproduct_versions: [{name: current, photos: [...]}, {name: old, photos: [...]}]; indexing guesses which version each shot shows, andlibrary_search(product_version="current")uses the guess unless a human annotation exists (a human annotation always wins). Give photos, not words. - Face-aware framing.
focus: "face"keeps the main face centred atface_y(0.38 of the frame by default) on clips, images, split panels and reveal sides; arevealalso puts both faces at the same place and size by default (align_faces).compare_pairuses the face detector too.
Voice-over (optional)
AdAnvil can add a generated voice-over with Chatterbox, an open-source text-to-speech model, with captions synced to the spoken words.
- Run
adanvil voice-setuponce. It creates a separate Python environment (in the AdAnvil cache folder) and downloads about 3 GB of models.adanvil voice-setup --engine kokoroadds the fast engine (below) to the same environment. - Generation runs on the CPU. One worker process per job loads each model once and serves every step (speech, alignment, check). Measured on an idle 8-core server (French, 3 to 9 lines of about 5 seconds): the Chatterbox voice takes about 25 to 35 seconds per line, so 9 lines take about 5.5 minutes (it took 10.5 before V2.6); a busy machine is slower, count up to 5 minutes per sentence.
- Two engines.
chatterboxis the default and the recommended voice for ads (the owner listened to both and kept it): it clones thereferencevoice, so it also fits a brand that has a voice to match.kokoro(Apache-2.0) has fixed voices and no cloning ({"engine": "kokoro", "voice": "ff_siwis"}, Frenchff_siwis, Englishaf_heartby default,bf_emmaand others for British English): a fast option for drafts and previews (check the script, the timing and the captions before paying for the real voice), about 25 seconds for 9 lines plus 50 seconds of alignment and check on the same server. It speaks French and English only. - The pronunciation check reuses the alignment transcript when every word is confident (
check_confidence, default 0.6) and the line reads as written; only doubtful lines are transcribed again by thecheck_model. Setcheck_confidencetonull(orADANVIL_VOICE_CHECK_CONFIDENCE=off) to check every line with thecheck_model. - The voice speaks for the brand, as a narrator. It must not pose as a fake customer.
- The voice language is the
languageof the voice spec. When the spec does not set it, AdAnvil uses thelanguageof the project'sbrand.yaml(fr-FRcounts asfr), andenwhen the brand has none. - When the voice repeats the end of a sentence, the line is cut after the last word of the script and flagged (
trimmed_extra); a repeat that cannot be cut makes the line suspect. Write a foreign word as it must sound insay({"say": "...", "show": "..."}) and avoid acronyms the voice spells badly. - Chatterbox embeds a Perth watermark in its audio. AdAnvil keeps it. Do not remove it.
- Use only a reference voice you have the right to use.
Talking-head UGC (optional)
A creator talking to camera is cut from the speech in the footage. library_index transcribes the clips and audio files that have sound (word timestamps, in the same job, once per file, each file stored as soon as it is done), with faster-whisper when it is installed (pip install 'adanvil[transcribe]') or else the voice environment (adanvil voice-setup); without either, indexing still succeeds and the entries say so. Indexing uses a fast model to make the speech searchable; speech_refine transcribes the clips you keep again with a stronger one, and the brand name, the product name and speech.vocabulary of brand.yaml are given to the transcriber. A voice recorded in a separate audio file is found by name (separate_audio_candidates on a video with silent sound) and laid with audio_from; syncing is up to the agent, on a preview. Then speech_takes picks the best take of each line, speech_view gives the cuts that keep the speech and drop pauses and hesitations, and a storyboard with audio.clips, audio_from (B-roll over the voice) and a speech_captions overlay renders the ad. The ugc_talking recipe puts it together; the guides explain each step.
ADANVIL_SPEECH_MODELsets the indexing model (defaultbase: fast, good enough to search).speech_refineusesmediumunless told otherwise. The language is thelanguageofbrand.yaml, else auto-detected.ADANVIL_SPEECH=offstopslibrary_indexfrom transcribing on its own (transcribe="auto");transcribe=truestill does.- The creator's words are claims: the validator warns
banned_word_spokenwhen a kept word is on the brand's banned list, andcut_mid_wordwhen a cut falls inside a word (not when the voice goes on across the cut). The fillers that are cut (euh, um, uh, er, genre...) can be replaced inbrand.yamlunderspeech, which also takes avocabularylist of words to spell right.startandendlimit aspeech_captionsoverlay to a window. A misheard word can be fixed in the captions withspeech_captions.corrections, close spellings only (a word the transcriber glued together can be split in up to three), and every correction is listed for review (speech_corrections).
Visual devices (optional)
A reveal segment (a divider line sweeps a before picture away to show the after picture, from two real pictures or two clips, with labels that follow their side) for a before/after the viewer watches happen, a split segment (side by side or top and bottom, with labels such as FROM THIS and TO THIS) for comparisons, an image overlay with animation, frame and rotate (a photo or a review screenshot that comes in over the video as a card), a video overlay (picture-in-picture, with a rect, rounded or circle shape, border and shadow), sticker overlays (arrow, hand-drawn circle and underline, badge, emoji, image, with a pop or draw animation), a progress bar, a punch (instant zoom) on a clip and an info_card (an information card AdAnvil draws itself: an accent intro card, then numbered item cards, one at a time, each while the voice says it, with an entry and an exit, no shadow by default). Use one or two per ad. Fields and rules: AGENTS.md and the editing guide.
Sound design (optional)
Sounds go over the audio bed of an ad: a whoosh on a cut, a pop on a caption, a ding on the price, a riser before the reveal.
adanvil sfx-fetch <project_dir>(orsfx_listwithfetch=true) builds a pack of about 18 short sounds in the project'ssfx/folder. Each one is downloaded from a pinned CC0 source (checked by SHA-1) or synthesised in code, then trimmed and set to one level. Nothing is stored in this repository; sources and licences are listed inexamples/sfx/README.mdand written tosfx/LICENCES.txt. Your own files insfx/work too.{"type": "sfx", "source": "sfx/pop.wav", "at": 3.2, "volume": 0.8}places a sound;audio.sfx_autoplaces them at the cuts and at the captions. Sounds never clip and never run past the end.music_beatsgives the beats of a track as it will play, andstoryboard_snapmoves the cuts onto them (the validator reports how many cuts are already on a beat).
AdAnvil MCP questions
How do I add AdAnvil MCP to Claude Code?
Run claude mcp add adanvil -- uvx adanvil mcp in your terminal. Add --scope user to make it available in every project.
How do I add AdAnvil MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does AdAnvil MCP provide?
It exposes 43 tools, including project_init, project_read_text, brand_onboard, brand_get, library_index.
What kind of video ads can AdAnvil create?
It uses 9 recipes for common ad shapes including text hooks, before and after, customer diaries, meme text, and talking-head UGC.
How does the agent handle video footage?
The agent can index footage, create contact sheets, and search clips by text, tags, emotion, or specific spoken sentences.
Can I use AdAnvil with Docker?
Yes, you can build a Docker image that includes ffmpeg and runs as a non-root user to avoid installing Python or ffmpeg locally.
Does the video rendering process change every time?
No, the rendering is deterministic, meaning the same storyboard will always produce the same video result.