Venturi Architecture
Internal architecture of the Venturi video editor: crates, data model, media/render/audio pipelines, application core, UI, concurrency and the MCP server. Developer-facing; not a user guide.
1. Overview
What Venturi is, the decisions that shape it, how the Cargo workspace is split into crates, and t...
Goals & Scope
Venturi is an editing-focused non-linear video editor (NLE) written in Rust. It does few things a...
Key Design Decisions
The choices that shape the rest of the code. Each one is detailed in the chapter of the crate it ...
Workspace Map
Venturi is a single Cargo workspace (edition 2024) of eight crates. Dependencies never point upwa...
Glossary
Terms used throughout the book. Code names are given where they differ from the plain term. Model...
2. Data Model (vv-core)
The project model, ids, keyframes, edits and undo, persistence and OTIO interchange.
Entities
The whole document is one plain struct, vv_core::Project ( model.rs). There is no node graph: ev...
IDs & IdMap
Entities are referenced by id, never by pointer or index into a Vec that could shift. The core r...
Keyframes & Transforms
Every animatable parameter is a Keyframed<T>: a sorted Vec<(FrameIdx, T, Interpolation)> plus a...
Commands, Undo/Redo
Undo uses the command pattern ( command.rs). Each command captures, when applied, the state it ne...
Persistence
A project is saved as one human-readable RON file, written straight from the Project struct by s...
OTIO Import/Export
Timelines travel to and from other NLEs as OpenTimelineIO JSON ( vv_core::otio), tested against D...
3. Media Pipeline (vv-media)
Probing, decoding with hardware acceleration, the frame cache, proxies, thumbnails, waveforms and...
Probe & Import
Importing turns a file path into a MediaItem in the project's media pool. Probing is the only st...
Decode & HW Acceleration
vv_media::Decoder decodes one video stream, sequentially ( next_frame) or after seek_to_time. Ev...
Frame Cache
Playback and scrubbing read decoded frames from one SharedFrameCache ( vv-media/src/cache.rs), f...
Proxies, Thumbnails, Waveforms
Three artifacts are derived from every imported media, each by its own background worker in vv-a...
Encode
vv_media::Encoder writes the export: H.264 video plus optional AAC audio, muxed into MP4. It rece...
4. Rendering (vv-render)
The wgpu compositor, text rendering and the GPU device shared with the UI.
GPU Compositor
vv_render::Compositor turns the stack of layers active at one timeline frame into a single RGBA t...
Color Correction & Scopes
Color correction is a per-pixel filter of the transform shader, FilterKind::ColorCorrection. The...
Text Rendering
Titles ( ClipSource::Text) are rasterized on the CPU by vv-render/src/text.rs with cosmic-text,...
Shared wgpu Device
The editor window and the viewer share one wgpu device: the composed frame is a texture that egui...
5. Audio (vv-audio, vv-vad)
The real-time mixer and effect chain, time-stretch, voiceover recording and voice activity detect...
Mixer & Effect Chain
All timeline audio goes through one function, vv_audio::mixer::mix_range. The preview calls it f...
Time-Stretch & Speed
Pitch-preserving time-stretch is libavfilter's rubberband filter, wrapped by vv_audio::stretch_...
Voiceover Recording
Voiceover records the microphone onto the armed audio tracks while the timeline plays at 1x, over...
Silence Detection
Silence removal tells speech apart from pauses with voice activity detection rather than a volume...
6. Application Core (vv-session)
The UI-free session shared by the editor and headless hosts: jobs, workers, frame provider and ex...
Session
vv_session::Session is an open document without any UI: the Project, its History, where it is s...
Jobs & Workers
Slow work (probing files, reading OTIO, scanning folders, exporting) runs off the host thread. Ea...
Frame Provider
frame_provider.rs holds the one mapping from a clip at a timeline frame to what the compositor dr...
Export Pipeline
export_timeline renders a frame range to a file with the same layers and the same audio mix as th...
7. Editor UI (vv-app)
The egui application: frame loop, timeline, viewer and playback, panels, dialogs, settings and lo...
App Structure & Frame Loop
vv-app is the only binary. main() picks one of three modes from the command line: Invocation Wha...
Timeline UI
timeline_ui.rs (~6.7k lines, the largest module) is the multi-track timeline widget. It is drawn ...
Viewer, Transport & Playback
Playback is split across threads so the UI never waits on a decoder: video is decoded ahead by R...
Panels & Dialogs
The window is built from egui docked panels plus floating windows. Each panel's visibility and si...
Settings, i18n, Theme
User settings settings.rs holds preferences of the program, not of the project. They are stored a...
8. Concurrency
Which threads exist, what each one owns, and how data moves between them.
9. MCP Server (vv-mcp)
How MCP tool calls reach a Session, headless and inside the editor, and the tool catalogue.
Architecture
vv-mcp exposes Venturi to AI agents over the Model Context Protocol. The protocol side (rmcp on a...
Headless vs Editor-Hosted
The same MCP server runs in two hosts. Headless, vv-app mcp [project] is the whole program: no w...
Tool Catalog
The 39 tools VenturiServer exposes, grouped by area. All ids (media, timelines, clips, markers) ...
10. Build & Distribution
Building from source, test conventions and packaging.
Building & Dependencies
Full instructions live in docs/BUILDING.md; this page summarises what the build needs and why. B...
Testing Conventions
Where unit tests live Unit tests are not inline. They live in crates/<crate>/src/tests/, mirrori...
Packaging
Releases ship three files: an AppImage for Linux x86_64, one for Linux aarch64, and a dmg for App...