setoutsoft

Posted on May 6

XMusic: A 10MB Cross-Platform Music Player Built with C++

#crossplatform #green #musicplayer #soui

In an era dominated by Electron and web technologies, we seem to have forgotten that desktop applications should be lighter and faster.

Have you ever encountered these frustrations?

❌ Your simple music player takes 200+ MB of RAM
❌ Startup time exceeds 5-10 seconds
❌ Distribution requires bundling Chromium or heavy runtime libraries
❌ Performance feels sluggish on older hardware

XMusic was born to solve these problems.

🚀 Performance That Speaks for Itself

Here's what makes XMusic stand out:

Metric	XMusic	Typical Electron App	Qt Application
Memory Usage	~10 MB	200-500 MB	80-150 MB
Startup Time	710ms*	5-10s	2-5s
Binary Size	15-25 MB	100-300 MB	50-200 MB
Dependencies	None (single file)	Node.js + Chromium	Qt runtime libs

*Note: 625ms is spent on SDL audio initialization; the UI itself launches in just **85ms.

All libraries are statically compiled into the final executable — one file handles everything.

🎯 Why XMusic Exists

The Problem with Modern Desktop Development

In today's landscape, developers often reach for Electron or web-based frameworks because:

Rich ecosystem: npm packages, React/Vue components
Familiar technology: HTML/CSS/JavaScript
Rapid prototyping: Quick to build MVPs

But this comes at a cost:

Bloated binaries: Simple apps balloon to 100MB+
High memory footprint: Chromium instances consume resources
Slow startup: Loading entire browser engine for a music player?
Security concerns: Larger attack surface with web technologies

The Native C++ Alternative

XMusic demonstrates that modern C++ desktop development can be:

✅ Lightweight: 10MB memory footprint

✅ Fast: Sub-second startup

✅ Cross-platform: Windows, Linux, macOS from one codebase

✅ Simple: Single executable, no external dependencies

🏗️ Technical Architecture

Core Technology Stack

┌─────────────────────────────────────┐
│        UI Layer (SOUI4)             │
│  Declarative XML Layout + CSS-like  │
│  Data-driven rendering engine       │
└─────────────────────────────────────┘
                  ↓
┌─────────────────────────────────────┐
│     Audio Engine (SDL3)             │
│  SDL_mixer3 for format decoding     │
│  Ring buffer for low-latency play   │
└─────────────────────────────────────┘
                  ↓
┌─────────────────────────────────────┐
│    Metadata & Encoding              │
│  TagLib (ID3v2 editing)             │
│  LAME (MP3 encoding)                │
│  LRCLIB API (lyrics fetching)       │
└─────────────────────────────────────┘

Key Technologies Explained

1. SOUI4: Modern Direct UI Framework

SOUI4 is a lightweight cross-platform UI framework that uses declarative XML layouts — similar to Android's approach but for desktop applications.

Advantages:

Separation of concerns: UI defined in XML, logic in C++
No traditional Win32/GDI bottlenecks: Direct rendering pipeline
Built-in high DPI support: Crisp on 4K displays
Multi-language: Automatic system locale detection
Animation system: Smooth transitions out of the box

Example XML layout:

<window width="800" height="600" title="XMusic">
  <window layout="vbox">
    <listView name="playlist" />
    <window layout="hbox">
      <button name="play" text="@string/play" />
      <button name="pause" text="@string/pause" />
      <slider name="volume" />
    </window>
  </window>
</window>

2. SDL3 + SDL_mixer3: Audio Powerhouse

Instead of reinventing the wheel, XMusic leverages industry-standard libraries:

Format support: MP3, FLAC, OGG, WAV, MOD, OPUS, M4A/AAC, WMA
Low-latency playback: Optimized ring buffer implementation
Cross-platform audio backends: DirectSound, ALSA, PulseAudio, CoreAudio

3. TagLib: Complete Metadata Management

Full ID3v2 tag editing capabilities:

Read/write artist, album, year, genre
Album art extraction and display
Batch metadata operations

4. LAME Encoder: Industry-Standard MP3 Conversion

Built-in batch conversion tool:

Convert FLAC/OGG/WAV → MP3
Configurable bitrate (128-320 kbps)
Multi-threaded encoding for speed

5. LRCLIB API: Online Lyrics Integration

Automatic lyrics fetching:

Search by artist + title
LRC format with timestamp synchronization
Karaoke-style word-by-word highlighting

🌍 True Cross-Platform Support

XMusic runs natively on all major operating systems with zero code changes:

Windows (xp/7/8/10/11)

Native Win32 API integration
System tray support
Dark/light theme adaptation

Linux (Ubuntu, Fedora, Arch, etc.)

X11/Wayland compatibility
PulseAudio/PipeWire support
Single-file deployment: No .so dependencies to distribute

macOS (10.15+)

Native Cocoa integration via swinx compatibility layer
Metal-accelerated rendering
Retina display support

The Secret Sauce: Swinx

SOUI4's swinx module provides a Windows API compatibility layer for Linux/macOS, allowing:

Reuse existing Windows code without modification
Consistent behavior across platforms
Avoid platform-specific #ifdef spaghetti

This is similar to a lightweight Wine implementation, but designed specifically for GUI applications.

📦 Deployment Simplicity

Traditional Approach

A typical cross-platform app requires distributing:

MyApp/
├── MyApp.exe
├── qt5core.dll
├── qt5gui.dll
├── qt5widgets.dll
├── libssl.so.1.1
├── libcrypto.so.1.1
├── plugins/
│   ├── platforms/
│   ├── imageformats/
│   └── ...
└── translations/
    └── qt_en.qm

XMusic Approach

Just one file:

XMusic.exe  (or xmusic_player on Linux/macOS)

How It Works

Resource embedding: All UI assets (XML, images, fonts) compiled into the binary via .rc files
Static linking: Every dependency (SDL3, TagLib, LAME, SOUI4) linked statically
Runtime extraction: Resources automatically extracted from PE/ELF sections at startup

This not only simplifies deployment but also improves security — resource files can't be tampered with or lost.

🤔 Why Not Qt or Electron?

Great question! Let's break it down:

Electron: Pros and Cons

Pros:

Massive frontend ecosystem (React, Vue, Angular)
Rapid development with web technologies
Easy to hire developers (everyone knows JavaScript)

Cons:

Huge binary size: 100-300 MB for simple apps
Memory hog: 200-500 MB RAM usage
Slow startup: 5-10 seconds to load Chromium
Overkill: Do you really need a full browser for a music player?

When to use Electron:

Complex web-based features needed
Team already skilled in web development
Rapid prototyping prioritized over performance

Qt: Pros and Cons

Pros:

Mature, battle-tested framework
Excellent documentation
Powerful QML for declarative UI

Cons:

Steep learning curve: Hundreds of classes to master
Large binaries: 50-200 MB even for simple apps
Complex dependencies: Multiple .dll/.so files
Licensing concerns: LGPL/commercial licenses

When to use Qt:

Large-scale enterprise applications
Need extensive widget library
Team experienced with C++/Qt

SOUI4: The Sweet Spot

Pros:

Lightweight: 15-25 MB binary, 10-50 MB RAM
Easy to learn: Familiar to Win32/MFC developers
Fast development: XML layouts + C++ logic
Zero dependencies: Single-file deployment
Free for commercial use: No licensing headaches

Cons:

Smaller community than Qt/Electron
Fewer third-party plugins
Documentation primarily in Chinese (improving!)

When to use SOUI4:

Medium-sized desktop applications
Performance and size matter
Existing Windows codebase to port to Linux/macOS
Prefer native C++ over web technologies

💡 What XMusic Demonstrates

XMusic proves that modern C++ desktop development is still viable and advantageous for certain use cases:

1. Performance Matters

For applications where responsiveness is critical (audio playback, real-time visualization), native code wins:

Low-latency audio: Direct hardware access via SDL
Smooth animations: GPU-accelerated rendering
Instant startup: No VM or interpreter overhead

2. Resource Efficiency

Not every user has a beefy machine:

Runs smoothly on older hardware
Doesn't monopolize system RAM
Suitable for embedded systems or thin clients

3. Simplified Distribution

One file to rule them all:

No installer needed
Portable (run from USB drive)
Easy to version control and distribute

4. Developer Productivity

Despite being C++, development is fast:

Declarative UI: Change XML, see results immediately
Hot reload: Some SOUI4 setups support live UI updates
Modular architecture: Easy to extend with new features

🛠️ Building XMusic

Getting started is straightforward:

Prerequisites

CMake 3.16+
C++17 compiler (MSVC, GCC, Clang)
Git (for submodules)

Build Steps

# Clone with submodules
git clone --recursive https://gitee.com/setoutsoft/xmusic.git
cd XMusic

# Build
mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
cmake --build . --config Release

# Run
./bin/xmusic_player  # Linux/macOS
..\bin\Release\XMusic.exe  # Windows

That's it! CMake automatically handles:

Downloading SDL3, SDL_mixer, TagLib, LAME, SOUI4
Compiling all dependencies as static libraries
Embedding UI resources into the binary

No manual dependency installation required.

🎨 Feature Showcase

Core Playback

Multi-format support (MP3, FLAC, OGG, WAV, etc.)
Gapless playback
Playlist management with drag-and-drop

Advanced Audio

Multi-band equalizer: Presets for Pop, Rock, Classical
Spectrum visualization: Real-time FFT animation
Volume normalization: Consistent loudness across tracks

Metadata & Tags

ID3v2 tag editor
Album art display
Batch metadata operations

Lyrics System

Auto-detect .lrc files
Online search via LRCLIB API
Karaoke-mode word highlighting
Smooth scale-fade transitions between lines

User Experience

Modern dark theme (#1a1a1a background, #e60026 accent)
System tray integration
Global hotkeys
Multi-language (auto-detects system locale)

📊 Real-World Use Cases

XMusic's architecture makes it suitable for:

✅ Personal Music Players

Lightweight alternative to bloated commercial players

✅ Digital Signage

Low-resource audio playback for kiosks

✅ Embedded Systems

Runs on Raspberry Pi, embedded Linux devices

✅ Educational Projects

Demonstrates modern C++ best practices

✅ Legacy App Modernization

Template for porting old Win32 apps to cross-platform

🚧 Future Roadmap

Planned enhancements:

[ ] Podcast support: RSS feed integration
[ ] Streaming: Internet radio stations
[ ] Cloud sync: Playlist backup to cloud storage
[ ] Mobile ports: iOS/Android via SOUI4 mobile backend
[ ] Plugin system: Third-party visualizations and effects

🤝 Contributing

XMusic is open-source and welcomes contributions!

Ways to help:

Report bugs on Gitee Issues
Submit pull requests for new features
Improve documentation and translations
Test on different Linux distributions

Development guidelines:

Follow C++11 standards
Maintain cross-platform compatibility
Add comments for complex logic
Test on Windows + Linux before submitting

📚 Learn More

Resources

XMusic Repository: Gitee | GitHub Mirror
SOUI4 Framework: Official Site | GitHub
SDL3 Documentation: libsdl.org
Build Guide: BUILD_GUIDE.md

🎯 Conclusion

XMusic demonstrates that native C++ desktop development is far from dead. In fact, for applications prioritizing:

⚡ Performance: Low latency, smooth animations
💾 Efficiency: Minimal memory and disk usage
📦 Simplicity: Single-file deployment
🌍 Portability: True cross-platform support

...there's no better choice than going native.

While Electron and web technologies dominate the conversation, projects like XMusic prove that traditional approaches, modernized, still have their place.

If you're building a desktop application where performance matters, consider giving native C++ another look. You might be surprised by how productive and enjoyable it can be with the right framework.

Enjoyed this article?

⭐ Star the XMusic repository

🐦 Share on Twitter

💬 Leave a comment below

Happy coding! 🎵