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

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:

*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:

1. Rich ecosystem: npm packages, React/Vue components
2. Familiar technology: HTML/CSS/JavaScript
3. 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

1. Resource embedding: All UI assets (XML, images, fonts) compiled into the binary via .rc files
2. Static linking: Every dependency (SDL3, TagLib, LAME, SOUI4) linked statically
3. 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! 🎵

🔗 Related Articles

• SOUI4: A Lightweight Alternative to Qt
• Why I Chose C++ Over Electron for My Desktop App
• Building Cross-Platform Apps Without JavaScript

Tags: #cpp #crossplatform #desktop #opensource #performance #soui4 #sdl #linux #windows #macos