# ygyg4255-dotcom/music-player architecture

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

- Interactive diagram: https://gitdiagram.com/ygyg4255-dotcom/music-player
- Repository: https://github.com/ygyg4255-dotcom/music-player

## Overview

Player Music is a Windows floating music timer. The user enters a song and duration; the app searches the Music folder first, opens a local match in its default player or falls back to a YouTube result in Brave, then synchronizes a monotonic countdown with the matching Windows media session. The graph also preserves settings, startup opt-in, and the floating interface. Several implementation details are unsampled, so those links rely on README statements; uncertain internal calls are omitted.

Main entry points: [`src/music_player/app.py`](https://github.com/ygyg4255-dotcom/music-player/blob/main/src/music_player/app.py) (App wiring), [`src/music_player/island.py`](https://github.com/ygyg4255-dotcom/music-player/blob/main/src/music_player/island.py) (Floating island), [`src/music_player/playback/orchestrator.py`](https://github.com/ygyg4255-dotcom/music-player/blob/main/src/music_player/playback/orchestrator.py) (Playback orchestrator), [`src/music_player/youtube.py`](https://github.com/ygyg4255-dotcom/music-player/blob/main/src/music_player/youtube.py) (YouTube fallback)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Floating interface"]
  node_island["Floating island<br/>[island.py]"]
  node_app["App wiring<br/>[app.py]"]
  node_theme["Visual theme<br/>[theme.py]"]
end

subgraph group_playback["Song playback"]
  node_orchestrator["Playback orchestrator<br/>[orchestrator.py]"]
  node_search["Local song search<br/>[local_search.py]"]
  node_local["Default-app playback<br/>[local.py]"]
  node_source["Playback source interface<br/>[base.py]"]
  node_youtube["YouTube fallback<br/>[youtube.py]"]
end

subgraph group_timing["Timer and sync"]
  node_timer["Countdown timer<br/>[timer.py]"]
  node_media["Media-session control<br/>[media_control.py]"]
end

subgraph group_preferences["Preferences and startup"]
  node_settings[("Settings storage<br/>[settings.py]")]
  node_config["App configuration<br/>[config.py]"]
  node_startup["Windows startup opt-in<br/>[startup.py]"]
end

node_user(("User"))
node_default_player["Windows default player"]
node_youtube_service["YouTube"]
node_brave["Brave browser"]
node_gsm["Windows media sessions"]
node_registry["Windows Run registry"]

node_user -->|"enters song and duration"| node_island
node_island -->|"requests start"| node_app
node_app -->|"starts search workflow"| node_orchestrator
node_orchestrator -->|"searches locally"| node_search
node_orchestrator -->|"opens local match"| node_local
node_local -->|"opens audio file"| node_default_player
node_app -->|"configures fallback"| node_youtube
node_youtube -->|"fetches search results"| node_youtube_service
node_youtube -->|"opens watch page"| node_brave
node_youtube -.->|"uses system browser if needed"| node_default_player
node_orchestrator -->|"tracks playback source"| node_source
node_app -->|"starts and resumes"| node_timer
node_island -->|"starts countdown"| node_timer
node_timer -->|"signals expiry"| node_app
node_app -->|"syncs playback state"| node_media
node_media -->|"monitors and controls"| node_gsm
node_app -->|"updates status"| node_island
node_island -->|"uses styling"| node_theme
node_app -->|"loads and saves"| node_settings
node_settings -->|"gets settings location"| node_config
node_island -->|"restores saved state"| node_settings
node_app -->|"wires opt-in"| node_startup
node_startup -->|"sets Run value"| node_registry

click node_island "https://github.com/ygyg4255-dotcom/music-player/blob/main/src/music_player/island.py"
click node_app "https://github.com/ygyg4255-dotcom/music-player/blob/main/src/music_player/app.py"
click node_theme "https://github.com/ygyg4255-dotcom/music-player/blob/main/src/music_player/theme.py"
click node_orchestrator "https://github.com/ygyg4255-dotcom/music-player/blob/main/src/music_player/playback/orchestrator.py"
click node_search "https://github.com/ygyg4255-dotcom/music-player/blob/main/src/music_player/local_search.py"
click node_local "https://github.com/ygyg4255-dotcom/music-player/blob/main/src/music_player/playback/local.py"
click node_source "https://github.com/ygyg4255-dotcom/music-player/blob/main/src/music_player/playback/base.py"
click node_youtube "https://github.com/ygyg4255-dotcom/music-player/blob/main/src/music_player/youtube.py"
click node_timer "https://github.com/ygyg4255-dotcom/music-player/blob/main/src/music_player/timer.py"
click node_media "https://github.com/ygyg4255-dotcom/music-player/blob/main/src/music_player/media_control.py"
click node_settings "https://github.com/ygyg4255-dotcom/music-player/blob/main/src/music_player/settings.py"
click node_config "https://github.com/ygyg4255-dotcom/music-player/blob/main/src/music_player/config.py"
click node_startup "https://github.com/ygyg4255-dotcom/music-player/blob/main/src/music_player/startup.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_island,node_app,node_theme,node_user,node_brave toneBlue
class node_orchestrator,node_search,node_local,node_source,node_youtube toneAmber
class node_timer,node_media toneMint
class node_settings,node_config,node_startup toneRose
class node_default_player,node_youtube_service,node_gsm,node_registry toneIndigo
```

## Components

### Floating interface

- [Floating island](https://github.com/ygyg4255-dotcom/music-player/blob/main/src/music_player/island.py): `src/music_player/island.py`
- [App wiring](https://github.com/ygyg4255-dotcom/music-player/blob/main/src/music_player/app.py): `src/music_player/app.py`
- [Visual theme](https://github.com/ygyg4255-dotcom/music-player/blob/main/src/music_player/theme.py): `src/music_player/theme.py`

### Song playback

- [Playback orchestrator](https://github.com/ygyg4255-dotcom/music-player/blob/main/src/music_player/playback/orchestrator.py): `src/music_player/playback/orchestrator.py`
- [Local song search](https://github.com/ygyg4255-dotcom/music-player/blob/main/src/music_player/local_search.py): `src/music_player/local_search.py`
- [Default-app playback](https://github.com/ygyg4255-dotcom/music-player/blob/main/src/music_player/playback/local.py): `src/music_player/playback/local.py`
- [Playback source interface](https://github.com/ygyg4255-dotcom/music-player/blob/main/src/music_player/playback/base.py): `src/music_player/playback/base.py`
- [YouTube fallback](https://github.com/ygyg4255-dotcom/music-player/blob/main/src/music_player/youtube.py): `src/music_player/youtube.py`

### Timer and sync

- [Countdown timer](https://github.com/ygyg4255-dotcom/music-player/blob/main/src/music_player/timer.py): `src/music_player/timer.py`
- [Media-session control](https://github.com/ygyg4255-dotcom/music-player/blob/main/src/music_player/media_control.py): `src/music_player/media_control.py`

### Preferences and startup

- [Settings storage](https://github.com/ygyg4255-dotcom/music-player/blob/main/src/music_player/settings.py): `src/music_player/settings.py`
- [App configuration](https://github.com/ygyg4255-dotcom/music-player/blob/main/src/music_player/config.py): `src/music_player/config.py`
- [Windows startup opt-in](https://github.com/ygyg4255-dotcom/music-player/blob/main/src/music_player/startup.py): `src/music_player/startup.py`

### Other components

- **User**
- **Windows default player**
- **YouTube**
- **Brave browser**
- **Windows media sessions**
- **Windows Run registry**

## Connections

- User → Floating island: enters song and duration (evidence: `README.md`)
- Floating island → App wiring: requests start (evidence: `README.md`)
- App wiring → Playback orchestrator: starts search workflow (evidence: `src/music_player/app.py`)
- Playback orchestrator → Local song search: searches locally (evidence: `src/music_player/playback/orchestrator.py`)
- Playback orchestrator → Default-app playback: opens local match (evidence: `README.md`)
- Default-app playback → Windows default player: opens audio file (evidence: `src/music_player/playback/local.py`)
- App wiring → YouTube fallback: configures fallback (evidence: `src/music_player/app.py`)
- YouTube fallback → YouTube: fetches search results (evidence: `README.md`)
- YouTube fallback → Brave browser: opens watch page (evidence: `README.md`)
- YouTube fallback → Windows default player: uses system browser if needed (evidence: `README.md`)
- Playback orchestrator → Playback source interface: tracks playback source (evidence: `src/music_player/playback/orchestrator.py`)
- App wiring → Countdown timer: starts and resumes (evidence: `src/music_player/app.py`)
- Floating island → Countdown timer: starts countdown (evidence: `src/music_player/island.py`)
- Countdown timer → App wiring: signals expiry (evidence: `src/music_player/app.py`)
- App wiring → Media-session control: syncs playback state (evidence: `src/music_player/app.py`)
- Media-session control → Windows media sessions: monitors and controls (evidence: `README.md`)
- App wiring → Floating island: updates status (evidence: `src/music_player/app.py`)
- Floating island → Visual theme: uses styling (evidence: `src/music_player/island.py`)
- App wiring → Settings storage: loads and saves (evidence: `src/music_player/app.py`)
- Settings storage → App configuration: gets settings location (evidence: `src/music_player/settings.py`)
- Floating island → Settings storage: restores saved state (evidence: `README.md`)
- App wiring → Windows startup opt-in: wires opt-in (evidence: `src/music_player/app.py`)
- Windows startup opt-in → Windows Run registry: sets Run value (evidence: `README.md`)