Repository navigation
feat(timeline): named timelines and make_short (shorts slice 1) - #73
Merged
Merged
Conversation
A workspace now holds several timelines: main stays at composition.json, others live in timelines/<id>/ with their own rev, lock and undo history. The make_short verb builds a vertical short on its own timeline from transcript word ranges of a source timeline: padded edges, cut from the source's clips so its silence and retake cuts carry in, a 9:16 cover canvas, -14 LUFS and captions, as one undoable edit. The CLI gains --timeline, `short`, `list` and `delete`; every MCP timeline tool takes an optional timeline id and timeline_show lists them. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A piece that only touches a range's words (they were cut out exactly) is dropped, so make_short refuses instead of playing padding alone. A range that continues the one before it in the same file starts where that one's padding ended, so neighboring words play straight through. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Adds the long recording → shorts quick start, the `short` command, the make_short verb in the MCP lists and an FAQ entry, and polishes the missing-timeline and non-empty-short errors for CLI users. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
whisper.cpp words abut, each pause going to the word before it, so the neighbor-word clamp removed all padding. Measured on a 30-sentence say recording with base.en and on jfk.wav: a range now starts 0.25 s before its first word (stopping halfway into the word before) and ends with its last word, which already runs through the pause after it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ords A timeline's folder is now checked against the workspace too, not only its files, so a timelines/ symlink out of the workspace can't receive temp files or a recursive delete through files that link back in. Captions on a short come only from the chosen words, not the word the lead padding reaches into, and a range whose words were all cut is refused even when a clip still covers the gap between them. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Captions came from the union of every range's words, so with reordered neighboring ranges one range's word could show in another's lead. Each piece now captions only the ranges it plays, from the transcripts the ranges were already read with. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This was referenced Nov 16, 2026
|
🎉 This PR is included in version 0.5.2 🎉 The release is available on:
Your semantic-release bot 📦🚀 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Slice 1 of 4 toward v0.5.2 (long recording → vertical shorts). Targets the integration branch
feat/shorts; merging it releases nothing.README: before · after. Look at the new "Quick start: a long recording → vertical shorts" section, the "Shorts from a long recording" row in the feature table, and the FAQ "Can it cut Shorts or Reels out of a podcast?".
What
Named timelines (
src/timeline/document-store.ts)mainstays atcomposition.json/composition-ops.json, so existing workspaces and olderclipversions keep working. Every other timeline lives intimelines/<id>/with the same two files.^[a-z0-9][a-z0-9-]{0,47}$(TimelineIdSchema,MAIN_TIMELINEinschema.ts). There is no "current timeline" pointer.main. A missing timeline other thanmainthrowsNoTimelineError. Onlymake_short(as the first verb of a batch) andclip timeline new --timelinecreate one, so a typo can't edit an empty document.listTimelines()returns main first, then each timeline by id. A document that doesn't parse is listed with its error.deleteTimeline(id)refusesmain.resolveInWorkspace, and the timeline folder is checked too, not only its files.Shorts (new
src/timeline/shorts.ts,make_shortverb inverbs.ts)planShortresolves each word range through the stored transcript (transcriptIdand source-changed checks included).v0track on acanvasFor(source, '9:16')cover canvas at the source's fps, framed byx/y(throughplanReframe). It sets loudness to -14 LUFS (nullturns it off) and adds captions made only from each piece's own range of words.adjustandvolume; fades are dropped and aspeedclip is refused. Withoutreplace, a timeline that already holds a short is refused.CLI (
src/cli-timeline.ts)--timeline <id>on everyclip timelinesubcommand.clip timeline short <id> <clipId> <from> <to> [...]with--source --aspect --x --y --words --no-captions --loudness --replace --dry-run. It prints the timeline, duration, pieces and warnings.clip timeline listandclip timeline delete <id>.MCP (
src/mcp/server.ts)timelineinput ontimeline_show,timeline_check,timeline_edit,timeline_transcript,timeline_undo,timeline_redoandtimeline_export. No new tool.timeline_showaddstimelineandtimelines.make_shortis added to thetimeline_editdescription.NoTimelineErrorandShortErrorcome back as{ error }.Elsewhere
clip ui: the verbs route answers aShortErrorwith 422 instead of 500. The UI itself still editsmainonly (slice 4).llms.txt,mcpb/manifest.json.src/index.tsexports the new API.Why
Finish line (approved 2026-11-15): a long talking-head or podcast recording becomes N vertical shorts from the CLI, MCP and the UI. Each short is picked by transcript, reframed to 9:16, captioned inside the safe zone and normalized to -14 LUFS. This slice adds the document model (several timelines, decision 1–2 of the plan) and the
make_shortverb (decisions 3–6), which the later slices build on.Edge padding, tuned (plan decision 6)
The plan's starting values were first word − 0.10 s and last word + 0.25 s, each clamped to the neighboring word's edge. Measured, they don't work with our transcripts, so this PR ships:
How it was measured:
say(Samantha and Daniel alternating, pauses of 0.15–0.6 s, a -63 dBFS noise floor), 83 s. Each sentence's true speech edges come from its own samples.clip timeline transcribe, with whisper.cpp 1.9.5 andggml-base.en.bin.jfk.wav, bundled with Homebrew's whisper.cpp, with pauses found from its energy.Findings:
-ml 1 -sow, 234 of 234 word pairs share an edge: each pause goes to the word before it. So the edge clamp cancelled the padding entirely; every lead and tail value gave identical cuts.jfk.wavagrees: next words start 0–0.13 s late, and the final word runs 0.64 s past the speech.docs/backlog/short-edges-snap-to-pause.md(a candidate for slice 2).How to test
Checks
pnpm lint: clean (7 pre-existing warnings intests/speed.test.tsandtests/transition.test.ts).pnpm type-check: clean.pnpm test: 890 passed, 28 skipped.pnpm build: OK.tests/timeline-shorts.test.ts(33): padding and the midpoint clamp; stopping at the file start and at a source clip's end; three silence-cut sub-clips giving three pieces; words cut out of main (including an exact cut and a cut leaving only the gap between words) refused; padding-only slivers dropped; neighboring ranges not replaying shared padding; multi-range order; two recordings; a repeated moment taken once; split joins; effects kept and dropped; speed refused; the exact op list (canvas, clip, framing,setLoudness, captions); captions only from each piece's own words; 720p and 1:1 canvases;replaceand the non-empty refusal; the verb's lowering, refusal on main and schema bounds; the store path (one undo empties the short, main untouched, a timeline created only by a batch that starts withmake_short).tests/document-store.test.ts(+10): paths per timeline, malformed ids,NoTimelineErrorfrom every entry point, separate rev and undo history, per-timeline write serialization,listTimelineswith a corrupt timeline and stray entries,deleteTimeline, and atimelines/symlink out of the workspace refused, including one whose files link back inside.tests/mcp-server.test.ts(+2):timeline_editwithtimeline: 'clip-1'andmake_shortgives 1080x1920,fit: cover, -14 LUFS and exportable; main is unchanged;timeline_showlists both; one undo empties the short; a missing timeline and a short on main answer{ error }; a malformed id is refused at the boundary. The tool-name pin is unchanged.CI=true, real FFmpeg 6.0: the newtests/integration/timeline-shorts.test.tspasses (11 s).timeline-reviewtimed out at vitest's default 5 s and passed on rerun. It does the same onfeat/shorts(docs/backlog/review-test-timeout.md).docs/backlog/segment-duration-rounding.md.codex review --base feat/shorts, gpt-6.1-sol).timelines/symlink out of the workspace, with files linking back in, passed the leaf-path check, so temp files anddeleteTimeline's recursive delete would act outside. The folder is now checked too, with a test that fails without the fix.Notes
planShorttakes nomediamap, andShortRequesthas nosource; the caller passes the source document.groupCaptionsanddefaultCaptionStyledirectly instead ofplanCaptions, so each piece captions only its own words.warningsis always empty until slice 2 adds sentence-edge warnings.clipignorestimelines/, so it sees and editsmainonly.short-edges-snap-to-pause.md,segment-duration-rounding.md,review-test-timeout.md.