craft-video-post
Footage/Veo clips to a finished mp4 with ArtCraft apps - FilmCraft assembly and alpha overlays, SRT captions, SoundCraft mix, h264+aac delivery; verified and resumable. Use for "edit these clips into
SKILL.mdpackages/craft-apps/.pi/skills/craft-video-post/SKILL.md
GitHubcraft-video-post — footage → captions + overlays + mix → verified mp4
Chains FilmCraft (timeline, captions, export), EffectCraft (alpha graphics) and SoundCraft (mix) with the
sibling skills for redaction, transcription and code-driven motion. App dialects, traps and the
discover → execute → save → verify loop are in the app skills and in craft-studio; read filmcraft before
step 3. Resumable-job rules are in the craft-studio router, section Craft jobs.
Step table
| # | Step | Tool | Input → Output | Gate |
|---|---|---|---|---|
| 0 | Preflight + job | agent | request → job.json |
check: job |
| 1 | Footage | veo-generator / footage-redaction / user files |
clips → 01-footage/*.mp4 |
pi-craft verify per clip |
| 2 | Graphics (optional) | EffectCraft or hyperframes-showreel |
text/data → 02-graphics/*.mov (ProRes 4444 alpha) |
pi-craft verify --alpha |
| 3 | Assembly | FilmCraft | clips + overlays → 03-assembly/cut.mp4, ref.mp4 |
pi-craft verify --frame-diff |
| 4 | Captions input | video-transcription |
recording → 04-captions/cues.srt |
check: srt |
| 5 | Mix | SoundCraft | footage audio + music → 05-mix/mix.wav (PCM 24-bit 48 kHz) |
pi-craft verify --codec audio=pcm_s24le |
| 6 | Delivery | FilmCraft | project + mix + srt → 06-delivery/final.mp4 |
pi-craft verify h264 + aac |
Hand-off formats: wav PCM 24-bit 48 kHz (audio), mov ProRes 4444 with alpha (graphics), srt (captions), mp4 h264 + aac
(delivery). Duration tolerance: ±0.1 s for picture, ±0.05 s for audio. Write the tolerance as ${PIC}±0.1 — in bash
$PIC±0.1 swallows the ± into the variable name.
Step 0 — Preflight and job
Output: craft-jobs/<slug>/job.json (created or loaded).
Gate: check: job.
Check what is available before promising anything (soft references — no package is required):
| Sibling | Package | Check | If missing |
|---|---|---|---|
veo-generator |
video-production |
skill in the loaded skill list; pi-veo on PATH |
the user supplies footage files |
footage-redaction |
video-production |
skill in the loaded skill list | no redaction — say so and confirm the footage is safe to ship |
video-transcription |
video-transcription |
skill in the loaded skill list; command -v pi-transcribe |
offer to continue without captions (skip steps 4 and the caption part of 6), or ask for a ready .srt |
hyperframes-showreel |
video-production |
skill in the loaded skill list and npx hyperframes --version succeeds |
no code-driven overlays — use EffectCraft graphics only |
"Loaded skill list" is the available-skills list in your own system prompt. A loaded skill does not prove its
runtime works, hence the extra probes; a failed probe counts as absent. Name the package to install
(pi install npm:@blackbelt-technology/pi-dashboard-video-production, …-video-transcription) when a sibling is
missing, then continue on the degraded path or stop if the request needs it.
Then set up the job (see Craft jobs in craft-studio: slug rule, job-helper snippet) and run Resume below.
# run from the directory that contains craft-jobs/ (SLUG set as in step 0)
jq -e '.name and .workflow and (.steps | type == "object")' "craft-jobs/$SLUG/job.json"
Step 1 — Footage
Output: 01-footage/*.mp4 (redacted or generated clips).
Gate: pi-craft verify on every clip.
Generate shots with veo-generator (one clip per camera cut) or take the user's files; run each clip through
footage-redaction when the footage shows anything sensitive. Keep originals out of 01-footage/.
pi-craft verify "$JOB/01-footage/c01.mp4" --has-video --duration "${CLIP_SECONDS}±0.2"
Step 2 — Graphics (optional)
Output: 02-graphics/title.mov (ProRes 4444, alpha).
Gate: pi-craft verify --alpha.
Two producers, one rule: the file must have an alpha channel.
- EffectCraft (default) — read the
effectcraftskill; render with--format prores --prores 4444 --channels rgba. For name/title lower-thirds usecraft-motion-titles. - HyperFrames — only for code-driven motion (data overlays); never author a composition here, use
hyperframes-showreel. Alpha render:npx hyperframes render . --format mov -o title.mov --fps 25(MOV is always the alpha-preserving ProRes 4444 profile; tested with HyperFrames 0.8.168).- Alpha branch — the render passes
pi-craft verify --alpha: overlay it on V2 in step 3. - Full-frame branch — it fails
--alpha(opaque render): do not overlay it. Place it as a full-frame segment on V1 in step 3 and gate the segment with--sizeagainst the sequence size (pi-craft verify seg.mp4 --size 1920x1080 --duration …).
- Alpha branch — the render passes
pi-craft verify "$JOB/02-graphics/title.mov" --alpha --size 1920x1080 --duration "${TITLE_SECONDS}±0.1"
A passing --alpha only proves the pixel format. EffectCraft template projects carry an opaque
"Preview Background" solid — delete it (see craft-motion-titles) or the overlay is opaque.
Step 3 — Assembly
Output: 03-assembly/p.fcproj, 03-assembly/cut.mp4 (V1 only) and 03-assembly/ref.mp4 (with overlays).
Gate: pi-craft verify --frame-diff (overlay visible, rest unchanged).
FilmCraft: footage on V1 with explicit playhead.set before every placement (trap in filmcraft), export the
un-overlaid cut.mp4, then place overlays on V2+ and export ref.mp4. Keep both files for the job's lifetime
— cut.mp4 is the reference for the overlay check, ref.mp4 for the caption check in step 6.
Overlay placement is the trap: source.overwrite goes to the targeted video track. Without a source patch it
overwrites V1 and silently replaces the footage (the export still has the right duration). Patch the source to V2:
cat > "$JOB/03-assembly/overlay.jsonl" <<JSONL
{"id":"source.open","params":{"item":$TITLE}}
{"id":"timeline.setTargeting","params":{"track":"V2","sourcePatch":true,"targeted":true}}
{"id":"timeline.setTargeting","params":{"track":"V1","targeted":false}}
{"id":"playhead.set","params":{"seconds":2}}
{"id":"source.overwrite","params":{}}
JSONL
pi-craft filmcraft exec --project "$JOB/03-assembly/p.fcproj" --save run "$JOB/03-assembly/overlay.jsonl"
pi-craft filmcraft exec --project "$JOB/03-assembly/p.fcproj" export "$JOB/03-assembly/ref.mp4" --format h264
# overlay visible (> 0.1 %) but footage not replaced (< 40 %), and untouched before the overlay starts
pi-craft verify "$JOB/03-assembly/ref.mp4" --duration "${PIC}±0.1" --size 1920x1080 \
--frame-diff "$T_OVERLAY:$JOB/03-assembly/cut.mp4>0.1" --frame-diff "$T_OVERLAY:$JOB/03-assembly/cut.mp4<40" \
--frame-diff "$T_BEFORE:$JOB/03-assembly/cut.mp4<0.1"
(Quote the >/< in --frame-diff or escape them.) The --frame-diff value is the share of pixels whose luma
differs by more than 40/255: a lower third is ~0.5–5 %, a replaced picture 50 %+.
Step 4 — Captions input
Output: 04-captions/cues.srt.
Gate: check: srt — at least one cue; an empty file stops the step and no caption is placed.
Transcribe the recording (or the final dialogue) with video-transcription — pi-transcribe <file> writes
<name>.srt beside the source (Soniox by default; needs its API key). Copy it to 04-captions/cues.srt. Offer a
hand-written or user-supplied .srt when the skill is missing. Never place captions from a file the check rejects.
# run inside the step directory: cd "$JOB/04-captions" (the file is named as below)
test "$(grep -cE '^[0-9:,.]+ --> [0-9:,.]+' cues.srt)" -ge 1
Step 5 — Mix
Output: 05-mix/mix.wav (PCM 24-bit, 48 kHz, stereo).
Gate: pi-craft verify — duration equals the picture, --codec audio=pcm_s24le, peak below clipping.
SoundCraft (read soundcraft): the music goes in first and is attenuated, then the footage audio extracted with
ffmpeg … -vn -ar 48000 -c:a pcm_s24le. Each import is a new track. Bounce, then convert — the bounce
itself only sets bit depth, not the rate:
pi-craft soundcraft exec convert "$JOB/05-mix/mix-raw.wav" "$JOB/05-mix/mix.wav" --bit-depth 24 --rate 48000
pi-craft verify "$JOB/05-mix/mix.wav" --duration "${PIC}±0.05" --codec audio=pcm_s24le --max-peak -1
A mix that is shorter or longer than the picture stops here: do not start step 6 (a wrong-length mix produced a
silent tail in the export). Sample rate and channel count are not machine-gated — they are fixed by convert.
For a loudness target on the final mix use the ffmpeg two-pass in craft-podcast-master (SoundCraft normalises to
peak only).
Step 6 — Delivery
Output: 06-delivery/p.fcproj, 06-delivery/final.mp4 (h264 + aac).
Gate: pi-craft verify — --codec video=h264 --codec audio=aac, duration ±0.1 s, --frame-diff for captions
and overlay.
FilmCraft, from the step-3 project saved as a new file: mute A1 (footage audio is already inside the mix),
place mix.wav on A2 with a source patch (same mechanics as the V2 overlay), captions.import the SRT, export
with captions burned in. captions.import makes a caption track but a plain export does not draw it — burning
needs the export setting:
pi-craft filmcraft exec --project "$JOB/06-delivery/p.fcproj" export "$JOB/06-delivery/final.mp4" --format h264 \
--settings '{"burnCaptions":true}'
pi-craft verify "$JOB/06-delivery/final.mp4" --duration "${PIC}±0.1" --size 1920x1080 --has-video --has-audio \
--codec video=h264 --codec audio=aac \
--frame-diff "$T_CUE:$JOB/03-assembly/ref.mp4>0.1" --frame-diff "$T_OVERLAY:$JOB/03-assembly/cut.mp4>0.1"
--frame-diff at a caption cue time against the retained uncaptioned ref.mp4 must show a difference (small text is
~0.3 % of a 640×360 frame — use >0.1). Without captions, drop the first frame-diff. Report the final path and the
verify output.
Resume
Follow the Craft jobs convention in craft-studio: read craft-jobs/<slug>/job.json as data, confirm the job
name, and start at the first step that has no passing report or whose recorded inputs (path, size, mtime) no
longer match the files — e.g. a footage clip replaced after the job ran. Re-run every step downstream of it; reuse the
verified outputs of the steps before it (an interrupted job whose mix passed starts again at step 6 or at
assembly if an input changed, and reuses 05-mix/mix.wav). After each passing gate record the step with the
job-helper snippet.
When a gate fails
Stop at the failed gate; never continue past it. Re-discover the commands you used (pi-craft <app> exec describe <id> /
commands <word> — ids change between releases), repeat the step, and re-run the gate. At most 2 retries per
step; after the second failure stop and report the verify output, what was tried and the file left behind.
Recipes
# The app steps of the workflow end to end: alpha overlay -> assembly -> srt check -> mix -> burned-in delivery.
# ffmpeg-made footage and music and a hand-written cues.srt stand in for the sibling skills' output.
PIC=6
ffmpeg -v error -y -f lavfi -i testsrc2=size=1280x720:rate=25:duration=$PIC -f lavfi -i sine=frequency=440:duration=$PIC \
-shortest -c:v libx264 -pix_fmt yuv420p -c:a aac footage.mp4
ffmpeg -v error -y -f lavfi -i sine=frequency=220:duration=$PIC -ar 48000 music.wav
printf '1\n00:00:00,500 --> 00:00:02,000\nFirst caption\n\n2\n00:00:03,000 --> 00:00:05,000\nSecond caption\n' > cues.srt
mkdir -p 02-graphics 03-assembly 04-captions 05-mix 06-delivery
# 02 graphics: EffectCraft alpha overlay, fully visible from 1 s of its comp
pi-craft effectcraft exec --empty --save-as 02-graphics/t.ecproj run \
comp.new '{"name":"Title","width":1280,"height":720,"frameRate":25,"duration":2}' \
layer.newText '{"text":"Lower","size":120,"position":[640,360]}' \
prop.addKey '{"layer":"Lower","path":"transform/opacity","time":0,"value":0}' \
prop.addKey '{"layer":"Lower","path":"transform/opacity","time":1,"value":100}'
pi-craft effectcraft exec --project 02-graphics/t.ecproj render --out 02-graphics/title.mov --format prores --prores 4444 --channels rgba
pi-craft verify 02-graphics/title.mov --alpha --size 1280x720 --duration 2±0.1
# 03 assembly: footage on V1 (un-overlaid cut kept), then the overlay on V2 at 2 s
pi-craft filmcraft exec --save-as 03-assembly/p.fcproj import footage.mp4 02-graphics/title.mov > 03-assembly/items.json
FOOT=$(jq -r '.items[0]' 03-assembly/items.json); TITLE=$(jq -r '.items[1]' 03-assembly/items.json)
cat > 03-assembly/cut.jsonl <<JSONL
{"id":"file.newSequence","params":{"name":"post","width":1280,"height":720,"fps":25,"fromItem":$FOOT}}
JSONL
pi-craft filmcraft exec --project 03-assembly/p.fcproj --save run 03-assembly/cut.jsonl
pi-craft filmcraft exec --project 03-assembly/p.fcproj export 03-assembly/cut.mp4 --format h264
pi-craft verify 03-assembly/cut.mp4 --duration ${PIC}±0.1 --size 1280x720 --has-video
cat > 03-assembly/overlay.jsonl <<JSONL
{"id":"source.open","params":{"item":$TITLE}}
{"id":"timeline.setTargeting","params":{"track":"V2","sourcePatch":true,"targeted":true}}
{"id":"timeline.setTargeting","params":{"track":"V1","targeted":false}}
{"id":"playhead.set","params":{"seconds":2}}
{"id":"source.overwrite","params":{}}
JSONL
pi-craft filmcraft exec --project 03-assembly/p.fcproj --save run 03-assembly/overlay.jsonl
pi-craft filmcraft exec --project 03-assembly/p.fcproj export 03-assembly/ref.mp4 --format h264
pi-craft verify 03-assembly/ref.mp4 --duration ${PIC}±0.1 --size 1280x720 \
--frame-diff 3.5:03-assembly/cut.mp4\>0.1 --frame-diff 3.5:03-assembly/cut.mp4\<40 --frame-diff 1:03-assembly/cut.mp4\<0.1
# 04 captions: the skill-level check, then keep the file
test "$(grep -cE '^[0-9:,.]+ --> [0-9:,.]+' cues.srt)" -ge 1
cp cues.srt 04-captions/cues.srt
# 05 mix: music under the footage audio, PCM 24-bit 48 kHz
ffmpeg -v error -y -i footage.mp4 -vn -ar 48000 -c:a pcm_s24le 05-mix/footage.wav
pi-craft soundcraft exec run \
--cmd session.new \
--cmd "file.import_audio={\"path\":\"$PWD/music.wav\"}" \
--cmd edit.select_all --cmd 'clip.gain={"db":-14}' \
--cmd "file.import_audio={\"path\":\"$PWD/05-mix/footage.wav\"}" \
--save 05-mix/mix.scraft --bounce 05-mix/mix-raw.wav
pi-craft soundcraft exec convert 05-mix/mix-raw.wav 05-mix/mix.wav --bit-depth 24 --rate 48000
pi-craft verify 05-mix/mix.wav --duration ${PIC}±0.05 --codec audio=pcm_s24le --max-peak -1
# 06 delivery: mix on A2 (A1 muted), captions burned in, mp4 h264 + aac
pi-craft filmcraft exec --project 03-assembly/p.fcproj --save-as 06-delivery/p.fcproj import 05-mix/mix.wav > 06-delivery/items.json
MIX=$(jq -r '.items[0]' 06-delivery/items.json)
cat > 06-delivery/deliver.jsonl <<JSONL
{"id":"timeline.setTrack","params":{"track":"A1","muted":true}}
{"id":"source.open","params":{"item":$MIX}}
{"id":"timeline.setTargeting","params":{"track":"A2","sourcePatch":true,"targeted":true}}
{"id":"timeline.setTargeting","params":{"track":"A1","targeted":false}}
{"id":"playhead.set","params":{"seconds":0}}
{"id":"source.overwrite","params":{}}
{"id":"captions.import","params":{"path":"$PWD/04-captions/cues.srt"}}
JSONL
pi-craft filmcraft exec --project 06-delivery/p.fcproj --save run 06-delivery/deliver.jsonl
pi-craft filmcraft exec --project 06-delivery/p.fcproj export 06-delivery/final.mp4 --format h264 --settings '{"burnCaptions":true}'
pi-craft verify 06-delivery/final.mp4 --duration ${PIC}±0.1 --size 1280x720 --has-video --has-audio \
--codec video=h264 --codec audio=aac \
--frame-diff 1:03-assembly/ref.mp4\>0.1 --frame-diff 3.5:03-assembly/cut.mp4\>0.1