# 6v17/videoseek architecture

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

- Interactive diagram: https://gitdiagram.com/6v17/videoseek
- Repository: https://github.com/6v17/videoseek

## Overview

VideoSeek is a Windows-first desktop application for indexing local video libraries and finding scenes by text or image. The main workflow is to add and sync a library, generate visual embeddings, search indexed frames or chunks, then preview and export matching clips. Other documented capabilities include hard-subtitle OCR search, optional video understanding and recap, video downloading, and a localhost Agent API. Relationships reflect the README and supplied source index/excerpts; unsampled subsystems are shown where documented, without assuming their internal call paths.

Main entry points: [`ui/controllers/search_controller.py`](https://github.com/6v17/videoseek/blob/master/ui/controllers/search_controller.py) (Search controller), [`src/core/clip_embedding.py`](https://github.com/6v17/videoseek/blob/master/src/core/clip_embedding.py) (Visual embeddings), [`src/services/search_service.py`](https://github.com/6v17/videoseek/blob/master/src/services/search_service.py) (Search service), [`src/services/search_chunk_pipeline.py`](https://github.com/6v17/videoseek/blob/master/src/services/search_chunk_pipeline.py) (Chunk search)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop workflow"]
  node_gui["Desktop UI<br/>[gui.py]"]
  node_search_ui["Search controller"]
  node_index_worker["Index worker<br/>[workers.py]"]
end

subgraph group_indexing["Indexing and models"]
  node_library["Library service<br/>[library_service.py]"]
  node_video_update["Video update flow<br/>[update_video.py]"]
  node_embeddings["Visual embeddings<br/>[clip_embedding.py]"]
  node_vision["ONNX vision engine"]
  node_config_store[("Config and profiles<br/>[config_store.py]")]
end

subgraph group_search["Search and retrieval"]
  node_search_service["Search service<br/>[search_service.py]"]
  node_chunk_search["Chunk search"]
  node_locate_search["In-video locate"]
  node_search_index[("Lance search index")]
  node_search_hit["Ranked hits<br/>[search_hit.py]"]
end

subgraph group_media["Media tools"]
  node_preview["Preview player<br/>[preview_dialog.py]"]
  node_clip_export["Clip export"]
end

subgraph group_optional["Optional capabilities"]
  node_subtitle_ocr["Subtitle OCR<br/>[ocr_pipeline.py]"]
  node_subtitle_search["Subtitle indexing"]
  node_understanding["Video understanding<br/>[pipeline.py]"]
  node_recap["Recap cuts<br/>[recap_service.py]"]
  node_agent["Localhost Agent API<br/>[service.py]"]
  node_download["Video download"]
end

node_user(("Local user"))
node_remote_vlm(("Remote vision provider"))

node_user -->|"uses"| node_gui
node_gui -.->|"routes search"| node_search_ui
node_search_ui -->|"requests search"| node_search_service
node_user -->|"syncs library"| node_index_worker
node_index_worker -->|"runs update"| node_video_update
node_video_update -.->|"updates library"| node_library
node_library -.->|"builds embeddings"| node_embeddings
node_embeddings -->|"uses engine"| node_vision
node_embeddings -->|"loads profile"| node_config_store
node_search_service -->|"runs chunk search"| node_chunk_search
node_chunk_search -->|"queries vectors"| node_search_index
node_chunk_search -->|"returns hits"| node_search_hit
node_search_service -.->|"searches index"| node_search_index
node_search_ui -->|"receives results"| node_search_hit
node_search_ui -.->|"locates hit"| node_locate_search
node_locate_search -->|"searches window"| node_search_index
node_user -->|"previews hit"| node_preview
node_preview -.->|"exports clip"| node_clip_export
node_user -->|"extracts subtitles"| node_subtitle_ocr
node_subtitle_ocr -.->|"indexes OCR text"| node_subtitle_search
node_user -->|"requests understanding"| node_understanding
node_understanding -.->|"may call provider"| node_remote_vlm
node_user -->|"plans recap"| node_recap
node_user -->|"sends HTTP request"| node_agent
node_user -->|"downloads video"| node_download

click node_gui "https://github.com/6v17/videoseek/blob/master/ui/windows/gui.py"
click node_search_ui "https://github.com/6v17/videoseek/blob/master/ui/controllers/search_controller.py"
click node_index_worker "https://github.com/6v17/videoseek/blob/master/ui/workers.py"
click node_library "https://github.com/6v17/videoseek/blob/master/src/services/library_service.py"
click node_video_update "https://github.com/6v17/videoseek/blob/master/src/workflows/update_video.py"
click node_embeddings "https://github.com/6v17/videoseek/blob/master/src/core/clip_embedding.py"
click node_vision "https://github.com/6v17/videoseek/blob/master/src/core/onnx_vision_engine.py"
click node_config_store "https://github.com/6v17/videoseek/blob/master/src/storage/config_store.py"
click node_search_service "https://github.com/6v17/videoseek/blob/master/src/services/search_service.py"
click node_chunk_search "https://github.com/6v17/videoseek/blob/master/src/services/search_chunk_pipeline.py"
click node_locate_search "https://github.com/6v17/videoseek/blob/master/src/services/search_locate_pipeline.py"
click node_search_index "https://github.com/6v17/videoseek/blob/master/src/storage/lance_search_index.py"
click node_search_hit "https://github.com/6v17/videoseek/blob/master/src/domain/search_hit.py"
click node_preview "https://github.com/6v17/videoseek/blob/master/ui/playback/preview_dialog.py"
click node_clip_export "https://github.com/6v17/videoseek/blob/master/src/services/clip_export_service.py"
click node_subtitle_ocr "https://github.com/6v17/videoseek/blob/master/src/core/subtitle_ocr/ocr_pipeline.py"
click node_subtitle_search "https://github.com/6v17/videoseek/blob/master/src/services/subtitle_index_service.py"
click node_understanding "https://github.com/6v17/videoseek/blob/master/src/core/understanding/pipeline.py"
click node_recap "https://github.com/6v17/videoseek/blob/master/src/services/recap_service.py"
click node_agent "https://github.com/6v17/videoseek/blob/master/src/web/agent_api/service.py"
click node_download "https://github.com/6v17/videoseek/blob/master/src/services/video_download_service.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_gui,node_search_ui,node_index_worker,node_user toneBlue
class node_library,node_video_update,node_embeddings,node_vision,node_config_store toneAmber
class node_search_service,node_chunk_search,node_locate_search,node_search_index,node_search_hit toneMint
class node_preview,node_clip_export toneRose
class node_subtitle_ocr,node_subtitle_search,node_understanding,node_recap,node_agent,node_download,node_remote_vlm toneIndigo
```

## Components

### Desktop workflow

- [Desktop UI](https://github.com/6v17/videoseek/blob/master/ui/windows/gui.py): `ui/windows/gui.py`
- [Search controller](https://github.com/6v17/videoseek/blob/master/ui/controllers/search_controller.py): `ui/controllers/search_controller.py`
- [Index worker](https://github.com/6v17/videoseek/blob/master/ui/workers.py): `ui/workers.py`

### Indexing and models

- [Library service](https://github.com/6v17/videoseek/blob/master/src/services/library_service.py): `src/services/library_service.py`
- [Video update flow](https://github.com/6v17/videoseek/blob/master/src/workflows/update_video.py): `src/workflows/update_video.py`
- [Visual embeddings](https://github.com/6v17/videoseek/blob/master/src/core/clip_embedding.py): `src/core/clip_embedding.py`
- [ONNX vision engine](https://github.com/6v17/videoseek/blob/master/src/core/onnx_vision_engine.py): `src/core/onnx_vision_engine.py`
- [Config and profiles](https://github.com/6v17/videoseek/blob/master/src/storage/config_store.py): `src/storage/config_store.py`

### Search and retrieval

- [Search service](https://github.com/6v17/videoseek/blob/master/src/services/search_service.py): `src/services/search_service.py`
- [Chunk search](https://github.com/6v17/videoseek/blob/master/src/services/search_chunk_pipeline.py): `src/services/search_chunk_pipeline.py`
- [In-video locate](https://github.com/6v17/videoseek/blob/master/src/services/search_locate_pipeline.py): `src/services/search_locate_pipeline.py`
- [Lance search index](https://github.com/6v17/videoseek/blob/master/src/storage/lance_search_index.py): `src/storage/lance_search_index.py`
- [Ranked hits](https://github.com/6v17/videoseek/blob/master/src/domain/search_hit.py): `src/domain/search_hit.py`

### Media tools

- [Preview player](https://github.com/6v17/videoseek/blob/master/ui/playback/preview_dialog.py): `ui/playback/preview_dialog.py`
- [Clip export](https://github.com/6v17/videoseek/blob/master/src/services/clip_export_service.py): `src/services/clip_export_service.py`

### Optional capabilities

- [Subtitle OCR](https://github.com/6v17/videoseek/blob/master/src/core/subtitle_ocr/ocr_pipeline.py): `src/core/subtitle_ocr/ocr_pipeline.py`
- [Subtitle indexing](https://github.com/6v17/videoseek/blob/master/src/services/subtitle_index_service.py): `src/services/subtitle_index_service.py`
- [Video understanding](https://github.com/6v17/videoseek/blob/master/src/core/understanding/pipeline.py): `src/core/understanding/pipeline.py`
- [Recap cuts](https://github.com/6v17/videoseek/blob/master/src/services/recap_service.py): `src/services/recap_service.py`
- [Localhost Agent API](https://github.com/6v17/videoseek/blob/master/src/web/agent_api/service.py): `src/web/agent_api/service.py`
- [Video download](https://github.com/6v17/videoseek/blob/master/src/services/video_download_service.py): `src/services/video_download_service.py`

### Other components

- **Local user**
- **Remote vision provider**

## Connections

- Local user → Desktop UI: uses (evidence: `README.md`)
- Desktop UI → Search controller: routes search
- Search controller → Search service: requests search (evidence: `ui/controllers/search_controller.py`)
- Local user → Index worker: syncs library (evidence: `README.md`)
- Index worker → Video update flow: runs update (evidence: `ui/workers.py`)
- Video update flow → Library service: updates library
- Library service → Visual embeddings: builds embeddings
- Visual embeddings → ONNX vision engine: uses engine (evidence: `src/core/clip_embedding.py`)
- Visual embeddings → Config and profiles: loads profile (evidence: `src/core/clip_embedding.py`)
- Search service → Chunk search: runs chunk search (evidence: `src/services/search_chunk_pipeline.py`)
- Chunk search → Lance search index: queries vectors (evidence: `src/services/search_chunk_pipeline.py`)
- Chunk search → Ranked hits: returns hits (evidence: `src/services/search_chunk_pipeline.py`)
- Search service → Lance search index: searches index
- Search controller → Ranked hits: receives results (evidence: `ui/controllers/search_controller.py`)
- Search controller → In-video locate: locates hit
- In-video locate → Lance search index: searches window (evidence: `src/services/search_locate_pipeline.py`)
- Local user → Preview player: previews hit (evidence: `README.md`)
- Preview player → Clip export: exports clip
- Local user → Subtitle OCR: extracts subtitles (evidence: `README.md`)
- Subtitle OCR → Subtitle indexing: indexes OCR text
- Local user → Video understanding: requests understanding (evidence: `README.md`)
- Video understanding → Remote vision provider: may call provider (evidence: `README.md`)
- Local user → Recap cuts: plans recap (evidence: `README.md`)
- Local user → Localhost Agent API: sends HTTP request (evidence: `README.md`)
- Local user → Video download: downloads video (evidence: `README.md`)
