Qt Music Player

A clean, native desktop music player built with Qt 6 and QML — featuring real-time ID3 tag parsing, embedded album art, and a polished, minimal interface.

---

Why this project?

Most tutorials stop at "play a sound file." This project goes further — it shows how to:

• Build a real cross-platform desktop app with Qt Quick + C++ backend
• Parse ID3v2 tags manually (title, artist, embedded cover art) with no external library
• Bridge a QObject C++ backend into QML using Q_PROPERTY and Q_INVOKABLE
• Ship a complete music UI: shuffle, repeat, volume, cover art, and playback controls

If you're learning Qt 6 / QML or you want a starting point for a multimedia app, this repo is a working reference you can fork and extend.

Features

🎵 MP3 playback	Play, pause, skip, previous, with smooth audio
🖼️ Album cover art	Reads embedded APIC frames (JPEG / PNG) from ID3v2 tags
🎚️ Volume slider	Vertical slider with fine-grained control
🔀 Shuffle & 🔁 Repeat	Toggleable playback modes
📂 Folder loader	Pick any folder and the player auto-discovers its .mp3 files
🏷️ ID3v2 metadata	Title (TIT2), artist (TPE1), cover art (APIC) — UTF-8/UTF-16/Latin-1 aware
🖥️ Cross-platform	Builds on Windows, macOS, and Linux with Qt 6.2+

Tech stack

• Qt 6.7.2 (works with Qt 6.2+) — Quick, Multimedia, Core, Widgets
• C++17 with the Qt meta-object system
• QML for the UI layer
• CMake 3.16+ as the build system
• TagLib + ZLIB linked at build time

Getting started

Prerequisites

Tool	Minimum version	Notes
Qt	6.2 (developed against 6.7.2)	Install via Qt Online Installer — include Quick, Multimedia, Widgets
CMake	3.16+	Bundled with Qt Creator
C++ compiler	C++17-capable	MSVC 2019+, Clang 12+, or GCC 9+
TagLib	1.13+	macOS: brew install taglib · Ubuntu: sudo apt install libtag1-dev · Windows: vcpkg vcpkg install taglib

Build & run

Option A — Qt Creator (easiest)

1. Clone the repo

   git clone https://github.com/hootbu/Qt-Music-Player.git

2. Open Qt-Music-Player/newMusicPlayer/CMakeLists.txt in Qt Creator
3. Configure with a Qt 6 kit, then Build → Run

Option B — Command line

git clone https://github.com/hootbu/Qt-Music-Player.git
cd Qt-Music-Player/newMusicPlayer
cmake -B build -S . -DCMAKE_PREFIX_PATH="<path/to/Qt/6.7.2/<compiler>>"
cmake --build build --config Release
./build/appnewMusicPlayer        # macOS / Linux
.\build\Release\appnewMusicPlayer.exe   # Windows

macOS users: if CMake can't find TagLib, set -DTagLib_DIR=$(brew --prefix taglib)/lib/cmake/taglib.

Usage

1. Click Load MP3s and select a folder containing .mp3 files
2. Pick a track from the list — title, artist, and cover art populate automatically
3. Use the playback bar:
   • ▶ / ⏸ — play / pause
   • ⏮ / ⏭ — previous / next
   • 🔀 — shuffle on/off
   • 🔁 — repeat on/off
   • Volume slider — vertical, on the right

Project structure

newMusicPlayer/
├── CMakeLists.txt          # Build configuration
├── main.cpp                # App entry, QML engine bootstrap
├── filemanagebackend.h     # C++ ↔ QML bridge (Q_PROPERTY, Q_INVOKABLE)
├── filemanagebackend.cpp   # Folder scanning + manual ID3v2 parser
├── Main.qml                # Full UI (controls, list, cover, sliders)
├── ui/assets/              # Icons, default cover art
└── soundFiles/             # Drop your MP3s here (gitignored)

How the C++ ↔ QML bridge works

• FileManageBackend is exposed to QML as the context property FileManageBackend
• Q_INVOKABLE QStringList fileSearch(QString path) — scans a folder for *.mp3
• Q_INVOKABLE void parseMp3(QString filePath) — extracts ID3v2 tags and emits change signals
• Q_PROPERTY title / artist / coverImagePath — bound to QML elements; the UI reacts automatically when a new track is selected

The ID3v2 parser walks frames manually (synchsafe sizes, encoding byte handling for TIT2, TPE1, APIC), so cover art works without TagLib's higher-level API.

Roadmap

• Drag-and-drop folder support
• Playlist save / load (M3U)
• Seek bar with waveform preview
• FLAC and OGG support
• Equalizer
• Dark / light theme toggle
• Pre-built binaries for Windows, macOS, Linux

Have an idea? Open an issue — contributions welcome.

Contributing

Pull requests are welcome. For larger changes, please open an issue first to discuss the direction.

1. Fork the repo
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes
4. Push and open a PR

License

This project is licensed under the MIT License — see LICENSE for details.

Author

Emir Yorgun — @hootbu

If this project helped you, please consider giving it a ⭐ — it makes a real difference for solo developers.