edit-session

name: edit-session description: "Loaded after a draft is ready for back-and-forth editing: cutting, overlay adjustments, timing fixes. Not a pipeline step — this is the interactive editing reference."

Edit Session

Load this skill when the draft is ready and the user wants to make refinements — cuts, overlay changes, re-timing, new overlays. This is not a workflow step; it covers the tools and conventions for iterative editing.

After every file change: push a UI refresh

After writing project.json or any overlay .jsx file, call the reload endpoint so the UI updates without a manual refresh:

curl -s -X POST http://localhost:3000/api/projects/{project_id}/reload

The file watcher is unreliable under load. Always call this explicitly after changes.

Before editing anything: verify the transcript

Always check that the transcript matches the current clip before using timestamps.

The clip filename tells you which transcript to use. For a clip at:

IMG_4900_fillers_concat_cut_cut.mp4

The transcript must be named after that exact file — e.g. IMG_4900_fillers_concat_cut_cut.json. If only an older transcript exists (e.g. IMG_4900_fillers_concat.json), it is stale — its timestamps come from a pre-cut file and will not align with the current video.

Re-transcribe when in doubt:

python3 steps/transcribe.py \
  --input "/abs/path/to/clip.mp4" \
  --model base.en

Output: clip.json (word-level timings) and clip.srt. Always read the fresh clip.json before deriving overlay or cut timings.

Cutting

Cut tool spec

steps/cut.py --input <video> [options]

Single cut:

python3 steps/cut.py --input clip.mp4 --start 4.2 --end 7.8

Multiple cuts in one pass:

python3 steps/cut.py --input clip.mp4 --cuts '[[1.0,3.5],[12.4,14.0]]'

Spec mode (no encode, fast):

python3 steps/cut.py --input clip.mp4 --cuts '[[1.0,3.5]]' --spec
# → {"path": "/tmp/clip_spec.json"}

Cut list (UI workflow)

When using the UI, cuts are non-destructive until applied:

1. "Add to cut list" — queues a [start, end] physical range on the clip instantly (no encode).
2. Pending cuts appear as red zones on the scrubber. PreviewPlayer skips over them.
3. "Apply cuts (N)" — encodes all queued cuts in one ffmpeg pass and updates the clip.

Overlap merging: if a new pending cut overlaps an existing one, they are merged to the outer bounds. Example:

Existing cut: [1.0, 3.0]
New cut:      [2.0, 5.0]
Result:       [1.0, 5.0]   ← outer bounds win

Existing: [1.0, 2.0]
New:      [0.0, 3.0]
Result:   [0.0, 3.0]       ← new fully contains old

After applying cuts, the clip file changes. Re-transcribe if you need to update overlay timings.

Overlays

What overlays can do

• Transparent overlays — float over footage. Position with position: absolute, leave root background alone.
• Opaque overlays ("opaque": true in project.json) — replace the video frame entirely. Root CSS controls the full frame. Good for title cards, stat cards, full-screen animations.

Timing overlays from transcript

Read word-level timings from clip.json. Each word has a start and end in seconds relative to the current clip. Use these to set overlay start/end in project.json and to compute per-item stagger delays inside the JSX.

Example: if "landing" appears at t=16.70s in the transcript and the overlay starts at 16.52s, the item's trigger frame inside the component is:

const ITEM_FRAME = Math.round((16.70 - 16.52) * fps)  // 0.18s * fps

tracks layout

{
  "tracks": [
    [
      // Track 0 — primary footage track
      { "id": "clip-0", "type": "video", "src": "/abs/path/clip.mp4", "start": 0.0, "end": 0.0 }
    ],
    [
      // Track 1 — background layer (opaque sections, backgrounds)
      { "id": "...", "type": "overlay", "src": "/abs/path.jsx", "start": 0.0, "end": 5.0, "opaque": true }
    ],
    [
      // Track 2+ — renders on top of track 1
      { "id": "...", "type": "overlay", "src": "/abs/path.jsx", "start": 2.0, "end": 4.0 }
    ]
  ]
}

• No time overlaps within a single track.
• Use separate tracks for simultaneous overlays at different z-levels.
• Always use absolute paths for src.

Icons

Use icons instead of emojis unless the user explicitly asks for emojis.

Phosphor Icons — Ph

All icons available as Ph.<Name>. Browse at phosphoricons.com.

<Ph.CheckCircle size={52} weight="fill" color="#34d399" />
<Ph.Lock size={48} weight="fill" color="#f87171" />
<Ph.X size={200} weight="bold" color="#ff1a1a" />

Weights: regular (default), bold, fill, duotone, light, thin.

Font Awesome — FaIcon + FaSolid / FaBrands

FaIcon is the renderer. Use FaSolid for general icons, FaBrands for brand logos (GitHub, YouTube, X/Twitter, TikTok, etc.).

<FaIcon icon={FaSolid.faBolt} style={{ fontSize: 48, color: '#fbbf24' }} />
<FaIcon icon={FaBrands.faGithub} style={{ fontSize: 48, color: 'white' }} />

Which to use

• Phosphor — default choice. Cleaner API, consistent weight, 9000+ icons.
• Font Awesome Brands — brand logos only (Phosphor doesn't have brand icons).
• Font Awesome Solid — fallback for anything Phosphor doesn't cover.

All four globals (Ph, FaIcon, FaSolid, FaBrands) are injected automatically in both the browser preview and the render pipeline. No imports needed.

JSX authoring quick reference

All overlay JSX has these globals injected — no imports, ever:

Rules:

• Default export only
• No hooks (useState, useEffect)
• No CSS animation or transition — all motion from frame
• Transparent root by default; opaque overlays set background on the root
• Never apply transform: translate/scale to the root element
• Animations must complete before the overlay ends (last frame is held)
• ALL code that references fps, frame, duration, or props MUST be inside the component function body. Top-level module code runs before these globals are injected in the render path (esbuild IIFE) and will throw ReferenceError. Style constant objects that don't reference these globals (e.g. const LABEL_STYLE = { fontSize: 42, ... }) are fine at the top level.