Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/junwen853/travel-video-studio-skill

Codex skill for route-aware DaVinci travel films from unordered GPS-less footage
https://github.com/junwen853/travel-video-studio-skill

codex codex-skill davinci-resolve ffmpeg travel-video video-editing

Last synced: 16 days ago
JSON representation

Codex skill for route-aware DaVinci travel films from unordered GPS-less footage

Awesome Lists containing this project

README 

          
# Travel Video Studio Skill



Turn unordered travel footage into a route-aware long-form edit package for DaVinci Resolve.



This is a portable Agent Skill for Codex, Claude Code, Hermes, OpenClaw/Lobster-style workflows, and any local coding agent that can read a `SKILL.md` skill folder. It handles the messy real-world case: a drive full of phone, DJI, action-cam, and camera videos with no GPS metadata, inconsistent folders, mixed portrait/landscape clips, unclear route order, missing BGM, and a user who wants a polished travel film instead of a raw montage.



## What It Does



- Scans local or external-drive footage without modifying source media.

- Extracts and reviews representative frames so Codex can identify likely filming locations from visual evidence.

- Reconstructs a trip route from unordered clips, folder names, dates, OCR/signage evidence, and optional cloud or local recognition passes.

- Scores and tiers raw footage before first assembly, then audits that large folders are actually cut from full-source hero/main/texture bridge candidates instead of filename order or blueprint fallback samples.

- Audits 100GB-class unordered folders for unattended readiness, proving media-root intake, whole-folder recognition, source selection, first assembly, first-draft chain, and blueprint preflight are connected before another AI or editor takes over.

- Plans the first three minutes as a real opening story: viewer promise, destination proof, clean title, practical arrival, lived-in texture, and first handoff.

- Plans each chapter as a complete vlog arc: context, movement, lived-in texture, destination payoff, and aftertaste/handoff before rhythm or Resolve trust.

- Audits that each chapter story spine survives into rhythm, creator-cut, selected source usage, scene grammar, timeline variety, and transition support instead of becoming title-only or effect-masked.

- Audits shot-flow continuity so every chapter's final clip order reads as setup/movement/texture/payoff/aftertaste instead of random scenic jumps hidden by effects.

- Builds recognition reports, route reviews, route decision sheets, and delivery packages.

- Learns from multiple local reference videos as an aggregate, non-copying batch profile.

- Builds a reference-review repair plan so supplied creator/reference videos must be reviewed as full films before the Skill learns from them: full timeline strips, opening/title, chapter rhythm, transition language, ending, BGM/audio/caption behavior, and non-copying takeaways must be closed before final QA.

- Audits the v0.1.2 baseline before release so the original Parallel World full-review, cover/hero title, title typography, and private-artifact cleanup lessons cannot regress while newer V14 gates are added.

- Runs a portable Skill release audit before publishing so frontmatter, required release-gate files, Python compilation, v0.1.2 baseline preservation, and trip-generalization are checked in one command.

- Creates a synthetic benchmark fixture when no user footage is available, covering landscape, portrait, square, source-audio, BGM-only bridge, scenic-title, black-slate, SRT, TXT, and bad-caption probes.

- Audits editor integration without writing timelines: DaVinci Resolve install/scripting vs live API reachability, plus no-GUI Jianying/CapCut app readiness across system, user, and Spotlight application locations; the top-level editor audit surfaces the exact Jianying/CapCut search roots and known app bundle names used.

- Audits DaVinci Resolve writeability without writing timelines, catching states where the API is reachable but a foreground modal or hidden project-library state blocks project/timeline creation.

- Separates Jianying/CapCut handoff readiness from actual in-app TTS/export proof, requiring package-local `gui_smoke_checklist.json`, completed `guiProofPendingFields`, `proofStatus=completed_gui_proof`, proof paths with `postExportAuditJson` either already passed or matching the current audit output, `appPathMatchesStateApplication=true`, `exportFileMatchesChecklist=true`, `exportFileIsPreparedInput=false`, accepted `postExportProofIdentity`/`acceptedByCurrentRun`, GUI export readback, explicit `--export-origin gui`, and a real `--export-file` before any success claim.

- Prepares a safe Jianying/CapCut handoff package with media, SRT, TXT text-for-TTS, BGM assets, and a machine-readable `gui_smoke_checklist.json` while explicitly not claiming a direct Jianying API.

- Runs a focused Jianying/CapCut GUI TTS/export smoke that reports `readyForGuiTtsExportSmoke`, `blockedByMissingApp`, `claimsJianyingTtsOrExport`, `exportCountsAsGuiProof`, and `exportFileIsPreparedInput` without launching the app or fabricating in-app TTS/export proof.

- Adds Resolve readback identity proof for live-write and V1/V3/A3 structure smokes, so a report must prove the readback project/timeline, item counts, and source paths match the current throwaway apply instead of an older Resolve state.

- Runs one no-material editor smoke test that combines fixture generation, audience-caption clean/bad probes with `audienceCaptionBadProbeBlocked`, a procedural sine-hum BGM musicality trap with `bgmHumTrapBlocked`, DaVinci integration audit, Jianying/CapCut handoff evidence, a false GUI export-origin trap, a no-file GUI export-origin trap, a stale manifest copied-handoff trap, a fake completed GUI proof trap, and a current-audit bootstrap trap in one JSON/MD report.

- Runs a no-material editor delivery matrix that combines the editor smoke, Resolve writeability audit, Resolve live-write dry-run, and optional approved Resolve write/readback proof.

- Runs a full no-material editor drill that ties release audit, editor matrix, focused Jianying/CapCut smoke, and optional DaVinci 4K render-export proof into one report while keeping `toolchainOnlyNoRealFootage=true`.

- Runs an optional no-material DaVinci live-write smoke test that creates only a new synthetic Resolve project/timeline, then reads it back without rendering or touching real footage.

- Audits no-material DaVinci render readiness so 4K, high-frame-rate, numeric high-bitrate export defaults can be guarded dry-run and optionally applied/read back in a throwaway Resolve project without queueing or starting a render; the apply path now requires the nested V1/V3/A3 structure prerequisite to have accepted identity and `sourcePathsMatch` proof before render settings are trusted.

- Runs an explicit no-material DaVinci render-export smoke that can queue/start one short synthetic Resolve render only with `--apply`, then ffprobe the output and sample frames while reporting `qualityProfile`, `renderStarted`, `renderCompleted`, `renderVideoQuality`, output resolution/FPS/bitrate, and `claimsFinalRender=false`; use `--quality-profile delivery-4k` to prove a short 3840x2160/59.94/high-VideoQuality export path.

- Runs story-style, reference-alignment, director-intent, route-texture, stock/aerial closure, and director-polish gates inside the safe workflow so a technically valid but AI-looking draft blocks before handoff.

- Treats every `blocked*` audit status as a safe-workflow blocker, so transition/watchability gates with specific names cannot disappear from the top-level repair list.

- Plans BGM, BGM phrase cues, subtitles, city/aerial establishing shots, chapter titles, transitions, typography, visual bridge material, and restrained effect-motion candidates with final application proof.

- Builds a title typography repair plan for ghosted/stacked hero titles, route/date/internal labels, black or stale `title_cards`, title-zone subtitle collisions, missing scenic title proof, and weak cover/hero title formula.

- Runs a title-bridge structural audit inside the safe workflow so stale `title_cards`, missing scenic bridge media, mismatched Resolve V2 title clips, duplicate/route/date title text, and title-zone subtitle overlap block before final QA.

- Audits BGM selection and musicality so scenic/title/transition sections use auditioned, real named music with provider/license/section-fit evidence, phrase coverage, dynamics, and multi-band energy instead of hums, tones, silence, procedural pads, or placeholders.

- Converts transition decisions into Resolve-ready recipes, non-copying reference-calibrated A/B/C candidate ladders, unattended-safe default transition selections with boundary-specific reasons and proof plans, and execution-blueprint transition payloads that carry the selected candidate into Resolve markers/clip metadata; audits the whole transition motif/cadence chain, plans 2-5 shot bridge sequences, materializes those beats, proves those bridge inserts survive into the final candidate, and proves final BGM-hit/title-safe/motion-proven/pair-continuous/execution-ready transition polish metadata plus Resolve marker/readback payloads and latest candidate-chain lineage survive into the active/final Resolve blueprint.

- Runs rhythm recut candidates from the latest BGM phrase blueprint and audits final application so long-shot repairs preserve transition, effect, music-cue metadata, and actual main-segment/cutaway survival in the final candidate.

- Converts blocked reference/director/QA style gaps into concrete repair rows with owner scripts, required artifacts, and acceptance evidence.

- Audits transition execution readiness so final transitions have package-local Resolve recipes, BGM hits, title-safe windows, pair readiness, and handle evidence before Resolve apply.

- Requires the ordered transition watch reel and transition audition packets to be explicitly muted in safe workflow, final QA, repair commands, and downstream review audits, so transition review cannot leak source-camera/user audio or falsely claim BGM-only readiness.

- Audits effect-motion application, transition-polish application, Resolve transition materialization, and Resolve transition apply paths so active/final blueprints cannot drop restrained title/rotation/whip/speed-ramp metadata, BGM-hit/title-safe transition metadata, marker/readback payloads, or visible-effect API/manual/bridge handoff proof after candidate generation.

- Audits bridge-sequence application so planned route/title/day-change bridge beats cannot be dropped from the final candidate blueprint.

- Audits final blueprint lineage, effect-motion application, film-level transition cadence, shot-to-shot transition microstructure, whole-film transition effect palette, motif coherence, pair-level visual match, transition choreography, transition cutpoint timing, transition action anchors, transition sensory continuity, transition bridge visual evidence, transition preview quality, transition audition quality, transition watch reel plus sequence-level review, transition storyboard proof, transition breathing-room, and transition viewer orientation so the active Resolve blueprint cannot silently fall back to an old or partial candidate, bare-cut montage, repeated-template chain, effect-spam transition rhythm, one dominant motif, arbitrary adjacent-pair cuts, unlanded BGM hits, unsafe titles, missing handles, missing leave/hit/landing cutpoint timing, missing readable outgoing/bridge-or-match/landing action anchors, missing visual/BGM/caption/route/landing continuity, missing route/title/caption/BGM/bridge orientation cues, dropped effect-motion rows, weak adjacent-pair joins, missing outgoing/bridge-or-motion/landing choreography, prose-only bridge beats, bridge clips without local video/frame evidence, blank/duplicate preview frames, unwatchable transition flow, missing ordered muted transition review reel, repeated template motion, stacked high-intensity effects, or unpreviewed day/title transitions after BGM phrase, effect motion, rhythm recut, bridge, transition execution, and transition polish stages.

- Audits final source usage so final raw clips must come from footage-select hero/main/texture choices instead of unmatched, repair, reject, or utility-dominant source material.

- Audits creator-cut application so rejected, weak, utility, or unmatched clips cannot remain active in the final candidate blueprint.

- Audits reference scene grammar so opening, chapters, transitions, and ending use context/movement/texture/payoff/aftertaste structure instead of flat montage.

- Audits scene-flow arcs so chapters become setup, movement, lived-in texture, payoff, and aftertaste/handoff sequences instead of landmark stacks or effect-hidden jumps.

- Audits final-cut smoothness so the final candidate's adjacent shots have bridge, match, breathing, stable landing, and rare motion-effect proof instead of rough hard joins.

- Audits narrative adjacency so every adjacent visual shot has a viewer-readable route, place, story-function, bridge, BGM, title, or transition reason instead of random clip stacking.

- Audits transition viewer orientation so important route, day, place, title, and ending transitions tell viewers where they are, why the film moved, and what the landing shot means after the cut.

- Audits transition scene settlement so important route, day, title, and ending transitions land into real local scene footage before the next idea instead of becoming a title-only/card-only jump.

- Audits transition motion accents so whip, rotation, push, zoom, slide, and speed-ramp effects stay rare, motivated, title-safe, BGM-hit aligned, and readable instead of random template motion.

- Builds a transition motion-accent repair plan when those visible effects fail, turning random/overused rotation, whip, speed-ramp, weak BGM hit, title-risk, or unstable-landing failures into owner-script repair rows instead of vague "make transitions better" notes.

- Summarizes motion-accent repair rows in the safe workflow report, so `ready_with_transition_motion_accent_repair_plan` blocks handoff instead of being buried as a side artifact.

- Builds a transition-flow repair plan when adjacent-shot flow still fails, aggregating cadence, microstructure, scene-arc, visual-match, source-coverage, cutpoint, action-anchor, sensory-continuity, preview/audition, breathing-room, final-smoothness, narrative, orientation, and scene-settlement blockers into executable owner-script rows.

- Runs rendered transition proof inside the safe workflow before transition reference-readiness, so missing final-MP4 transition-window evidence is routed to the owner audit instead of surfacing only as a downstream one-shot blocker.

- Audits transition reference-readiness so all transition craft, watch-reel, rendered-proof, Resolve-apply, bridge, reference-fit, and repair-closure gates pass as one chain before V14/final QA claims.

- Audits transition sequence satisfaction so the ordered transition experience is muted, restrained, bridged, landed, reference-like, and free of random rotation/whip/template effects before first-draft, final QA, V14, or handoff claims.

- Audits transition effect recipes so visible rotation, whip, push, zoom, speed-ramp, dissolve, and title-breath effects have restrained Resolve keyframes, easing, parameter envelopes, BGM-only audio, BGM-hit timing, and stable landing holds.

- Audits rendered transition windows from the final MP4 so planned effects cannot hide black flashes, white flashes, raw pillarboxed vertical footage, or unstable transition landings in the actual export.

- Builds an unattended repair queue when gates block, ordering P0/P1 fixes by phase with owner script, command, required artifact, acceptance evidence, and forbidden workaround.

- Audits first-draft satisfaction so source intake, opening/title, BGM/captions, story/rhythm, transition readiness, reference fit, route texture, and watchdown must all have zero open rows before final QA, V14, or handoff claims.

- Audits whole-film satisfaction so the final MP4 is judged as one viewer experience, aggregating opening, chapters, rhythm, BGM, captions, transitions, reference fit, director intent, route texture, watchdown, viewer friction, first-draft satisfaction, and unattended repair closure before final QA, V14, or handoff claims.

- Audits one-shot autonomy so a raw unordered folder must prove intake, source selection, story, rhythm, BGM source quality, final-MP4 BGM mix, captions, titles, ordered muted transition watch reel/review, transition-reference readiness, rendered transition-window proof, reference-profile application, reference transition language, reference scene grammar, timeline variety, director intent, route texture, current-output editorial watchdown, repair closure, whole-film satisfaction, unattended first draft, and preflight are connected before claiming another AI can produce a V14-level first run without extra diagnosis.

- Audits reference review closure, reference profile application, and reference transition profile so multi-video learning is first based on full-film review evidence, then reaches opening, chapter, rhythm, creator-cut, transition, caption, audio, scene-grammar, and current-film bridge/breath/match/motion-balance gates instead of remaining unused analysis.

- Audits timeline variety so the final film has movement, lived-in texture, destination payoff, and ending aftertaste instead of hiding weak shot choice behind transitions.

- Audits the unattended first-draft chain before Resolve apply, connecting raw intake, first-assembly source order, story, BGM, BGM musicality, final rendered BGM mix, captions, titles, rhythm, rhythm-recut application, final-source usage, creator-cut application, reference-profile application, reference-transition-profile, chapter-story-spine, shot-flow-continuity, scene-flow-arc, final-cut-smoothness, pacing-watchability, narrative-adjacency, transition-viewer-orientation, transition-scene-settlement, transition-motion-accent, transition-effect-recipe, timeline-variety, effect-motion application, transition reference candidates, transition reference selection, transition action-anchor proof, transition sensory-continuity proof, transition-polish application, Resolve transition materialization/apply paths, bridge-sequence application, final-blueprint lineage, transition cadence, transition microstructure, transition scene-arc/effect-palette/visual-match/preview-quality/audition-quality/storyboard/breathing-room, execution readiness, scene grammar, repair closure, unattended repair queue, and blueprint preflight into one gate.

- Generates DaVinci Resolve timeline blueprints and safety contracts before writing to Resolve.

- Audits final delivery quality: clean titles, no portrait regressions, BGM-only no-voiceover mode, BGM musicality, final-MP4 BGM mix, dense title-safe subtitles, full-source first-assembly order, final-source usage, creator-cut application, rhythm-recut application, reference-review closure, reference-profile application, reference-transition-profile, chapter-story-spine, shot-flow-continuity, scene-flow-arc, final-cut-smoothness, pacing-watchability, narrative-adjacency, transition-viewer-orientation, transition-scene-settlement, transition-motion-accent, transition-effect-recipe, timeline-variety, effect-motion application, transition reference candidates, transition reference selection, transition-polish application, Resolve transition materialization/apply paths, bridge-sequence application, transition bridge visual evidence, final-blueprint lineage, transition cadence, transition microstructure, transition cutpoint timing, transition action anchors, transition sensory continuity, transition effect palette, transition motif coherence, transition visual match, transition choreography, transition preview quality, transition audition quality, transition watch reel and review contract, transition storyboard, transition breathing-room, transition reference-readiness, transition-sequence-satisfaction, transition pair-continuity/execution readiness, reference scene grammar, route texture, final viewer friction aggregation, first-draft satisfaction aggregation, one-shot autonomy aggregation, export quality, and V14 baseline maturity.



The default finishing path is DaVinci Resolve through the Resolve Python API. GUI automation is treated as a fallback, not the normal route.



## Why This Exists



The V14 baseline encoded here came from repeated failure fixes:



- No ghosted or duplicated opening titles.

- No accidental portrait clips in a 16:9 master.

- No voice or camera audio leaking under scenic/title sections when BGM-only is required.

- No empty BGM plan.

- No sparse subtitles.

- No black-card chapter jumps.

- No "AI slideshow" pacing where clips are simply stacked together.

- No stale Tokyo/Japan defaults leaking into future trips.

- No final claim without machine-readable QA.



The point is not to preserve one finished film. The point is to make the first serious draft from a new folder behave like the corrected V14 version.



## Requirements



- Codex Desktop/CLI, Claude Code, Hermes, OpenClaw, or another agent that can read a local Agent Skill folder.

- macOS recommended for DaVinci Resolve integration.

- Python 3.10 or newer.

- `ffmpeg` and `ffprobe` on PATH.

- DaVinci Resolve or DaVinci Resolve Studio for final timeline creation and render handoff.

- Optional: Tesseract OCR for local sign/station OCR.

- Optional: Ollama vision model only when explicitly requested. The normal route is Codex visual inspection plus approved cloud/API calls only when needed.



## Install



Use the cross-agent installer from a source checkout:



```bash

python3 scripts/install_for_agent.py --agent codex

python3 scripts/install_for_agent.py --agent claude-code

python3 scripts/install_for_agent.py --agent hermes

python3 scripts/install_for_agent.py --agent openclaw

python3 scripts/install_for_agent.py --agent lobster

```



Install into every known user-level target:



```bash

python3 scripts/install_for_agent.py --agent all

```



Install from the latest release asset:



```bash

mkdir -p ~/.codex/skills/travel-video-studio

curl -L -o /tmp/travel-video-studio-skill-v0.1.173.zip \

  https://github.com/junwen853/travel-video-studio-skill/releases/download/v0.1.173/travel-video-studio-skill-v0.1.173.zip

unzip -oq /tmp/travel-video-studio-skill-v0.1.173.zip -d ~/.codex/skills/travel-video-studio

```



Or install from source:



```bash

git clone https://github.com/junwen853/travel-video-studio-skill.git ~/.codex/skills/travel-video-studio

```



If you use a custom Codex home:



```bash

export CODEX_HOME=/path/to/.codex

mkdir -p "$CODEX_HOME/skills"

git clone https://github.com/junwen853/travel-video-studio-skill.git "$CODEX_HOME/skills/travel-video-studio"

```



Restart Codex or open a new Codex thread if the skill list does not refresh immediately.



For non-Codex runtimes, install the same folder into the runtime's local skill directory. Default targets are documented in `references/agent-runtime-compatibility.md`.



## Quick Start



Set your VideoClaw Studio app or project root if you have one:



```bash

export VIDEO_CLAW_STUDIO_DIR="$HOME/Pictures/Video-make/video-claw-studio"

```



Then ask Codex:



```text

Use $travel-video-studio to inspect /Volumes/TravelDrive/2026-Japan.

Do not modify the source drive.

Identify where each video was likely filmed, reconstruct the route,

build a 20-minute DaVinci Resolve delivery package, use BGM-only,

export TXT/SRT narration, and run the full V14 QA gates before saying it is deliverable.

```



For a pure project-state check:



```bash

python3 ~/.codex/skills/travel-video-studio/scripts/check_project_state.py \

  --project-dir "$VIDEO_CLAW_STUDIO_DIR"

```



For a safe local workflow:



```bash

python3 ~/.codex/skills/travel-video-studio/scripts/run_delivery_workflow.py \

  --project-dir "$VIDEO_CLAW_STUDIO_DIR" \

  --target-duration-minutes 20

```



If you do not have footage yet, run a no-material self-test:



```bash

python3 ~/.codex/skills/travel-video-studio/scripts/run_no_material_full_editor_drill.py \

  --skill-dir ~/.codex/skills/travel-video-studio \

  --output-dir /tmp/travel-video-studio-full-editor-drill \

  --expected-version v0.1.173 \

  --overwrite \

  --json

python3 ~/.codex/skills/travel-video-studio/scripts/run_no_material_editor_smoke.py \

  --output-dir /tmp/travel-video-studio-editor-smoke \

  --overwrite \

  --json

python3 ~/.codex/skills/travel-video-studio/scripts/run_jianying_gui_tts_export_smoke.py \

  --output-dir /tmp/travel-video-studio-jianying-gui-smoke \

  --overwrite \

  --json

python3 ~/.codex/skills/travel-video-studio/scripts/audit_resolve_writeability_state.py \

  --output-dir /tmp/travel-video-studio-resolve-writeability \

  --json

python3 ~/.codex/skills/travel-video-studio/scripts/run_resolve_live_write_smoke.py \

  --output-dir /tmp/travel-video-studio-resolve-live-smoke \

  --overwrite \

  --json

python3 ~/.codex/skills/travel-video-studio/scripts/run_resolve_delivery_structure_smoke.py \

  --output-dir /tmp/travel-video-studio-resolve-structure-smoke \

  --overwrite \

  --json

python3 ~/.codex/skills/travel-video-studio/scripts/run_resolve_render_readiness_smoke.py \

  --output-dir /tmp/travel-video-studio-resolve-render-readiness \

  --overwrite \

  --json

```



The Resolve live-write and delivery-structure smokes default to dry-run. Add `--apply` only when you explicitly want a throwaway Resolve project/timeline created and read back. The delivery-structure smoke proves V1/V3/A3 placement only; it is not real BGM musicality or final subtitle visibility proof. The render-readiness smoke proves only the render-plan settings contract by default; add `--apply-resolve-settings` only when you want a throwaway Resolve project/timeline created so Resolve `SetRenderSettings`/`GetRenderSettings` readback is proven without render queue/start. When applied, render-readiness must expose `resolveStructurePrerequisiteSourcePathsMatch=true` before trusting the render-settings readback.



To prove the actual Resolve render/export path without user footage, run this separately because it intentionally queues and starts one short synthetic render:



```bash

python3 ~/.codex/skills/travel-video-studio/scripts/run_resolve_render_export_smoke.py \

  --output-dir /tmp/travel-video-studio-resolve-render-export \

  --overwrite \

  --apply \

  --json

```



This smoke must report `renderStarted=true`, `renderCompleted=true`, a ffprobe-readable output with audio, nonblank sample frames, and `claimsFinalRender=false`. It does not prove route, subtitle visibility, BGM quality, or viewer-quality delivery.



To prove the high-quality Resolve export path, run the same smoke with the delivery profile:



```bash

python3 ~/.codex/skills/travel-video-studio/scripts/run_no_material_full_editor_drill.py \

  --skill-dir ~/.codex/skills/travel-video-studio \

  --output-dir /tmp/travel-video-studio-full-editor-drill-4k \

  --expected-version v0.1.173 \

  --overwrite \

  --apply-resolve-render-export \

  --quality-profile delivery-4k \

  --json

python3 ~/.codex/skills/travel-video-studio/scripts/run_resolve_render_export_smoke.py \

  --output-dir /tmp/travel-video-studio-resolve-render-export-4k \

  --overwrite \

  --apply \

  --quality-profile delivery-4k \

  --json

```



This profile must report `qualityProfile=delivery-4k`, `renderVideoQuality>=80000`, output width/height at least 3840x2160, output FPS at least 59, and `claimsFinalRender=false`. The full drill must also report `toolchainOnlyNoRealFootage=true` and must not claim Jianying/CapCut TTS/export without real GUI proof.



Do not run Resolve `--apply` smoke tests in parallel. Resolve scripting is stateful; the smoke reports include `readbackIdentityProof` with `sourcePathsMatch` to block stale or cross-read timeline evidence.



For debugging individual sub-steps:



```bash

python3 ~/.codex/skills/travel-video-studio/scripts/create_skill_benchmark_fixture.py \

  --output-dir /tmp/travel-video-studio-benchmark \

  --overwrite \

  --json

python3 ~/.codex/skills/travel-video-studio/scripts/audit_editor_integration_contract.py \

  --output-dir /tmp/travel-video-studio-benchmark/editor_integration \

  --json

python3 ~/.codex/skills/travel-video-studio/scripts/prepare_jianying_handoff_package.py \

  --source-dir /tmp/travel-video-studio-benchmark/source_media_read_only \

  --subtitle-file /tmp/travel-video-studio-benchmark/viewer_subtitles.srt \

  --text-file /tmp/travel-video-studio-benchmark/text_only_narration_export.txt \

  --output-dir /tmp/travel-video-studio-benchmark/jianying_handoff \

  --overwrite \

  --json

python3 ~/.codex/skills/travel-video-studio/scripts/audit_jianying_handoff_contract.py \

  --handoff-dir /tmp/travel-video-studio-benchmark/jianying_handoff \

  --json

python3 ~/.codex/skills/travel-video-studio/scripts/audit_jianying_tts_export_readiness.py \

  --handoff-dir /tmp/travel-video-studio-benchmark/jianying_handoff \

  --json

python3 ~/.codex/skills/travel-video-studio/scripts/run_jianying_gui_tts_export_smoke.py \

  --handoff-dir /tmp/travel-video-studio-benchmark/jianying_handoff \

  --output-dir /tmp/travel-video-studio-benchmark/jianying_gui_smoke \

  --overwrite \

  --json

```



The handoff package writes `gui_smoke_checklist.json` and `Jianying_GUI_SMOKE_CHECKLIST.md`; use those proof fields when a GUI operator imports media, generates in-app TTS, and exports a test render. The no-material smoke, matrix, and focused Jianying smoke surface `readyForGuiTtsExportSmoke`, `blockedByMissingApp`, `claimsJianyingTtsOrExport`, `audienceCaptionBadProbeBlocked`, `bgmHumTrapBlocked`, `bgmHumTrapRejectedAsHumTone`, `guiProofPendingFields`, `proofStatus=completed_gui_proof`, proof-path checks including `postExportAuditJson`, `appPathMatchesStateApplication`, `postExportProofIdentity`, `currentAuditJsonWillBeWritten`, `currentAuditJsonMatchesChecklist`, `acceptedByCurrentRun`, `exportFileMatchesChecklist`, `exportFileIsPreparedInput`, `jianyingCurrentAuditBootstrapTrapBlocked`, `jianyingCurrentAuditBootstrapAcceptedByCurrentRun`, package-local checklist binding, a false GUI export-origin trap, a no-file GUI export-origin trap, a stale manifest copied-handoff trap, a fake completed GUI proof trap, and a current-audit bootstrap trap; pending fields must be empty, proof paths must exist or `postExportAuditJson` must match the current `--output-dir/jianying_tts_export_readiness_audit.json`, the app path must match a recognized state audit app, the manifest checklist path must match the current handoff folder, clean viewer-facing subtitles/TXT must pass through `audit_audience_caption_contract.py`, the bad-caption fixture must block, the procedural sine-hum BGM fixture must block through `audit_bgm_musicality_contract.py`, and the supplied export must match the checklist `exportFile` while not being source/handoff input media before a Jianying/CapCut TTS/export claim is valid. App detection checks common CapCut/Jianying/剪映 bundle names in system and user Applications folders, then uses Spotlight as a fallback. After a real Jianying/CapCut GUI export, set checklist `postExportAuditJson` to the planned output file and rerun the focused smoke or readiness audit with `--export-file  --export-origin gui --output-dir `; the first valid run may pass through `acceptedByCurrentRun` and then writes the durable audit JSON for later reuse. A synthetic fixture, Resolve export, arbitrary MP4, copied handoff with stale manifest paths, fake completed GUI proof, editor-facing captions, hum-like placeholder BGM, source/handoff input media, or `--export-origin gui` without an export file must not be counted as Jianying TTS/export proof.



For an optional local reference film:



```bash

python3 ~/.codex/skills/travel-video-studio/scripts/analyze_reference_video.py \

  --reference /path/to/reference-travel-film.mp4 \

  --output-dir /path/to/delivery-package/reference

```



## Typical Output



A delivery package usually contains:



- `footage_recognition_route_report.md`

- `confirmed_route_timeline.json`

- `delivery_plan.json`

- `subtitles.srt`

- `caption_story_plan/text_only_narration_export.txt`

- `opening_story_plan/opening_story_plan.md`

- `chapter_arc_plan/chapter_arc_plan.md`

- `chapter_story_spine_contract_audit.md`

- `reference/reference_batch_profile.md`

- `reference_review_repair_plan/reference_review_repair_plan.md`

- `reference_profile_application_contract_audit.md`

- `bgm_sourcing/bgm_sourcing_brief.md`

- `transition_bridge_plan/transition_bridge_plan.md`

- `transition_execution_plan/transition_execution_plan.md`

- `transition_reference_candidates/transition_reference_candidates.md`

- `transition_reference_selection/transition_reference_selection.md`

- `transition_execution_blueprint/transition_execution_blueprint_report.md`

- `transition_motif_plan/transition_motif_plan.md`

- `bridge_sequence_plan/bridge_sequence_plan.md`

- `bridge_sequence_blueprint/bridge_sequence_blueprint_report.md`

- `bridge_sequence_application_contract_audit.md`

- `transition_bridge_visual_evidence_contract_audit.md`

- `effect_motion_application_contract_audit.md`

- `transition_polish_application_contract_audit.md`

- `final_blueprint_lineage_contract_audit.md`

- `transition_cadence_contract_audit.md`

- `transition_microstructure_contract_audit.md`

- `transition_scene_arc_contract_audit.md`

- `transition_effect_palette_contract_audit.md`

- `transition_motif_coherence_contract_audit.md`

- `transition_visual_match_contract_audit.md`

- `transition_source_coverage_contract_audit.md`

- `transition_motion_direction_contract_audit.md`

- `transition_effect_recipe_contract_audit.md`

- `rendered_transition_proof_contract_audit.md`

- `transition_cutpoint_contract_audit.md`

- `transition_action_anchor_contract_audit.md`

- `transition_sensory_continuity_contract_audit.md`

- `transition_preview_packet/transition_preview_packet.md`

- `transition_preview_quality_contract_audit.md`

- `transition_audition_packet/transition_audition_packet.md`

- `transition_audition_quality_contract_audit.md`

- `transition_audition_visual_proof_contract_audit.md`

- `transition_audition_role_integrity_contract_audit.md`

- `transition_storyboard_contract_audit.md`

- `transition_breathing_room_contract_audit.md`

- `scene_flow_arc_contract_audit.md`

- `final_cut_smoothness_contract_audit.md`

- `transition_continuity_rehearsal_contract_audit.md`

- `pacing_watchability_contract_audit.md`

- `narrative_adjacency_contract_audit.md`

- `transition_viewer_orientation_contract_audit.md`

- `transition_scene_settlement_contract_audit.md`

- `transition_motion_accent_contract_audit.md`

- `transition_sequence_satisfaction_contract_audit.md`

- `whole_film_satisfaction_contract_audit.md`

- `one_shot_autonomy_contract_audit.md`

- `reference_transition_profile_contract_audit.md`

- `final_source_usage_contract_audit.md`

- `reference_style_repair_plan/reference_style_repair_plan.md`

- `effect_motion_blueprint/effect_motion_blueprint_report.md`

- `bgm_phrase_blueprint/bgm_phrase_blueprint_report.md`

- `bgm_musicality_contract_audit.md`

- `final_bgm_mix_contract_audit.md`

- `rhythm_recut_blueprint/rhythm_recut_blueprint_report.md`

- `rhythm_recut_application_contract_audit.md`

- `transition_polish_blueprint/transition_polish_blueprint_report.md`

- `transition_quality_contract_audit.md`

- `shot_transition_boundary_contract_audit.md`

- `transition_motivation_contract_audit.md`

- `transition_pair_continuity_contract_audit.md`

- `transition_execution_readiness_contract_audit.md`

- `creator_cut_application_contract_audit.md`

- `reference_scene_grammar_contract_audit.md`

- `shot_flow_continuity_contract_audit.md`

- `audience_caption_contract_audit.md`

- `unattended_first_draft_contract_audit.md`

- `title_typography_plan/title_typography_plan.md`

- `title_typography_repair_plan/title_typography_repair_plan.md`

- `cover_title_contract_audit.md`

- `title_visual_proof_contract_audit.md`

- `title_bridge_contract_audit.md`

- `raw_intake_completeness_audit.md`

- `source_selection_repair_plan/source_selection_repair_plan.md`

- `source_selection_coverage_contract_audit.md`

- `first_assembly_source_order_contract_audit.md`

- `large_source_unattended_readiness_contract_audit.md`

- `unattended_repair_queue/unattended_repair_queue.md`

- `reference_repair_closure_audit.md`

- `visual_establishing_plan/visual_establishing_plan.md`

- `resolve_timeline_blueprint.json`

- `resolve_blueprint_preflight.md`

- `render_plan.json`

- final QA reports, including `final_qa_suite_report.json`, `bgm_musicality_contract_audit.json`, `final_bgm_mix_contract_audit.json`, `title_visual_proof_contract_audit.json`, `title_bridge_contract_audit.json`, `title_typography_repair_plan/title_typography_repair_plan.json`, `reference_review_repair_plan/reference_review_repair_plan.json`, `transition_pair_continuity_contract_audit.json`, `transition_execution_readiness_contract_audit.json`, `transition_reference_candidates/transition_reference_candidates.json`, `transition_reference_selection/transition_reference_selection.json`, `transition_source_coverage_contract_audit.json`, `transition_polish_application_contract_audit.json`, `effect_motion_application_contract_audit.json`, `bridge_sequence_application_contract_audit.json`, `transition_bridge_visual_evidence_contract_audit.json`, `source_selection_coverage_contract_audit.json`, `first_assembly_source_order_contract_audit.json`, `large_source_unattended_readiness_contract_audit.json`, `unattended_repair_queue/unattended_repair_queue.json`, `final_blueprint_lineage_contract_audit.json`, `transition_cadence_contract_audit.json`, `transition_microstructure_contract_audit.json`, `transition_scene_arc_contract_audit.json`, `transition_effect_palette_contract_audit.json`, `transition_motif_coherence_contract_audit.json`, `transition_visual_match_contract_audit.json`, `transition_motion_direction_contract_audit.json`, `transition_motion_accent_contract_audit.json`, `transition_motion_accent_repair_plan/transition_motion_accent_repair_plan.json`, `transition_flow_repair_plan/transition_flow_repair_plan.json`, `transition_reference_readiness_contract_audit.json`, `transition_sequence_satisfaction_contract_audit.json`, `whole_film_satisfaction_contract_audit.json`, `one_shot_autonomy_contract_audit.json`, `transition_effect_recipe_contract_audit.json`, `rendered_transition_proof_contract_audit.json`, `transition_cutpoint_contract_audit.json`, `transition_action_anchor_contract_audit.json`, `transition_sensory_continuity_contract_audit.json`, `transition_preview_packet/transition_preview_packet.json`, `transition_preview_quality_contract_audit.json`, `transition_audition_packet/transition_audition_packet.json`, `transition_audition_quality_contract_audit.json`, `transition_watch_reel/transition_watch_reel.json`, `transition_watch_reel_review_contract_audit.json`, `transition_audition_visual_proof_contract_audit.json`, `transition_audition_role_integrity_contract_audit.json`, `transition_storyboard_contract_audit.json`, `transition_breathing_room_contract_audit.json`, `scene_flow_arc_contract_audit.json`, `final_cut_smoothness_contract_audit.json`, `transition_continuity_rehearsal_contract_audit.json`, `pacing_watchability_contract_audit.json`, `narrative_adjacency_contract_audit.json`, `transition_viewer_orientation_contract_audit.json`, `transition_scene_settlement_contract_audit.json`, `reference_transition_profile_contract_audit.json`, `chapter_story_spine_contract_audit.json`, `shot_flow_continuity_contract_audit.json`, `final_source_usage_contract_audit.json`, `creator_cut_application_contract_audit.json`, `rhythm_recut_application_contract_audit.json`, `reference_scene_grammar_contract_audit.json`, `reference_profile_application_contract_audit.json`, `first_draft_satisfaction_contract_audit.json`, and `v14_baseline_contract_audit.json`



## DaVinci Resolve Path



The skill prefers DaVinci Resolve API control:



1. Inspect Resolve availability with `check_resolve_api.py`.

2. Inspect Resolve writeability with `audit_resolve_writeability_state.py`; if the API is reachable but the project database is not exposed, dismiss foreground Resolve modals such as Software Update and rerun the audit.

3. Build or refresh the package blueprint.

4. Run `audit_resolve_blueprint.py` before any apply.

5. Prepare `prepare_resolve_apply_contract.py`.

6. Apply only after explicit approval.

7. Read back the actual Resolve timeline.

8. Render at high quality and run final QA.



This is intentionally stricter than simply making an FFMPEG montage. The skill is designed for repeatable, auditable finishing.



## Quality Gates



A package is not considered deliverable until the relevant audits pass:



- visual/audio style audit

- BGM/audio contract

- client delivery rules

- location truth contract

- long-form delivery audit

- story style contract

- reference style alignment

- director intent contract

- route texture contract

- title bridge contract

- stock/aerial closure

- director polish contract

- feedback regression audit

- package integrity audit

- raw intake completeness audit

- first assembly source-order contract

- large source unattended-readiness contract

- transition pair-continuity contract

- transition execution-readiness contract

- transition reference candidates

- transition reference selection

- transition-polish application contract

- effect-motion application contract

- Resolve transition materialization contract

- Resolve transition apply contract

- bridge-sequence application contract

- transition bridge visual evidence contract

- final blueprint lineage contract

- transition cadence contract

- transition microstructure contract

- transition effect palette contract

- transition motif coherence contract

- transition visual match contract

- transition choreography plan/contract

- transition effect recipe contract

- rendered transition proof contract

- transition cutpoint timing contract

- transition action-anchor contract

- transition sensory-continuity contract

- transition preview quality contract

- transition audition quality contract and ordered transition watch reel review with motion-execution coverage

- transition reference-readiness contract aggregating all transition craft gates into one no-open-row handoff gate

- transition sequence satisfaction contract aggregating watch-reel, bridge, breath, landing, motion-restraint, Resolve, rendered-proof, and reference-fit issues into one viewer-sequence handoff gate

- final viewer friction contract aggregating title, BGM, caption, source, story, transition, reference-fit, route-texture, and watchdown blockers into owner-script repair rows

- first draft satisfaction contract aggregating source, opening, BGM, captions, story, rhythm, transitions, reference fit, route texture, and watchdown into a no-open-row first-draft handoff gate

- whole film satisfaction contract aggregating the current final MP4, opening, chapter flow, rhythm, BGM/captions, transitions, reference fit, director/route texture, watchdown, viewer friction, first draft satisfaction, and unattended repair closure into one viewer-experience gate

- one-shot autonomy contract aggregating raw-folder intake, source selection, story, rhythm, BGM, captions, titles, ordered muted transition watch reel/review, transition-reference readiness, rendered transition-window proof, reference-profile application, reference transition profile, reference scene grammar, timeline variety, director intent, route texture, current-output editorial watchdown, transition satisfaction, repair closure, whole-film satisfaction, unattended first-draft closure, and Resolve preflight into a no-extra-diagnosis first-run gate

- title visual proof contract

- transition storyboard contract

- creator-cut application contract

- reference scene grammar contract

- shot flow continuity contract

- scene flow arc contract

- final cut smoothness contract

- narrative adjacency contract

- unattended repair queue

- reference profile application contract

- skill maturity contract

- V14 baseline contract

- final QA suite



## Safety Rules



- Source media is read-only.

- Cloud recognition, downloads, route file writes, Resolve writes, renders, and TTS generation are approval-gated.

- Exact per-video location is never claimed from visuals alone. GPS-grade claims require GPS, user confirmation, or verified per-clip evidence.

- BGM/stock/font rows must keep source URL and license evidence for future-safe delivery.



## Repository Layout



- `SKILL.md`: Codex skill entrypoint and workflow rules.

- `references/`: editing, DaVinci, BGM, subtitles, route, and output contracts.

- `scripts/`: executable helpers and audit gates.

- `examples/`: public summaries and release notes, without private project paths.



## Validate The Skill



```bash

python3 ~/.codex/skills/travel-video-studio/scripts/run_skill_release_audit.py \

  --skill-dir ~/.codex/skills/travel-video-studio \

  --expected-version v0.1.173 \

  --json

python3 ~/.codex/skills/travel-video-studio/scripts/run_no_material_full_editor_drill.py \

  --skill-dir ~/.codex/skills/travel-video-studio \

  --output-dir /tmp/travel-video-studio-full-editor-drill \

  --expected-version v0.1.173 \

  --overwrite \

  --json

python3 ~/.codex/skills/travel-video-studio/scripts/run_editor_delivery_matrix.py \

  --output-dir /tmp/travel-video-studio-editor-matrix \

  --overwrite \

  --json

python3 ~/.codex/skills/travel-video-studio/scripts/run_no_material_editor_smoke.py \

  --output-dir /tmp/travel-video-studio-editor-smoke \

  --overwrite \

  --json

python3 ~/.codex/skills/travel-video-studio/scripts/audit_resolve_writeability_state.py \

  --output-dir /tmp/travel-video-studio-resolve-writeability \

  --json

python3 ~/.codex/skills/travel-video-studio/scripts/audit_jianying_capcut_state.py \

  --output-dir /tmp/travel-video-studio-jianying-state \

  --json

python3 ~/.codex/skills/travel-video-studio/scripts/run_resolve_live_write_smoke.py \

  --output-dir /tmp/travel-video-studio-resolve-live-smoke \

  --overwrite \

  --json

python3 ~/.codex/skills/travel-video-studio/scripts/run_resolve_delivery_structure_smoke.py \

  --output-dir /tmp/travel-video-studio-resolve-structure-smoke \

  --overwrite \

  --json

python3 ~/.codex/skills/travel-video-studio/scripts/run_resolve_render_readiness_smoke.py \

  --output-dir /tmp/travel-video-studio-resolve-render-readiness \

  --overwrite \

  --json

python3 ~/.codex/skills/travel-video-studio/scripts/create_skill_benchmark_fixture.py \

  --output-dir /tmp/travel-video-studio-benchmark \

  --overwrite \

  --json

python3 ~/.codex/skills/travel-video-studio/scripts/audit_editor_integration_contract.py \

  --output-dir /tmp/travel-video-studio-benchmark/editor_integration \

  --json

python3 ~/.codex/skills/travel-video-studio/scripts/audit_jianying_capcut_state.py \

  --output-dir /tmp/travel-video-studio-benchmark/jianying_state \

  --json

python3 ~/.codex/skills/travel-video-studio/scripts/prepare_jianying_handoff_package.py \

  --source-dir /tmp/travel-video-studio-benchmark/source_media_read_only \

  --subtitle-file /tmp/travel-video-studio-benchmark/viewer_subtitles.srt \

  --text-file /tmp/travel-video-studio-benchmark/text_only_narration_export.txt \

  --output-dir /tmp/travel-video-studio-benchmark/jianying_handoff \

  --overwrite \

  --json

python3 ~/.codex/skills/travel-video-studio/scripts/audit_jianying_handoff_contract.py \

  --handoff-dir /tmp/travel-video-studio-benchmark/jianying_handoff \

  --json

python3 ~/.codex/skills/travel-video-studio/scripts/audit_jianying_tts_export_readiness.py \

  --handoff-dir /tmp/travel-video-studio-benchmark/jianying_handoff \

  --json

python3 -m py_compile ~/.codex/skills/travel-video-studio/scripts/*.py

python3 ~/.codex/skills/travel-video-studio/scripts/audit_large_source_unattended_readiness_contract.py \

  --package-dir /path/to/delivery-package \

  --min-free-gb 40 \

  --working-set-ratio 0.35 \

  --json

python3 ~/.codex/skills/travel-video-studio/scripts/audit_first_draft_satisfaction_contract.py \

  --package-dir /path/to/delivery-package \

  --json

python3 ~/.codex/skills/travel-video-studio/scripts/prepare_unattended_repair_queue.py \

  --package-dir /path/to/delivery-package \

  --json

python3 ~/.codex/skills/travel-video-studio/scripts/audit_whole_film_satisfaction_contract.py \

  --package-dir /path/to/delivery-package \

  --json

python3 ~/.codex/skills/travel-video-studio/scripts/audit_one_shot_autonomy_contract.py \

  --package-dir /path/to/delivery-package \

  --json

python3 ~/.codex/skills/travel-video-studio/scripts/audit_v012_baseline_regression.py \

  --skill-dir ~/.codex/skills/travel-video-studio \

  --json

python3 ~/.codex/skills/travel-video-studio/scripts/audit_v14_baseline_contract.py \

  --package-dir /path/to/delivery-package \

  --skill-dir ~/.codex/skills/travel-video-studio

```



For a full final package:



```bash

python3 ~/.codex/skills/travel-video-studio/scripts/prepare_editorial_watchdown_repair_plan.py \

  --package-dir /path/to/delivery-package \

  --final-output /path/to/final.mp4 \

  --json

python3 ~/.codex/skills/travel-video-studio/scripts/run_final_qa_suite.py \

  --package-dir /path/to/delivery-package

```



## License



MIT. See `LICENSE`.