How augani/openreel-video works
1. Repo shape
This is a pnpm monorepo with three main product surfaces:
- apps/web: the primary browser-based video editor
- apps/image: a separate browser-based image editor
- shared libraries under packages/*, especially packages/core, packages/image-core, and packages/ui
2. Primary architectural split
The video editor is intentionally split into a React UI layer and a core engine layer. UI code lives in apps/web/src/components, stores, services, and bridges; media processing and timeline logic live in packages/core. The UI orchestrates user interaction, while the core package performs heavy editing, rendering, and export work.
3. Web editor UI composition
apps/web/src/components/editor contains the major workspace regions: timeline, preview, inspector, toolbar, dialogs, recorder, templates, and AI panels. These components are mostly presentational and interaction-heavy, but they do not implement media algorithms themselves. They read/write shared app state and call into service/bridge modules.
4. State management boundary
apps/web/src/stores uses Zustand stores to hold editor state such as project, timeline, UI, recorder, settings, theme, notifications, and TTS. This store layer is the main coordination point between UI events and engine actions. The editor is built around a stateful but local-only model; there is no central backend database in the normal editing path.
5. Bridge and service layer
apps/web/src/bridges is the integration boundary between UI state and core engines. These bridges connect features like audio, effects, graphics, motion tracking, playback, rendering, transitions, photo editing, silence cutting, and text. apps/web/src/services handles app-level concerns such as auto-save, project management, secure storage, screen recording, template cloud access, background generation, and processing orchestration.
6. Core media engine
packages/core is the main computation layer for the video product. It is organized by domain:
- video: decoding, compositing, WebGPU rendering, transitions, keyframes, frame caching, stabilization, upscaling, effects
- audio: mixing, effects, beat detection, waveform generation, noise reduction, real-time graph processing
- text: subtitles, title rendering, audio-text sync, speech-to-text, animations
- graphics and effects: shapes, stickers, particles, SVG, blend modes
- photo: adjustment and retouching
- export: final render/export pipeline
- storage: project serialization and schema handling
7. Rendering and playback flow
The primary runtime flow is: user edits in React UI → stores update → bridges invoke core engines → preview renders through WebGPU/WebCodecs/Web Audio where available. packages/core/src/video and packages/core/src/playback are the main realtime path, with fallback renderers and frame caches supporting progressive enhancement when hardware features are missing or limited.
8. Export and background processing
Export is handled in packages/core/src/export and is coordinated by the web app’s processing-manager/export dialog flow. The system is designed for long-running operations with progress reporting and cancellation. Worker-style processing appears throughout the core package, including decode/export helpers and audio worklet-style processing.
9. Persistence and recovery
Projects are stored client-side, not on a primary server path. The app uses IndexedDB-oriented storage and local recovery helpers (auto-save, project-manager, secure-storage, media-storage, recovery hooks). Project schema/migration logic exists in both the web app and core/storage layers, showing that durable local project compatibility is a first-class concern.
10. External services and network boundaries
Most editing happens locally, but a few features cross the network boundary:
- apps/web/functions/api/proxy is a Cloudflare Worker-style proxy for API calls
- apps/web/src/services/kieai and related UI support remote AI image generation
- transcription/TTS-related UI and services integrate with external voice APIs
- infra/transcribe-gpu is a separate Python/Docker deployment for GPU/CPU transcription support
These are feature-specific integrations rather than the main data path.
11. Shared UI and design system
packages/ui provides reusable React primitives and styling utilities used by both apps. This is a presentation-only package that supports consistent controls like dialogs, sliders, toggles, menus, buttons, and color pickers. It reduces duplication but does not own business logic.
12. Image editor as a parallel product
apps/image is not a subset of the video editor; it is its own browser-based editor with its own stores, services, tools, filters, and inspector UI. It depends on packages/image-core for project/command/operation/schema logic and uses a separate set of adjustment and tool subsystems. Architecturally, it mirrors the same pattern: React UI on top, a domain core package underneath.
13. Platform and delivery
The repo is optimized for the browser with Vite, React, TypeScript, Tailwind, service workers, and PWA assets. GitHub Actions handle CI and review automation. Native wrapper projects for Android and iOS exist in the tree, but the README and code layout indicate the browser app is the primary product surface.
14. Important diagram boundary
If drawing the architecture, the clearest top-level boundary is:
UI apps (apps/web, apps/image) → app state/services → core engine packages (packages/core, packages/image-core) → browser/platform APIs and optional external services.
That boundary captures where user interaction ends and media computation begins, which is the central architectural idea in this repository.
Main entry points: components/editor React UI · bridges Bridges · services App services · components/editor Image UI
Components 21
Web editor
Primary browser-based video editor surface and its local app layers.
- React UI · Main video editor interface: workspace regions, dialogs, preview, timeline, inspector, and tooling UI.
apps/web/src/components/editor - Editor state · Local state coordination for project, timeline, UI, recorder, settings, notifications, theme, and TTS.
apps/web/src/stores - App services · Autosave, project management, secure storage, processing, templates, recording, and cloud/AI integrations.
apps/web/src/services - Bridges · Feature-specific adapters that connect UI state and app events to core media engines.
apps/web/src/bridges - Preview path · Browser preview and canvas/three.js rendering used for realtime playback feedback.
apps/web/src/components/editor/preview - Timeline UI · Clip lanes, playhead, markers, keyframes, and timeline interactions.
apps/web/src/components/editor/timeline - Inspector UI · Clip and project panels for audio, text, motion, effects, AI, and other edit controls.
apps/web/src/components/editor/inspector - KieAI UI · Browser dialogs and forms for remote image generation workflows.
apps/web/src/components/editor/kieai
Image editor
Standalone browser-based image editor surface.
- Image UI · Standalone image editor interface with canvas, layers, panels, inspector, and tool controls.
apps/image/src/components/editor - Image state · Local image editor state for canvas, selection, history, color, project, and UI.
apps/image/src/stores - Image tools · Brush, retouch, transform, vector, and text tools used by the image editor.
apps/image/src/tools - Image services · Export, background removal, template, font, keyboard, and project migration services.
apps/image/src/services
Video core
Computation-heavy video editing, playback, export, and media subsystems.
- Video engine · Main video computation path for decode, compose, render, playback, caching, transitions, keyframes, stabilization, and effects.
packages/core/src/video - Audio engine · Mixing, beat detection, waveform generation, noise reduction, realtime graph processing, and audio effects.
packages/core/src/audio - Text engine · Subtitles, title rendering, speech-to-text, audio-text sync, and text animations.
packages/core/src/text - Export pipeline · Final render/export execution, including worker-based processing and progress/cancellation handling.
packages/core/src/export - Project storage · Client-side project serialization, schema handling, cache management, and storage engine logic.
packages/core/src/storage
Shared packages
Reusable UI and image-domain libraries shared across app surfaces.
- UI kit · Reusable presentation components and styling utilities shared by both apps.
packages/ui/src/components - Image core · Command, operation, schema, migration, project, mask, selection, and adjustment model for the image editor.
packages/image-core/src
Platform
Browser, worker, cloud, and delivery boundaries around the product.
- Platform APIs · IndexedDB, workers, WebGPU/WebCodecs/Web Audio, service workers, and browser delivery surfaces.
- External services · Cloud proxy, AI generation, voice/transcription integrations, and GPU transcription deployment.
apps/web/functions/api/proxy
Connections 25
- React UI → Editor state: reads/writes · UI interactions update local editor state and react to state changes.
- Editor state → Bridges: drives · State changes trigger engine-adapter calls for editing actions and playback.
- React UI → Preview path: renders · Workspace preview surfaces show realtime composition feedback.
- React UI → Timeline UI: uses · Timeline components provide the main clip-editing interaction surface.
- React UI → Inspector UI: uses · Inspector panels expose per-clip and per-project controls.
- React UI → KieAI UI: opens · AI image generation flows are exposed through dedicated dialogs and forms.
- App services → Editor state: syncs · Autosave, recovery, and processing services coordinate with local state.
- App services → External services: calls · Remote AI, voice, and proxy-backed integrations cross the network boundary.
- Bridges → Video engine: invokes · Video editing actions are delegated to the core engine layer.
- Bridges → Audio engine: invokes · Audio-related edit actions route into the audio engine.
- Bridges → Text engine: invokes · Text, subtitles, TTS, and sync features route into the text engine.
- Bridges → Project storage: serializes · Bridges participate in project and timeline persistence flows.
- App services → Export pipeline: coordinates · Export dialogs and processing manager coordinate long-running renders.
- Image UI → Image state: reads/writes · Image editor interactions are coordinated through local stores.
- Image UI → Image tools: uses · Canvas and inspector UI expose image editing tools.
- Image services → Image core: orchestrates · Services manage export, migrations, and project-level operations on top of the image core.
- Image UI → Image services: uses · Dialogs and panels call into image editor services.
- Video engine → Platform APIs: runs on · Realtime rendering and decoding depend on browser graphics and media APIs where available.
- Audio engine → Platform APIs: runs on · Audio processing uses browser audio and worker-style execution paths.
- Export pipeline → Platform APIs: runs on · Export workers and browser runtime support the render pipeline.
- Project storage → Platform APIs: persists on · Project durability relies on client-side storage and recovery APIs.
- UI kit → React UI: supports · Shared presentation primitives reduce UI duplication in the web editor.
- UI kit → Image UI: supports · Shared controls and styling are reused by the image editor.
- Image core → Platform APIs: persists on · Image project schema and operations ultimately run in the browser runtime.
- External services → App services: integrates with · Networked feature integrations are consumed by app-level services.