dhananjayanrajan/atmostream

1. Atmostream is a dual-edition desktop audio player. The repository contains a native C++/GTK application as the main product and a Bash-based “Lite” edition that reuses the same configuration and state concepts but drives external tools from shell scripts.

2. The C++ edition is organized around a controller-centric architecture. main.cpp starts GTK, sets process/runtime defaults, and hands control to ApplicationController, which owns startup, wiring, lifecycle, and periodic UI refreshes.

3. The C++ codebase uses dependency inversion heavily. src/interfaces/ defines the contracts, src/core/ provides concrete services, src/features/ contains self-contained feature modules, src/ui/ provides reusable windows/dialogs, and src/platform/ contains OS-specific integration. Feature code depends on interfaces, not concrete implementations.

4. The central runtime data path is audio playback. AudioEngine wraps three mpv-backed streams: narration/main, ambience, and noise. PipeWireManager builds the downstream audio graph, including low-pass filtering, sidechain compression, and optional noise generation, then routes everything to the system sink.

5. The application’s audio behavior is intentionally layered. The main track carries speech, ambience ducks under narration through PipeWire sidechain control, and the noise layer is filtered to stay unobtrusive. Volume hierarchy is enforced in the controller/service layer so noise never exceeds ambience, and ambience never exceeds main.

6. Persistent state is isolated in StateManager and stored as JSON under the user data directory. It handles resume data, bookmarks/markers, favorites, presets, settings, and statistics. Writes are atomic, and older bookmark formats are migrated on read.

7. Configuration is separate from state and is loaded by ConfigLoader. The app merges plain-text config files from local, system, and user locations, then uses them for channel maps, source pools, defaults, thresholds, and fallback URLs.

8. Source acquisition is its own subsystem. SourcesManager and the Librivox browser deal with YouTube-facing selection and validation, while LauncherDialog provides the GTK UI for browsing channels and videos. The C++ edition fetches playable URLs and metadata via yt-dlp-style flows rather than embedding a browser.

9. UI is split into tray, mini player, launch dialogs, and feature panels. TrayManager is the primary shell, MiniPlayer is a floating overlay, VolumePanel exposes mixer controls and safe-listening limits, and the various feature panels are standalone dialogs that can be shown or hidden from the tray menu.

10. Platform integration is explicit and separate from business logic. mpris2.cpp exposes the app on the desktop session bus for media controls, hotkeys.cpp captures global X11 media keys, and safe_listening.h models device detection and conservative output-volume limits.

11. Feature modules are mostly independent vertical slices under src/features/. Each folder bundles its own logic and panel for a specific capability such as binaural beats, cinematic DSP presets, voice profiles, timers, favorites, stats, quick EQ, bookmarks, drift detection, auto-ambience, noise generation, and source browsing.

12. The Bash Lite edition mirrors the same domain concepts with a simpler execution model. bash/bin/atmostream-lite sources modular scripts for core lifecycle, audio setup, UI rendering, input handling, state save, source selection, MPRIS-style command forwarding, and cleanup. It runs external mpv processes, manages PipeWire links from shell, and falls back from TUI to a single-line status display when terminal capabilities are limited.

13. The main architectural boundary between editions is control plane versus audio plane. In C++, the control plane is in-process and GUI-driven; in Bash, it is script-driven and terminal-driven. In both cases, the audio plane is still built around mpv plus PipeWire plus Calf LV2 plugins, so the user-visible feature set stays aligned.

14. tests/ contains focused checks for core services and panel construction, which reinforces the repo’s modular design: service contracts can be validated independently from the UI shell, and panels can be instantiated without relying on the whole application.