System Requirements Document

1. Introduction

This document specifies the requirements for a long-form-to-short-form clip generation system built to answer one operational need: get the viral moments out of a long-form video and turn them into clips.

The source material for this SRD is a single recorded long-form video — a 24-hour life-swap challenge in which a well-known trading creator and a struggling trader exchange daily routines ("I Swapped Lives With A Broke Trader For 24 Hours"). The recording is delivered as a timestamped transcript with per-line start/end times, speaker turns, and non-speech markers (music, laughter, bleeped/inaudible passages). The system's job is to read that source, identify the moments with clip potential, and produce finished clips from them without an editor manually scrubbing the full runtime.

The source is not unstructured: it follows a repeated day-arc itinerary, alternates between two mirrored household/vehicle/food setups, and contains several self-contained content blocks (side-hustle advice, a live coaching call, a betting sequence, an outro address). Those structural regularities are themselves clip-generation signals, and the system is required to use them.

The system is single-operator tooling. It does not require accounts, tenancy, administration, payments, or a public-facing portal; none of those are implied by the request or the source material.

2. System Overview

The system takes one long-form source (video plus its timestamped transcript) and returns a shortlist of candidate viral moments and a set of rendered clips cut from them.

It operates in four stages:

1. Ingest — load the source video and its timestamped transcript; normalize transcript lines into discrete, timecoded units (spoken lines, speaker turns, non-speech markers).
2. Detect — scan the full runtime for candidate viral moments using signals present in the source: hook lines, emotional peaks, contradiction/turn beats, scene changes across the day's arc, recurring motifs, structured content blocks, and brand/sponsor mentions.
3. Assemble — expand each selected moment into a clip with precise in/out points, snapped to sentence and speaker boundaries so the setup and payoff both survive the cut.
4. Export — render clips in short-form framing with captions, and emit a planning sheet of clip titles, hook lines, and source timecodes.

The operator reviews and can override every automated decision. Nothing is published, shared, or re-cut destructively: all generated clips remain traceable to the exact source timecodes they came from.

3. Functional Requirements

3.1 Source Ingest and Transcript Preparation

• FR-1 — As a Clip Editor, I want to load the full long-form source video in one action so that the system has the complete raw material to clip from, rather than a pre-trimmed excerpt.
• FR-2 — As a Clip Editor, I want the source transcript ingested with each line's own start and end time so that every spoken line maps to an exact position in the video.
• FR-3 — As a Clip Editor, I want transcript lines preserved as discrete units rather than merged into paragraphs, so that clips can be cut on line boundaries.
• FR-4 — As a Clip Editor, I want speaker turns identified and retained in the transcript so that clips can be cut on speaker changes and dialogue exchanges stay intact.
• FR-5 — As a Clip Editor, I want non-speech markers in the transcript — music, laughter, silence, bleeped or inaudible passages — labeled as non-speech so they are never mistaken for spoken hook material.
• FR-6 — As a Clip Editor, I want to see the full transcript in the order it occurs with its timecodes so that the detection output can be checked against the actual source.
• FR-7 — As a Clip Editor, I want transcript text preserved verbatim as delivered, including run-on phrasing, filler, and censored tokens, so that downstream detection can judge a line on what was actually said rather than on a cleaned-up paraphrase.
• FR-8 — As a Clip Editor, I want the system to identify utterance-level discourse markers and connective filler (for example "so", "okay", "then", "but", "yeah", "boom") as transition markers rather than as content, so that they can be used as boundary hints and never promoted to a clip title or hook.

3.2 Viral Moment Detection

• FR-9 — As a Clip Editor, I want the system to surface candidate viral moments across the entire runtime in a single pass so that I do not have to scrub the timeline manually to find them.
• FR-10 — As a Clip Editor, I want each candidate moment ranked by predicted clip potential so that I can start reviewing from the strongest.
• FR-11 — As a Clip Editor, I want hook lines — short, quotable, high-energy statements — flagged as moment candidates so that clips can open on a strong first second.
• FR-12 — As a Clip Editor, I want emotional peaks flagged as moment candidates, including reactions, disbelief, boasts, confrontation, and laughter beats.
• FR-13 — As a Clip Editor, I want turn/contradiction beats flagged — a claim immediately followed by an objection, reversal, or payoff reaction — because these read as self-contained clip narratives.
• FR-14 — As a Clip Editor, I want scene and location changes across the day's arc treated as candidate clip boundaries so that clips respect the natural segmentation of a 24-hour-format video.
• FR-15 — As a Clip Editor, I want recurring motifs, repeated catchphrases, and callbacks detected so that repeating bits can be clipped as a series rather than as one-offs.
• FR-16 — As a Clip Editor, I want brand, sponsor, and product mentions detected and flagged so that I can decide per clip whether to keep or trim them.
• FR-17 — As a Clip Editor, I want recognizable luxury-label props and apparel callouts flagged as visual-hook candidates, because on-screen branded objects are frequently the strongest frame in a clip.
• FR-18 — As a Clip Editor, I want to see which signals caused a moment to be flagged so that I can trust, down-rank, or override the automated ranking.
• FR-19 — As a Clip Editor, I want candidate moments deduplicated so that adjacent overlapping detections of the same beat appear once in the shortlist.
• FR-20 — As a Clip Editor, I want to reject or dismiss a candidate moment so that the shortlist stays focused on moments I intend to cut.
• FR-21 — As a Clip Editor, I want to manually mark a moment the system missed so that obvious viral beats are never lost to a detection gap.

3.3 Structural Block and Beat Detection

• FR-22 — As a Clip Editor, I want the system to detect the source's repeating day-in-the-life itinerary structure — the ordered sequence of daily beats such as waking, trading, filming short-form posts, napping, leisure, exercise, business calls, and meals — so that the day's beats are located for me instead of inferred.
• FR-23 — As a Clip Editor, I want each itinerary beat labeled with what it is and when it occurs so that I can cut one clip per beat.
• FR-24 — As a Clip Editor, I want mirrored beats across the two swapped lives paired automatically — the same beat performed in both the high-end and the low-end setup — so that contrast clips can be assembled from both halves without manual matching.
• FR-25 — As a Clip Editor, I want meal and food beats detected across the runtime, including fast-food value meals, cheap-menu ordering, fine-dining ordering, home-fridge inspection, and takeaway runs, so that the food thread can be clipped as its own series.
• FR-26 — As a Clip Editor, I want price-contrast beats flagged, where the cost or quality of the same activity is contrasted between the two setups, so that the comparison lands inside a single clip.
• FR-27 — As a Clip Editor, I want vehicle and ride beats detected, including ride-hail trips, private car use, exotic-car handling, and interior-feature commentary, so that the vehicle thread can be clipped as its own series.
• FR-28 — As a Clip Editor, I want side-hustle and income-advice blocks detected as a distinct clip class — segments where the speaker gives actionable self-employment guidance, compares hustles, and outlines a daily scheduling strategy — so that advice clips are grouped separately from entertainment clips.
• FR-29 — As a Clip Editor, I want coaching-session and student-teaching blocks detected as a distinct clip class — segments where students present trade results, ask questions, receive rulings, and are promoted or escalated — so that teaching and call-and-response clips are grouped separately.
• FR-30 — As a Clip Editor, I want monetization and speculation beats flagged, including realized payout figures, position results, and placed wagers, so that money-result moments are captured as candidate hooks.
• FR-31 — As a Clip Editor, I want imagined-future and self-narration beats flagged — moments where a speaker narrates an idealized version of their day or a future life — because these read as standalone aspirational clips.
• FR-32 — As a Clip Editor, I want closing and direct-address-to-audience beats detected, including sign-offs, audience guidance, and final reflections, so that an outro clip can be cut from the end of the source.
• FR-33 — As a Clip Editor, I want exclusive-access and unrepeatable-location beats flagged — moments where the speaker gains entry to a space, asset, or setting they normally cannot access — since novelty is a primary clip driver.

3.4 Clip Assembly

• FR-34 — As a Clip Editor, I want a selected moment expanded into a clip with explicit in and out points so that the cut has a defined start and end.
• FR-35 — As a Clip Editor, I want clip boundaries snapped to sentence and speaker boundaries by default so that clips do not cut off mid-thought.
• FR-36 — As a Clip Editor, I want transition markers used as preferred cut points when a sentence boundary is ambiguous, so that clips start and end on clean discourse transitions.
• FR-37 — As a Clip Editor, I want the setup-and-payoff arc of a moment preserved inside the clip so that it lands without the viewer needing the rest of the video.
• FR-38 — As a Clip Editor, I want the system to refuse to promote a fragmentary, mid-sentence utterance to a clip hook or title, so that clip openings and titles are always complete thoughts.
• FR-39 — As a Clip Editor, I want to manually adjust the in and out points of any clip so that I can correct a bad automatic boundary.
• FR-40 — As a Clip Editor, I want to preview a clip before committing it so that weak cuts are rejected before rendering.
• FR-41 — As a Clip Editor, I want to generate multiple clips from one source in a single run so that a long video yields a batch rather than one clip at a time.
• FR-42 — As a Clip Editor, I want recurring-motif detections assembled into a multi-part clip series with consistent titling so that a repeated bit is released as a coherent set.
• FR-43 — As a Clip Editor, I want each clip to retain a reference to its exact source timecodes so that I can verify it against the original and re-cut it later.
• FR-44 — As a Clip Editor, I want clips rendered in short-form vertical framing so that they are ready for short-form feeds without further framing work.
• FR-45 — As a Clip Editor, I want captions generated from the transcript and burned into the clip so that it is legible with sound off.
• FR-46 — As a Clip Editor, I want bleeped, inaudible, and explicit spoken passages handled consistently across all clips so that exported clips meet platform standards.
• FR-47 — As a Clip Editor, I want a suggested clip title and hook line generated for each assembled clip so that the planning sheet is populated without manual naming.

3.5 Export and Handoff

• FR-48 — As a Clip Editor, I want each clip exported as an individual media file so that it can be handed directly to distribution.
• FR-49 — As a Clip Editor, I want a summary sheet listing each clip's title, hook line, rank, duration, and source timecodes so that I can plan posting without opening every file.
• FR-50 — As a Clip Editor, I want to export a selected subset of clips rather than the whole batch so that I can ship only what I have approved.

3.6 Review and Approval

• FR-51 — As a Source Creator, I want to review the shortlisted moments and their assembled clips in one place so that I can confirm which cuts represent my material accurately.
• FR-52 — As a Source Creator, I want to approve or reject individual clips so that only approved cuts move to publishing.
• FR-53 — As a Clip Editor, I want every clip's status visible in the batch — candidate, assembled, approved, exported — so that I always know what remains to be done.

4. User Personas

4.1 Clip Editor (primary)

The operator who runs the system. Loads the long-form source, works the ranked shortlist, adjusts boundaries, previews and renders clips, and produces the export batch and planning sheet. Works primarily in a timeline/preview surface and cares about speed of triage and precision of cut points.

4.2 Source Creator (secondary)

The owner of the long-form video whose material is being clipped. Reviews the assembled clips against their own intent, approves or rejects individual cuts, and takes approved clips to publishing. Does not operate the detection or assembly tooling.

System actors (not personas): the media processing layer that decodes and renders clips, and the short-form distribution platforms that receive approved exports.

5. Core User Flows

Flow A — Source to Shortlist

1. Clip Editor loads the long-form source video.
2. System ingests the timestamped transcript and normalizes it into timecoded units: spoken lines, speaker turns, and non-speech markers.
3. System identifies transition markers separately from content lines.
4. System scans the full runtime and flags candidate moments: hooks, emotional peaks, turn/contradiction beats, scene changes, recurring motifs, and brand or sponsor mentions.
5. System additionally maps the structural layer: itinerary beats, mirrored beat pairs across the two setups, food thread, vehicle thread, advice block, coaching block, monetization beats, imagined-future beats, and the closing address.
6. System deduplicates overlapping candidates and ranks the shortlist.
7. Clip Editor opens the shortlist, sees each candidate's triggering signals and timecodes, and dismisses weak candidates.
8. Clip Editor manually marks any obvious moment the system missed.
9. Clip Editor confirms the working shortlist.

Flow B — Shortlist to Exported Clips

1. Clip Editor selects a candidate moment or a beat from the structural view.
2. System expands it into a clip with in/out points snapped to sentence, speaker, or transition boundaries, preserving the setup and payoff.
3. For a mirrored beat pair, system proposes a comparison clip drawing from both halves.
4. For a recurring motif, system proposes the series set with consistent titling.
5. Clip Editor previews the clip.
6. Clip Editor adjusts in/out points where the automatic boundary is wrong, and handles flagged sponsor or explicit passages.
7. On acceptance, system renders the clip in short-form vertical framing with captions burned in from the transcript.
8. Clip Editor repeats across the shortlist in a single batch run.
9. System emits the clip files plus a planning sheet with titles, hook lines, durations, and source timecodes.
10. Clip Editor exports the approved subset.

Flow C — Creator Review to Publish

1. Source Creator opens the assembled clip batch.
2. Creator reviews each clip against the source material.
3. Creator approves or rejects individual clips.
4. Approved clips move to export and are handed to short-form distribution.
5. Rejected clips return to the Clip Editor with the source timecodes intact for re-cutting.

6. Visuals, Colors and Theme

Not specified by the user or the source material; the following restrained defaults are derived from the domain — single-operator editing work on high-energy, money-and-lifestyle creator content, viewed in long sessions on a dark editing surface.

• Base canvas: near-black charcoal (#0C0C0E) so video preview and waveform carry the visual weight.
• Panels and rails: elevated dark surfaces (#151519, borders #26262C) with generous vertical rhythm; no decorative chrome.
• Primary accent: warm gold/amber (#E8B241) reserved for selection, clip in/out handles, and approved/exported status — a single accent that reads as "value" without competing with video content.
• Signal color: a muted magenta-to-amber gradient used only for the virality heat ribbon over the timeline, so intensity is legible at a glance.
• Text: off-white (#EDEDF0) for primary, mid-gray (#8A8A93) for timecodes and metadata; timecodes always monospaced and tabular-aligned.
• Status vocabulary: neutral gray (candidate), amber outline (assembled), solid gold (approved), check-marked (exported). Color is never the only status indicator.
• Type: one clean geometric sans for UI, one condensed sans for clip titles and burned-in captions; no display faces.

7. Signature Design Concept

The Heat Ribbon. A single continuous horizontal band sits directly above the waveform for the entire source runtime. It is the product's identity: a compression of the whole long video into one glanceable strip of intensity, where flagged moments appear as warm peaks and dead stretches as flat cool line. Every other surface in the product is subordinate to it — the shortlist is a vertical read-out of the ribbon's peaks, the preview is the ribbon opened at one point, and an exported clip is a segment of the ribbon lifted out and framed.

A second, thinner rail runs directly beneath the ribbon carrying the structural layer — the itinerary beats, the advice and coaching blocks, the money beats — so the operator can read content intensity and content structure at the same time without a second screen.

The ribbon makes the value proposition physical: the whole runtime, and exactly where the clips live inside it.

8. Interaction Model & Motion Direction

• Scrub-first: the timeline is the primary navigation surface and is always visible; the shortlist, transcript, and preview stay synchronized to the playhead at all times.
• Click a peak, get a clip: selecting a flagged moment immediately opens it in the preview with provisional in/out handles already placed, so the default interaction is one click rather than a trim exercise.
• Beat rails are directly manipulable: hovering a structural beat shows its full transcript span and lets the operator promote the whole beat to a clip in one action.
• Keyboard-driven triage: navigation between candidates, preview play/pause, nudge of in/out points, accept, and reject are all available without leaving the keyboard, because shortlist review is repetitive by nature.
• Non-destructive everywhere: rejection, re-cutting, and re-rendering never destroy prior work; every clip can be reopened at its source timecodes.
• Motion direction: motion is functional and short — handles snap with a brief eased settle (~120ms) when they lock to a sentence boundary; the heat ribbon draws in left-to-right once on load so the runtime is read as a single span; the structural rail fades in behind it once loaded; nothing animates during playback, and there is no ambient or decorative motion.
• Feedback: every automated decision (a flag, a rank, a boundary snap, a beat label) shows a compact inline reason, so the operator can distinguish "the system decided" from "I decided."

9. Non-Functional Requirements

• NFR-1 — Timestamp fidelity. Clip in/out points must map to source timecodes with no cumulative drift across a full ~1,750-second runtime; rendered clips must be frame-accurate to the specified points.
• NFR-2 — Full-runtime coverage. Detection must scan the entire source in one pass, including late-runtime sections, so late moments and the closing address are not systematically under-ranked.
• NFR-3 — Detection throughput. A detection-and-ranking pass over a source in the observed ~30-minute range must complete in a few minutes on a single operator machine, not in real time.
• NFR-4 — Batch rendering. Rendering a batch of clips must not require re-encoding the untouched portions of the source; per-clip render time must stay in the seconds range.
• NFR-5 — Transcript robustness. The system must correctly handle censored tokens, bleeped dialogue, bracketed non-speech markers, and ASR-style disfluencies without dropping lines or misaligning timecodes.
• NFR-6 — Fragment tolerance. Detection must tolerate incomplete, run-on, and grammatically broken transcript lines without treating them as noise to be discarded, while still preventing fragments from reaching hook or title output.
• NFR-7 — Explainability. Every ranking, beat label, and automated boundary must be inspectable; no black-box score is shown without its contributing signals.
• NFR-8 — Reproducibility. Re-running detection on the same source and transcript must produce the same ranked shortlist and the same structural map, so an operator can compare runs.
• NFR-9 — Non-destructive storage. Source media is never modified; generated clips, decisions, and project state are stored separately and can be regenerated.
• NFR-10 — Local-first handling. Source media and rendered clips remain on the operator's machine unless explicitly exported; the tool requires no third-party account or public endpoint to function.
• NFR-11 — Long-session usability. The interface must remain legible and responsive during extended review sessions with a large clip batch and an active structural overlay.
• NFR-12 — Rights constraint. The system must only operate on source material the operator has the right to clip; it performs no ingestion of third-party content on its own.

10. Tech Stack

Only the layers the accepted delivery shape requires are specified. This is single-operator tooling over an openly supplied source file and transcript; no account, application server fleet, or multi-tenant data layer is implied.

• Operator workspace (client): browser-based editing surface providing synchronized video playback, waveform plus heat-ribbon timeline with an overlaid structural beat rail, transcript pane, and shortlist — necessary because clip boundary judgment requires visual and audio review.
• Media layer: local command-line media processing (FFmpeg-class tooling) for decode, trim, vertical reframe, caption burn-in, and clip encode; the source is never re-encoded wholesale, only the selected segments.
• Transcript layer: transcript-first ingestion accepting the timestamped transcript delivered with the source; an optional speech-alignment step only when a transcript is absent or timecodes are missing.
• Detection and scoring layer: local analysis over transcript text, timecodes, speaker turns, and non-speech markers, producing both a moment ranking and a structural beat map; deterministic, explainable scoring — no external inference service is required.
• Project state and storage: local filesystem/object storage for the source media, rendered clips, and a structured project file holding candidates, beat labels, decisions, and clip definitions.
• Delivery: run as a local single-operator workspace; export produces standalone media files and a planning sheet for handoff to short-form distribution platforms.

11. Assumptions and Constraints

• The source is supplied as a long-form video accompanied by a transcript with per-line start and end times in seconds; the sample provided runs to roughly 1,750 seconds across a multi-scene 24-hour-format structure.
• The transcript contains non-speech markers (music, laughter) and censored or inaudible tokens; these are treated as content to classify, not as errors to repair.
• The transcript is a raw ASR-style rendering and therefore contains many incomplete and run-on utterances; the system must treat these as normal input, not as corrupt data, while keeping them out of user-facing hook and title output.
• The source content is spoken-word, dialogue-heavy, and multi-speaker, with rapid conversational back-and-forth; clips must therefore be cut on speaker and sentence boundaries, with transition markers as fallbacks.
• The source follows a repeated day-in-the-life itinerary performed twice, once in each swapped life; the itinerary layer is a detection input, and mirrored beats are expected to be paired.
• The source contains a sustained advice/talking-head block on self-employment and side work, and a sustained live coaching-session block; both are treated as distinct clip classes rather than as generic dialogue.
• The source material contains profanity and explicit passages; clip output must apply consistent handling so exports meet platform standards.
• The source material contains brand, sponsor, product, and luxury-label references inside the flow of the video; these are detection targets for operator decisions, not automatic removals.
• The source depicts food, vehicles, and property of highly varied cost; price-contrast is treated as a first-class clip signal because it is a recurring structural device in the source.
• The system is single-operator and local by default; no authentication, multi-user roles, administration surface, or hosted account model is required by the source material or the request.
• Clip output targets short-form vertical feeds; aspect reframing and burned-in captions are in scope, and long-form re-editing is not.
• The operator is responsible for holding the rights to the source material being clipped.
• Detection quality is bounded by transcript quality: missing timecodes, misaligned lines, or unlabeled non-speech reduce ranking, beat-map, and boundary accuracy.

12. Glossary

• Source / long-form source: the complete video and its timestamped transcript that clips are cut from.
• Viral moment: a candidate segment of the source identified as having standalone clip potential.
• Candidate: a flagged moment in the ranked shortlist, before it is cut.
• Clip: a rendered, exported segment cut from the source with defined in/out points.
• Hook line: a short, quotable statement used as a clip's opening beat.
• Turn / contradiction beat: a claim immediately followed by an objection, reversal, or payoff reaction; a self-contained clip narrative.
• Scene change: a shift in location or activity within the source's day arc; treated as a natural clip boundary.
• Motif / callback: a repeated phrase or bit that recurs across the source and can be clipped as a series.
• Non-speech marker: a transcript token denoting music, laughter, silence, or an inaudible/bleeped passage.
• Transition marker: a short discourse connective or filler ("so", "okay", "then", "but", "yeah", "boom") used as a boundary hint, never as content or a title.
• Incomplete utterance / fragment: a transcript line that does not express a complete thought; usable as context, never promoted to a hook or title.
• Itinerary beat: one step in the repeated day-in-the-life sequence, such as waking, trading, posting, napping, leisure, exercise, business calls, or meals.
• Mirrored beat: the same itinerary beat performed in both swapped lives, used to build contrast clips.
• Structural rail: the secondary timeline band showing itinerary beats and detected content blocks beneath the heat ribbon.
• Advice block: a sustained talking-head segment giving self-employment or side-work guidance.
• Coaching block: a sustained live teaching segment in which students present results, ask questions, and receive rulings.
• Monetization beat: a moment presenting a realized payout, position result, or placed wager.
• Imagined-future beat: a moment where a speaker narrates an idealized version of their day or a future life.
• Closing address / outro beat: a direct-to-audience sign-off or final reflection at the end of the source.
• Contrast clip: a clip built from a mirrored beat pair to show the same activity in two different economic settings.
• Heat ribbon: the signature intensity band above the waveform representing clip potential across the entire runtime.
• Boundary snap: automatic alignment of a clip's in/out points to sentence, speaker, or transition boundaries.
• Setup and payoff: the setup line and its resolution, both of which must fall inside a clip for it to stand alone.
• Planning sheet: the exported summary of clip titles, hook lines, ranks, durations, and source timecodes.
• Timecode: the exact position in the source, in seconds, that a transcript line or clip boundary maps to.
• Short-form framing: vertical aspect output with burned-in captions, ready for short-form feeds.

Appendix A — Source Fragment Disposition Map

The completeness check supplied a list of strings drawn from the uploaded transcript. Those strings are raw ASR fragments and sentence fragments rather than discrete system capabilities, so they are not promoted to standalone user stories; promoting a mid-sentence fragment such as "I guess" to its own requirement would create an untestable requirement. Each string is instead accounted for by the requirement that consumes it, so that nothing from the flagged list is silently dropped.