# huangchihhungleo/claude-real-video architecture

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

- Interactive diagram: https://gitdiagram.com/huangchihhungleo/claude-real-video
- Repository: https://github.com/huangchihhungleo/claude-real-video

## Overview

claude-real-video is a local video-analysis tool that turns a URL or file into timestamped keyframes and a transcript for an LLM, with CLI, local web, and MCP entry points. The main flow is source acquisition, windowed scene-aware frame selection and deduplication, optional transcription and speaker labeling, then browsable or machine-readable outputs. A separate recall flow indexes analyses locally for later cross-video search. Core internals are represented at the capability level; the sampled core.py excerpt is partial, so uncertain implementation wiring is omitted.

Main entry points: [`src/claude_real_video/core.py`](https://github.com/huangchihhungleo/claude-real-video/blob/master/src/claude_real_video/core.py) (Analysis pipeline), [`src/claude_real_video/mcp_server.py`](https://github.com/huangchihhungleo/claude-real-video/blob/master/src/claude_real_video/mcp_server.py) (MCP server), [`src/claude_real_video/cli.py`](https://github.com/huangchihhungleo/claude-real-video/blob/master/src/claude_real_video/cli.py) (CLI), [`src/claude_real_video/memory.py`](https://github.com/huangchihhungleo/claude-real-video/blob/master/src/claude_real_video/memory.py) (Memory index)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_cli["CLI<br/>[cli.py]"]
  node_web["Local web UI<br/>[serve.py]"]
  node_mcp["MCP server<br/>[mcp_server.py]"]
end

subgraph group_analysis["Video analysis"]
  node_core["Analysis pipeline<br/>[core.py]"]
  node_window["Time window<br/>[core.py]"]
  node_frames["Scene frames<br/>[core.py]"]
  node_transcript["Transcription<br/>[core.py]"]
  node_speakers["Speaker labels<br/>[speakers.py]"]
  node_temporal["Temporal check<br/>[temporal_check.py]"]
end

subgraph group_outputs["Analysis outputs"]
  node_artifacts["Output artifacts<br/>[core.py]"]
  node_viewer["Local viewer<br/>[viewer.py]"]
end

subgraph group_recall["Persistent recall"]
  node_memory[("Memory index<br/>[memory.py]")]
  node_ask["Cross-video search<br/>[memory.py]"]
end

node_person(("User"))
node_agent(("LLM agent"))
node_source["URL or file"]
node_ffmpeg["ffmpeg"]
node_whisper["Whisper backend"]
node_diarization["sherpa-onnx"]

node_person -->|"runs analysis"| node_cli
node_person -->|"submits video"| node_web
node_agent -->|"requests analysis"| node_mcp
node_cli -->|"calls pipeline"| node_core
node_web -->|"launches command"| node_cli
node_mcp -->|"calls pipeline"| node_core
node_source -->|"provides video"| node_core
node_core -->|"applies range"| node_window
node_window -->|"selects keyframes"| node_frames
node_core -->|"extracts video data"| node_ffmpeg
node_core -->|"transcribes audio"| node_transcript
node_transcript -.->|"uses backend"| node_whisper
node_transcript -.->|"adds speaker labels"| node_speakers
node_core -->|"checks timing"| node_temporal
node_core -->|"writes results"| node_artifacts
node_cli -->|"generates viewer"| node_viewer
node_artifacts -->|"reads frames and transcript"| node_viewer
node_cli -->|"indexes analysis"| node_memory
node_mcp -->|"indexes analysis"| node_memory
node_artifacts -->|"reads manifest and transcript"| node_memory
node_person -->|"searches videos"| node_ask
node_ask -->|"queries index"| node_memory
node_mcp -->|"searches memory"| node_ask
node_mcp -->|"returns frames and transcript"| node_agent

click node_cli "https://github.com/huangchihhungleo/claude-real-video/blob/master/src/claude_real_video/cli.py"
click node_web "https://github.com/huangchihhungleo/claude-real-video/blob/master/src/claude_real_video/serve.py"
click node_mcp "https://github.com/huangchihhungleo/claude-real-video/blob/master/src/claude_real_video/mcp_server.py"
click node_core "https://github.com/huangchihhungleo/claude-real-video/blob/master/src/claude_real_video/core.py"
click node_window "https://github.com/huangchihhungleo/claude-real-video/blob/master/src/claude_real_video/core.py"
click node_frames "https://github.com/huangchihhungleo/claude-real-video/blob/master/src/claude_real_video/core.py"
click node_transcript "https://github.com/huangchihhungleo/claude-real-video/blob/master/src/claude_real_video/core.py"
click node_speakers "https://github.com/huangchihhungleo/claude-real-video/blob/master/src/claude_real_video/speakers.py"
click node_temporal "https://github.com/huangchihhungleo/claude-real-video/blob/master/src/claude_real_video/temporal_check.py"
click node_artifacts "https://github.com/huangchihhungleo/claude-real-video/blob/master/src/claude_real_video/core.py"
click node_viewer "https://github.com/huangchihhungleo/claude-real-video/blob/master/src/claude_real_video/viewer.py"
click node_memory "https://github.com/huangchihhungleo/claude-real-video/blob/master/src/claude_real_video/memory.py"
click node_ask "https://github.com/huangchihhungleo/claude-real-video/blob/master/src/claude_real_video/memory.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_cli,node_web,node_mcp,node_person toneBlue
class node_core,node_window,node_frames,node_transcript,node_speakers,node_temporal toneAmber
class node_artifacts,node_viewer toneMint
class node_memory,node_ask toneRose
class node_agent,node_source,node_ffmpeg,node_whisper,node_diarization toneIndigo
```

## Components

### User interfaces

- [CLI](https://github.com/huangchihhungleo/claude-real-video/blob/master/src/claude_real_video/cli.py): `src/claude_real_video/cli.py`
- [Local web UI](https://github.com/huangchihhungleo/claude-real-video/blob/master/src/claude_real_video/serve.py): `src/claude_real_video/serve.py`
- [MCP server](https://github.com/huangchihhungleo/claude-real-video/blob/master/src/claude_real_video/mcp_server.py): `src/claude_real_video/mcp_server.py`

### Video analysis

- [Analysis pipeline](https://github.com/huangchihhungleo/claude-real-video/blob/master/src/claude_real_video/core.py): `src/claude_real_video/core.py`
- [Time window](https://github.com/huangchihhungleo/claude-real-video/blob/master/src/claude_real_video/core.py): `src/claude_real_video/core.py`
- [Scene frames](https://github.com/huangchihhungleo/claude-real-video/blob/master/src/claude_real_video/core.py): `src/claude_real_video/core.py`
- [Transcription](https://github.com/huangchihhungleo/claude-real-video/blob/master/src/claude_real_video/core.py): `src/claude_real_video/core.py`
- [Speaker labels](https://github.com/huangchihhungleo/claude-real-video/blob/master/src/claude_real_video/speakers.py): `src/claude_real_video/speakers.py`
- [Temporal check](https://github.com/huangchihhungleo/claude-real-video/blob/master/src/claude_real_video/temporal_check.py): `src/claude_real_video/temporal_check.py`

### Analysis outputs

- [Output artifacts](https://github.com/huangchihhungleo/claude-real-video/blob/master/src/claude_real_video/core.py): `src/claude_real_video/core.py`
- [Local viewer](https://github.com/huangchihhungleo/claude-real-video/blob/master/src/claude_real_video/viewer.py): `src/claude_real_video/viewer.py`

### Persistent recall

- [Memory index](https://github.com/huangchihhungleo/claude-real-video/blob/master/src/claude_real_video/memory.py): `src/claude_real_video/memory.py`
- [Cross-video search](https://github.com/huangchihhungleo/claude-real-video/blob/master/src/claude_real_video/memory.py): `src/claude_real_video/memory.py`

### Other components

- **User**
- **LLM agent**
- **URL or file**
- **ffmpeg**
- **Whisper backend**
- **sherpa-onnx**

## Connections

- User → CLI: runs analysis
- User → Local web UI: submits video
- LLM agent → MCP server: requests analysis
- CLI → Analysis pipeline: calls pipeline
- Local web UI → CLI: launches command
- MCP server → Analysis pipeline: calls pipeline
- URL or file → Analysis pipeline: provides video
- Analysis pipeline → Time window: applies range
- Time window → Scene frames: selects keyframes
- Analysis pipeline → ffmpeg: extracts video data
- Analysis pipeline → Transcription: transcribes audio
- Transcription → Whisper backend: uses backend
- Transcription → Speaker labels: adds speaker labels
- Analysis pipeline → Temporal check: checks timing
- Analysis pipeline → Output artifacts: writes results
- CLI → Local viewer: generates viewer
- Output artifacts → Local viewer: reads frames and transcript
- CLI → Memory index: indexes analysis
- MCP server → Memory index: indexes analysis
- Output artifacts → Memory index: reads manifest and transcript
- User → Cross-video search: searches videos
- Cross-video search → Memory index: queries index
- MCP server → Cross-video search: searches memory
- MCP server → LLM agent: returns frames and transcript