craft-motion-titles
Name and title graphics from a transcript with ArtCraft apps - speaker names from an SRT, EffectCraft template alpha renders, FilmCraft overlay, mp4 delivery; verified and resumable. Use for "add lowe
SKILL.mdpackages/craft-apps/.pi/skills/craft-motion-titles/SKILL.md
GitHubcraft-motion-titles — names from the transcript → alpha lower thirds → overlay on the video
Template-driven motion graphics: EffectCraft renders one transparent ProRes 4444 clip per name, FilmCraft lays them
over the footage on V2. Read effectcraft (render flags, alpha trap) and filmcraft (playhead and track trap)
first. For free-form titles without a template, use EffectCraft's text layers directly (degraded path below).
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 | Names | speaker-id / video-transcription / the user |
named srt → 01-names/names.json |
check: names |
| 2 | Template | EffectCraft | templates.list → 02-template/choice.json |
check: template |
| 3 | Titles | EffectCraft | name + template → 03-titles/<name>.mov (ProRes 4444 alpha) |
pi-craft verify --alpha + check: alpha |
| 4 | Overlay + delivery | FilmCraft | footage + titles → 04-overlay/final.mp4 |
pi-craft verify h264 + aac + --frame-diff |
Hand-off formats: srt/json in, mov ProRes 4444 with alpha between, mp4 h264 + aac out. Write tolerances 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.
| Sibling | Package | Check | If missing |
|---|---|---|---|
speaker-id |
video-transcription |
skill in the loaded skill list; command -v pi-voiceid |
use the anonymous [Speaker N] labels, or ask the user for the names |
video-transcription |
video-transcription |
skill in the loaded skill list; command -v pi-transcribe |
ask the user for the list of names and start times (type names.json by hand) or a ready .srt |
Package: pi install npm:@blackbelt-technology/pi-dashboard-video-transcription. One of the two is enough; with
neither, the user supplies the names. "Loaded skill list" is the available-skills list in your own system prompt; a
loaded skill does not prove its runtime works, so a failed probe counts as absent. Roles/titles are not in an SRT —
ask the user (ask_user) for each name's title line.
Set up the job (Craft jobs in craft-studio: slug rule, job-helper) and run Resume.
# 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 — Names
Output: 01-names/names.json — [{"name","title","at"}], at = seconds into the video.
Gate: check: names.
From the named SRT ([Name] text cues from speaker-id): the first turn of each speaker gives the name and the
start time (awk, see the recipe); titles come from the user. Titles that overlap in time need separate overlay
tracks (sequence.addTracks); this workflow places them sequentially on V2.
# run inside the step directory: cd "$JOB/01-names" (the file is named as below)
jq -e 'length>0 and all(.[]; .name and .at>=0)' names.json
Step 2 — Template
Output: 02-template/choice.json — the chosen template id and its control names.
Gate: check: template.
Probed path (EffectCraft 0.10): templates.list returns built-in templates with their controls — the built-in
lower-third has Name, Title, Bar Color at 1920×1080, 30 fps, 6 s; templates.create {"id":…,"projectPath":…}
makes a project from it. (file.newFromTemplate only opens the GUI's Home tab; essential.importTemplate imports a
.ectemplate file — use it for a user's own template.) Discover, never guess:
pi-craft effectcraft exec --empty run templates.list '{}' | jq -c '.[] | {id, controls, width, height, frameRate, duration}'
# run inside the step directory: cd "$JOB/02-template" (the file is named as below)
jq -e '.id and (.controls | index("Name"))' choice.json
Degraded path — no template with the needed controls: build the title from text layers (comp.new,
layer.newText, layer.applyTextPreset, prop.addKey — the title-alpha recipe in effectcraft), same render
flags, same gates.
Step 3 — Titles
Output: 03-titles/<slug>.mov per name (ProRes 4444, alpha) and <slug>.ecproj.
Gate: pi-craft verify --alpha, size/duration of the template, and check: alpha (transparent corner).
Per name: templates.create into 03-titles/<slug>.ecproj; read the layer behind each control with
essential.list (the control Name is a property of a layer, set the layer's text/sourceText; essential.set
is for precomp layers and fails here); set the text with set - <layer id> text/sourceText "<value>"
(--save); delete the template's "Preview Background (delete over footage)" solid (project.delete with its
item id from info); render with the alpha flags.
The trap that --alpha cannot see: with the preview background still in the project the render is yuva444p12le with
an opaque background — --alpha passes, the overlay hides the footage. check: alpha reads one corner pixel:
it must be fully transparent.
pi-craft effectcraft exec --project "$P" render --out "$JOB/03-titles/$SLUG.mov" --format prores --prores 4444 --channels rgba
pi-craft verify "$JOB/03-titles/$SLUG.mov" --alpha --size 1920x1080 --duration 6±0.1
# run inside the step directory: cd "$JOB/03-titles" (the file is named as below)
test "$(ffmpeg -v error -ss 3 -i title.mov -frames:v 1 -vf crop=1:1:0:0,format=rgba -f rawvideo - | od -An -tx1 | tr -d ' \n')" = 00000000
Step 4 — Overlay and delivery
Output: 04-overlay/p.fcproj, 04-overlay/cut.mp4 (reference) and 04-overlay/final.mp4 (h264 + aac).
Gate: pi-craft verify — --codec video=h264 --codec audio=aac, duration ±0.1 s, --frame-diff at every title
(visible, but not replacing the picture) and before the first one (untouched).
FilmCraft: footage on V1 (file.newSequence with fromItem), export the un-overlaid cut.mp4, then for each title
source.open, playhead.set to its at, source.overwrite with the source patched to V2
(timeline.setTargeting … sourcePatch:true on V2, V1 untargeted) — without the patch the title overwrites V1 and
replaces the footage. Make the sequence the footage's size and rate (a 1080p template over 720p footage is
scaled).
pi-craft filmcraft exec --project "$JOB/04-overlay/p.fcproj" export "$JOB/04-overlay/final.mp4" --format h264
pi-craft verify "$JOB/04-overlay/final.mp4" --duration "${PIC}±0.1" --size 1920x1080 --has-video --has-audio \
--codec video=h264 --codec audio=aac \
--frame-diff "$T_TITLE:$JOB/04-overlay/cut.mp4>0.1" --frame-diff "$T_TITLE:$JOB/04-overlay/cut.mp4<40" \
--frame-diff "$T_BEFORE:$JOB/04-overlay/cut.mp4<0.1"
A lower third is ~0.5–5 % of the frame; a replaced picture is 50 %+ — the <40 bound catches the missing source
patch. Keep cut.mp4 for the job's lifetime.
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 with no passing report or whose recorded inputs (path, size, mtime) changed —
an edited SRT, a replaced footage file or a new names.json. Re-run every step downstream of it (a new name list
re-renders the titles and the overlay) and reuse the verified outputs before it. Record each step with the
job-helper snippet after its gate passed.
When a gate fails
Stop at the failed gate; never continue past it. Re-discover the commands you used (pi-craft effectcraft exec commands --filter <word> / pi-craft filmcraft exec describe <id>), repeat the step and re-run the gate. At most 2
retries per step; after the second failure stop and report the verify output and what was tried.
Recipes
# Names from a hand-made named SRT -> Lower Third template -> alpha renders -> V2 overlays -> verified mp4.
PIC=14
ffmpeg -v error -y -f lavfi -i testsrc2=size=1920x1080:rate=30:duration=$PIC -f lavfi -i sine=frequency=330:duration=$PIC \
-shortest -c:v libx264 -pix_fmt yuv420p -c:a aac footage.mp4
printf '1\n00:00:00,500 --> 00:00:02,000\n[Ann] Welcome to the show.\n\n2\n00:00:07,000 --> 00:00:09,000\n[Bob] Thanks for having me.\n' > named.srt
mkdir -p 01-names 03-titles 04-overlay
# 01 names: first turn of every speaker -> name + start time (titles/roles come from the user)
LC_ALL=C awk 'BEGIN{RS="";FS="\n"} function sec(x,a){split(x,a,/[:,]/);return a[1]*3600+a[2]*60+a[3]+a[4]/1000}
{split($2,t," --> "); if (match($3,/^\[[^]]+\]/)) { n=substr($3,RSTART+1,RLENGTH-2); if (!(n in seen)) { seen[n]=1; printf "%s\t%.3f\n", n, sec(t[1]) } } }' named.srt > 01-names/first-turns.tsv
jq -R -s -c 'split("\n")|map(select(length>0)|split("\t"))|map({name:.[0],title:"Guest",at:(.[1]|tonumber)})' 01-names/first-turns.tsv > 01-names/names.json
jq -e 'length>0 and all(.[]; .name and .at>=0)' 01-names/names.json
# 03 titles: one alpha render per name from the built-in Lower Third template
pi-craft effectcraft exec --empty run templates.list '{}' | jq -e '.[]|select(.id=="lower-third")|.controls|index("Name")' >/dev/null
jq -c '.[]' 01-names/names.json | while IFS= read -r row; do
NAME=$(jq -r .name <<<"$row"); TITLE=$(jq -r .title <<<"$row"); SLUG=$(printf '%s' "$NAME" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g')
P=03-titles/$SLUG.ecproj
pi-craft effectcraft exec --empty run templates.create "{\"id\":\"lower-third\",\"projectPath\":\"$PWD/$P\"}" >/dev/null
CTRL=$(pi-craft effectcraft exec --project "$P" run essential.list '{}')
pi-craft effectcraft exec --project "$P" --save set - "$(jq -r '.controls[]|select(.name=="Name")|.layer' <<<"$CTRL")" text/sourceText "$NAME" >/dev/null
pi-craft effectcraft exec --project "$P" --save set - "$(jq -r '.controls[]|select(.name=="Title")|.layer' <<<"$CTRL")" text/sourceText "$TITLE" >/dev/null
BG=$(pi-craft effectcraft exec --project "$P" info | awk '/^ *item [0-9]+ +Solid +Preview Background/{print $2}')
if [ -n "$BG" ]; then pi-craft effectcraft exec --project "$P" --save run project.delete "{\"items\":[$BG]}" >/dev/null; fi
pi-craft effectcraft exec --project "$P" render --out "03-titles/$SLUG.mov" --format prores --prores 4444 --channels rgba >/dev/null
pi-craft verify "03-titles/$SLUG.mov" --alpha --size 1920x1080 --duration 6±0.1
test "$(ffmpeg -v error -ss 3 -i "03-titles/$SLUG.mov" -frames:v 1 -vf crop=1:1:0:0,format=rgba -f rawvideo - | od -An -tx1 | tr -d ' \n')" = 00000000
done
# 04 overlay: FilmCraft, every title on V2 at its start time; the un-overlaid cut is the reference
pi-craft filmcraft exec --save-as 04-overlay/p.fcproj import footage.mp4 03-titles/ann.mov 03-titles/bob.mov > 04-overlay/items.json
FOOT=$(jq -r '.items[0]' 04-overlay/items.json)
echo "{\"id\":\"file.newSequence\",\"params\":{\"name\":\"titles\",\"width\":1920,\"height\":1080,\"fps\":30,\"fromItem\":$FOOT}}" > 04-overlay/cut.jsonl
pi-craft filmcraft exec --project 04-overlay/p.fcproj --save run 04-overlay/cut.jsonl
pi-craft filmcraft exec --project 04-overlay/p.fcproj export 04-overlay/cut.mp4 --format h264
pi-craft verify 04-overlay/cut.mp4 --duration ${PIC}±0.1 --size 1920x1080 --has-video
{ echo '{"id":"timeline.setTargeting","params":{"track":"V2","sourcePatch":true,"targeted":true}}'
echo '{"id":"timeline.setTargeting","params":{"track":"V1","targeted":false}}'
jq -c --argjson ids "$(jq -c '.items[1:]' 04-overlay/items.json)" 'to_entries[] | {id:"source.open",params:{item:$ids[.key]}}, {id:"playhead.set",params:{seconds:.value.at}}, {id:"source.overwrite",params:{}}' 01-names/names.json; } > 04-overlay/overlay.jsonl
pi-craft filmcraft exec --project 04-overlay/p.fcproj --save run 04-overlay/overlay.jsonl
pi-craft filmcraft exec --project 04-overlay/p.fcproj export 04-overlay/final.mp4 --format h264
pi-craft verify 04-overlay/final.mp4 --duration ${PIC}±0.1 --size 1920x1080 --has-video --has-audio --codec video=h264 --codec audio=aac \
--frame-diff 3.5:04-overlay/cut.mp4\>0.1 --frame-diff 3.5:04-overlay/cut.mp4\<40 --frame-diff 10:04-overlay/cut.mp4\>0.1 --frame-diff 0.2:04-overlay/cut.mp4\<0.1