# flashml-org/freevideo architecture

> Architecture diagram of the GitHub repository flashml-org/freevideo, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/flashml-org/freevideo
- Repository: https://github.com/flashml-org/freevideo

## Overview

FreeVideo is a local MiniMax H3 video-inference engine, exposed through a ComfyUI creative workspace and a Linux CLI, with a Windows launcher for setup. The main user flow is to configure an installation, submit a prompt and optional media references, encode conditioning, admit and run a hardware-aware sampling request, then decode and present the video. Separate branches cover model/environment deployment, ComfyUI setup and workflow UI, and resource planning and telemetry. Connections are limited to README statements and relationships visible in the supplied excerpts or SOURCE INDEX; unsampled internals are not asserted.

Main entry points: [`freevideo_engine/worker.py`](https://github.com/flashml-org/freevideo/blob/main/freevideo_engine/worker.py) (Sampling worker), [`web/studio.js`](https://github.com/flashml-org/freevideo/blob/main/web/studio.js) (Studio UI), [`freevideo_engine/adaptive.py`](https://github.com/flashml-org/freevideo/blob/main/freevideo_engine/adaptive.py) (Adaptive recovery), [`freevideo_engine/bootstrap.py`](https://github.com/flashml-org/freevideo/blob/main/freevideo_engine/bootstrap.py) (Environment setup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Creative workspace"]
  node_studio["Studio UI<br/>[studio.js]"]
  node_setupui["Setup UI<br/>[setup.js]"]
  node_engine_plugin["ComfyUI plugin<br/>[comfy_nodes.py]"]
end

subgraph group_inference["Video inference"]
  node_encoder["Media encoder<br/>[encode_worker.py]"]
  node_worker["Sampling worker<br/>[worker.py]"]
  node_runtime["Inference runtime<br/>[runtime.py]"]
  node_decoder["Video decode<br/>[decode.py]"]
  node_request["Media request<br/>[media_request.py]"]
end

subgraph group_planning["Resource planning"]
  node_policy["Resource policy<br/>[policy.py]"]
  node_adaptive["Adaptive recovery<br/>[adaptive.py]"]
  node_history[("Resource history")]
  node_monitor["Device monitoring<br/>[monitoring.py]"]
end

subgraph group_deployment["Setup and launch"]
  node_launcher["Windows launcher"]
  node_bootstrap["Environment setup<br/>[bootstrap.py]"]
  node_network["Downloads<br/>[network.py]"]
  node_storage["Model storage<br/>[storage.py]"]
end

node_user(("Creator"))
node_comfy["ComfyUI"]

node_user -->|"creates request"| node_studio
node_comfy -->|"hosts plugin"| node_engine_plugin
node_studio -->|"calls host API"| node_comfy
node_studio -->|"opens setup"| node_setupui
node_setupui -->|"setup requests"| node_comfy
node_engine_plugin -.->|"admits inputs"| node_request
node_request -.->|"encodes media"| node_encoder
node_encoder -.->|"provides conditioning"| node_worker
node_worker -->|"plans resources"| node_policy
node_worker -->|"runs inference"| node_runtime
node_runtime -->|"decodes latents"| node_decoder
node_worker -->|"recovers attempts"| node_adaptive
node_adaptive -->|"reads observations"| node_history
node_adaptive -->|"consults plan"| node_policy
node_worker -->|"samples device"| node_monitor
node_user -->|"installs runtime"| node_launcher
node_launcher -->|"sets up environment"| node_bootstrap
node_bootstrap -->|"downloads packages"| node_network
node_bootstrap -.->|"records models"| node_storage

click node_studio "https://github.com/flashml-org/freevideo/blob/main/web/studio.js"
click node_setupui "https://github.com/flashml-org/freevideo/blob/main/web/setup.js"
click node_engine_plugin "https://github.com/flashml-org/freevideo/blob/main/freevideo_engine/comfy_nodes.py"
click node_encoder "https://github.com/flashml-org/freevideo/blob/main/freevideo_engine/encode_worker.py"
click node_worker "https://github.com/flashml-org/freevideo/blob/main/freevideo_engine/worker.py"
click node_runtime "https://github.com/flashml-org/freevideo/blob/main/freevideo_engine/runtime.py"
click node_decoder "https://github.com/flashml-org/freevideo/blob/main/freevideo_engine/decode.py"
click node_request "https://github.com/flashml-org/freevideo/blob/main/freevideo_engine/media_request.py"
click node_policy "https://github.com/flashml-org/freevideo/blob/main/freevideo_engine/policy.py"
click node_adaptive "https://github.com/flashml-org/freevideo/blob/main/freevideo_engine/adaptive.py"
click node_history "https://github.com/flashml-org/freevideo/blob/main/freevideo_engine/resource_history.py"
click node_monitor "https://github.com/flashml-org/freevideo/blob/main/freevideo_engine/monitoring.py"
click node_launcher "https://github.com/flashml-org/freevideo/blob/main/freevideo_engine/launcher_session.py"
click node_bootstrap "https://github.com/flashml-org/freevideo/blob/main/freevideo_engine/bootstrap.py"
click node_network "https://github.com/flashml-org/freevideo/blob/main/freevideo_engine/network.py"
click node_storage "https://github.com/flashml-org/freevideo/blob/main/freevideo_engine/storage.py"

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_studio,node_setupui,node_engine_plugin,node_comfy toneBlue
class node_encoder,node_worker,node_runtime,node_decoder,node_request toneAmber
class node_policy,node_adaptive,node_history,node_monitor toneMint
class node_launcher,node_bootstrap,node_network,node_storage toneRose
class node_user toneIndigo
```

## Components

### Creative workspace

- [Studio UI](https://github.com/flashml-org/freevideo/blob/main/web/studio.js): `web/studio.js`
- [Setup UI](https://github.com/flashml-org/freevideo/blob/main/web/setup.js): `web/setup.js`
- [ComfyUI plugin](https://github.com/flashml-org/freevideo/blob/main/freevideo_engine/comfy_nodes.py): `freevideo_engine/comfy_nodes.py`

### Video inference

- [Media encoder](https://github.com/flashml-org/freevideo/blob/main/freevideo_engine/encode_worker.py): `freevideo_engine/encode_worker.py`
- [Sampling worker](https://github.com/flashml-org/freevideo/blob/main/freevideo_engine/worker.py): `freevideo_engine/worker.py`
- [Inference runtime](https://github.com/flashml-org/freevideo/blob/main/freevideo_engine/runtime.py): `freevideo_engine/runtime.py`
- [Video decode](https://github.com/flashml-org/freevideo/blob/main/freevideo_engine/decode.py): `freevideo_engine/decode.py`
- [Media request](https://github.com/flashml-org/freevideo/blob/main/freevideo_engine/media_request.py): `freevideo_engine/media_request.py`

### Resource planning

- [Resource policy](https://github.com/flashml-org/freevideo/blob/main/freevideo_engine/policy.py): `freevideo_engine/policy.py`
- [Adaptive recovery](https://github.com/flashml-org/freevideo/blob/main/freevideo_engine/adaptive.py): `freevideo_engine/adaptive.py`
- [Resource history](https://github.com/flashml-org/freevideo/blob/main/freevideo_engine/resource_history.py): `freevideo_engine/resource_history.py`
- [Device monitoring](https://github.com/flashml-org/freevideo/blob/main/freevideo_engine/monitoring.py): `freevideo_engine/monitoring.py`

### Setup and launch

- [Windows launcher](https://github.com/flashml-org/freevideo/blob/main/freevideo_engine/launcher_session.py): `freevideo_engine/launcher_session.py`
- [Environment setup](https://github.com/flashml-org/freevideo/blob/main/freevideo_engine/bootstrap.py): `freevideo_engine/bootstrap.py`
- [Downloads](https://github.com/flashml-org/freevideo/blob/main/freevideo_engine/network.py): `freevideo_engine/network.py`
- [Model storage](https://github.com/flashml-org/freevideo/blob/main/freevideo_engine/storage.py): `freevideo_engine/storage.py`

### Other components

- **Creator**
- **ComfyUI**

## Connections

- Creator → Studio UI: creates request (evidence: `README.md`)
- ComfyUI → ComfyUI plugin: hosts plugin (evidence: `README.md`)
- Studio UI → ComfyUI: calls host API (evidence: `web/studio.js`)
- Studio UI → Setup UI: opens setup (evidence: `web/studio.js`)
- Setup UI → ComfyUI: setup requests (evidence: `web/setup.js`)
- ComfyUI plugin → Media request: admits inputs
- Media request → Media encoder: encodes media (evidence: `freevideo_engine/encode_worker.py`)
- Media encoder → Sampling worker: provides conditioning
- Sampling worker → Resource policy: plans resources (evidence: `freevideo_engine/worker.py`)
- Sampling worker → Inference runtime: runs inference (evidence: `freevideo_engine/worker.py`)
- Inference runtime → Video decode: decodes latents (evidence: `freevideo_engine/runtime.py`)
- Sampling worker → Adaptive recovery: recovers attempts (evidence: `freevideo_engine/worker.py`)
- Adaptive recovery → Resource history: reads observations (evidence: `freevideo_engine/adaptive.py`)
- Adaptive recovery → Resource policy: consults plan (evidence: `freevideo_engine/adaptive.py`)
- Sampling worker → Device monitoring: samples device (evidence: `freevideo_engine/worker.py`)
- Creator → Windows launcher: installs runtime (evidence: `README.md`)
- Windows launcher → Environment setup: sets up environment (evidence: `freevideo_engine/launcher_session.py`)
- Environment setup → Downloads: downloads packages (evidence: `freevideo_engine/bootstrap.py`)
- Environment setup → Model storage: records models
