# azhagurajpandians/vfx-player architecture

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

- Interactive diagram: https://gitdiagram.com/azhagurajpandians/vfx-player
- Repository: https://github.com/azhagurajpandians/vfx-player

## Overview

VFX Review Player is a desktop review application whose primary workflow is loading media into a frame-accurate player, reviewing and comparing shots, applying color transforms and annotations, then exporting a slate-and-burn-in delivery or publishing review notes to Kitsu. The README documents the playback, comparison, grading, tracking, and delivery capabilities; sampled source confirms the timeline, color, playlist, annotation, export, and Kitsu responsibilities. Some subsystem wiring is documented rather than shown in the excerpts, so the graph omits uncertain call links.

Main entry points: [`gui/main_window.py`](https://github.com/azhagurajpandians/vfx-player/blob/main/gui/main_window.py) (Review Window), [`core/player_core.py`](https://github.com/azhagurajpandians/vfx-player/blob/main/core/player_core.py) (Media Player), [`gui/export_dialog.py`](https://github.com/azhagurajpandians/vfx-player/blob/main/gui/export_dialog.py) (Export Dialog), [`gui/vispy_viewport.py`](https://github.com/azhagurajpandians/vfx-player/blob/main/gui/vispy_viewport.py) (GPU Viewport)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_playback["Playback"]
  node_player["Media Player<br/>[player_core.py]"]
  node_timeline["Timeline &amp; Timecode"]
  node_playlist["Playlist Service"]
  node_playlist_ui["Playlist Browser<br/>[playlist_widget.py]"]
  node_version["Version Detection"]
end

subgraph group_review["Review"]
  node_app["Review Window<br/>[main_window.py]"]
  node_viewport["GPU Viewport<br/>[vispy_viewport.py]"]
  node_annotations["Annotations"]
end

subgraph group_color["Color"]
  node_color_manager["OCIO Manager<br/>[color_manager.py]"]
  node_color_pipeline["Grade Pipeline<br/>[color_pipeline.py]"]
  node_ocio_configs["ACES Configurations"]
  node_scopes["Scopes &amp; Analysis<br/>[scopes_dialog.py]"]
end

subgraph group_delivery["Delivery"]
  node_export["Export Dialog<br/>[export_dialog.py]"]
  node_slate["Slate Builder<br/>[slate_builder.py]"]
end

subgraph group_studio["Studio"]
  node_kitsu_ui["Kitsu Workflow UI<br/>[kitsu_dialog.py]"]
  node_kitsu["Kitsu Service<br/>[kitsu_service.py]"]
end

node_user(("Reviewer"))
node_media["Source Media"]
node_delivery_files["Rendered Delivery"]
node_kitsu_server["Kitsu / Zou"]
node_review_sidecars["Review Sidecars"]

node_user -->|"operates"| node_app
node_app -->|"controls playback"| node_player
node_media -->|"decoded frames"| node_player
node_player -->|"maps frames"| node_timeline
node_app -->|"manages shots"| node_playlist_ui
node_playlist_ui -->|"updates playlist"| node_playlist
node_app -->|"finds versions"| node_version
node_player -->|"supplies frames"| node_viewport
node_app -->|"sets review state"| node_viewport
node_app -->|"manages markup"| node_annotations
node_annotations -->|"saves annotations"| node_review_sidecars
node_app -->|"selects color config"| node_color_manager
node_color_manager -->|"loads transforms"| node_ocio_configs
node_app -->|"updates grade"| node_color_pipeline
node_color_pipeline -->|"transforms frames"| node_viewport
node_app -->|"opens scopes"| node_scopes
node_app -->|"configures export"| node_export
node_export -->|"reads frames"| node_player
node_export -->|"generates slate"| node_slate
node_export -->|"renders output"| node_delivery_files
node_app -->|"starts tracking workflow"| node_kitsu_ui
node_kitsu_ui -->|"requests tracking actions"| node_kitsu
node_kitsu -.->|"syncs reviews"| node_kitsu_server

click node_app "https://github.com/azhagurajpandians/vfx-player/blob/main/gui/main_window.py"
click node_player "https://github.com/azhagurajpandians/vfx-player/blob/main/core/player_core.py"
click node_timeline "https://github.com/azhagurajpandians/vfx-player/blob/main/core/timeline_service.py"
click node_playlist "https://github.com/azhagurajpandians/vfx-player/blob/main/core/playlist_service.py"
click node_playlist_ui "https://github.com/azhagurajpandians/vfx-player/blob/main/gui/playlist_widget.py"
click node_version "https://github.com/azhagurajpandians/vfx-player/blob/main/core/version_detector.py"
click node_viewport "https://github.com/azhagurajpandians/vfx-player/blob/main/gui/vispy_viewport.py"
click node_annotations "https://github.com/azhagurajpandians/vfx-player/blob/main/core/annotation_service.py"
click node_color_manager "https://github.com/azhagurajpandians/vfx-player/blob/main/core/color_manager.py"
click node_color_pipeline "https://github.com/azhagurajpandians/vfx-player/blob/main/core/color_pipeline.py"
click node_ocio_configs "https://github.com/azhagurajpandians/vfx-player/tree/main/configs/ocio/python/aces_ocio"
click node_scopes "https://github.com/azhagurajpandians/vfx-player/blob/main/gui/scopes_dialog.py"
click node_export "https://github.com/azhagurajpandians/vfx-player/blob/main/gui/export_dialog.py"
click node_slate "https://github.com/azhagurajpandians/vfx-player/blob/main/core/slate_builder.py"
click node_kitsu_ui "https://github.com/azhagurajpandians/vfx-player/blob/main/gui/kitsu_dialog.py"
click node_kitsu "https://github.com/azhagurajpandians/vfx-player/blob/main/core/kitsu_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_player,node_timeline,node_playlist,node_playlist_ui,node_version,node_user,node_review_sidecars toneBlue
class node_app,node_viewport,node_annotations toneAmber
class node_color_manager,node_color_pipeline,node_ocio_configs,node_scopes toneMint
class node_export,node_slate toneRose
class node_kitsu_ui,node_kitsu,node_media,node_delivery_files,node_kitsu_server toneIndigo
```

## Components

### Playback

- [Media Player](https://github.com/azhagurajpandians/vfx-player/blob/main/core/player_core.py): `core/player_core.py`
- [Timeline & Timecode](https://github.com/azhagurajpandians/vfx-player/blob/main/core/timeline_service.py): `core/timeline_service.py`
- [Playlist Service](https://github.com/azhagurajpandians/vfx-player/blob/main/core/playlist_service.py): `core/playlist_service.py`
- [Playlist Browser](https://github.com/azhagurajpandians/vfx-player/blob/main/gui/playlist_widget.py): `gui/playlist_widget.py`
- [Version Detection](https://github.com/azhagurajpandians/vfx-player/blob/main/core/version_detector.py): `core/version_detector.py`

### Review

- [Review Window](https://github.com/azhagurajpandians/vfx-player/blob/main/gui/main_window.py): `gui/main_window.py`
- [GPU Viewport](https://github.com/azhagurajpandians/vfx-player/blob/main/gui/vispy_viewport.py): `gui/vispy_viewport.py`
- [Annotations](https://github.com/azhagurajpandians/vfx-player/blob/main/core/annotation_service.py): `core/annotation_service.py`

### Color

- [OCIO Manager](https://github.com/azhagurajpandians/vfx-player/blob/main/core/color_manager.py): `core/color_manager.py`
- [Grade Pipeline](https://github.com/azhagurajpandians/vfx-player/blob/main/core/color_pipeline.py): `core/color_pipeline.py`
- [ACES Configurations](https://github.com/azhagurajpandians/vfx-player/tree/main/configs/ocio/python/aces_ocio): `configs/ocio/python/aces_ocio`
- [Scopes & Analysis](https://github.com/azhagurajpandians/vfx-player/blob/main/gui/scopes_dialog.py): `gui/scopes_dialog.py`

### Delivery

- [Export Dialog](https://github.com/azhagurajpandians/vfx-player/blob/main/gui/export_dialog.py): `gui/export_dialog.py`
- [Slate Builder](https://github.com/azhagurajpandians/vfx-player/blob/main/core/slate_builder.py): `core/slate_builder.py`

### Studio

- [Kitsu Workflow UI](https://github.com/azhagurajpandians/vfx-player/blob/main/gui/kitsu_dialog.py): `gui/kitsu_dialog.py`
- [Kitsu Service](https://github.com/azhagurajpandians/vfx-player/blob/main/core/kitsu_service.py): `core/kitsu_service.py`

### Other components

- **Reviewer**
- **Source Media**
- **Rendered Delivery**
- **Kitsu / Zou**
- **Review Sidecars**

## Connections

- Reviewer → Review Window: operates
- Review Window → Media Player: controls playback
- Source Media → Media Player: decoded frames
- Media Player → Timeline & Timecode: maps frames
- Review Window → Playlist Browser: manages shots
- Playlist Browser → Playlist Service: updates playlist
- Review Window → Version Detection: finds versions
- Media Player → GPU Viewport: supplies frames
- Review Window → GPU Viewport: sets review state
- Review Window → Annotations: manages markup
- Annotations → Review Sidecars: saves annotations
- Review Window → OCIO Manager: selects color config
- OCIO Manager → ACES Configurations: loads transforms
- Review Window → Grade Pipeline: updates grade
- Grade Pipeline → GPU Viewport: transforms frames
- Review Window → Scopes & Analysis: opens scopes
- Review Window → Export Dialog: configures export
- Export Dialog → Media Player: reads frames
- Export Dialog → Slate Builder: generates slate
- Export Dialog → Rendered Delivery: renders output
- Review Window → Kitsu Workflow UI: starts tracking workflow
- Kitsu Workflow UI → Kitsu Service: requests tracking actions
- Kitsu Service → Kitsu / Zou: syncs reviews