# Splice Desk

Splice Desk is a local macOS video editor for assembling a captioned interview from footage, cutaways and a separate music bed. The bundled development build runs on Apple silicon with macOS 26 or later.

[Feature inventory](FEATURES.md) · [User guide](USER_GUIDE.md)

## Open the editor

Double-click **Splice Desk.app** inside **build**, or run this command from the project directory.

```sh
open "build/Splice Desk.app"
```

1. Choose **Import media** and select local SDR MP4, MOV, WAV or PNG files. Select a movie in the bin to open its source monitor. **Mark in** and **Mark out** choose the source range to place.
2. Choose **Place in sequence → Insert story clip**. Selecting a story clip makes it the insertion point for the next insert or overwrite. With that story selected, choose a second source and **Attach cutaway** to connect it to the story. Music stays at its sequence position.
3. Select a clip to change its source range, position, gain or fade in the inspector. Timing fields use frames at 30 fps. Click the ruler to place the playhead. **Loop cut** auditions up to a second on each side. **Match source frame** opens the original at the corresponding moment.
4. Add a **Caption** or **Title**, edit its wording and length, then **Apply changes**. Lane menus control locking, mute and solo. After an edit or a jump outside the loaded preview, Splice Desk prepares a local preview around the playhead. Sequences up to 20 seconds preview in full. Longer sequences preview in six-second windows. Splice Desk prepares the next window in the background and resumes at its first frame. If it is still rendering when playback reaches the boundary, playback resumes when it is ready. Up to three recently viewed windows can be reused for nearby seeks. Edits, media relinks and proxy cleanup discard them. Use the Program monitor’s render button for full-sequence playback, or **Loop cut** to replay a transition. On supported movies, **Create preview proxy** generates a lightweight local copy for review while the original is offline.
5. Choose **Export → 1080p master · MP4** for a 1920×1080, 30 fps SDR movie with burned-in titles and captions and stereo AAC audio. **Subtitle track · SRT** writes a separate text track. Master export checks source identity, video dimensions, frame count and stream codecs before replacing the chosen destination.

The current session recovers automatically. **⌘Z** and **⇧⌘Z** step through edit history. **⌘S** writes a portable JSON project copy. Bring its original media when moving it to another Mac and use **Relink original** to select matching files.

## Reframe a sequence for portrait

Choose **Portrait 9:16** from the format menu beside **Export**. Select a Story or Cutaway clip and adjust **Horizontal crop** in the inspector, then click **Apply changes**. Portrait previews and the 1080 × 1920 MP4 use the same crop. The format and shot framing are saved with the project. Switch back to **Landscape 16:9** when you need the wide version. **Suggest face crop** samples up to five frames on-device and proposes a single crop. It flags sampled faces that are too far apart for one crop. Use **Preview crop** to review it, then **Apply changes** to commit it. Use **Review portrait framing** in the format menu to scan the sequence. The review flags missing originals, inconsistent face detections, and faces that span more than one crop. Apply all clear suggestions together or open a shot for individual review. Existing crops and locked lanes are preserved.

## Switch to another camera

Select a Story clip and click the timeline ruler where you want the angle to change. Open the alternate movie in the media bin and mark its source in and out points. Choose **Place in sequence → Switch camera at playhead**. The alternate picture runs for the marked duration or until the selected Story clip ends, whichever comes first. Its audio starts muted, so the Story dialogue continues across the switch.

If both cameras recorded the same sound, mark a rough in-point in the alternate clip and choose **Align camera by audio** before switching. Splice Desk searches up to 15 seconds on either side of that mark and moves the source in-point to a clear match. The Story playhead needs at least one second of following audio. Review the suggested mark and switch when ready.

## Edit an interview by transcript

Select a **story** clip with speech and open **Transcript** above the timeline. Choose **Transcribe on this Mac**. If the local language model is missing, **Install language model** requests it from Apple for the Mac’s current language. Recognition runs on the original audio locally. The transcript becomes part of the project copy and its local recovery history.

Open **Highlights** in Transcript to browse up to 12 suggested excerpts from the current Story. Ranking uses length and sentence endings, and repeated wording appears once. Check the highlights to include and choose **Save reel draft** to save a separate editable project in timeline order. The draft includes overlapping captions, cutaways and music. Reopen it with **Open Project**. Cuts use the sentence boundaries, and fades are limited to the length of each retained clip. Use **Search Story quotes** to find complete phrases across transcribed Story clips. Results show timeline timecodes and list repeated quotes at each occurrence. **Jump to quote** selects the clip and positions the playhead. Clear the search to return to the selected clip’s transcript. **Loop quote** plays the sentence with half a second of surrounding timeline context. **Export quote** writes a standalone MP4 with that same context or just the sentence. It uses the current framing, captions, audio, and camera cuts. **Cut sentence** removes it from the selected occurrence, trims crossing cutaways and moves later anchored material with its story. Locked lanes protect their edits. One undo restores the entire cut. The panel shows complete recognized phrases within the selected clip.

In **Smart Cut**, expand a suggested pause to see the resulting timeline duration and how many existing captions and cutaways it affects. **Before** loops the original pause with surrounding context. **After** loops the proposed transition. **Apply cut** commits the reviewed edit in one undo step. **Review protected batch** groups the selected clip’s suggested pauses and skips any removal range that intersects a Caption or Cutaway clip. It shows Story time saved and plays both versions before you apply the group in one undo step.

Choose **Caption → Generate captions from Story** to create editable captions for complete spoken phrases in the current cut. Missing transcripts are generated on-device. Repeat a quote to caption each occurrence. Existing captions take priority in overlapping ranges. Select a generated cue in the Caption lane to correct text or insert a line break. The same cue timing drives the 1080p master and SRT export.

## Privacy and storage

The signed application uses the macOS App Sandbox. It has user-selected file access and app-scoped bookmarks. Media tools inherit the sandbox. The app requests no network entitlement and includes no account, analytics or upload workflow.

Project copies contain filenames, content hashes, clip timing and authored text. Read-only access bookmarks and the SQLite recovery database stay in the app container. The last 100 edit revisions are retained. Proxies contain actual footage. **Local workspace** provides separate controls to clear proxies and forget file grants. Working copies are removed after processing, and the next launch clears interrupted temporary jobs. The application relies on macOS for storage encryption.

## Build and verify

Rebuilding needs Apple silicon, the Swift toolchain, Python 3 and a local Homebrew FFmpeg installation with libx264. The packaging script copies the media tools and their libraries, rewrites their load paths, signs the bundle locally, verifies the signature and records the minimum macOS version required by the bundled libraries.

```sh
python3 scripts/package.py
scripts/test.sh
```

The test suite generates synthetic originals and checks recovery, undo/redo, lock enforcement, anchored splits, overwrite timing, matching-file relink, incorrect-original rejection, offline proxy playback, burned caption boundaries, SRT timing, cut-loop frames and decoded output. A one-hour fractional-frame-rate source tests flash-to-tone alignment near its end. The test outputs live in a temporary directory that is removed after the run.

## Build status

This development build uses SwiftUI and AVKit for the desktop interface and playback, SQLite for recovery, and FFmpeg for shared preview and master rendering. The transport uses a fixed 30 fps SDR timeline. Preview preparation time depends on source length and effects. The reference-M1 ten-minute playback and random-seek performance budgets remain unmeasured. Public distribution also requires release signing, notarization and a review of bundled codec distribution terms. HDR finishing and team collaboration remain later milestones in the [architecture proposal](ARCHITECTURE.md).

### Repeat the speech end-to-end check

After packaging the editor, run `scripts/build-speech-e2e.sh` and open **build/transcript-qa/Transcript Verification.app**. This separate sandbox synthesizes three English sentences, requests Apple's local language model if necessary, and runs the production recognition, quote-loop renderer, sentence cut, master export, undo, redo and recovery code. The English fixture assumes an English recognition locale. The runner displays the recognized words and the result. **Inspect verified interview** opens the production editor view on the synthetic project for interactive search and playback checks.

See [the implementation reference](IMPLEMENTATION.md) for the code map, rendering and data flows, security model, and verification commands.
