# sanjeev-naik/naikavplayer architecture

> Architecture diagram of the GitHub repository sanjeev-naik/naikavplayer, 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/sanjeev-naik/naikavplayer
- Repository: https://github.com/sanjeev-naik/naikavplayer

## Overview

NaikAVPlayer is a native media player and audio/video processing engine. Its principal workflow is selecting media, demuxing packets, decoding audio/video/subtitles, processing streams, and presenting synchronized playback through the UI. The graph includes documented HDR/color, playlist, DSP, and diagnostics capabilities. Source excerpts and the SOURCE INDEX establish many module references; some runtime calls and UI wiring were not shown, so those relationships are omitted or marked unverified.

Main entry points: [`src/player/PlayerController.cpp`](https://github.com/sanjeev-naik/naikavplayer/blob/main/src/player/PlayerController.cpp) (Playback Controller), [`src/audio/AudioDecoder.cpp`](https://github.com/sanjeev-naik/naikavplayer/blob/main/src/audio/AudioDecoder.cpp) (Audio Decoder), [`src/audio/dsp/DspChain.hpp`](https://github.com/sanjeev-naik/naikavplayer/blob/main/src/audio/dsp/DspChain.hpp) (DSP Chain), [`src/app/main.cpp`](https://github.com/sanjeev-naik/naikavplayer/blob/main/src/app/main.cpp) (Application Loop)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_playback["Playback Control"]
  node_app["Application Loop<br/>[main.cpp]"]
  node_ui["Player UI<br/>[PlayerUI.cpp]"]
  node_controller["Playback Controller"]
end

subgraph group_media["Media Pipeline"]
  node_demuxer["Demuxer<br/>[Demuxer.cpp]"]
  node_queue["Thread-Safe Queues"]
  node_subtitle_decoder["Subtitle Decoder"]
  node_subtitle_track["Subtitle Events<br/>[SubtitleTrack.hpp]"]
end

subgraph group_audio["Audio Processing"]
  node_audio_decoder["Audio Decoder<br/>[AudioDecoder.cpp]"]
  node_dsp_chain["DSP Chain<br/>[DspChain.hpp]"]
  node_equalizer["Parametric EQ<br/>[ParametricEQ.hpp]"]
  node_biquad["Biquad Filters<br/>[Biquad.hpp]"]
  node_noise_gate["Noise Gate<br/>[NoiseGate.hpp]"]
  node_compressors["Compressors<br/>[Compressor.hpp]"]
  node_limiter["Limiter<br/>[Limiter.hpp]"]
  node_loudness["Loudness Tools"]
  node_loudness_prescan["Loudness Prescan"]
end

subgraph group_video["Video Processing"]
  node_video_decoder["Video Decoder<br/>[VideoDecoder.cpp]"]
  node_tone_mapper["HDR Tone Mapper<br/>[ToneMapper.hpp]"]
  node_color_adjust["Color Adjustment<br/>[ColorAdjust.hpp]"]
  node_frame_export["Frame Export<br/>[FrameExporter.hpp]"]
end

subgraph group_support["Player Features"]
  node_playlist["Playlist<br/>[Playlist.hpp]"]
  node_filter["Media Filter"]
  node_playlist_io["Playlist I/O<br/>[PlaylistIO.hpp]"]
  node_metrics["Pipeline Metrics"]
  node_metric_ring["Metric Rings<br/>[MetricRing.hpp]"]
end

node_user(("User"))

node_user -->|"operates"| node_ui
node_app -.->|"coordinates"| node_controller
node_app -.->|"presents"| node_ui
node_playlist -->|"classifies files"| node_filter
node_playlist -->|"uses"| node_playlist_io
node_controller -->|"uses"| node_playlist
node_controller -->|"coordinates"| node_demuxer
node_controller -->|"coordinates"| node_audio_decoder
node_controller -->|"coordinates"| node_video_decoder
node_controller -->|"coordinates"| node_subtitle_decoder
node_controller -->|"tracks pipeline"| node_metrics
node_demuxer -->|"queues packets"| node_queue
node_audio_decoder -->|"consumes packets"| node_queue
node_video_decoder -->|"consumes packets"| node_queue
node_demuxer -->|"discovers tracks"| node_subtitle_track
node_subtitle_decoder -->|"produces events"| node_subtitle_track
node_audio_decoder -->|"processes audio"| node_dsp_chain
node_audio_decoder -->|"uses"| node_limiter
node_audio_decoder -->|"normalizes"| node_loudness
node_audio_decoder -->|"prescans"| node_loudness_prescan
node_dsp_chain -->|"runs"| node_equalizer
node_dsp_chain -->|"runs"| node_noise_gate
node_dsp_chain -->|"runs"| node_compressors
node_dsp_chain -->|"runs"| node_limiter
node_equalizer -->|"filters with"| node_biquad
node_video_decoder -->|"maps HDR"| node_tone_mapper
node_video_decoder -->|"adjusts picture"| node_color_adjust
node_ui -->|"controls playback"| node_controller
node_metrics -->|"records samples"| node_metric_ring
node_app -->|"classifies inputs"| node_filter
node_app -.->|"uses exporter"| node_frame_export

click node_app "https://github.com/sanjeev-naik/naikavplayer/blob/main/src/app/main.cpp"
click node_ui "https://github.com/sanjeev-naik/naikavplayer/blob/main/src/ui/PlayerUI.cpp"
click node_controller "https://github.com/sanjeev-naik/naikavplayer/blob/main/src/player/PlayerController.cpp"
click node_playlist "https://github.com/sanjeev-naik/naikavplayer/blob/main/src/playlist/Playlist.hpp"
click node_filter "https://github.com/sanjeev-naik/naikavplayer/blob/main/src/playlist/MediaFileFilter.hpp"
click node_playlist_io "https://github.com/sanjeev-naik/naikavplayer/blob/main/src/playlist/PlaylistIO.hpp"
click node_demuxer "https://github.com/sanjeev-naik/naikavplayer/blob/main/src/media/Demuxer.cpp"
click node_queue "https://github.com/sanjeev-naik/naikavplayer/blob/main/src/core/ThreadSafeQueue.hpp"
click node_audio_decoder "https://github.com/sanjeev-naik/naikavplayer/blob/main/src/audio/AudioDecoder.cpp"
click node_dsp_chain "https://github.com/sanjeev-naik/naikavplayer/blob/main/src/audio/dsp/DspChain.hpp"
click node_equalizer "https://github.com/sanjeev-naik/naikavplayer/blob/main/src/audio/dsp/ParametricEQ.hpp"
click node_biquad "https://github.com/sanjeev-naik/naikavplayer/blob/main/src/audio/dsp/Biquad.hpp"
click node_noise_gate "https://github.com/sanjeev-naik/naikavplayer/blob/main/src/audio/dsp/NoiseGate.hpp"
click node_compressors "https://github.com/sanjeev-naik/naikavplayer/blob/main/src/audio/dsp/Compressor.hpp"
click node_limiter "https://github.com/sanjeev-naik/naikavplayer/blob/main/src/audio/dsp/Limiter.hpp"
click node_loudness "https://github.com/sanjeev-naik/naikavplayer/blob/main/src/audio/dsp/LoudnessNormalizer.hpp"
click node_loudness_prescan "https://github.com/sanjeev-naik/naikavplayer/blob/main/src/audio/dsp/LoudnessPrescan.hpp"
click node_video_decoder "https://github.com/sanjeev-naik/naikavplayer/blob/main/src/video/VideoDecoder.cpp"
click node_tone_mapper "https://github.com/sanjeev-naik/naikavplayer/blob/main/src/video/ToneMapper.hpp"
click node_color_adjust "https://github.com/sanjeev-naik/naikavplayer/blob/main/src/video/ColorAdjust.hpp"
click node_frame_export "https://github.com/sanjeev-naik/naikavplayer/blob/main/src/video/FrameExporter.hpp"
click node_subtitle_decoder "https://github.com/sanjeev-naik/naikavplayer/blob/main/src/subtitle/SubtitleDecoder.cpp"
click node_subtitle_track "https://github.com/sanjeev-naik/naikavplayer/blob/main/src/subtitle/SubtitleTrack.hpp"
click node_metrics "https://github.com/sanjeev-naik/naikavplayer/blob/main/src/core/PipelineMetrics.hpp"
click node_metric_ring "https://github.com/sanjeev-naik/naikavplayer/blob/main/src/core/MetricRing.hpp"

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_app,node_ui,node_controller,node_user toneBlue
class node_demuxer,node_queue,node_subtitle_decoder,node_subtitle_track toneAmber
class node_audio_decoder,node_dsp_chain,node_equalizer,node_biquad,node_noise_gate,node_compressors,node_limiter,node_loudness,node_loudness_prescan toneMint
class node_video_decoder,node_tone_mapper,node_color_adjust,node_frame_export toneRose
class node_playlist,node_filter,node_playlist_io,node_metrics,node_metric_ring toneIndigo
```

## Components

### Playback Control

- [Application Loop](https://github.com/sanjeev-naik/naikavplayer/blob/main/src/app/main.cpp): `src/app/main.cpp`
- [Player UI](https://github.com/sanjeev-naik/naikavplayer/blob/main/src/ui/PlayerUI.cpp): `src/ui/PlayerUI.cpp`
- [Playback Controller](https://github.com/sanjeev-naik/naikavplayer/blob/main/src/player/PlayerController.cpp): `src/player/PlayerController.cpp`

### Media Pipeline

- [Demuxer](https://github.com/sanjeev-naik/naikavplayer/blob/main/src/media/Demuxer.cpp): `src/media/Demuxer.cpp`
- [Thread-Safe Queues](https://github.com/sanjeev-naik/naikavplayer/blob/main/src/core/ThreadSafeQueue.hpp): `src/core/ThreadSafeQueue.hpp`
- [Subtitle Decoder](https://github.com/sanjeev-naik/naikavplayer/blob/main/src/subtitle/SubtitleDecoder.cpp): `src/subtitle/SubtitleDecoder.cpp`
- [Subtitle Events](https://github.com/sanjeev-naik/naikavplayer/blob/main/src/subtitle/SubtitleTrack.hpp): `src/subtitle/SubtitleTrack.hpp`

### Audio Processing

- [Audio Decoder](https://github.com/sanjeev-naik/naikavplayer/blob/main/src/audio/AudioDecoder.cpp): `src/audio/AudioDecoder.cpp`
- [DSP Chain](https://github.com/sanjeev-naik/naikavplayer/blob/main/src/audio/dsp/DspChain.hpp): `src/audio/dsp/DspChain.hpp`
- [Parametric EQ](https://github.com/sanjeev-naik/naikavplayer/blob/main/src/audio/dsp/ParametricEQ.hpp): `src/audio/dsp/ParametricEQ.hpp`
- [Biquad Filters](https://github.com/sanjeev-naik/naikavplayer/blob/main/src/audio/dsp/Biquad.hpp): `src/audio/dsp/Biquad.hpp`
- [Noise Gate](https://github.com/sanjeev-naik/naikavplayer/blob/main/src/audio/dsp/NoiseGate.hpp): `src/audio/dsp/NoiseGate.hpp`
- [Compressors](https://github.com/sanjeev-naik/naikavplayer/blob/main/src/audio/dsp/Compressor.hpp): `src/audio/dsp/Compressor.hpp`
- [Limiter](https://github.com/sanjeev-naik/naikavplayer/blob/main/src/audio/dsp/Limiter.hpp): `src/audio/dsp/Limiter.hpp`
- [Loudness Tools](https://github.com/sanjeev-naik/naikavplayer/blob/main/src/audio/dsp/LoudnessNormalizer.hpp): `src/audio/dsp/LoudnessNormalizer.hpp`
- [Loudness Prescan](https://github.com/sanjeev-naik/naikavplayer/blob/main/src/audio/dsp/LoudnessPrescan.hpp): `src/audio/dsp/LoudnessPrescan.hpp`

### Video Processing

- [Video Decoder](https://github.com/sanjeev-naik/naikavplayer/blob/main/src/video/VideoDecoder.cpp): `src/video/VideoDecoder.cpp`
- [HDR Tone Mapper](https://github.com/sanjeev-naik/naikavplayer/blob/main/src/video/ToneMapper.hpp): `src/video/ToneMapper.hpp`
- [Color Adjustment](https://github.com/sanjeev-naik/naikavplayer/blob/main/src/video/ColorAdjust.hpp): `src/video/ColorAdjust.hpp`
- [Frame Export](https://github.com/sanjeev-naik/naikavplayer/blob/main/src/video/FrameExporter.hpp): `src/video/FrameExporter.hpp`

### Player Features

- [Playlist](https://github.com/sanjeev-naik/naikavplayer/blob/main/src/playlist/Playlist.hpp): `src/playlist/Playlist.hpp`
- [Media Filter](https://github.com/sanjeev-naik/naikavplayer/blob/main/src/playlist/MediaFileFilter.hpp): `src/playlist/MediaFileFilter.hpp`
- [Playlist I/O](https://github.com/sanjeev-naik/naikavplayer/blob/main/src/playlist/PlaylistIO.hpp): `src/playlist/PlaylistIO.hpp`
- [Pipeline Metrics](https://github.com/sanjeev-naik/naikavplayer/blob/main/src/core/PipelineMetrics.hpp): `src/core/PipelineMetrics.hpp`
- [Metric Rings](https://github.com/sanjeev-naik/naikavplayer/blob/main/src/core/MetricRing.hpp): `src/core/MetricRing.hpp`

### Other components

- **User**

## Connections

- User → Player UI: operates (evidence: `README.md`)
- Application Loop → Playback Controller: coordinates
- Application Loop → Player UI: presents
- Playlist → Media Filter: classifies files (evidence: `src/playlist/Playlist.hpp`)
- Playlist → Playlist I/O: uses (evidence: `src/playlist/Playlist.hpp`)
- Playback Controller → Playlist: uses
- Playback Controller → Demuxer: coordinates
- Playback Controller → Audio Decoder: coordinates
- Playback Controller → Video Decoder: coordinates
- Playback Controller → Subtitle Decoder: coordinates
- Playback Controller → Pipeline Metrics: tracks pipeline
- Demuxer → Thread-Safe Queues: queues packets
- Audio Decoder → Thread-Safe Queues: consumes packets
- Video Decoder → Thread-Safe Queues: consumes packets
- Demuxer → Subtitle Events: discovers tracks
- Subtitle Decoder → Subtitle Events: produces events
- Audio Decoder → DSP Chain: processes audio
- Audio Decoder → Limiter: uses
- Audio Decoder → Loudness Tools: normalizes
- Audio Decoder → Loudness Prescan: prescans
- DSP Chain → Parametric EQ: runs (evidence: `src/audio/dsp/DspChain.hpp`)
- DSP Chain → Noise Gate: runs (evidence: `src/audio/dsp/DspChain.hpp`)
- DSP Chain → Compressors: runs (evidence: `src/audio/dsp/DspChain.hpp`)
- DSP Chain → Limiter: runs (evidence: `src/audio/dsp/DspChain.hpp`)
- Parametric EQ → Biquad Filters: filters with (evidence: `src/audio/dsp/ParametricEQ.hpp`)
- Video Decoder → HDR Tone Mapper: maps HDR
- Video Decoder → Color Adjustment: adjusts picture
- Player UI → Playback Controller: controls playback
- Pipeline Metrics → Metric Rings: records samples (evidence: `src/core/PipelineMetrics.hpp`)
- Application Loop → Media Filter: classifies inputs (evidence: `src/app/main.cpp`)
- Application Loop → Frame Export: uses exporter (evidence: `src/app/main.cpp`)
