# reco-project/video-stitcher architecture

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

- Interactive diagram: https://gitdiagram.com/reco-project/video-stitcher
- Repository: https://github.com/reco-project/video-stitcher

## Overview

Reco is a GPU-accelerated panoramic sports-video stitcher, provided as a CLI, desktop app, and OBS plugin. The main workflow is to ingest paired video or live-camera frames, calibrate camera geometry and synchronization, optionally detect and track players or a ball to drive framing, render a stitched panorama, and encode or display the result. The graph also preserves documented replay, stacked-video, operator-control, and calibration-profile capabilities. Edges use README statements or source-index references; unsampled implementation details are not asserted.

Main entry points: [`crates/reco-core/src/session/mod.rs`](https://github.com/reco-project/video-stitcher/blob/main/crates/reco-core/src/session/mod.rs) (Stitch Session), [`crates/reco-io/src/stitch_job.rs`](https://github.com/reco-project/video-stitcher/blob/main/crates/reco-io/src/stitch_job.rs) (Stitch Job), [`crates/reco-gui/src/main.rs`](https://github.com/reco-project/video-stitcher/blob/main/crates/reco-gui/src/main.rs) (Desktop App), [`crates/reco-cli/src/main.rs`](https://github.com/reco-project/video-stitcher/blob/main/crates/reco-cli/src/main.rs) (CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_consumers["Applications"]
  node_cli["CLI<br/>[main.rs]"]
  node_desktop["Desktop App<br/>[main.rs]"]
  node_obs["OBS Plugin<br/>[source.rs]"]
  node_calibrate_cmd["Calibration Command<br/>[calibrate.rs]"]
  node_obs_output["OBS Source Output<br/>[source.rs]"]
end

subgraph group_media["Media I/O"]
  node_stitch_job["Stitch Job<br/>[stitch_job.rs]"]
  node_video_decode["Video Decode<br/>[decoder.rs]"]
  node_camera_ingest["Camera Ingest<br/>[camera.rs]"]
  node_encode["Video Encoding<br/>[encoder.rs]"]
  node_replay["Replay and Stacked Video<br/>[replay.rs]"]
end

subgraph group_engine["Stitch Engine"]
  node_session["Stitch Session<br/>[mod.rs]"]
  node_gpu["GPU Context<br/>[mod.rs]"]
  node_render["Panorama Renderer<br/>[renderer.rs]"]
  node_pipeline["Stitch Pipeline<br/>[pipeline.rs]"]
end

subgraph group_vision["Calibration and Tracking"]
  node_calibration["Calibration Pipeline<br/>[pipeline.rs]"]
  node_lens_profiles[("Lens Profiles<br/>[lens_database.rs]")]
  node_tracking["Detection and Tracking<br/>[director.rs]"]
  node_inference["Inference Backends<br/>[mod.rs]"]
  node_autocam["Auto Framing<br/>[field.rs]"]
end

subgraph group_live["Live Operations"]
  node_control["Operator Controls<br/>[lib.rs]"]
  node_events["Pipeline Events<br/>[pipeline_event.rs]"]
end

node_operator(("Operator"))

node_operator -->|"invokes"| node_cli
node_operator -->|"operates"| node_desktop
node_operator -->|"configures"| node_obs
node_cli -->|"dispatches"| node_calibrate_cmd
node_cli -->|"runs"| node_stitch_job
node_calibrate_cmd -.->|"runs"| node_calibration
node_desktop -.->|"calibrates"| node_calibration
node_desktop -.->|"exports"| node_stitch_job
node_obs -->|"submits frames"| node_session
node_stitch_job -->|"decodes"| node_video_decode
node_stitch_job -->|"encodes output"| node_encode
node_stitch_job -->|"uses replay"| node_replay
node_camera_ingest -.->|"supplies frames"| node_session
node_calibration -->|"loads profiles"| node_lens_profiles
node_session -->|"dispatches detection"| node_tracking
node_tracking -.->|"runs inference"| node_inference
node_session -.->|"applies framing"| node_autocam
node_session -->|"submits frames"| node_pipeline
node_pipeline -->|"uses device"| node_gpu
node_pipeline -->|"renders"| node_render
node_session -->|"emits events"| node_events
node_control -->|"translates intent"| node_desktop
node_replay -->|"writes video"| node_encode
node_obs -.->|"presents frames"| node_obs_output

click node_cli "https://github.com/reco-project/video-stitcher/blob/main/crates/reco-cli/src/main.rs"
click node_desktop "https://github.com/reco-project/video-stitcher/blob/main/crates/reco-gui/src/main.rs"
click node_obs "https://github.com/reco-project/video-stitcher/blob/main/crates/reco-obs/src/source.rs"
click node_calibrate_cmd "https://github.com/reco-project/video-stitcher/blob/main/crates/reco-cli/src/calibrate.rs"
click node_stitch_job "https://github.com/reco-project/video-stitcher/blob/main/crates/reco-io/src/stitch_job.rs"
click node_video_decode "https://github.com/reco-project/video-stitcher/blob/main/crates/reco-io/src/ffmpeg/decoder.rs"
click node_camera_ingest "https://github.com/reco-project/video-stitcher/blob/main/crates/reco-io/src/gstreamer/camera.rs"
click node_calibration "https://github.com/reco-project/video-stitcher/blob/main/crates/reco-calibrate/src/pipeline.rs"
click node_lens_profiles "https://github.com/reco-project/video-stitcher/blob/main/crates/reco-calibrate/src/lens_database.rs"
click node_tracking "https://github.com/reco-project/video-stitcher/blob/main/crates/reco-core/src/detect/director.rs"
click node_inference "https://github.com/reco-project/video-stitcher/blob/main/crates/reco-detect/src/detectors/mod.rs"
click node_autocam "https://github.com/reco-project/video-stitcher/blob/main/crates/reco-autocam/src/panners/field.rs"
click node_session "https://github.com/reco-project/video-stitcher/blob/main/crates/reco-core/src/session/mod.rs"
click node_gpu "https://github.com/reco-project/video-stitcher/blob/main/crates/reco-core/src/gpu/mod.rs"
click node_render "https://github.com/reco-project/video-stitcher/blob/main/crates/reco-core/src/render/renderer.rs"
click node_pipeline "https://github.com/reco-project/video-stitcher/blob/main/crates/reco-core/src/render/pipeline.rs"
click node_encode "https://github.com/reco-project/video-stitcher/blob/main/crates/reco-io/src/ffmpeg/encoder.rs"
click node_replay "https://github.com/reco-project/video-stitcher/blob/main/crates/reco-io/src/stacked_video/replay.rs"
click node_control "https://github.com/reco-project/video-stitcher/blob/main/crates/reco-control/src/lib.rs"
click node_events "https://github.com/reco-project/video-stitcher/blob/main/crates/reco-core/src/detect/pipeline_event.rs"
click node_obs_output "https://github.com/reco-project/video-stitcher/blob/main/crates/reco-obs/src/source.rs"

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_cli,node_desktop,node_obs,node_calibrate_cmd,node_obs_output toneBlue
class node_stitch_job,node_video_decode,node_camera_ingest,node_encode,node_replay toneAmber
class node_session,node_gpu,node_render,node_pipeline toneMint
class node_calibration,node_lens_profiles,node_tracking,node_inference,node_autocam toneRose
class node_control,node_events,node_operator toneIndigo
```

## Components

### Applications

- [CLI](https://github.com/reco-project/video-stitcher/blob/main/crates/reco-cli/src/main.rs): `crates/reco-cli/src/main.rs`
- [Desktop App](https://github.com/reco-project/video-stitcher/blob/main/crates/reco-gui/src/main.rs): `crates/reco-gui/src/main.rs`
- [OBS Plugin](https://github.com/reco-project/video-stitcher/blob/main/crates/reco-obs/src/source.rs): `crates/reco-obs/src/source.rs`
- [Calibration Command](https://github.com/reco-project/video-stitcher/blob/main/crates/reco-cli/src/calibrate.rs): `crates/reco-cli/src/calibrate.rs`
- [OBS Source Output](https://github.com/reco-project/video-stitcher/blob/main/crates/reco-obs/src/source.rs): `crates/reco-obs/src/source.rs`

### Media I/O

- [Stitch Job](https://github.com/reco-project/video-stitcher/blob/main/crates/reco-io/src/stitch_job.rs): `crates/reco-io/src/stitch_job.rs`
- [Video Decode](https://github.com/reco-project/video-stitcher/blob/main/crates/reco-io/src/ffmpeg/decoder.rs): `crates/reco-io/src/ffmpeg/decoder.rs`
- [Camera Ingest](https://github.com/reco-project/video-stitcher/blob/main/crates/reco-io/src/gstreamer/camera.rs): `crates/reco-io/src/gstreamer/camera.rs`
- [Video Encoding](https://github.com/reco-project/video-stitcher/blob/main/crates/reco-io/src/ffmpeg/encoder.rs): `crates/reco-io/src/ffmpeg/encoder.rs`
- [Replay and Stacked Video](https://github.com/reco-project/video-stitcher/blob/main/crates/reco-io/src/stacked_video/replay.rs): `crates/reco-io/src/stacked_video/replay.rs`

### Stitch Engine

- [Stitch Session](https://github.com/reco-project/video-stitcher/blob/main/crates/reco-core/src/session/mod.rs): `crates/reco-core/src/session/mod.rs`
- [GPU Context](https://github.com/reco-project/video-stitcher/blob/main/crates/reco-core/src/gpu/mod.rs): `crates/reco-core/src/gpu/mod.rs`
- [Panorama Renderer](https://github.com/reco-project/video-stitcher/blob/main/crates/reco-core/src/render/renderer.rs): `crates/reco-core/src/render/renderer.rs`
- [Stitch Pipeline](https://github.com/reco-project/video-stitcher/blob/main/crates/reco-core/src/render/pipeline.rs): `crates/reco-core/src/render/pipeline.rs`

### Calibration and Tracking

- [Calibration Pipeline](https://github.com/reco-project/video-stitcher/blob/main/crates/reco-calibrate/src/pipeline.rs): `crates/reco-calibrate/src/pipeline.rs`
- [Lens Profiles](https://github.com/reco-project/video-stitcher/blob/main/crates/reco-calibrate/src/lens_database.rs): `crates/reco-calibrate/src/lens_database.rs`
- [Detection and Tracking](https://github.com/reco-project/video-stitcher/blob/main/crates/reco-core/src/detect/director.rs): `crates/reco-core/src/detect/director.rs`
- [Inference Backends](https://github.com/reco-project/video-stitcher/blob/main/crates/reco-detect/src/detectors/mod.rs): `crates/reco-detect/src/detectors/mod.rs`
- [Auto Framing](https://github.com/reco-project/video-stitcher/blob/main/crates/reco-autocam/src/panners/field.rs): `crates/reco-autocam/src/panners/field.rs`

### Live Operations

- [Operator Controls](https://github.com/reco-project/video-stitcher/blob/main/crates/reco-control/src/lib.rs): `crates/reco-control/src/lib.rs`
- [Pipeline Events](https://github.com/reco-project/video-stitcher/blob/main/crates/reco-core/src/detect/pipeline_event.rs): `crates/reco-core/src/detect/pipeline_event.rs`

### Other components

- **Operator**

## Connections

- Operator → CLI: invokes (evidence: `README.md`)
- Operator → Desktop App: operates (evidence: `README.md`)
- Operator → OBS Plugin: configures (evidence: `README.md`)
- CLI → Calibration Command: dispatches (evidence: `crates/reco-cli/src/main.rs`)
- CLI → Stitch Job: runs (evidence: `README.md`)
- Calibration Command → Calibration Pipeline: runs
- Desktop App → Calibration Pipeline: calibrates
- Desktop App → Stitch Job: exports
- OBS Plugin → Stitch Session: submits frames (evidence: `README.md`)
- Stitch Job → Video Decode: decodes (evidence: `crates/reco-io/src/stitch_job.rs`)
- Stitch Job → Video Encoding: encodes output (evidence: `crates/reco-io/src/stitch_job.rs`)
- Stitch Job → Replay and Stacked Video: uses replay (evidence: `crates/reco-io/src/stitch_job.rs`)
- Camera Ingest → Stitch Session: supplies frames
- Calibration Pipeline → Lens Profiles: loads profiles (evidence: `crates/reco-calibrate/src/pipeline.rs`)
- Stitch Session → Detection and Tracking: dispatches detection (evidence: `crates/reco-core/src/session/mod.rs`)
- Detection and Tracking → Inference Backends: runs inference
- Stitch Session → Auto Framing: applies framing
- Stitch Session → Stitch Pipeline: submits frames (evidence: `crates/reco-core/src/session/mod.rs`)
- Stitch Pipeline → GPU Context: uses device (evidence: `crates/reco-core/src/render/pipeline.rs`)
- Stitch Pipeline → Panorama Renderer: renders (evidence: `crates/reco-core/src/render/pipeline.rs`)
- Stitch Session → Pipeline Events: emits events (evidence: `crates/reco-core/src/detect/pipeline_event.rs`)
- Operator Controls → Desktop App: translates intent (evidence: `crates/reco-gui/src/main.rs`)
- Replay and Stacked Video → Video Encoding: writes video
- OBS Plugin → OBS Source Output: presents frames (evidence: `crates/reco-obs/src/source.rs`)
