# martindelophy/ai-video-editor architecture

> Architecture diagram of the GitHub repository martindelophy/ai-video-editor, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/martindelophy/ai-video-editor
- Repository: https://github.com/martindelophy/ai-video-editor
- Video tour (about a minute): https://gitdiagram.com/martindelophy/ai-video-editor/video

## Overview

Timeline Studio is a local-first browser video editor. Users import media, arrange and refine clips on a multitrack timeline, apply AI-assisted audio, caption, visual, and avatar workflows, preview the composition, then export a portable result. The map includes the documented AI branches and the separate MCP editing interface. Source excerpts are partial, so uncertain connections among UI hooks, workers, and export are omitted; README capabilities identify unsampled feature branches.

Main entry points: [`src/App.jsx`](https://github.com/martindelophy/ai-video-editor/blob/main/src/App.jsx) (Editor app), [`src/components/PreviewStage.jsx`](https://github.com/martindelophy/ai-video-editor/blob/main/src/components/PreviewStage.jsx) (Preview stage), [`src/hooks/useVoiceGeneration.js`](https://github.com/martindelophy/ai-video-editor/blob/main/src/hooks/useVoiceGeneration.js) (Voice generation), [`src/hooks/useAiMusicGeneration.js`](https://github.com/martindelophy/ai-video-editor/blob/main/src/hooks/useAiMusicGeneration.js) (AI music)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_editing["Editing and preview"]
  node_editor["Editor app<br/>[App.jsx]"]
  node_timeline_ui["Timeline UI<br/>[Timeline.jsx]"]
  node_preview["Preview stage<br/>[PreviewStage.jsx]"]
  node_timeline_model["Timeline model"]
end

subgraph group_ai["AI media workflows"]
  node_captions["Automatic captions<br/>[useAutoCaptions.js]"]
  node_voice["Voice generation"]
  node_voice_profiles[("Voice profiles")]
  node_music["AI music"]
  node_music_worker["Music inference<br/>[ai-music.worker.js]"]
  node_repair["AI repair<br/>[useMiganRepair.js]"]
  node_restoration["Video restoration"]
  node_framing["Smart framing<br/>[useSmartFrame.js]"]
  node_vision["Visual analysis"]
  node_vocal["Vocal separation"]
  node_avatar["Talking avatar"]
  node_avatar_worker["LivePortrait inference"]
end

subgraph group_output["Projects and export"]
  node_project_commands["Project commands"]
  node_export["Video export<br/>[useVideoExport.js]"]
  node_archive["Project archives<br/>[projectArchive.js]"]
end

subgraph group_integration["External editing interfaces"]
  node_mcp["MCP editing server<br/>[server.mjs]"]
  node_cli["Timeline command"]
end

node_user(("Editor user"))
node_model_hosts[("Model hosts")]
node_browser["Browser runtime"]

node_user -->|"edits media"| node_editor
node_editor -->|"renders timeline"| node_timeline_ui
node_editor -->|"renders preview"| node_preview
node_editor -->|"uses timeline state"| node_timeline_model
node_preview -->|"shows composition"| node_timeline_model
node_editor -->|"requests captions"| node_captions
node_editor -->|"requests voiceover"| node_voice
node_voice -->|"loads profiles"| node_voice_profiles
node_editor -->|"requests music"| node_music
node_music -->|"dispatches inference"| node_music_worker
node_music_worker -->|"fetches models"| node_model_hosts
node_editor -->|"requests repair"| node_repair
node_editor -->|"requests restoration"| node_restoration
node_editor -->|"requests framing"| node_framing
node_editor -->|"requests analysis"| node_vision
node_editor -->|"requests separation"| node_vocal
node_editor -->|"requests avatar"| node_avatar
node_avatar -->|"dispatches rendering"| node_avatar_worker
node_avatar_worker -->|"fetches models"| node_model_hosts
node_editor -->|"exports composition"| node_export
node_export -->|"encodes media"| node_browser
node_editor -->|"loads and saves"| node_archive
node_user -.->|"sends edit requests"| node_mcp
node_mcp -->|"executes commands"| node_cli
node_cli -->|"applies operations"| node_project_commands
node_project_commands -->|"reads and writes"| node_archive

click node_editor "https://github.com/martindelophy/ai-video-editor/blob/main/src/App.jsx"
click node_timeline_ui "https://github.com/martindelophy/ai-video-editor/blob/main/src/components/Timeline.jsx"
click node_preview "https://github.com/martindelophy/ai-video-editor/blob/main/src/components/PreviewStage.jsx"
click node_timeline_model "https://github.com/martindelophy/ai-video-editor/blob/main/src/hooks/useTimelineModel.js"
click node_project_commands "https://github.com/martindelophy/ai-video-editor/blob/main/src/lib/projectCommandEngine.js"
click node_captions "https://github.com/martindelophy/ai-video-editor/blob/main/src/hooks/useAutoCaptions.js"
click node_voice "https://github.com/martindelophy/ai-video-editor/blob/main/src/hooks/useVoiceGeneration.js"
click node_voice_profiles "https://github.com/martindelophy/ai-video-editor/blob/main/src/lib/voiceProfileStorage.js"
click node_music "https://github.com/martindelophy/ai-video-editor/blob/main/src/hooks/useAiMusicGeneration.js"
click node_music_worker "https://github.com/martindelophy/ai-video-editor/blob/main/src/workers/ai-music.worker.js"
click node_repair "https://github.com/martindelophy/ai-video-editor/blob/main/src/hooks/useMiganRepair.js"
click node_restoration "https://github.com/martindelophy/ai-video-editor/blob/main/src/hooks/useNanoVsrRestoration.js"
click node_framing "https://github.com/martindelophy/ai-video-editor/blob/main/src/hooks/useSmartFrame.js"
click node_vision "https://github.com/martindelophy/ai-video-editor/blob/main/src/hooks/useVisionAnalysis.js"
click node_vocal "https://github.com/martindelophy/ai-video-editor/blob/main/src/hooks/useVocalSeparation.js"
click node_avatar "https://github.com/martindelophy/ai-video-editor/blob/main/src/hooks/useAvatarGeneration.js"
click node_avatar_worker "https://github.com/martindelophy/ai-video-editor/blob/main/src/workers/liveportrait.worker.js"
click node_export "https://github.com/martindelophy/ai-video-editor/blob/main/src/hooks/useVideoExport.js"
click node_archive "https://github.com/martindelophy/ai-video-editor/blob/main/src/lib/projectArchive.js"
click node_mcp "https://github.com/martindelophy/ai-video-editor/blob/main/skills/edit-timeline-studio/mcp/server.mjs"
click node_cli "https://github.com/martindelophy/ai-video-editor/blob/main/scripts/timeline-command.mjs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_editor,node_timeline_ui,node_preview,node_timeline_model,node_user,node_browser toneBlue
class node_captions,node_voice,node_voice_profiles,node_music,node_music_worker,node_repair,node_restoration,node_framing,node_vision,node_vocal,node_avatar,node_avatar_worker,node_model_hosts toneAmber
class node_project_commands,node_export,node_archive toneMint
class node_mcp,node_cli toneRose
```

## Components

### Editing and preview

- [Editor app](https://github.com/martindelophy/ai-video-editor/blob/main/src/App.jsx): `src/App.jsx`
- [Timeline UI](https://github.com/martindelophy/ai-video-editor/blob/main/src/components/Timeline.jsx): `src/components/Timeline.jsx`
- [Preview stage](https://github.com/martindelophy/ai-video-editor/blob/main/src/components/PreviewStage.jsx): `src/components/PreviewStage.jsx`
- [Timeline model](https://github.com/martindelophy/ai-video-editor/blob/main/src/hooks/useTimelineModel.js): `src/hooks/useTimelineModel.js`

### AI media workflows

- [Automatic captions](https://github.com/martindelophy/ai-video-editor/blob/main/src/hooks/useAutoCaptions.js): `src/hooks/useAutoCaptions.js`
- [Voice generation](https://github.com/martindelophy/ai-video-editor/blob/main/src/hooks/useVoiceGeneration.js): `src/hooks/useVoiceGeneration.js`
- [Voice profiles](https://github.com/martindelophy/ai-video-editor/blob/main/src/lib/voiceProfileStorage.js): `src/lib/voiceProfileStorage.js`
- [AI music](https://github.com/martindelophy/ai-video-editor/blob/main/src/hooks/useAiMusicGeneration.js): `src/hooks/useAiMusicGeneration.js`
- [Music inference](https://github.com/martindelophy/ai-video-editor/blob/main/src/workers/ai-music.worker.js): `src/workers/ai-music.worker.js`
- [AI repair](https://github.com/martindelophy/ai-video-editor/blob/main/src/hooks/useMiganRepair.js): `src/hooks/useMiganRepair.js`
- [Video restoration](https://github.com/martindelophy/ai-video-editor/blob/main/src/hooks/useNanoVsrRestoration.js): `src/hooks/useNanoVsrRestoration.js`
- [Smart framing](https://github.com/martindelophy/ai-video-editor/blob/main/src/hooks/useSmartFrame.js): `src/hooks/useSmartFrame.js`
- [Visual analysis](https://github.com/martindelophy/ai-video-editor/blob/main/src/hooks/useVisionAnalysis.js): `src/hooks/useVisionAnalysis.js`
- [Vocal separation](https://github.com/martindelophy/ai-video-editor/blob/main/src/hooks/useVocalSeparation.js): `src/hooks/useVocalSeparation.js`
- [Talking avatar](https://github.com/martindelophy/ai-video-editor/blob/main/src/hooks/useAvatarGeneration.js): `src/hooks/useAvatarGeneration.js`
- [LivePortrait inference](https://github.com/martindelophy/ai-video-editor/blob/main/src/workers/liveportrait.worker.js): `src/workers/liveportrait.worker.js`

### Projects and export

- [Project commands](https://github.com/martindelophy/ai-video-editor/blob/main/src/lib/projectCommandEngine.js): `src/lib/projectCommandEngine.js`
- [Video export](https://github.com/martindelophy/ai-video-editor/blob/main/src/hooks/useVideoExport.js): `src/hooks/useVideoExport.js`
- [Project archives](https://github.com/martindelophy/ai-video-editor/blob/main/src/lib/projectArchive.js): `src/lib/projectArchive.js`

### External editing interfaces

- [MCP editing server](https://github.com/martindelophy/ai-video-editor/blob/main/skills/edit-timeline-studio/mcp/server.mjs): `skills/edit-timeline-studio/mcp/server.mjs`
- [Timeline command](https://github.com/martindelophy/ai-video-editor/blob/main/scripts/timeline-command.mjs): `scripts/timeline-command.mjs`

### Other components

- **Editor user**
- **Model hosts**
- **Browser runtime**

## Connections

- Editor user → Editor app: edits media
- Editor app → Timeline UI: renders timeline
- Editor app → Preview stage: renders preview
- Editor app → Timeline model: uses timeline state
- Preview stage → Timeline model: shows composition
- Editor app → Automatic captions: requests captions
- Editor app → Voice generation: requests voiceover
- Voice generation → Voice profiles: loads profiles
- Editor app → AI music: requests music
- AI music → Music inference: dispatches inference
- Music inference → Model hosts: fetches models
- Editor app → AI repair: requests repair
- Editor app → Video restoration: requests restoration
- Editor app → Smart framing: requests framing
- Editor app → Visual analysis: requests analysis
- Editor app → Vocal separation: requests separation
- Editor app → Talking avatar: requests avatar
- Talking avatar → LivePortrait inference: dispatches rendering
- LivePortrait inference → Model hosts: fetches models
- Editor app → Video export: exports composition
- Video export → Browser runtime: encodes media
- Editor app → Project archives: loads and saves
- Editor user → MCP editing server: sends edit requests
- MCP editing server → Timeline command: executes commands
- Timeline command → Project commands: applies operations
- Project commands → Project archives: reads and writes