# Video editor architecture proposal

**Decision requested · 20 November 2026.** Approve a local-first desktop editor for solo creators and small editorial teams, with macOS on Apple silicon as the first validation platform. The first release should let one person finish a captioned interview from original footage through a verified export. Team review, transcript editing and advanced finishing build on that foundation. These are proposed product choices. No implementation or benchmark results are implied.

## What to borrow

This is a representative worldwide product survey of 15 editors using public first-party documentation. Coverage spans professional post-production, mobile creation, open source, browser editing and screen recording. “Best” here means a feature solves a recurring editing problem, works alongside the other selections and can be tested on a real project. The selections reflect design judgment and documentation review, without hands-on comparative benchmarks.

| Editor | Documented strength | How it earns a place in this design |
|---|---|---|
| Final Cut Pro | Magnetic editing keeps related material in sync. [Apple guide](https://support.apple.com/en-ca/guide/final-cut-pro/verb8fcfc133/mac) | A cutaway can follow a sentence when the editor moves it. Store its anchor explicitly. |
| Adobe Premiere | Precision trimming, text-based editing and review comments share an editorial workflow. [Adobe](https://www.adobe.com/products/premiere/editing-and-trimming.html) | Expose precise trim commands to the keyboard and later to transcript selections. |
| DaVinci Resolve | Editors can mix sound directly on the edit page and deliver multiple formats. [Blackmagic Design](https://www.blackmagicdesign.com/products/davinciresolve/edit) | Share one sequence between cut, mix and delivery views. A gain change must be audible immediately. |
| Avid Media Composer | Shared projects protect bins against conflicting writes. [Avid editing guide](https://resources.avid.com/SupportFiles/attach/Media_Composer_Editing_Guide_8.3.pdf) | Give each shared sequence an identifiable writer. Other editors can work on separate sequences. |
| Kdenlive | Project bins support proxy editing. [Kdenlive manual](https://docs.kdenlive.org/en/project_and_asset_management/project_bin/project_bin_use.html) | Make lightweight media replaceable and retain original source identity through export. |
| Shotcut | Mixed-format timelines and frame-accurate seeking accommodate varied footage. [Shotcut](https://shotcut.org/features/) | Track source timestamps independently of the sequence frame rate. |
| OpenShot | Effect properties can be animated over time. [OpenShot](https://www.openshot.org/features/) | Use the same keyframe evaluator for titles, transforms and effect controls. |
| Descript | Editing transcript words can cut and rearrange footage. [Descript](https://www.descript.com/) | Map each selected word occurrence to a source range and preview the resulting cut. |
| CapCut | Automatic captions simplify social-video production. [CapCut](https://www.capcut.com/tools/auto-caption-generator) | Make generated captions editable cues with reusable styles and explicit export choices. |
| Canva | Drag-and-drop video design and templates speed composition. [Canva](https://www.canva.com/video-editor/) | Expand templates into editable clips, text and styling with replaceable media slots. |
| iMovie | Storyboard shot lists guide users through filling placeholders. [Apple guide](https://support.apple.com/en-gb/guide/imovie-iphone/kna088f6fb9b/3.0.4/ios/17.0) | Offer a shot-list view and flag empty required slots before delivery. |
| LumaFusion | Mobile multitrack editing combines titles, audio and effects. [LumaTouch](https://luma-touch.com/purchase/) | Keep edit commands independent of gestures so a future touch client can use the same rules. |
| Camtasia | Integrated screen recording and editing suit tutorials. [TechSmith](https://www.techsmith.com/camtasia/) | Feed screen and microphone recordings through the normal ingest and sync path. |
| Clipchamp | Screen, webcam and voice recording sit alongside subtitle creation. [Microsoft](https://clipchamp.com/en/) | Preserve camera and narration as separate editable streams in capture sessions. |
| VEED | Reusable ad templates support repeated production. [VEED](https://www.veed.io/tools/video-editor) | Store template revisions and pin the version used for a given project. |

## The editing experience

An editor imports an interview, a separate music bed and phone B-roll. The bin becomes usable as each file is indexed. The editor marks interview ranges in the source monitor, inserts them into a sequence, attaches B-roll to a moment in the interview and pins the music to sequence time. Shortening the interview moves downstream narrative clips and their attached B-roll. The pinned music keeps its start time. The editor corrects captions, checks audio peaks and exports a landscape master. A later portrait variant can reuse sources and cuts while retaining its own crop and title positions.

## Runtime and ownership

Use a modular desktop application with a native C++ editing core, Qt desktop shell, SQLite project store and FFmpeg-based media workers as the initial stack proposal. This lets the team test a single local application before operating network services. Package and codec distribution terms, supported profiles and hardware paths need verification against the actual build before distribution. Keep GPU operations behind a small rendering interface, starting with Metal on the reference Mac and a CPU reference path for image comparisons.

| Boundary | Owns | Contract |
|---|---|---|
| Desktop shell | Bin, source and program monitors, timeline, inspector, mixer, keyboard focus | Sends an edit intent with an expected revision. Receives a committed change or an actionable conflict. Drag previews stay transient until drop. |
| Editing core | Sequence rules, anchor resolution, trim validation, undo and revisions | Resolves an intent into one atomic set of operations. Returns affected sequence ranges for redraw and cache invalidation. |
| Project store | Asset records, editorial state, recovery history, schema version | Commits state and journal together. Supplies immutable snapshots to render jobs. |
| Media workers | Probe, index, thumbnails, waveform peaks, proxy generation and decode | Consume file access limited to the chosen inputs and cache. Return timestamped frames, samples and structured errors. |
| Playback and compositor | Transport clock, decode queues, frame selection, compositing and mixing | Evaluates a sequence snapshot for a time interval at a requested quality and output specification. |
| Job controller | Priorities, resource budgets, cancellation and retry | Pauses speculative proxy work during interactive seeks. Persists export job input revision, progress and outcome. |
| Optional team service | Project membership, revision manifests, review copies and comments | Added after desktop validation. Desktop publishes selected revisions and receives changes through the edit command boundary. |

## Project format and edit semantics

A project directory contains a versioned SQLite database, a manifest identifying its format and optional managed media. Originals may also live on external drives. Regenerable proxies, waveforms and thumbnails live in a separately budgeted cache. A portable archive gathers the selected originals, project snapshot and used fonts or identifies missing dependencies in a packing report.

| Record | Required information |
|---|---|
| Asset and stream | Stable ID, locations, size, content fingerprint, stream selection, time base, start timestamp, channel layout, orientation and color metadata |
| Sequence and lane | Stable IDs, canvas, rational frame rate, audio sample rate, ordered video layers, audio routing, lane lock and edit policy |
| Clip occurrence | Own ID, asset and stream references, half-open source interval, timeline placement, playback mapping, link group, optional parent occurrence and anchor offset |
| Effect, title and cue | Typed parameters, evaluation order, keyframes with interpolation, font reference, language, text and cue interval |
| Revision and job | Parent revision, command ID, affected objects, reversible changes, snapshot ID, input fingerprints, render settings and result |
| Later additions | Word ranges reference source streams. Review comments reference a published revision. Multicam angles reference a synchronized source group. |

Use integers and rational time bases throughout. Sequence video boundaries fall on sequence frames. Audio trims and fades resolve at sample boundaries. Variable-frame-rate sources use indexed presentation timestamps. A proxy records correspondence to those timestamps so relinking and final export select the same source moment.

**Edit rules.** Insert shifts the affected unlocked ripple group. Overwrite replaces only the intersecting interval on targeted lanes. A linked audio/video trim updates both boundaries unless explicitly unlinked. Moving a parent carries its anchored children. Deleting a parent with surviving children asks the editor to delete them or preserve their sequence positions. A ripple that would violate a lock fails as a whole and identifies the blocking lane. Anchors form an acyclic graph. Repeated use of the same source creates independent occurrences. Undo reverses the whole gesture, including induced moves.

**Persistence.** Assign each command a unique ID. In one transaction, check the expected revision, apply validated changes, record their inverse and advance the revision. A repeated command returns its recorded result. A stale command returns the current revision for refresh. Checkpoint history periodically and retain revisions referenced by exports. Recover the last committed revision after interruption. Back up before schema migration and open newer unsupported projects read-only where the schema permits.

## Playback, audio and delivery

1. Probe each input, then index keyframes and presentation timestamps. Display bins incrementally. Queue proxies for expensive sources and show readiness per asset. If a drive disconnects, allow available proxies to continue serving preview.
2. Compile a snapshot into an ordered graph of source reads, time maps, transforms, effects, layer composites, titles and output conversion. Use bounded decode queues and cancel obsolete seeks. Key cached results by source fingerprint, stream, time range, graph dependencies, quality and engine version.
3. Use the audio device as the playback clock. Decode ahead into an audio buffer and select video frames for that clock. Reduce preview resolution under load and count dropped preview frames. Export evaluates every requested output frame independently of playback speed.
4. For the first release, normalize supported SDR sources into a defined working space, composite with explicit alpha handling and tag the exported Rec.709 output. Surface unsupported HDR inputs during ingest. Mix at 48 kHz floating point with clip gain, fades, track mute/solo, master peak meter and explicit stereo routing.
5. Export pins the revision and source fingerprints, checks original availability, codec capability, output permissions and storage, then renders from originals into a temporary file. Verify stream properties and duration, close the file and atomically publish it. On cancellation or worker failure, preserve the project and existing destination. Retrying starts from the same snapshot. Missing originals produce a relink list.
6. Caption export offers burn-in and a sidecar. Both consume identical cue timing. Preview and export use the same font resolution and layout. Record any font substitution before rendering.

## Extensions and collaboration

**Transcript editing.** Transcription produces source-timed words and confidence values in a background job. The transcript view projects words through each clip occurrence. Correcting spelling edits text only. Removing footage is a separate command showing the affected ranges and attached clips before commit. Stale analysis is invalidated when the underlying media changes.

**Finishing.** An effect declares input type, output type, color expectations, parameter schema and version. Start with built-in transforms and opacity. Add scopes, curves, LUTs, audio buses and multicam as independent capabilities. A multicam switch stores the chosen angle and preserves the selected continuous audio source. Unsupported effects must be reported when exchanging projects.

**Review and shared editing.** Upload an explicitly selected review render with its revision and time map. Comments attach to that revision and a frame or range. Later edits can map a comment to a surviving occurrence or mark it unresolved. For shared writing, issue expiring sequence leases with a monotonically increasing fencing token. The server accepts a publish only if token and base revision match. A disconnected editor retains a local branch and can publish it as an alternate sequence on reconnect. A reviewer can annotate a shared revision without receiving access to original media.

## Delivery order and release gates

| Stage | Deliverable | Acceptance gate |
|---|---|---|
| 0 · After approval | Validate native decode, timestamp mapping, shared preview/export evaluation and packaging on the reference Mac | Repeated seeks around cuts in phone VFR and 30000/1001 footage select the expected source frames in preview and export. Record performance and dependency constraints before locking the stack. |
| 1 · First usable release | Local bins, proxies, source/program monitors, multitrack insert/overwrite, linked and anchored edits, gain/fades, titles, manual captions, undo/recovery and 1080p SDR MP4 export. Initial inputs H.264 MP4/MOV, WAV and PNG. | Complete the interview workflow offline, reopen it, relink moved originals and export H.264/AAC plus SRT. Verify frame count, cut positions, caption boundaries and audio sync on the decoded result. |
| 2 · Faster creator workflows | Transcript rough cuts, automatic captions, storyboard templates, portrait variants and screen/camera capture | A transcript edit updates the timeline once, undo restores it, and a portrait export retains its framing when reopened. Screen capture preserves microphone alignment. |
| 3 · Professional finishing | Multicam, keyframes, color scopes, advanced audio and editorial interchange | Switch camera angles across a continuous audio bed. Round-trip a documented interchange subset and report every unsupported operation. |
| 4 · Team and platform expansion | Revision review, shared sequence leases, Windows validation and touch-client evaluation | Two editors can publish distinct sequences. A stale writer cannot overwrite a newer revision. A reviewer can identify the exact approved render. |

**Proposed performance budget.** On a reference M1 Mac with 16 GB RAM and local SSD, target uninterrupted stereo audio and under 1% dropped preview frames over ten minutes of two-layer 1080p30 proxy playback. Target a warm seek under 150 ms at the 95th percentile over 100 randomized seeks. Capture cold seeks separately. Check sync at the start and end of a one-hour fractional-rate fixture within one output video frame, accounting for codec priming. These are acceptance targets to measure after approval.

**Highest-risk tests.** Compare proxy and original frame identity across variable-rate cuts. Compare CPU reference frames and export frames with an explicit codec-appropriate tolerance. Terminate the editor during autosave and terminate a worker during export. Simulate a full cache disk, a moved source, missing fonts and an interrupted migration. Preserve the last committed edit and identify the affected asset or job in every failure report.

## Approval scope

Approval authorizes Stage 0 and the Stage 1 desktop release, subject to the validation gate. Stages 2–4 describe the intended architecture and sequencing. They carry no delivery dates or budget commitments. A browser-first product, a mobile-first release or mandatory multi-user editing on day one would materially change the first milestone and should be decided before development.
