# henzfdev/hc-player architecture

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

- Interactive diagram: https://gitdiagram.com/henzfdev/hc-player
- Repository: https://github.com/henzfdev/hc-player

## Overview

HC Player is a native Windows media player: users open media, control playback and its queue, inspect media details, and customize playback through a WinUI interface backed by mpv. The graph preserves documented playback, subtitle/audio, HDR/shader, playlist, information, and Windows-integration capabilities. MainPage and several managers were sampled or indexed; the README supports the broader feature branches, but unsampled implementation details and call ownership are not assumed.

Main entry points: [`HC Player/MainPage.cpp`](https://github.com/henzfdev/hc-player/blob/main/HC%20Player/MainPage.cpp) (Player window), [`HC Player/SettingsPage.cpp`](https://github.com/henzfdev/hc-player/blob/main/HC%20Player/SettingsPage.cpp) (Settings UI), [`HC Player/PlayerBridge.h`](https://github.com/henzfdev/hc-player/blob/main/HC%20Player/PlayerBridge.h) (Player command bridge), [`HC Player/StoragePaths.cpp`](https://github.com/henzfdev/hc-player/blob/main/HC%20Player/StoragePaths.cpp) (User data paths)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Player interface"]
  node_main["Player window<br/>[MainPage.cpp]"]
  node_playlist["Playback queue<br/>[PlaylistPage.cpp]"]
  node_settings["Settings UI<br/>[SettingsPage.cpp]"]
  node_media_info_ui["Media details UI<br/>[MediaInfoPage.cpp]"]
  node_context["Playback context menu"]
  node_localization["UI localization"]
end

subgraph group_playback["Playback and media"]
  node_engine["mpv playback engine<br/>[HCPlayer.cpp]"]
  node_player_bridge["Player command bridge<br/>[PlayerBridge.h]"]
  node_media_info["MediaInfo analysis"]
  node_thumbnail["Timeline thumbnails"]
  node_thumbnail_control["Thumbnail requests"]
end

subgraph group_configuration["Playback configuration"]
  node_mpv_settings["mpv options and import"]
  node_shaders["Shader management<br/>[ShaderManager.cpp]"]
  node_external_tools["Optional tools"]
end

subgraph group_platform["Windows integration"]
  node_system_controls["Windows media controls"]
  node_file_associations["File associations"]
  node_portable_registration["Portable registration"]
end

subgraph group_persistence["User data"]
  node_recent["Recent media"]
  node_storage["User data paths<br/>[StoragePaths.cpp]"]
end

node_user(("Media user"))

node_user -->|"opens and controls"| node_main
node_main -.->|"issues player commands"| node_player_bridge
node_player_bridge -.->|"controls playback"| node_engine
node_main -.->|"opens queue"| node_playlist
node_main -.->|"opens settings"| node_settings
node_main -.->|"shows details"| node_media_info_ui
node_main -.->|"opens context menu"| node_context
node_playlist -.->|"manages queue"| node_player_bridge
node_settings -.->|"configures playback"| node_mpv_settings
node_settings -.->|"manages shaders"| node_shaders
node_settings -.->|"imports optional tools"| node_external_tools
node_media_info_ui -.->|"requests analysis"| node_media_info
node_main -.->|"requests previews"| node_thumbnail_control
node_thumbnail_control -.->|"decodes frames"| node_thumbnail
node_main -.->|"tracks recent media"| node_recent
node_shaders -->|"applies shader list"| node_engine
node_shaders -->|"resolves managed paths"| node_storage
node_mpv_settings -->|"resolves config paths"| node_storage
node_external_tools -->|"resolves tool paths"| node_storage
node_recent -->|"resolves data root"| node_storage
node_main -->|"publishes playback state"| node_system_controls
node_system_controls -.->|"receives transport commands"| node_player_bridge
node_user -.->|"registers media types"| node_file_associations
node_user -.->|"registers portable app"| node_portable_registration
node_main -.->|"resolves UI text"| node_localization

click node_main "https://github.com/henzfdev/hc-player/blob/main/HC%20Player/MainPage.cpp"
click node_playlist "https://github.com/henzfdev/hc-player/blob/main/HC%20Player/PlaylistPage.cpp"
click node_settings "https://github.com/henzfdev/hc-player/blob/main/HC%20Player/SettingsPage.cpp"
click node_media_info_ui "https://github.com/henzfdev/hc-player/blob/main/HC%20Player/MediaInfoPage.cpp"
click node_context "https://github.com/henzfdev/hc-player/blob/main/HC%20Player/ContextMenuPage.cpp"
click node_engine "https://github.com/henzfdev/hc-player/blob/main/HC%20Player/HCPlayer.cpp"
click node_player_bridge "https://github.com/henzfdev/hc-player/blob/main/HC%20Player/PlayerBridge.h"
click node_media_info "https://github.com/henzfdev/hc-player/blob/main/HC%20Player/MediaInfoBridge.cpp"
click node_thumbnail "https://github.com/henzfdev/hc-player/blob/main/HC%20Player/ThumbnailBridge.cpp"
click node_thumbnail_control "https://github.com/henzfdev/hc-player/blob/main/HC%20Player/ThumbnailController.cpp"
click node_mpv_settings "https://github.com/henzfdev/hc-player/blob/main/HC%20Player/MpvSettingsManager.cpp"
click node_shaders "https://github.com/henzfdev/hc-player/blob/main/HC%20Player/ShaderManager.cpp"
click node_external_tools "https://github.com/henzfdev/hc-player/blob/main/HC%20Player/ExternalToolsManager.cpp"
click node_recent "https://github.com/henzfdev/hc-player/blob/main/HC%20Player/RecentMediaManager.cpp"
click node_storage "https://github.com/henzfdev/hc-player/blob/main/HC%20Player/StoragePaths.cpp"
click node_system_controls "https://github.com/henzfdev/hc-player/blob/main/HC%20Player/SystemMediaControlsManager.cpp"
click node_file_associations "https://github.com/henzfdev/hc-player/blob/main/HC%20Player/FileAssociationManager.cpp"
click node_portable_registration "https://github.com/henzfdev/hc-player/blob/main/HC%20Player/PortableRegistrationManager.cpp"
click node_localization "https://github.com/henzfdev/hc-player/blob/main/HC%20Player/LocalizationManager.cpp"

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_main,node_playlist,node_settings,node_media_info_ui,node_context,node_localization,node_user toneBlue
class node_engine,node_player_bridge,node_media_info,node_thumbnail,node_thumbnail_control toneAmber
class node_mpv_settings,node_shaders,node_external_tools toneMint
class node_system_controls,node_file_associations,node_portable_registration toneRose
class node_recent,node_storage toneIndigo
```

## Components

### Player interface

- [Player window](https://github.com/henzfdev/hc-player/blob/main/HC%20Player/MainPage.cpp): `HC Player/MainPage.cpp`
- [Playback queue](https://github.com/henzfdev/hc-player/blob/main/HC%20Player/PlaylistPage.cpp): `HC Player/PlaylistPage.cpp`
- [Settings UI](https://github.com/henzfdev/hc-player/blob/main/HC%20Player/SettingsPage.cpp): `HC Player/SettingsPage.cpp`
- [Media details UI](https://github.com/henzfdev/hc-player/blob/main/HC%20Player/MediaInfoPage.cpp): `HC Player/MediaInfoPage.cpp`
- [Playback context menu](https://github.com/henzfdev/hc-player/blob/main/HC%20Player/ContextMenuPage.cpp): `HC Player/ContextMenuPage.cpp`
- [UI localization](https://github.com/henzfdev/hc-player/blob/main/HC%20Player/LocalizationManager.cpp): `HC Player/LocalizationManager.cpp`

### Playback and media

- [mpv playback engine](https://github.com/henzfdev/hc-player/blob/main/HC%20Player/HCPlayer.cpp): `HC Player/HCPlayer.cpp`
- [Player command bridge](https://github.com/henzfdev/hc-player/blob/main/HC%20Player/PlayerBridge.h): `HC Player/PlayerBridge.h`
- [MediaInfo analysis](https://github.com/henzfdev/hc-player/blob/main/HC%20Player/MediaInfoBridge.cpp): `HC Player/MediaInfoBridge.cpp`
- [Timeline thumbnails](https://github.com/henzfdev/hc-player/blob/main/HC%20Player/ThumbnailBridge.cpp): `HC Player/ThumbnailBridge.cpp`
- [Thumbnail requests](https://github.com/henzfdev/hc-player/blob/main/HC%20Player/ThumbnailController.cpp): `HC Player/ThumbnailController.cpp`

### Playback configuration

- [mpv options and import](https://github.com/henzfdev/hc-player/blob/main/HC%20Player/MpvSettingsManager.cpp): `HC Player/MpvSettingsManager.cpp`
- [Shader management](https://github.com/henzfdev/hc-player/blob/main/HC%20Player/ShaderManager.cpp): `HC Player/ShaderManager.cpp`
- [Optional tools](https://github.com/henzfdev/hc-player/blob/main/HC%20Player/ExternalToolsManager.cpp): `HC Player/ExternalToolsManager.cpp`

### Windows integration

- [Windows media controls](https://github.com/henzfdev/hc-player/blob/main/HC%20Player/SystemMediaControlsManager.cpp): `HC Player/SystemMediaControlsManager.cpp`
- [File associations](https://github.com/henzfdev/hc-player/blob/main/HC%20Player/FileAssociationManager.cpp): `HC Player/FileAssociationManager.cpp`
- [Portable registration](https://github.com/henzfdev/hc-player/blob/main/HC%20Player/PortableRegistrationManager.cpp): `HC Player/PortableRegistrationManager.cpp`

### User data

- [Recent media](https://github.com/henzfdev/hc-player/blob/main/HC%20Player/RecentMediaManager.cpp): `HC Player/RecentMediaManager.cpp`
- [User data paths](https://github.com/henzfdev/hc-player/blob/main/HC%20Player/StoragePaths.cpp): `HC Player/StoragePaths.cpp`

### Other components

- **Media user**

## Connections

- Media user → Player window: opens and controls (evidence: `README.md`)
- Player window → Player command bridge: issues player commands (evidence: `HC Player/MainPage.cpp`)
- Player command bridge → mpv playback engine: controls playback
- Player window → Playback queue: opens queue
- Player window → Settings UI: opens settings
- Player window → Media details UI: shows details
- Player window → Playback context menu: opens context menu
- Playback queue → Player command bridge: manages queue
- Settings UI → mpv options and import: configures playback
- Settings UI → Shader management: manages shaders
- Settings UI → Optional tools: imports optional tools
- Media details UI → MediaInfo analysis: requests analysis
- Player window → Thumbnail requests: requests previews
- Thumbnail requests → Timeline thumbnails: decodes frames
- Player window → Recent media: tracks recent media
- Shader management → mpv playback engine: applies shader list (evidence: `HC Player/ShaderManager.cpp`)
- Shader management → User data paths: resolves managed paths (evidence: `HC Player/ShaderManager.cpp`)
- mpv options and import → User data paths: resolves config paths (evidence: `HC Player/MpvSettingsManager.cpp`)
- Optional tools → User data paths: resolves tool paths (evidence: `HC Player/ExternalToolsManager.cpp`)
- Recent media → User data paths: resolves data root (evidence: `HC Player/RecentMediaManager.cpp`)
- Player window → Windows media controls: publishes playback state (evidence: `HC Player/MainPage.cpp`)
- Windows media controls → Player command bridge: receives transport commands (evidence: `HC Player/SystemMediaControlsManager.cpp`)
- Media user → File associations: registers media types
- Media user → Portable registration: registers portable app
- Player window → UI localization: resolves UI text
