Assemble & polish

You have approved clips and assets. Now you want one finished video you can actually share — with a title card, a voice reading your narration, gentle motion on each slide, and music underneath. That is exactly what vclaw video assemble does. It takes the pieces and bakes them into a single narrated MP4 (a standard video file). After that, a few small "polish" commands reshape and package that video for YouTube, Shorts, Reels, and more.

This page is the last step before your video is ready to publish. If something breaks along the way, jump to Troubleshooting.

Two ways to type every command

The examples use the source-checkout form node dist/cli/vclaw.js video ... (for people who cloned the code). If you installed videoclaw as a package, you can drop that prefix and just type vclaw video .... They do the same thing.

What "assemble" actually does

Think of assemble as an assembly line. It runs these steps in order, all on its own:

1. Slides — pulls page images out of a slide deck PDF (if your project has one).
2. Title card — paints an opening title frame (if your brand profile defines one).
3. TTS narration — turns your written narration into spoken audio. (TTS = text-to-speech, a computer voice reading your words.)
4. Slide animation — adds a slow pan/zoom (the "Ken Burns" effect) to each slide, with the length matched to the narration so the picture lasts exactly as long as the voice.
5. Background music — lays a music bed under the narration (optional).
6. Stitch — joins every segment into one final MP4 and mixes the music softly under the voice.
7. Quality check — inspects the finished file to make sure it's really valid.

You don't run these one by one. One command runs the whole line.

Plan it for free first (--dry-run)

Before spending any money or needing any keys, ask videoclaw to plan the whole job and show you what it would do. This is free and safe.

node dist/cli/vclaw.js video assemble --project my-project --dry-run

What it does: prints the full plan — every FFmpeg command and provider call — and writes an assemble-report.json with status: "dry-run", but spends nothing and needs no keys or software. Expect JSON output listing each planned stage and any warnings. This is the safe way to check your project is ready.

Always dry-run first

A --dry-run costs nothing and catches missing pieces (no narration, no slides) before you pay for a real render. Make it a habit.

Render it for real

A real render needs two things installed/set up:

• ffmpeg (and ffprobe) — the free video-processing tool, available on your system's PATH (the list of programs your computer can find by name).
• API keys — an ElevenLabs key for the voice, and a Kie.ai/Suno key only if your brand profile turns on music.

Set the keys, then run without --dry-run:

export ELEVENLABS_API_KEY=sk_your_key_here
export KIE_API_KEY=your_key_here
node dist/cli/vclaw.js video assemble --project my-project

What it does: runs the full assembly line and produces your finished narrated MP4. Expect JSON output with the final video's outputPath, an assemble-report.json artifact path, a per-stage manifest, and any warnings. The MP4 is 1280×720, H.264 video with AAC audio — a normal, shareable video file.

ffmpeg must be installed

If ffmpeg or ffprobe aren't found, a real render can't run. Install ffmpeg first, or point videoclaw at your binaries with VCLAW_FFMPEG_BIN and VCLAW_FFPROBE_BIN. See Troubleshooting.

Handy flags

Flag	Meaning
--project <slug>	Which project to assemble (required).
--root <path>	Workspace root, if it isn't your current folder.
--brand-profile <path>	A brand-profile.json with voice/title/music settings.
--dry-run	Plan everything for free, no keys or ffmpeg needed.

The automatic quality check (Media QC)

On a real (non-dry-run) render, videoclaw doesn't just trust that the file came out right — it measures it. After stitching, it uses ffprobe to inspect every animated slide clip and the final master video, confirming each one really has the audio and video it should.

Each clip and the master get a verdict of pass, warning, or fail. Common things it flags: a missing audio track, an unexpected codec or sample rate, or the final video drifting more than half a second from the sum of its parts. These findings show up in two places: in the warnings list (as qc.<code>[<scope>]: <message> lines) and in a full qc block inside assemble-report.json. Warnings are advisory — they tell you what to listen for, they don't stop the render.

Narration that fits the picture (narration-fit)

A common headache: the voice is longer than the video clip, or shorter. videoclaw plans around this automatically with a narration-fit step:

• Voice fits inside the video — nothing changes; it plays at normal speed.
• Voice is a little long — it speeds the voice up slightly (up to 1.25×) to fit, and notes voice-speedup-applied.
• Voice is much too long — instead of making the voice sound rushed, it keeps the speech natural and loops/extends the visual behind it (voice-too-long-loop-video).

You don't configure any of this — it's why each slide ends up lasting exactly as long as the words spoken over it.

Polish & package your final video

Once you have a finished MP4, these small commands reshape and dress it up for different platforms. Each one works on either a project (--project <slug>, it finds the final video for you) or a standalone file (--file <path>), and each accepts an optional --output <path> so you don't overwrite earlier versions.

Check the render is structurally sound

node dist/cli/vclaw.js video verify-final --project my-project

What it does: probes the final video and confirms its codec, resolution, duration, audio presence, and a midpoint frame are all correct. Expect a JSON pass/fail summary. Run this first if you're unsure the render finished cleanly.

Make a vertical cut (phones, Shorts, Reels, TikTok)

node dist/cli/vclaw.js video make-vertical --project my-project

What it does: produces a 9:16 tall version of the video. Expect a new *-vertical.mp4. Add --output my-vertical.mp4 to name it yourself.

Make a square cut (feed posts)

node dist/cli/vclaw.js video make-square --project my-project

What it does: produces a 1:1 square version for square-friendly feeds. Expect a new *-square.mp4.

Make a seamless loop (ads, GIF-style clips)

node dist/cli/vclaw.js video make-loop --project my-project

What it does: produces a version that loops back on itself smoothly. Expect a new *-loop.mp4.

Generate a thumbnail (the click-driving still)

node dist/cli/vclaw.js video thumbnail --project my-project --text "See It In Motion"

What it does: extracts a still image and overlays your headline text. Expect a .jpg thumbnail. The --text is optional — leave it off for a plain frame.

If the text doesn't appear

The text overlay needs ffmpeg's drawtext feature. If it isn't available, thumbnail quietly falls back to a clean extracted frame instead of failing — so you still get a usable image.

Burn subtitles into the video

node dist/cli/vclaw.js video burn-subtitles --project my-project --subtitle captions.srt

What it does: permanently draws your subtitle file (a .srt captions file) onto the video so the words are always visible, even where captions can't be toggled. Expect a new captioned MP4. The --subtitle <path> is required; --file works in place of --project for any standalone video.

Archive the finished project

node dist/cli/vclaw.js video archive-project --project my-project

What it does: packages the whole project into a single archives/<slug>-<timestamp>.tar.gz file you can store or hand off. Expect the archive path in the JSON output. Add --cleanup to delete the working project folder after archiving, or --archive-dir <path> to choose where the archive lands.

A typical finishing sequence

Put together, polishing a freshly assembled project usually looks like this:

node dist/cli/vclaw.js video verify-final --project my-project
node dist/cli/vclaw.js video thumbnail --project my-project --text "Watch This"
node dist/cli/vclaw.js video make-vertical --project my-project
node dist/cli/vclaw.js video make-square --project my-project
node dist/cli/vclaw.js video archive-project --project my-project

What it does: verifies the render, makes a thumbnail and platform cuts, then archives the finished project. You now have everything you need to publish.

You're basically done

After assemble + polish, your video is ready. If a step misbehaved — a missing key, no ffmpeg, an empty narration — head to the next page.

Next

→ Troubleshooting — fixes for the most common assemble and render problems.