HyperFrames Sports Director
Purpose
Turn a local mixed-media sports directory into an immersive, evidence-backed 16:9 Vlog. Use the bundled scripts for deterministic work and keep editorial or visual judgment with the Agent. HyperFrames owns visual direction and motion composition; FFmpeg owns media analysis, assembly, encoding, and measurement.
Use boundary
Use this Skill for participant-led sports stories assembled from a directory of videos and/or stills, optionally with recorded activity data and local music.
Do not use it for a generic FFmpeg command, a single-file transcode or retouch, sports-data-only analysis, training advice, score lookup, an advertisement, or promotional motion graphics. V1 never generates, searches for, or downloads music remotely.
Start here
- Read the workflow and final-inspection gate on every run.
- Inspect the input directory without modifying it. Check local capabilities before creating a project.
- Normalize the editing brief, then follow the current
PROJECT_STATE.json; do not skip ahead or infer a completed gate from filenames.
- Use the Unix command pipeline for exact command order and inputs.
Input and brief discovery
Resolve these values from the request and local directory:
- sport and maturity profile;
- videos, stills, local music, voice/dialogue, and optional FIT/KML/normalized activity data;
- duration target, required moments, exclusions, title/caption/copy language, and experiential intent;
- 16:9 resolution (
3840x2160 or 1920x1080), MP4 container, video/audio codecs, source-compatible frame-rate policy, and optional maximum file size;
- privacy requirements, including route trimming and footage exclusions.
Keep genuinely missing optional values null or status: "unavailable". Ask only when a missing value would materially change the single director approval; otherwise choose the narrowest profile-compatible default and record it in EDIT_BRIEF.json.
State router
Resume from the current integrity-valid state:
| State |
Next responsibility |
INTAKE |
Run the capability check; do not start media work when mandatory FFmpeg, ffprobe, Sharp, or HyperFrames support is absent. |
CAPABILITY_CHECK |
Ingest the immutable input directory and establish the portable media index plus private locator registry. |
SCAN |
Probe sources, build analysis proxies, and normalize the optional activity-data chain. |
ANALYZE |
Segment mechanically, inspect review derivatives, author/validate evidence-backed shots, then build the original-backed timeline and audio continuity. |
ROUGH_CUT |
Render/re-probe the proxy rough cut and prepare two or three complete direction proposals. |
DIRECTOR_REVIEW_READY |
Present the local workbench and record exactly one hash-bound approval. |
DIRECTOR_LOCK |
Produce and accept one full-resolution Style Anchor, then one representative real-footage combination proof. |
STYLE_ANCHOR |
Accept the representative component/real-footage combination proof before batch production. |
ASSET_PRODUCTION |
Finish approved batches and at least two semantically different final combination proofs. |
MOTION_COMPOSITION |
Validate ownership, semantic tokens, layouts, paused-time motion, contrast, and color before final render. |
FINAL_RENDER |
Inspect the closed encoded MP4 with machine gates and create final-only review evidence. |
FINAL_QA |
Record Agent judgments from decoded final-MP4 evidence; accepted evidence alone reaches DELIVERED. |
DELIVERED |
Report the output and evidence. USER_ACCEPTED is optional later input, never an inference. |
BLOCKED / CANCELLED |
Stop honestly, preserve evidence, and report the exact cause; do not claim delivery. |
Non-negotiable boundaries
- Never modify the input directory or commit originals, GPS, biometrics, secrets, large media, or evaluation workspaces.
- Portable artifacts use stable IDs and project-relative paths, never private filenames or absolute input paths.
- Render final video only from hash-matching originals. Proxies and review derivatives are analysis evidence, never delivery sources.
- Recorded footage and activity values are evidence. Generated visuals may interpret a journey but cannot impersonate a shot or invent a metric.
- Keep truth chains independent:
PROBE → SEGMENTS → SHOTS → TIMELINE; ACTIVITY → SYNC_MAP → DATA_OVERLAYS; and DESIGN_SYSTEM + LOOK_PROFILE → ASSET_MANIFEST → MOTION_MAP.
- Use only semantic colors frozen in
DESIGN_SYSTEM.json; keep asset appearance, motion ownership, and timing in their separate contracts.
- A normal run has one
DIRECTOR_LOCK approval. A requested change to story, key shots, direction, tokens, Look, music, privacy, or delivery starts a separate project revision.
Conditional references
- When footage or stills exist, read ingest and shot understanding.
- When activity data exists, read activity data.
- For the selected sport, read sport profiles.
- While selecting shots and building the story, read continuity editing.
- When speech, important ambience, or local music exists, read audio continuity.
- While preparing
DIRECTOR_REVIEW_READY or recording approval, read director workbench.
- When defining visual direction, read visual standard and HyperFrames composition.
- After lock, when generated visual assets are planned, read Image Gen asset pipeline and asset choreography and render QA.
- Before final render, read clarity and export.
Completion contract
Required output evidence includes the current project state, source/probe/shot/timeline chain, optional truthful activity chain, the one approval and frozen direction, accepted asset and motion contracts, renders/final.mp4 plus provenance, final inspection metrics, decoded evidence, and review/REVIEW_REPORT.md.
Run machine gates before Agent review. Automatic repair is limited to three attempts for allowed downstream roles and may not cross an approved boundary. A closed file that re-probes successfully is still not delivered until all hard gates pass and the Agent accepts composition, density, restraint, pacing, Style Anchor consistency, and transition meaning from the encoded MP4.
Every completion or blocker handoff states the current project state, whether a final output actually exists, the used/remaining repair budget, and that USER_ACCEPTED remains separate from DELIVERED.
1---2name: hyperframes-sports-director3description: Use when editing a local directory of sports videos, action-camera footage, still images, local music, or optional FIT/KML data into an immersive sports Vlog with shot evidence, one director approval, truthful graphics, mandatory FFmpeg processing, HyperFrames motion design, unattended QA, and 16:9 4K/1080p delivery.4---56# HyperFrames Sports Director78## Purpose910Turn a local mixed-media sports directory into an immersive, evidence-backed 16:9 Vlog. Use the bundled scripts for deterministic work and keep editorial or visual judgment with the Agent. HyperFrames owns visual direction and motion composition; FFmpeg owns media analysis, assembly, encoding, and measurement.1112## Use boundary1314Use this Skill for participant-led sports stories assembled from a directory of videos and/or stills, optionally with recorded activity data and local music.1516Do not use it for a generic FFmpeg command, a single-file transcode or retouch, sports-data-only analysis, training advice, score lookup, an advertisement, or promotional motion graphics. V1 never generates, searches for, or downloads music remotely.1718## Start here19201. Read [the workflow and final-inspection gate](references/workflow.md) on every run.212. Inspect the input directory without modifying it. Check local capabilities before creating a project.223. Normalize the editing brief, then follow the current `PROJECT_STATE.json`; do not skip ahead or infer a completed gate from filenames.234. Use [the Unix command pipeline](references/unix-pipeline.md) for exact command order and inputs.2425### Input and brief discovery2627Resolve these values from the request and local directory:2829- sport and maturity profile;30- videos, stills, local music, voice/dialogue, and optional FIT/KML/normalized activity data;31- duration target, required moments, exclusions, title/caption/copy language, and experiential intent;32- 16:9 resolution (`3840x2160` or `1920x1080`), MP4 container, video/audio codecs, source-compatible frame-rate policy, and optional maximum file size;33- privacy requirements, including route trimming and footage exclusions.3435Keep genuinely missing optional values `null` or `status: "unavailable"`. Ask only when a missing value would materially change the single director approval; otherwise choose the narrowest profile-compatible default and record it in `EDIT_BRIEF.json`.3637## State router3839Resume from the current integrity-valid state:4041| State | Next responsibility |42| --- | --- |43| `INTAKE` | Run the capability check; do not start media work when mandatory FFmpeg, ffprobe, Sharp, or HyperFrames support is absent. |44| `CAPABILITY_CHECK` | Ingest the immutable input directory and establish the portable media index plus private locator registry. |45| `SCAN` | Probe sources, build analysis proxies, and normalize the optional activity-data chain. |46| `ANALYZE` | Segment mechanically, inspect review derivatives, author/validate evidence-backed shots, then build the original-backed timeline and audio continuity. |47| `ROUGH_CUT` | Render/re-probe the proxy rough cut and prepare two or three complete direction proposals. |48| `DIRECTOR_REVIEW_READY` | Present the local workbench and record exactly one hash-bound approval. |49| `DIRECTOR_LOCK` | Produce and accept one full-resolution Style Anchor, then one representative real-footage combination proof. |50| `STYLE_ANCHOR` | Accept the representative component/real-footage combination proof before batch production. |51| `ASSET_PRODUCTION` | Finish approved batches and at least two semantically different final combination proofs. |52| `MOTION_COMPOSITION` | Validate ownership, semantic tokens, layouts, paused-time motion, contrast, and color before final render. |53| `FINAL_RENDER` | Inspect the closed encoded MP4 with machine gates and create final-only review evidence. |54| `FINAL_QA` | Record Agent judgments from decoded final-MP4 evidence; accepted evidence alone reaches `DELIVERED`. |55| `DELIVERED` | Report the output and evidence. `USER_ACCEPTED` is optional later input, never an inference. |56| `BLOCKED` / `CANCELLED` | Stop honestly, preserve evidence, and report the exact cause; do not claim delivery. |5758## Non-negotiable boundaries5960- Never modify the input directory or commit originals, GPS, biometrics, secrets, large media, or evaluation workspaces.61- Portable artifacts use stable IDs and project-relative paths, never private filenames or absolute input paths.62- Render final video only from hash-matching originals. Proxies and review derivatives are analysis evidence, never delivery sources.63- Recorded footage and activity values are evidence. Generated visuals may interpret a journey but cannot impersonate a shot or invent a metric.64- Keep truth chains independent: `PROBE → SEGMENTS → SHOTS → TIMELINE`; `ACTIVITY → SYNC_MAP → DATA_OVERLAYS`; and `DESIGN_SYSTEM + LOOK_PROFILE → ASSET_MANIFEST → MOTION_MAP`.65- Use only semantic colors frozen in `DESIGN_SYSTEM.json`; keep asset appearance, motion ownership, and timing in their separate contracts.66- A normal run has one `DIRECTOR_LOCK` approval. A requested change to story, key shots, direction, tokens, Look, music, privacy, or delivery starts a separate project revision.6768## Conditional references6970- When footage or stills exist, read [ingest and shot understanding](references/ingest-and-shot-understanding.md).71- When activity data exists, read [activity data](references/activity-data.md).72- For the selected sport, read [sport profiles](references/sport-profiles.md).73- While selecting shots and building the story, read [continuity editing](references/continuity-editing.md).74- When speech, important ambience, or local music exists, read [audio continuity](references/audio-continuity.md).75- While preparing `DIRECTOR_REVIEW_READY` or recording approval, read [director workbench](references/director-workbench.md).76- When defining visual direction, read [visual standard](references/visual-standard.md) and [HyperFrames composition](references/hyperframes-composition.md).77- After lock, when generated visual assets are planned, read [Image Gen asset pipeline](references/imagegen-asset-pipeline.md) and [asset choreography and render QA](references/asset-choreography-and-render-qa.md).78- Before final render, read [clarity and export](references/clarity-and-export.md).7980## Completion contract8182Required output evidence includes the current project state, source/probe/shot/timeline chain, optional truthful activity chain, the one approval and frozen direction, accepted asset and motion contracts, `renders/final.mp4` plus provenance, final inspection metrics, decoded evidence, and `review/REVIEW_REPORT.md`.8384Run machine gates before Agent review. Automatic repair is limited to three attempts for allowed downstream roles and may not cross an approved boundary. A closed file that re-probes successfully is still not delivered until all hard gates pass and the Agent accepts composition, density, restraint, pacing, Style Anchor consistency, and transition meaning from the encoded MP4.8586Every completion or blocker handoff states the current project state, whether a final output actually exists, the used/remaining repair budget, and that `USER_ACCEPTED` remains separate from `DELIVERED`.
geekjourneyx