# hhaider3/macmpv architecture

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

- Interactive diagram: https://gitdiagram.com/hhaider3/macmpv
- Repository: https://github.com/hhaider3/macmpv

## Overview

macmpv is a native macOS media player. Users open local media, network streams, or torrents; the player manages playback and queue state, displays video and controls, and can inspect media metadata. The graph includes the documented torrent, preview, subtitle, resume, and queue capabilities. Source excerpts support the main app-to-player and playback relationships; several feature links are documented in the README rather than verified in sampled implementation code.

Main entry points: [`Sources/Cinewave/PlayerModel.swift`](https://github.com/hhaider3/macmpv/blob/main/Sources/Cinewave/PlayerModel.swift) (Player state and orchestration), [`Sources/Cinewave/ContentView.swift`](https://github.com/hhaider3/macmpv/blob/main/Sources/Cinewave/ContentView.swift) (Player window), [`Sources/Cinewave/PlayerControls.swift`](https://github.com/hhaider3/macmpv/blob/main/Sources/Cinewave/PlayerControls.swift) (Playback controls), [`Sources/Cinewave/CinewaveApp.swift`](https://github.com/hhaider3/macmpv/blob/main/Sources/Cinewave/CinewaveApp.swift) (App entry and commands)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App and interface"]
  node_app["App entry and commands<br/>[CinewaveApp.swift]"]
  node_view["Player window<br/>[ContentView.swift]"]
  node_controls["Playback controls"]
  node_queueui["Queue sidebar<br/>[QueueSidebar.swift]"]
  node_seekpop["Seek preview popover"]
end

subgraph group_playback["Playback and media"]
  node_model["Player state and orchestration<br/>[PlayerModel.swift]"]
  node_queue["Queue operations"]
  node_models["Media types and support<br/>[MediaModels.swift]"]
  node_surface["Video surface<br/>[VideoSurface.swift]"]
  node_engine["mpv engine<br/>[MPVEngine.swift]"]
  node_preview["Seek preview generation<br/>[SeekPreview.swift]"]
  node_completion["Playback completion"]
end

subgraph group_torrent["Torrent streaming"]
  node_magnet["Torrent session and stream<br/>[MagnetStream.swift]"]
  node_runtime["WebTorrent runtime helper"]
end

subgraph group_support["Metadata and state"]
  node_probe["Media metadata probe<br/>[MediaProbe.swift]"]
  node_persistence["Playback persistence"]
end

node_user(("macOS user"))
node_mpv["mpv playback library"]
node_webtorrent["WebTorrent CLI and library"]
node_ffprobe["ffprobe"]

node_user -->|"opens media"| node_app
node_app -->|"creates window"| node_view
node_view -->|"renders"| node_controls
node_view -->|"renders"| node_queueui
node_view -->|"renders"| node_surface
node_controls -->|"invokes actions"| node_model
node_queueui -->|"invokes queue actions"| node_model
node_app -->|"creates state"| node_model
node_model -->|"controls playback"| node_engine
node_model -->|"requests metadata"| node_probe
node_model -->|"starts torrent stream"| node_magnet
node_model -->|"checks completion"| node_completion
node_model -->|"manages queue"| node_queue
node_surface -->|"renders frames"| node_engine
node_engine -->|"embeds playback"| node_mpv
node_probe -->|"reads metadata"| node_ffprobe
node_magnet -->|"uses runtime helper"| node_runtime
node_runtime -->|"starts torrent client"| node_webtorrent
node_magnet -->|"streams torrent files"| node_webtorrent
node_controls -.->|"requests seek preview"| node_preview
node_controls -.->|"shows preview"| node_seekpop
node_model -.->|"saves playback state"| node_persistence

click node_app "https://github.com/hhaider3/macmpv/blob/main/Sources/Cinewave/CinewaveApp.swift"
click node_view "https://github.com/hhaider3/macmpv/blob/main/Sources/Cinewave/ContentView.swift"
click node_controls "https://github.com/hhaider3/macmpv/blob/main/Sources/Cinewave/PlayerControls.swift"
click node_queueui "https://github.com/hhaider3/macmpv/blob/main/Sources/Cinewave/QueueSidebar.swift"
click node_seekpop "https://github.com/hhaider3/macmpv/blob/main/Sources/Cinewave/SeekPreviewPopover.swift"
click node_model "https://github.com/hhaider3/macmpv/blob/main/Sources/Cinewave/PlayerModel.swift"
click node_queue "https://github.com/hhaider3/macmpv/blob/main/Sources/Cinewave/PlayerModel%2BQueue.swift"
click node_models "https://github.com/hhaider3/macmpv/blob/main/Sources/Cinewave/MediaModels.swift"
click node_surface "https://github.com/hhaider3/macmpv/blob/main/Sources/Cinewave/VideoSurface.swift"
click node_engine "https://github.com/hhaider3/macmpv/blob/main/Sources/Cinewave/MPVEngine.swift"
click node_preview "https://github.com/hhaider3/macmpv/blob/main/Sources/Cinewave/SeekPreview.swift"
click node_completion "https://github.com/hhaider3/macmpv/blob/main/Sources/Cinewave/PlaybackCompletion.swift"
click node_magnet "https://github.com/hhaider3/macmpv/blob/main/Sources/Cinewave/MagnetStream.swift"
click node_runtime "https://github.com/hhaider3/macmpv/blob/main/Sources/Cinewave/TorrentDownloadRuntime.swift"
click node_probe "https://github.com/hhaider3/macmpv/blob/main/Sources/Cinewave/MediaProbe.swift"
click node_persistence "https://github.com/hhaider3/macmpv/blob/main/Sources/Cinewave/PlayerModel%2BPersistence.swift"

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_view,node_controls,node_queueui,node_seekpop,node_user toneBlue
class node_model,node_queue,node_models,node_surface,node_engine,node_preview,node_completion toneAmber
class node_magnet,node_runtime toneMint
class node_probe,node_persistence toneRose
class node_mpv,node_webtorrent,node_ffprobe toneIndigo
```

## Components

### App and interface

- [App entry and commands](https://github.com/hhaider3/macmpv/blob/main/Sources/Cinewave/CinewaveApp.swift): `Sources/Cinewave/CinewaveApp.swift`
- [Player window](https://github.com/hhaider3/macmpv/blob/main/Sources/Cinewave/ContentView.swift): `Sources/Cinewave/ContentView.swift`
- [Playback controls](https://github.com/hhaider3/macmpv/blob/main/Sources/Cinewave/PlayerControls.swift): `Sources/Cinewave/PlayerControls.swift`
- [Queue sidebar](https://github.com/hhaider3/macmpv/blob/main/Sources/Cinewave/QueueSidebar.swift): `Sources/Cinewave/QueueSidebar.swift`
- [Seek preview popover](https://github.com/hhaider3/macmpv/blob/main/Sources/Cinewave/SeekPreviewPopover.swift): `Sources/Cinewave/SeekPreviewPopover.swift`

### Playback and media

- [Player state and orchestration](https://github.com/hhaider3/macmpv/blob/main/Sources/Cinewave/PlayerModel.swift): `Sources/Cinewave/PlayerModel.swift`
- [Queue operations](https://github.com/hhaider3/macmpv/blob/main/Sources/Cinewave/PlayerModel%2BQueue.swift): `Sources/Cinewave/PlayerModel+Queue.swift`
- [Media types and support](https://github.com/hhaider3/macmpv/blob/main/Sources/Cinewave/MediaModels.swift): `Sources/Cinewave/MediaModels.swift`
- [Video surface](https://github.com/hhaider3/macmpv/blob/main/Sources/Cinewave/VideoSurface.swift): `Sources/Cinewave/VideoSurface.swift`
- [mpv engine](https://github.com/hhaider3/macmpv/blob/main/Sources/Cinewave/MPVEngine.swift): `Sources/Cinewave/MPVEngine.swift`
- [Seek preview generation](https://github.com/hhaider3/macmpv/blob/main/Sources/Cinewave/SeekPreview.swift): `Sources/Cinewave/SeekPreview.swift`
- [Playback completion](https://github.com/hhaider3/macmpv/blob/main/Sources/Cinewave/PlaybackCompletion.swift): `Sources/Cinewave/PlaybackCompletion.swift`

### Torrent streaming

- [Torrent session and stream](https://github.com/hhaider3/macmpv/blob/main/Sources/Cinewave/MagnetStream.swift): `Sources/Cinewave/MagnetStream.swift`
- [WebTorrent runtime helper](https://github.com/hhaider3/macmpv/blob/main/Sources/Cinewave/TorrentDownloadRuntime.swift): `Sources/Cinewave/TorrentDownloadRuntime.swift`

### Metadata and state

- [Media metadata probe](https://github.com/hhaider3/macmpv/blob/main/Sources/Cinewave/MediaProbe.swift): `Sources/Cinewave/MediaProbe.swift`
- [Playback persistence](https://github.com/hhaider3/macmpv/blob/main/Sources/Cinewave/PlayerModel%2BPersistence.swift): `Sources/Cinewave/PlayerModel+Persistence.swift`

### Other components

- **macOS user**
- **mpv playback library**
- **WebTorrent CLI and library**
- **ffprobe**

## Connections

- macOS user → App entry and commands: opens media (evidence: `README.md`)
- App entry and commands → Player window: creates window (evidence: `Sources/Cinewave/CinewaveApp.swift`)
- Player window → Playback controls: renders (evidence: `Sources/Cinewave/ContentView.swift`)
- Player window → Queue sidebar: renders (evidence: `Sources/Cinewave/ContentView.swift`)
- Player window → Video surface: renders (evidence: `Sources/Cinewave/ContentView.swift`)
- Playback controls → Player state and orchestration: invokes actions (evidence: `Sources/Cinewave/PlayerControls.swift`)
- Queue sidebar → Player state and orchestration: invokes queue actions (evidence: `Sources/Cinewave/QueueSidebar.swift`)
- App entry and commands → Player state and orchestration: creates state (evidence: `Sources/Cinewave/CinewaveApp.swift`)
- Player state and orchestration → mpv engine: controls playback (evidence: `Sources/Cinewave/PlayerModel.swift`)
- Player state and orchestration → Media metadata probe: requests metadata (evidence: `Sources/Cinewave/PlayerModel.swift`)
- Player state and orchestration → Torrent session and stream: starts torrent stream (evidence: `Sources/Cinewave/PlayerModel.swift`)
- Player state and orchestration → Playback completion: checks completion (evidence: `Sources/Cinewave/PlayerModel.swift`)
- Player state and orchestration → Queue operations: manages queue (evidence: `Sources/Cinewave/PlayerModel+Queue.swift`)
- Video surface → mpv engine: renders frames (evidence: `Sources/Cinewave/VideoSurface.swift`)
- mpv engine → mpv playback library: embeds playback (evidence: `README.md`)
- Media metadata probe → ffprobe: reads metadata (evidence: `README.md`)
- Torrent session and stream → WebTorrent runtime helper: uses runtime helper (evidence: `Sources/Cinewave/MagnetStream.swift`)
- WebTorrent runtime helper → WebTorrent CLI and library: starts torrent client (evidence: `Sources/Cinewave/TorrentDownloadRuntime.swift`)
- Torrent session and stream → WebTorrent CLI and library: streams torrent files (evidence: `README.md`)
- Playback controls → Seek preview generation: requests seek preview
- Playback controls → Seek preview popover: shows preview (evidence: `Sources/Cinewave/PlayerControls.swift`)
- Player state and orchestration → Playback persistence: saves playback state (evidence: `Sources/Cinewave/PlayerModel+Persistence.swift`)
