How segin/psymp3 works
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)