craft-podcast-master
Master a spoken recording with ArtCraft apps - transcribe, name speakers, per-speaker SoundCraft mix, loudness-targeted master, optional chapters and mp4 mux; verified and resumable. Use for "master t
SKILL.mdpackages/craft-apps/.pi/skills/craft-podcast-master/SKILL.md
GitHubcraft-podcast-master — recording → per-speaker tracks → loudness-targeted master
Speech-first pipeline: video-transcription + speaker-id tell who speaks when, SoundCraft mixes one track per
speaker, ffmpeg loudnorm hits the loudness target (SoundCraft only peak-normalises), FilmCraft muxes the
master back onto a video recording. Read soundcraft (and filmcraft for step 7) first. 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 | Transcribe | video-transcription |
recording → 01-transcript/rec.srt |
check: srt |
| 2 | Name speakers | speaker-id |
srt → 02-speakers/rec.named.srt ([Name] text) |
check: named |
| 3 | Stems | ffmpeg | recording + named srt → 03-stems/<speaker>.wav |
pi-craft verify per stem |
| 4 | Mix | SoundCraft | stems → 04-mix/mix.wav (PCM 24-bit 48 kHz) |
pi-craft verify --codec audio=pcm_s24le |
| 5 | Master | ffmpeg loudnorm |
mix → 05-master/master.wav |
pi-craft verify --loudness |
| 6 | Chapters (optional) | agent | named srt → 06-chapters/chapters.txt |
check: chapters |
| 7 | Deliver | FilmCraft (video) / the wav | master (+ picture) → 07-delivery/final.mp4 |
pi-craft verify h264 + aac |
Hand-off formats: wav PCM 24-bit 48 kHz between steps, srt with [Name] speaker prefixes, mp4 h264 + aac for a video
recording. The reference length is the recording's (or its picture's) duration; every audio step is gated
against it with ±0.05 s. Write tolerances as ${REF}±0.05 — in bash $REF±0.05 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 |
|---|---|---|---|
video-transcription |
video-transcription |
skill in the loaded skill list; command -v pi-transcribe |
ask for a ready .srt with speaker labels, or stop (no transcript → no per-speaker split; a single-track master is still possible: skip steps 1–3, import the recording as one track) |
speaker-id |
video-transcription |
skill in the loaded skill list; command -v pi-voiceid (needs the optional sherpa-onnx-node) |
continue with the anonymous [Speaker N] labels — one track per label, not named |
Package: pi install npm:@blackbelt-technology/pi-dashboard-video-transcription. "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. Needs ffmpeg (stems and loudness): without it step 3/5 cannot run — stop and say so.
The reference length: REF=$(ffprobe -v error -show_entries format=duration -of csv=p=0 "$REC").
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 — Transcribe
Output: 01-transcript/rec.srt.
Gate: check: srt — at least one cue.
pi-transcribe <recording> writes <name>.srt beside the recording (diarized [Speaker N] labels, needs the
Soniox key). Copy it to 01-transcript/rec.srt.
# run inside the step directory: cd "$JOB/01-transcript" (the file is named as below)
test "$(grep -cE '^[0-9:,.]+ --> [0-9:,.]+' rec.srt)" -ge 1
Step 2 — Name the speakers
Output: 02-speakers/rec.named.srt.
Gate: check: named — cues still timed and every speaker label is a [Name] prefix.
pi-voiceid label --srt rec.srt --dry-run, read the decision table, then pi-voiceid label --srt rec.srt (writes
rec.named.srt, never overwrites the source). Never guess a name: unmatched clusters keep [Speaker N]. If
analyze reports drift (one person split in two), name both clusters the same — they land on one track.
pi-voiceid needs the recording beside the SRT.
pi-voiceid analyze --srt "$JOB/01-transcript/rec.srt"
# run inside the step directory: cd "$JOB/02-speakers" (the file is named as below)
test "$(grep -cE '^[0-9:,.]+ --> [0-9:,.]+' rec.named.srt)" -ge 1 && grep -qE '^\[[^]]+\]' rec.named.srt
Step 3 — Stems
Output: 03-stems/<speaker>.wav (PCM 24-bit 48 kHz, full recording length).
Gate: pi-craft verify on every stem — duration = reference.
Decision (open question of the design): pre-split stems — each speaker's stem is the recording silenced outside
that speaker's cues (0.15 s padding), plus an 80 Hz high-pass for rumble. Deterministic, gate-able and independent of
SoundCraft's selection state. Extract turns from the named SRT with awk ([Name] prefix), build one ffmpeg filter
script per speaker, render. Set LC_ALL=C so decimals use a point.
LC_ALL=C awk -F'\t' -v w="$who" '$1==w{e=e (e?"+":"") sprintf("between(t,%.3f,%.3f)",$2-0.15,$3+0.15)} END{printf "highpass=f=80,volume=enable=\x27not(%s)\x27:volume=0\n", e}' turns.tsv > "$slug.filter"
ffmpeg -v error -y -i rec.wav -filter_script:a "$slug.filter" -c:a pcm_s24le "$slug.wav"
pi-craft verify "$slug.wav" --duration "${REF}±0.05" --codec audio=pcm_s24le
The full loop (turn extraction, one stem per speaker) is in recipe podcast-master-core. A stem whose length differs
from the reference stops the workflow here — the recording extract was cut short or the SRT is for another file.
Step 4 — Mix
Output: 04-mix/mix.wav (PCM 24-bit, 48 kHz), 04-mix/mix.scraft.
Gate: pi-craft verify — duration = reference, --codec audio=pcm_s24le, --max-peak -1.
SoundCraft (soundcraft skill): session.new, then one file.import_audio per stem (each import is a new track —
that is how speakers play together), balance with clip.gain (db sets the gain; give the clip id or run
edit.select_all first), optional edit.fades_create at the edges, --save the session, --bounce, then convert
to 24-bit 48 kHz (the bounce only sets the bit depth). A mono stem bounced to the stereo bus is 3 dB quieter.
pi-craft soundcraft exec convert "$JOB/04-mix/mix-raw.wav" "$JOB/04-mix/mix.wav" --bit-depth 24 --rate 48000
pi-craft verify "$JOB/04-mix/mix.wav" --duration "${REF}±0.05" --codec audio=pcm_s24le --max-peak -1
A mix whose length differs from the reference stops here; the master step is not started.
Step 5 — Master to a loudness target
Output: 05-master/master.wav (PCM 24-bit, 48 kHz).
Gate: pi-craft verify --loudness (integrated LUFS) and --max-peak.
SoundCraft has no LUFS-target command (probed: only peak normalise, file.bounce_mix normalize). Use ffmpeg
loudnorm in two passes: measure with print_format=json, then apply with the measured values and
linear=true (single-pass loudnorm is dynamic and pumps on speech). Podcast targets: −16 LUFS stereo / −19 LUFS
mono, true peak −1.5 dBTP.
M=$(ffmpeg -hide_banner -nostats -i 04-mix/mix.wav -af loudnorm=I=-16:TP=-1.5:LRA=11:print_format=json -f null - 2>&1 | sed -n '/^{/,/^}/p')
ffmpeg -v error -y -i 04-mix/mix.wav -af "loudnorm=I=-16:TP=-1.5:LRA=11:measured_I=$(jq -r .input_i <<<"$M"):measured_TP=$(jq -r .input_tp <<<"$M"):measured_LRA=$(jq -r .input_lra <<<"$M"):measured_thresh=$(jq -r .input_thresh <<<"$M"):offset=$(jq -r .target_offset <<<"$M"):linear=true" -ar 48000 -c:a pcm_s24le 05-master/master.wav
pi-craft verify 05-master/master.wav --duration "${REF}±0.05" --codec audio=pcm_s24le --loudness -16±1 --max-peak -1.5
Without ffmpeg, pi-craft verify --loudness exits 3 naming it: stop after the un-normalised bounce and report that
the loudness target could not be met or checked. Linear mode needs the measured LRA to be within the target;
if ffmpeg falls back to dynamic mode the verify still decides.
Step 6 — Chapters (optional)
Output: 06-chapters/chapters.txt (MM:SS title per line).
Gate: check: chapters — first chapter at 00:00, every line well formed.
Pick chapter starts from the named SRT (topic changes, speaker introductions) with the user. Probed: FilmCraft has
markers.addChapter (video only, not verified to be written into the mp4) and SoundCraft only session markers
(markers.add, memory locations that are not written into a wav) — so chapters ship as a sidecar text file
(YouTube/podcast-app style).
# run inside the step directory: cd "$JOB/06-chapters" (the file is named as below)
grep -qE '^00:00 ' chapters.txt && ! grep -vqE '^[0-9]{2}:[0-9]{2}(:[0-9]{2})? .+' chapters.txt
Step 7 — Deliver
Output: 07-delivery/final.mp4 for a video recording; for audio-only the deliverable is 05-master/master.wav.
Gate: pi-craft verify — --codec video=h264 --codec audio=aac, duration ±0.1 s, --frame-diff (picture
untouched).
Audio-only: the master wav is the deliverable (gate = step 5). Video recording: FilmCraft sequence from the recording,
mute A1, place master.wav on A2 with a source patch (timeline.setTargeting … sourcePatch, as in
craft-video-post), export h264 + aac. Plain source.overwrite without a source patch lands on the targeted
track — check the track in inspect sequence.
pi-craft filmcraft exec --project "$JOB/07-delivery/p.fcproj" export "$JOB/07-delivery/final.mp4" --format h264
pi-craft verify "$JOB/07-delivery/final.mp4" --duration "${REF}±0.1" --has-video --has-audio \
--codec video=h264 --codec audio=aac --frame-diff "1:$REC<0.5"
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 —
a re-recorded file or an edited SRT. Re-run every step downstream of it (a changed rec.named.srt re-cuts the stems,
mix, master and delivery) 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 soundcraft exec describe <id> / commands <word> — note the filter is positional in SoundCraft), 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
# Stems -> SoundCraft mix -> loudnorm master -> chapters check -> mp4 mux, with a hand-made named SRT standing in
# for speaker-id. SRC_DUR (default 5) is the recording's audio length; REF is the picture's — a shorter audio
# source stops the workflow at the first duration gate and no master is written.
REF=5; SRC=${SRC_DUR:-5}
ffmpeg -v error -y -f lavfi -i testsrc2=size=640x360:rate=25:duration=$REF -f lavfi -i sine=frequency=300:duration=$REF \
-shortest -c:v libx264 -pix_fmt yuv420p -c:a aac rec.mp4
# the recording's audio (here SRC seconds of it) and a hand-made named transcript (speaker-id's output: "[Name] text")
ffmpeg -v error -y -i rec.mp4 -t $SRC -vn -ar 48000 -c:a pcm_s24le rec.wav
printf '1\n00:00:00,000 --> 00:00:02,000\n[Ann] Welcome to the show.\n\n2\n00:00:02,500 --> 00:00:04,500\n[Bob] Thanks for having me.\n' > named.srt
mkdir -p 03-stems 04-mix 05-master 06-chapters 07-delivery
# 03 stems: one wav per speaker, silent outside that speaker's cues, 80 Hz high-pass for rumble
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,/^\[[^]]+\]/)) print substr($3,RSTART+1,RLENGTH-2) "\t" sec(t[1]) "\t" sec(t[2])}' named.srt > 03-stems/turns.tsv
cut -f1 03-stems/turns.tsv | sort -u | while IFS= read -r who; do
slug=$(printf '%s' "$who" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g')
LC_ALL=C awk -F'\t' -v w="$who" '$1==w{e=e (e?"+":"") sprintf("between(t,%.3f,%.3f)",$2-0.15,$3+0.15)} END{printf "highpass=f=80,volume=enable=\x27not(%s)\x27:volume=0\n", e}' 03-stems/turns.tsv > "03-stems/$slug.filter"
ffmpeg -v error -y -i rec.wav -filter_script:a "03-stems/$slug.filter" -c:a pcm_s24le "03-stems/$slug.wav"
pi-craft verify "03-stems/$slug.wav" --duration ${REF}±0.05 --codec audio=pcm_s24le
done
# 04 mix: one SoundCraft track per speaker, balanced, bounced, PCM 24-bit 48 kHz
pi-craft soundcraft exec run \
--cmd session.new \
--cmd "file.import_audio={\"path\":\"$PWD/03-stems/ann.wav\"}" \
--cmd "file.import_audio={\"path\":\"$PWD/03-stems/bob.wav\"}" \
--save 04-mix/mix.scraft --bounce 04-mix/mix-raw.wav
pi-craft soundcraft exec convert 04-mix/mix-raw.wav 04-mix/mix.wav --bit-depth 24 --rate 48000
pi-craft verify 04-mix/mix.wav --duration ${REF}±0.05 --codec audio=pcm_s24le --max-peak -1
# 05 master: ffmpeg two-pass loudnorm to -16 LUFS (measure, then apply the measured values linearly)
M=$(ffmpeg -hide_banner -nostats -i 04-mix/mix.wav -af loudnorm=I=-16:TP=-1.5:LRA=11:print_format=json -f null - 2>&1 | sed -n '/^{/,/^}/p')
ffmpeg -v error -y -i 04-mix/mix.wav -af "loudnorm=I=-16:TP=-1.5:LRA=11:measured_I=$(jq -r .input_i <<<"$M"):measured_TP=$(jq -r .input_tp <<<"$M"):measured_LRA=$(jq -r .input_lra <<<"$M"):measured_thresh=$(jq -r .input_thresh <<<"$M"):offset=$(jq -r .target_offset <<<"$M"):linear=true" \
-ar 48000 -c:a pcm_s24le 05-master/master.wav
pi-craft verify 05-master/master.wav --duration ${REF}±0.05 --codec audio=pcm_s24le --loudness -16±1 --max-peak -1.5
# 06 chapters: sidecar text, one "MM:SS title" per line, first at 00:00
printf '00:00 Welcome\n00:02 Guest introduction\n' > 06-chapters/chapters.txt
grep -qE '^00:00 ' 06-chapters/chapters.txt && ! grep -vqE '^[0-9]{2}:[0-9]{2}(:[0-9]{2})? .+' 06-chapters/chapters.txt
# 07 deliver: master replaces the recording's audio, picture untouched, mp4 h264 + aac
pi-craft filmcraft exec --save-as 07-delivery/p.fcproj import rec.mp4 05-master/master.wav > 07-delivery/items.json
REC=$(jq -r '.items[0]' 07-delivery/items.json); MASTER=$(jq -r '.items[1]' 07-delivery/items.json)
cat > 07-delivery/deliver.jsonl <<JSONL
{"id":"file.newSequence","params":{"name":"podcast","width":640,"height":360,"fps":25,"fromItem":$REC}}
{"id":"timeline.setTrack","params":{"track":"A1","muted":true}}
{"id":"source.open","params":{"item":$MASTER}}
{"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":{}}
JSONL
pi-craft filmcraft exec --project 07-delivery/p.fcproj --save run 07-delivery/deliver.jsonl
pi-craft filmcraft exec --project 07-delivery/p.fcproj export 07-delivery/final.mp4 --format h264
pi-craft verify 07-delivery/final.mp4 --duration ${REF}±0.1 --has-video --has-audio --codec video=h264 --codec audio=aac \
--frame-diff 1:rec.mp4\<0.5