Screencast Editor

Process steps in order. Do not skip ahead.

Resolve the absolute path of this loaded SKILL.md, then set speaker_toolkit_root to the plugin root two directories above the directory containing this file. Never derive it from the consumer working directory. Treat {speaker_toolkit_root} as absolute in every toolkit-owned command; recording, project, and output paths remain consumer-owned.

The lessons behind every step, and the incidents that taught them: skills/screencast-editor/references/production-lessons.md. Read it before the first edit of a session. File formats: skills/screencast-editor/references/camtasia-format.md.

Camtasia owns any project it has open. Never write a project file until the user has saved and closed it. Never screenshot the whole screen. Look at pixels only through the stills this skill renders.

Every script prints its diagnostics on stderr and exits 2 on a usage error (bad or missing arguments); each step lists its other outcomes.

Steps 2, 8, 9, 10, 13, 14, 15, 16, and 17 hand work to the user and end the turn. When the user reports back, resume at the step each one names.

Step 1 — Resolve the interpreter

python3 "{speaker_toolkit_root}/skills/screencast-recorder/scripts/resolve-interpreter.py" <vault_root>

Stdout: {"ok": true, "python_path", "vault_root", "database"}. Set python_path from it; it is the interpreter for every command below. On exit 1, repair through Skill(skill: "vault-ingress"). Never fall back to whichever python3 is on PATH. Proceed immediately to Step 2.

Step 2 — Request the transcript

Ask the user to open the recording's project in Camtasia, add dynamic captions to it (this makes Camtasia transcribe the take), save it outside Camtasia's Temporary Projects folder, and close it. Camtasia deletes temporary projects and recordings on its own schedule. Finish here; resume at Step 3 when the user confirms.

Step 3 — Export the transcript

"{python_path}" "{speaker_toolkit_root}/skills/screencast-editor/scripts/transcript.py" <raw.cmproj> > transcript.json

Output: {"words": [[seconds, word]], "sentences": [{"start", "end", "text"}]} in source seconds; the last sentence has no end. Exit 1 means the project has no transcript: return to Step 2. Word onsets are the only clock for cuts. Proceed immediately to Step 4.

Step 4 — Map what the screen shows

A screen + camera take whose edit uses no screen footage skips Steps 4, 6, and 7: its plan has only speaker shots, and the unused screen track stays in the recording. Proceed immediately to Step 5 for such a take. A camera-only recording is out of scope: build-project.py requires Camtasia's screen + camera layout.

"{python_path}" "{speaker_toolkit_root}/skills/screencast-editor/scripts/screen-changes.py" <recording.trec> > changes.json
"{python_path}" "{speaker_toolkit_root}/skills/screencast-editor/scripts/trec-pointer.py" <recording.trec> --out pointer.json

changes.json is {"changes": [seconds]}: page switches and scrolls. pointer.json is {"capture": {"x", "y", "width", "height"}, "samples": [[seconds, x, y]]} with x and y normalized to the captured display. Exit 1 from either names what failed (ffmpeg, or no pointer data in the recording). Proceed immediately to Step 5.

Step 5 — Write the shot plan

Write shot-plan.json per skills/screencast-editor/references/shot-plan.md: the presenter full-frame for the opening, commentary, and close; the screen only while the words point at it; every cut between sentences. Proceed immediately to Step 6, or to Step 8 when the plan has no screen shots.

Step 6 — Audit the framing

"{python_path}" "{speaker_toolkit_root}/skills/screencast-editor/scripts/audit-framing.py" shot-plan.json pointer.json

Stdout lists each screen shot with its pointing misses. Exit 1 names each shot whose framing cuts off what the presenter points at; exit 2 is an invalid plan or pointer file. Fix the plan and rerun until exit 0. Proceed immediately to Step 7.

Step 7 — Look at every framing

"{python_path}" "{speaker_toolkit_root}/skills/screencast-editor/scripts/framing-stills.py" <recording.trec> shot-plan.json --out stills

Stdout: {"stills": [paths], "sheet": path}; exit 1 names an ffmpeg or write failure. Read stills/sheet.png and any still in doubt. The red box is the inset's footprint: it must never cover text being read. Fix the plan and return to Step 6 for any still that fails. Proceed immediately to Step 8.

Step 8 — Build the project

"{python_path}" "{speaker_toolkit_root}/skills/screencast-editor/scripts/build-project.py" <raw.cmproj> shot-plan.json --out "<title>.cmproj"

Stdout: {"project", "screen_shots", "speaker_shots"}, plus "unchanged": true on a no-op rerun. Exit 1 is an invalid template or plan; exit 2 means --out already holds a different edit and is never overwritten. Read rules/camtasia-validation-authority.md and ask the user to open the bundle and confirm its observations 1 to 4. Finish here; resume at Step 9 when the user approves the cut, or at Step 5 with their changes, building into a new bundle name.

Step 9 — Request the captions

Ask the user to add dynamic captions to the approved project, save, and close. Finish here; resume at Step 10 when the user confirms.

Step 10 — Correct the captions

Write captions.txt as corrected English: names spelled right, sentence punctuation, false starts dropped, grammar fixed. The words the speaker meant, not a verbatim record. Then:

"{python_path}" "{speaker_toolkit_root}/skills/screencast-editor/scripts/apply-captions.py" "<title>.cmproj" captions.txt

For a word whose measured onset differs, pass --override WORD=SECONDS when the word occurs once in the captions, or --override WORD#N=SECONDS for its Nth occurrence; a repeated word without #N is refused. Pass the size and position flags for a different inset. Stdout: {"words", "matched", "interpolated", "pauses", "backup"}; exit 1 names the problem (project open, no transcript or caption callout, bad override, unrelated text) and leaves the project unchanged. Ask the user to confirm observations 5 and 6 of the Camtasia validation rule. Finish here; resume at Step 10 with their corrections, or at Step 11 when they approve.

Step 11 — Time the chapters

Write chapters.json (first entry's phrase null), then:

"{python_path}" "{speaker_toolkit_root}/skills/screencast-editor/scripts/chapters.py" "<title>.cmproj" chapters.json

Stdout: {"chapters": [{"seconds", "clock", "title"}], "lines"}. Exit 1 names what YouTube would reject, or a malformed chapters file: a missing phrase, or a chapter list that breaks the length and count limits in chapters.py. Fix and rerun. Proceed immediately to Step 12.

Step 12 — Draft the description

Write the video description around the chapter lines, linking only public sources you have verified. Proceed immediately to Step 13.

Step 13 — Offer thumbnail backgrounds

Pick three to five engaged moments and extract exact screen frames:

"{python_path}" "{speaker_toolkit_root}/skills/screencast-editor/scripts/extract-frames.py" <recording.trec> --stream 0:0 --at <seconds> --out thumb --prefix screen

Stdout: {"frames": [paths]}; exit 1 means a time lies outside the recording or ffmpeg failed. Ask the user which background to use, per the thumbnail-generation-rules rule. Finish here; resume at Step 14 when the user picks.

Step 14 — Resolve the speaker photo

Use publishing_process.thumbnail.speaker_photo_path from the speaker profile when it is set, and proceed immediately to Step 15. Otherwise extract candidate camera frames:

"{python_path}" "{speaker_toolkit_root}/skills/screencast-editor/scripts/extract-frames.py" <recording.trec> --stream 0:1 --at <seconds> --out thumb --prefix camera

Ask the user for a photo path or URL, offering these frames as the alternative. Finish here; resume at Step 15 with their choice.

Step 15 — Confirm the thumbnail title

Propose a hook title within the thumbnail-generation-rules word limit and ask the user to confirm it. Finish here; resume at Step 16 when confirmed.

Step 16 — Compose the thumbnail

"{python_path}" "{speaker_toolkit_root}/skills/screencast-editor/scripts/compose-thumbnail.py" --slide-image thumb/<screen-frame>.png --speaker-photo <photo> --title "<TITLE>" --aesthetic <photo|comic_book> --vault <vault_root> --output thumbnail.png

It runs the illustrations thumbnail generator. Stdout: {"thumbnail", "format", "width", "height", "bytes"}; a JPEG fallback is renamed to .jpg, and the generator's progress goes to stderr. Exit 1 means the generator failed or wrote no image; exit 2 includes a title over the word limit. Choose the aesthetic by the rule's precedence and read the result. Ask the user to approve it. Finish here; resume at Step 16 with one change at a time, or at Step 17 when they approve.

Step 17 — Hand off the release

Ask the user to export the video from Camtasia, upload it, and publish it with the description and the thumbnail. Finish here.