# Clip DR by Sakib

Native Rust desktop application for transcript-driven interview clipping, with a Lua connector to DaVinci Resolve Studio 21.1+. Windows build 0.1.0.

## Open the app

In Resolve, open your master timeline and choose **Workspace → Scripts → Utility → Clip DR by Sakib**. If the new entry is missing, restart Resolve once. Click **Connect / refresh** in Clip DR.

Resolve's **Preferences → System → General → External scripting using** must allow **Local** access. The app invokes Resolve's own `fuscript` interpreter for individual Lua API requests. It does not require Python, a web server, Electron, an AI API key, or a continuously running bridge inside Resolve.

## Workflow

1. Connect to the master timeline. Existing native transcription words are preferred for supported normal-speed, matching-frame-rate audio clips. Timeline subtitle cues are a fallback. You can also import timeline-relative SRT/VTT.
2. Select Start and End in the transcript to create a clip, or enter exact start/end phrases under **Clips & retakes** to find every occurrence.
3. Under **AI selections**, copy an ID-based prompt, use your preferred AI service, and import its JSON response. Use the frame-range controls to divide long interviews into chapters. Clip DR does not contact an AI service itself.
4. Review candidates, edit titles/hooks/translations and frame boundaries, classify takes, and approve the intended occurrences. Use ↑/↓ to set trailer order.
5. Under **Deliver**, add/update master markers, create separate nested clip timelines, assemble an ordered trailer, or queue master render ranges. Rendering starts from Resolve's Deliver page.

Each selection starts unapproved. Ten identical performances produce ten candidates. Phrase matching never silently chooses one. ID imports reject nonexistent IDs, reversed boundaries, and cross-source references. Subtitle cues remain cue-level timing; the app does not pretend they have exact word timing.

Legacy START/END responses and PodClipper 5 timed BLOCK responses can be imported. Timed BLOCK data is interpreted as timeline-relative timecode. Review it before delivery.

## Included

- Rust native UI and selection/session processing; Lua API connector.
- Icon Studio purple/lavender palette with light and dark modes.
- Stable transcript identities, explicit repeated-take candidates, manual selection, and overlap warnings.
- Clips, trailer prompts, bilingual take-review prompts, translation/reel/status notes.
- Exact boundary editing, before/after frame handles, trailer ordering.
- Native transcription reading; SRT/VTT and subtitle-track fallbacks.
- Nested master excerpts for editable clip outputs and trailer assembly.
- Nested-bin asset discovery, optional Fusion hook text template, optional effect/adjustment template.
- Output timeline dimensions and optional Smart Reframe for new excerpts.
- Named render presets, deterministic filename suffixes, persistent render-job ledger.
- Saved sessions, delivery recipes, manifest export, selection undo (Ctrl/Cmd+Z), save (Ctrl/Cmd+S).
- Bounded request queue, one API request at a time, cancellation and timeout, single app instance per installation.
- Timeline identity/edit-structure checks before write operations.

## Important first-build behavior

You requested to handle live testing yourself. The Windows executable compiles successfully. Live editing, native-transcript source alignment, template behavior and rendering need validation on your projects. This is a first build, not a claim of production validation.

- **New clip/trailer timelines nest the master**, rather than reconstructing its tracks. Existing master edits remain inside that nested timeline. Nested caption tracks, Fairlight routing, mixed rates, retimes, multicam and complex Fusion edits need your review.
- The native transcript mapping accepts normal speed and matching source/timeline rates. Unsupported clips fall back to subtitle cues/imported transcripts; complete mixed-source coverage is not guaranteed. Transcribe your source in Resolve before refreshing.
- Source transcription data is read from audio timeline items. Multiple overlapping audio tracks may produce ambiguous text ordering. Use an SRT from the finished timeline when necessary.
- **Master range rendering uses the existing master styling.** Templates, Smart Reframe and new dimensions apply to newly created output timelines, not master range jobs. Render the new timelines from Resolve for those styled outputs.
- The supplied asset list includes media-pool items; choose an actual Fusion title or suitable effect/adjustment template. Hook templates need a `StyledText` input. Some templates cannot be extended to arbitrary durations.
- Selection undo restores in-app selections; it does not reverse Resolve operations. Cancel stops the connector request; operations already applied in Resolve can remain.
- Marker collisions are reported. Resolve cannot store two timeline markers at the same frame. Successful earlier markers can remain if a later one fails.
- Export jobs already recorded in the queue are skipped on repeated requests. To recreate a failed job, remove it from Resolve's queue, then queue again. The ledger is stored in `runtime/render-ledger.json`.
- Preview seeking currently requires non-drop-frame timeline timecode. Frame-based markers/render ranges do not use that preview conversion.
- Autosave preserves the active session. A different timeline's previous session is archived beside the executable. Timeline edits invalidate approvals when refreshed.
- Fully automatic best-performance judging, semantic ranking, silence/filler removal, automatic chapter segmentation, continuous render monitoring, multi-format export variants and flat track reconstruction are not implemented in this build.

## Files and privacy

`session.json` and archived sessions contain transcripts, selections and preferences locally beside the executable. `runtime/` contains API requests/responses and the render ledger. The copied AI prompt includes your transcript; you decide where to paste it. The app sends no transcript to an external service automatically.

Your PodClipper 3, 4 and 5 scripts remain intact.

## Build and platforms

Source is portable Rust with platform-specific Resolve interpreter/Utility paths. Windows x64 is built. macOS and Linux binaries must be built and tested on those systems; they are not included as verified binaries.

With a normal Rust installation and platform development dependencies:

```text
cargo build --release --locked
```

Copy the executable next to `bridge.lua` and `dkjson.lua`, then run the appropriate installer. Windows uses `clip-dr.exe`; macOS/Linux use `clip-dr`. `CLIPDR_FUSCRIPT` can override the interpreter path for custom Resolve installations.

See `Build Windows.ps1`, `install.sh`, and `.github/workflows/build.yml` for packaging. Keep the generated Cargo.lock for reproducible dependency versions. Rust 1.89+ is required for the single-instance file lock; use current stable Rust for dependencies.

## Third-party code

UI: eframe/egui (MIT / Apache-2.0). JSON: serde/serde_json (MIT / Apache-2.0). File dialogs: rfd (MIT). Hashing: sha2 (MIT / Apache-2.0). Lua serialization: dkjson 2.9, David Heiko Kolf (MIT; full notice included in `dkjson.lua`).