# segin/psymp3 architecture

> Architecture diagram of the GitHub repository segin/psymp3, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/segin/psymp3
- Repository: https://github.com/segin/psymp3

## Overview

##### Project Type and Purpose
- This is a desktop GUI audio player (“psymp3”) written in C++.
- It uses a custom widget toolkit (include/*.h & src/*.cpp under Widget, LayoutWidget, etc.), a media-pipeline subsystem (Demuxers, Codecs, Streams), network integrations (LastFM, HTTPClient), and persistent storage.

##### File Structure
- Top-level directories:
– include/ & src/: core C++ headers and implementations
– libs/libseven: third-party support library
– util/: build scripts
– .github/workflows/: CI configuration
- Patterns:
– Widget hierarchy → custom UI layer
– MediaFactory + IOHandler + Demuxer + Codec → media pipeline
– Adapter pattern: TagLibIOHandlerAdapter
– Chain of Responsibility: ChainedStream, ModernStream
- Build: Autotools (configure.ac, Makefile.am), cross-platform Windows increment logic.

##### README

1. User Interface Layer
- ApplicationWidget, MainUIWidget, various Widget subclasses
2. Playback Engine / Core Logic
- MediaFactory, Player (player.cpp), Playlist, PersistentStorage
3. Media I/O Subsystem
- IOHandler (FileIOHandler, HTTPIOHandler, TagLibIOHandlerAdapter)
- URI, HTTPClient
4. Demuxers & Stream Layer
- Demuxer, ChunkDemuxer, OggDemuxer, ISODemuxer, RawAudioDemuxer
- ChainedStream, DemuxedStream, ModernStream
5. Codec Layer
- AudioCodec interface and implementations (libmpg123, PCMCodecs, FLAC, Vorbis, Opus)
6. Audio Output & System Integration
- system.cpp, surface, audio backend
7. External Services
- LastFM integration, Scrobble, PersistentStorage (for settings)
8. Third-Party Libraries
- libseven, TagLib, Autotools, libmpg123, libvorbis, libflac
b. Relationships & Data Flows:
- UI → Playback Engine: user commands (play, pause, next, volume)
- Playback Engine → MediaFactory: select appropriate IOHandler + Demuxer + Codec
- MediaFactory → IOHandler: open file or HTTP stream
- IOHandler → Demuxer: feed raw bytes
- Demuxer → Stream: split into audio frames
- Stream → Codec: decode frames to PCM
- Codec → Audio Output: push PCM samples to system audio API
- Playback Engine → UI: progress updates, spectrum data
- Playback Engine ↔ External Services: LastFM now playing, scrobble events over HTTPClient
- Engine ↔ PersistentStorage: save/load user settings and playlists
c. Architectural Patterns & Principles:
- Factory pattern: MediaFactory chooses concrete IO/Demuxer/Codec
- Adapter pattern: TagLibIOHandlerAdapter for TagLib metadata support
- Chain of Responsibility: ChainedStream layering filters
- Separation of Concerns: UI widget layer vs. core playback logic vs. I/O vs. external services
- Modular plugin-style: new codecs/demuxers can be added by subclassing interfaces
d. Key Technologies/Frameworks:
- C++17 (assumed), custom widget framework
- Autotools (configure.ac, Makefile.am) for build & cross-platform support
- libmpg123, libflac, libvorbis, libopus
- TagLib for metadata
- HTTPClient for REST calls
- libseven (third-party utility library)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layers
    subgraph "User Interface Layer"
        UI["UI Widget Layer"]:::ui
    end

    subgraph "Playback Engine / Core Logic"
        Engine["Playback Engine"]:::core
    end

    subgraph "Media I/O Subsystem"
        IO["Media I/O"]:::pipeline
    end

    subgraph "Demuxers & Stream Layer"
        Demux["Demuxer & Stream"]:::pipeline
    end

    subgraph "Codec Layer"
        Codec["Audio Codec"]:::pipeline
    end

    subgraph "Audio Output & System Integration"
        AudioOut["Audio Output"]:::storage
    end

    subgraph "External Services"
        ExtServ["LastFM & Storage"]:::ext
    end

    subgraph "Third-Party Libraries"
        lib7["libseven"]:::thirdparty
        Autotools["Autotools"]:::thirdparty
    end

    %% Data Flows
    UI -->|"user commands"| Engine
    Engine -->|"open media"| IO
    IO -->|"raw bytes"| Demux
    Demux -->|"audio frames"| Codec
    Codec -->|"PCM buffer"| AudioOut
    AudioOut -->|"audio API"| System["System API"]:::storage

    Engine -->|"REST API"| ExtServ
    Engine -->|"settings & playlists"| ExtServ

    %% Click Events
    click UI "https://github.com/segin/psymp3/blob/master/src/ApplicationWidget.cpp"
    click Engine "https://github.com/segin/psymp3/blob/master/src/player.cpp"
    click IO "https://github.com/segin/psymp3/blob/master/src/IOHandler.cpp"
    click Demux "https://github.com/segin/psymp3/blob/master/src/Demuxer.cpp"
    click Codec "https://github.com/segin/psymp3/blob/master/src/AudioCodec.cpp"
    click AudioOut "https://github.com/segin/psymp3/blob/master/src/audio.cpp"
    click ExtServ "https://github.com/segin/psymp3/blob/master/src/LastFM.cpp"
    click lib7 "https://github.com/segin/psymp3/tree/master/libs/libseven/"
    click Autotools "https://github.com/segin/psymp3/blob/master/configure.ac"

    %% Styles
    classDef ui fill:#cce5ff,stroke:#3366cc;
    classDef core fill:#d4edda,stroke:#28a745;
    classDef pipeline fill:#fff3cd,stroke:#ffcc00;
    classDef storage fill:#d1ecf1,stroke:#0c5460;
    classDef ext fill:#e2e3e5,stroke:#6c757d;
    classDef thirdparty fill:#f8d7da,stroke:#721c24;
```
