A local music player written in C++17 / Qt 6. It plays your own library and pulls music from YouTube, SoundCloud and 1000+ other sites through yt-dlp — search, listen immediately, or save to a FLAC library, all inside the same window.
Status: 0.4.2 — early, actively breaking. The Discover section now shows live
charts (Deezer, Apple Music, SoundCloud). Read
Known limitations before expecting it to behave like foobar2000.
Clone FLACORE, build it, and add it to your applications menu:
sudo pacman -S --needed base-devel cmake desktop-file-utils qt6-base \
qt6-multimedia qt6-multimedia-ffmpeg yt-dlp ffmpeg
git clone https://github.com/kiruimaru/FLACORE.git
cd FLACORE
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release \
-DCMAKE_INSTALL_PREFIX="$HOME/.local"
cmake --build build -j"$(nproc)"
cmake --install build
update-desktop-database "$HOME/.local/share/applications"Press Super+Alt+Space, search for FLACORE, and press Enter. In Omarchy,
Super+Space opens the main menu; Super+Alt+Space opens the Apps menu.
- Play local music: choose
File → Open Files, then double-click a playlist track. The next track starts automatically when it finishes. - Search online: open the
YouTubetab, search for a track, then choose Listen to play it or To library to save it. - Launch from a terminal: run
flacore.
yt-dlp is needed for online search and downloads. ffmpeg is used when saving
audio in a selected format. For other Linux distributions and Windows, see
Build.
On Windows, users who only want to run FLACORE should download the ready-made
FLACORE-windows-x64.zip from GitHub Releases.
They do not need to install a compiler, Qt, CMake, or Python; see the Windows
steps in Build.
- Quick start
- Features
- Screenshots
- Requirements
- Build
- Usage
- How the yt-dlp integration works
- Configuration
- Tests
- Project structure
- Known limitations
- Roadmap
- Troubleshooting
- Contributing
- Legal
- License
- Русская версия
- FLAC, MP3, WAV, OGG, M4A, AAC through Qt Multimedia
- Multi-file open dialog and drag & drop of files onto the track list
- Tags are read (FLAC/MP3/WAV): title, artist, album, duration and embedded cover
- Play / pause / stop / next / previous, drag-to-seek, volume
- Auto-advance to the next track, readable errors on broken files
- Double-click a playlist row to play it,
Ctrl+O/Space/Ctrl+←/Ctrl+→shortcuts
- Glass layout: custom window frame, sidebar sections, floating player bar, aurora backdrop that reacts to the accent colour
- Themes are packages —
theme.json+ optionaltheme.qss+assets/, five built in (liquid-glass,midnight,carbon,sugar-cloud,neon), your own dropped into the themes folder and picked fromAppearance → Themes - Tune everything: accent colour (or take it from the track's cover art), background image from a file or a URL, font family and scale, corner radius, glass density, blur, animations, performance mode
- Your own CSS over the theme, applied live, with tokens (
@accent,@radius,@font-sans, …) and stable hooks such asQWidget[dataUi="player"] - Way out if a style breaks the UI:
Ctrl+Alt+Shift+Cor--no-custom-css - Search filter in the header, toast messages instead of a status bar
- Full reference: docs/THEMES.md
- Search on YouTube or SoundCloud from the
YouTubetab (15 results) - Paste a link and get the track without searching — URL detection is automatic
- Listen — downloads the best audio stream into a local cache and starts playback; a second click reuses the cached file
- Save to library — extracts audio to FLAC (default), MP3, Opus or M4A, embeds metadata, and drops the track into the playlist
- Download a playlist URL in one job and add all downloaded tracks to the library
- Live download progress (percent, speed, ETA), a cancel button, and readable errors instead of silent failure
Discoveris the first section on the left: shelves with live charts from open endpoints that need no registration and no API key- Deezer chart — worldwide top or by genre (17 genres: pop, rap, electronic, dance, rock, R&B, jazz, classical, metal, Russian music, …), 30 tracks each
- Apple Music chart — most-played or new music by country (US, UK, DE, FR, RU)
- SoundCloud chart — read through
yt-dlp(--flat-playlist); if SoundCloud is unreachable (it answers 404 to Russian IPs), the shelf says so instead of pretending to be empty - Tracks show artist, duration and source; cover art is fetched in the background
and cached in
covercache, so the page paints instantly next time - Right-click a row: play a 30-second preview immediately (Deezer and Apple
serve one), listen in full or save to library through yt-dlp, open the
track page, or copy
artist - title - Listen / Save from a chart reuse the YouTube tab: the row becomes a search query on the chosen source, the first playable match is downloaded into the cache and starts playing. If a match is DRM-protected or dead, the next candidates are tried (up to three, and the source switches YouTube ↔ SoundCloud)
FLACORE_OFFLINE=1keeps the app off the network completely — the shelves stay empty and nothing is requested- The engine lives in
core/online/:Charts(URLs, parsers, catalogues) andCoverLoader(async covers with a disk cache), so it is testable without a UI
YtDlpis an asyncQProcesswrapper — no shell, no injection, no blocking UI- One process at a time; the UI disables itself while a job is running
- No FFmpeg libraries required to build; the
yt-dlpandffmpegexecutables are called at runtime
| What | Why | Version |
|---|---|---|
| C++ compiler | build | C++17 (GCC 11+, Clang 14+, MSVC 2019+) |
| CMake | build | 3.21+ |
Qt 6: Core, Gui, Widgets, Multimedia, Network |
UI, playback and background image download | 6.5+ (tested on 6.12) |
yt-dlp |
online search / download | recent (tested 2026.08.19) |
ffmpeg binary |
only for saving/converting audio to FLAC/MP3/Opus/M4A | 4.x+ |
| Qt Multimedia backend | actual audio output | qt6-multimedia-ffmpeg on Linux |
ffmpeg is optional: listening works without it because the stream is cached
as-is. Saving to the library in FLAC/MP3/Opus/M4A needs it for audio
post-processing. Local playback does not need the separate ffmpeg executable.
FFmpeg dev packages (libavcodec-dev etc.) are not needed. If you want
them anyway, configure with -DFLACORE_USE_FFMPEG_LIBS=ON.
sudo apt install build-essential cmake qt6-base-dev qt6-multimedia-dev \
qt6-multimedia-ffmpeg
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j"$(nproc)"
./build/src/flacoresudo pacman -S --needed base-devel cmake qt6-base qt6-multimedia
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j"$(nproc)"
./build/src/flacoresudo dnf install gcc-c++ cmake qt6-qtbase-devel qt6-qtmultimedia-devel
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j"$(nproc)"
./build/src/flacoreNo development tools are needed to run the release build:
| What you want to do | What must be installed |
|---|---|
| Play files already on the computer | Nothing extra |
| Search/download from YouTube (full current support) | Included in the release ZIP (yt-dlp.exe + Deno) |
| Search/download from SoundCloud | Included in the release ZIP (yt-dlp.exe) |
| Save/convert downloads to FLAC, MP3, Opus or M4A | Included in the release ZIP (ffmpeg.exe + ffprobe.exe) |
| Compile FLACORE from source | Git, Visual Studio C++ tools, Qt 6.8.3 MSVC 2022 x64, CMake |
The release ZIP includes portable yt-dlp.exe, Deno, FFmpeg and FFprobe in its
tools folder, so no Python, package manager, or separate install is needed
for online search, downloads, or audio conversion. FFmpeg is not needed for
local playback.
- Open GitHub Releases and
download
FLACORE-windows-x64.zipfrom the release's Assets list. Do not download the automatically generated Source code archive. - In File Explorer, right-click the ZIP and choose Extract All. Extract
the whole archive; do not try to run
flacore.exefrom inside the ZIP. - In the extracted files, open the folder that contains
flacore.exe(it may be inside aReleasesubfolder) and run it. Keep the other files and subfolders there; they contain the Qt libraries and plugins.
The archive is for 64-bit Windows and includes the Qt runtime files and the Microsoft compiler runtime deployed by the release workflow. Do not separately install Qt, Visual Studio, CMake, MSYS2, or Python just to use this archive. Local music playback works without the online tools below.
For YouTube and SoundCloud, just run FLACORE from the extracted release folder.
The ZIP already contains yt-dlp.exe, Deno, FFmpeg and FFprobe, and FLACORE
discovers them in the adjacent tools folder. Keep that folder beside
flacore.exe.
If you need to refresh those tools manually, install Python 3.10 or newer, open PowerShell in the extracted application folder, and run:
py -3 setup_windows.py --forceThe script downloads the official portable tools and verifies their published
checksums. The setup_windows.bat file runs the same helper by double-clicking.
The ready-made release already includes FFmpeg. If you are using an older archive or a source checkout, the helper can download it too (it is a large download):
py -3 setup_windows.py --ffmpegThis places both ffmpeg.exe and ffprobe.exe in tools/ffmpeg/bin, where
FLACORE finds them automatically. If the application still reports that
ffprobe is missing, close FLACORE, run this command from the folder containing
setup_windows.py, and start the application again.
Alternatively, use winget install --id Gyan.FFmpeg -e and select its folder
in the ffmpeg field on the yt-dlp page if it is not detected automatically.
If Windows reports a missing VCRUNTIME or MSVCP DLL, install the latest
Microsoft Visual C++ Redistributable for x64
and restart FLACORE. If SmartScreen warns that the publisher is unknown, first
verify that the ZIP came from the FLACORE GitHub Releases page; the release is
not code-signed.
Install MSYS2 and open the UCRT64 shell:
pacman -S --needed mingw-w64-ucrt-x86_64-gcc \
mingw-w64-ucrt-x86_64-cmake \
mingw-w64-ucrt-x86_64-ninja \
mingw-w64-ucrt-x86_64-qt6-base \
mingw-w64-ucrt-x86_64-qt6-multimedia
cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release \
-DCMAKE_PREFIX_PATH=/ucrt64
cmake --build build -j 8
./build/src/flacore.exeRunning the .exe outside the MSYS2 shell needs the Qt DLLs nearby — either add
C:\msys64\ucrt64\bin to PATH or run windeployqt build/src/flacore.exe.
To compile FLACORE yourself, install these components first:
- Install Git for Windows.
- Install Visual Studio Community 2022 or Visual Studio Build Tools 2022. In Visual Studio Installer, select the Desktop development with C++ workload and a Windows 10 or 11 SDK. Make sure the MSVC v143 x64/x86 build tools are selected.
- Install Qt 6.8.3 with the Qt
online installer. Expand Qt 6.8.3 and select MSVC 2022 64-bit plus the
Qt Multimedia module. The other required modules (
Core,Gui,Widgets, andNetwork) are included in this kit. The compiler and Qt kit must both be MSVC 2022 64-bit; do not select MinGW for this build. - Install CMake 3.21 or newer and enable its
option to add CMake to
PATH.
Open Developer PowerShell for VS 2022 (or x64 Native Tools Command Prompt). Clone the repository and enter its folder:
git clone https://github.com/kiruimaru/FLACORE.git
cd FLACOREIf Qt was installed somewhere other than C:\Qt, change the $Qt path below:
$Qt = "C:/Qt/6.8.3/msvc2022_64"
cmake -S . -B build -G "Visual Studio 17 2022" -A x64 `
"-DCMAKE_PREFIX_PATH=$Qt" -DFLACORE_BUILD_TESTS=ON
cmake --build build --config Release --parallel
ctest --test-dir build -C Release --output-on-failureTo run the locally built executable outside the Qt development environment, deploy its Qt runtime files from the same PowerShell window:
& "$Qt\bin\windeployqt.exe" --release --compiler-runtime `
".\build\src\Release\flacore.exe"
.\build\src\Release\flacore.exeThis source-build setup is not needed when using the ready-made release ZIP above.
The CMake files are portable; install qt6-base, qt6-multimedia, cmake and
ninja from ports/packages. This configuration is not tested by the maintainers.
# yt-dlp
pipx install yt-dlp # or: pip install --user -U yt-dlp
sudo pacman -S yt-dlp # Arch
winget install yt-dlp.yt-dlp # Windows
winget install DenoLand.Deno # JavaScript runtime for full YouTube support
# ffmpeg (only for saving/converting to FLAC/MP3/Opus/M4A)
sudo apt install ffmpeg # Debian/Ubuntu
winget install Gyan.FFmpeg # WindowsIf yt-dlp is not in PATH, point the app at it:
Tools → yt-dlp settings… (Инструменты → Настройки yt-dlp…).
File → Open Files(Ctrl+O) and pick one or more audio files.- Double-click a row in the
Playlisttab, or press Play. - Drag the progress slider to seek; the volume slider sits below the buttons.
- Switch to the
YouTubetab. - Choose the source in the dropdown: YouTube or SoundCloud.
- Type a query and press
Enter/ «Найти». Results show title, author, duration. - Pick a row and press:
- «Слушать» — download into the cache and start playing right away;
- «В библиотеку» — save to the library folder (FLAC by default) and add the track to the playlist.
- To download a full playlist, paste its URL and enable «Плейлист целиком».
Отменаstops the current download;Ctrl+Qquits the app.
Pasting a direct link (https://…) into the search field skips the search and
fetches that single track.
- Open the
Discoversection (it is the first one, shown on start). - Pick a genre for Deezer or a country and feed for Apple Music — the shelf reloads as soon as you change the dropdown, or press «Показать».
Обновить всёreloads every shelf, including the SoundCloud chart.- Select a row and press
Enter/double-click to listen in full, or right-click for the menu:▶ Превью 30 секунд,Слушать полностью,Сохранить в библиотеку,Открыть страницу трека,Скопировать «исполнитель — название». - Full playback happens on the
YouTubetab, where progress is visible; the player picks the file up as soon as it is downloaded.
Tools → yt-dlp settings… — path to yt-dlp, the folder containing ffmpeg,
the library folder, and the save format (FLAC / MP3 320 / Opus / M4A). The dialog
probes yt-dlp --version and shows the result immediately. Tools → Open library folder opens the library in your file manager.
src/core/ytdlp/YtDlp.{h,cpp} is a thin, opinionated wrapper around the CLI.
These are the exact commands it builds:
Search
yt-dlp "ytsearch15:<query>" --dump-single-json --flat-playlist --skip-download --no-warnings
yt-dlp "scsearch15:<query>" --dump-single-json --flat-playlist --skip-download --no-warnings
Single URL
yt-dlp "<url>" --no-playlist --dump-single-json --flat-playlist --skip-download --no-warnings
Listen (cache, no re-encode)
yt-dlp -f "bestaudio[ext=m4a]/bestaudio/best" \
--no-playlist --newline --no-warnings --progress \
--progress-template "download:FLACORE_PROGRESS %(progress._percent_str)s|%(progress.downloaded_bytes)s|%(progress.total_bytes_estimate)s|%(progress._speed_str)s|%(progress._eta_str)s" \
--print "after_move:FLACORE_FILE %(filepath)s" \
-o "<cache>/%(title)s [%(id)s].%(ext)s" "<url>"
Save to library
yt-dlp -f bestaudio/best -x --audio-format flac --audio-quality 0 \
--embed-metadata --add-metadata --ffmpeg-location "<ffmpeg dir>" \
--no-playlist --newline --no-warnings --progress \
--progress-template "download:FLACORE_PROGRESS ..." \
--print "after_move:FLACORE_FILE %(filepath)s" \
-o "<library>/%(artist,uploader,channel)s - %(title)s.%(ext)s" "<url>"
Why this shape:
m4ais preferred for playback because the WMF backend on Windows cannot play WebM/Opus, while MP3/M4A/FLAC work everywhere.--print after_move:filepathis the only reliable way to learn the final path after post-processing (-xchanges the extension and may rename the file).--progressis passed explicitly:--printimplies--quiet, which would otherwise swallow the progress lines.PYTHONIOENCODING=utf-8andPYTHONUTF8=1are set for the child process so Cyrillic titles are not mangled on Windows.
Stored with QSettings — no config file parsing involved:
| Key | Meaning | Default |
|---|---|---|
ytdlp/binary |
full path to yt-dlp |
auto: PATH |
ytdlp/ffmpegDir |
folder containing the ffmpeg binary |
auto: PATH |
ytdlp/libraryDir |
where «В библиотеку» saves | ~/Music/FLACORE |
ytdlp/audioFormat |
flac / mp3 / opus / m4a |
flac |
appearance/theme |
active theme id | liquid-glass |
appearance/accent |
accent override (#rrggbb), empty = from the theme |
empty |
appearance/customCss, appearance/customCssEnabled |
your CSS and its toggle | empty, on |
appearance/backgroundImage, appearance/backgroundBlur |
wallpaper and its blur | empty, theme value |
appearance/{radius,glassAlpha,blur,font,fontScale,mode,animations} |
appearance sliders | theme values |
Where it lands:
- Linux:
~/.config/flacore.conf, cache in~/.cache/flacore/ytdlp - Windows: registry
HKEY_CURRENT_USER\Software\flacore, cache in%LOCALAPPDATA%\flacore\cache\ytdlp - Your themes:
%APPDATA%\FLACORE\FLACORE\themeson Windows,~/.local/share/FLACORE/FLACORE/themeson Linux (see docs/THEMES.md)
Two environment variables change behaviour without touching the settings:
FLACORE_OFFLINE=1— never touch the network (charts stay empty). Used by the tests, handy on a metered connection.FLACORE_LIVE_YTDLP=<path>— used by the manual live probe to point atyt-dlp.
Delete those to factory-reset the app.
No network, no real yt-dlp, no audio device needed — the CLI contract is
exercised against a compiled stub (tests/fake_ytdlp.cpp).
cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug
cmake --build build -j
ctest --test-dir build --output-on-failureWhat is covered (five test binaries, 304 assertions):
ytdlp_test— the CLI contract against a compiled stub: availability probe, search JSON (playlist, direct URL,uploader→channel, live streams),ytsearchvsscsearch, download progress and final path, failures, cancelmedia_test— tag reading on fixtures built byte by byte (FLAC STREAMINFO + VORBIS_COMMENT + PICTURE, MP3 ID3v2 + MPEG frame, WAV), playlist metadata, cover palette extractiontheme_test—theme.jsonparsing and validation, token derivation for dark and light themes,@tokensubstitution, custom CSS sanitising, built stylesheet (no unresolved tokens), plus WCAG contrast checks for every built-in themecharts_test— the Discover engine on fixtures: Deezer and Apple chart JSON (artist-picture fallback,durationInMillis,100x100bb→600x600bb), error payloads and broken JSON, source URLs and limits, genre and country catalogues,artist - titlequeries,yt-dlprecords → chart rows, and the SoundCloud chart read through theyt-dlpstubui_test(offscreen) — window shell, playlist wired to the view, add/remove/ clear, index shifts, all built-in themes applied on a live window, custom CSS, theCtrl+Alt+Shift+Cescape hatch, the Discover shelves fed with synthetic chart rows (roles, durations,artist - titlerouting, 30-second preview URL); it also saves screenshots
Turn tests off with -DFLACORE_BUILD_TESTS=OFF.
tests/live_probe.cpp is built but not registered with ctest: it needs the
real network and the real yt-dlp. It boots the whole window and checks what
fixtures cannot: Deezer and Apple charts actually arriving, a preview stream
actually playing, a chart row actually becoming a cached file in the playlist,
and the SoundCloud chart responding.
cd build/tests
FLACORE_LIVE_YTDLP=/path/to/yt-dlp ./live_probe.exeFLACORE/
├── CMakeLists.txt # Qt6 lookup, optional FFmpeg libs, tests
├── src/
│ ├── main.cpp # QApplication, --no-custom-css, ThemeManager
│ ├── CMakeLists.txt # flacore_lib + qt_add_executable, -Wall -Wextra
│ ├── resources.qrc # built-in themes (theme.json + theme.qss)
│ ├── core/
│ │ ├── media/ # MediaTags (FLAC/MP3/WAV tags, cover), CoverPalette
│ │ ├── online/ # Charts (Deezer/Apple charts, parsers), CoverLoader
│ │ ├── player/Playlist.* # Track, list, current index, signals
│ │ └── ytdlp/
│ │ ├── YtDlpTypes.h # YtDlpResult, formatDuration()
│ │ └── YtDlp.* # QProcess wrapper: search/download/cancel
│ ├── themes/<id>/ # built-in themes: theme.json + theme.qss
│ └── ui/
│ ├── MainWindow.* # shell: title bar, sidebar, pages, player bar
│ ├── YouTubePanel.* # search UI, progress, play/save buttons
│ ├── YtDlpSettingsForm.* # shared settings form
│ ├── YtDlpSettingsDialog.* # the same form as a dialog
│ ├── theme/ # Theme, StyleSheet, ThemeManager, ThemeUtil
│ ├── pages/ # Discover, Library, Appearance, ThemeTile, YtDlp
│ └── widgets/ # AuroraBackdrop, GlassPanel, CoverArt, SeekBar,
│ # TitleBar, PlayerBar, TrackDelegate, ShelfDelegate,
│ # Icons
├── themes/example/ # user theme to copy (see docs/THEMES.md)
├── docs/THEMES.md # theme format, tokens, hooks, own CSS
├── tests/
│ ├── fake_ytdlp.cpp # stub with the same CLI contract
│ ├── ytdlp_test.cpp # yt-dlp wrapper, no network
│ ├── media_test.cpp # tags and cover palette on synthetic fixtures
│ ├── theme_test.cpp # theme JSON, tokens, custom CSS
│ ├── charts_test.cpp # charts, parsers, yt-dlp records (fixtures)
│ ├── ui_test.cpp # offscreen UI + screenshots
│ ├── live_probe.cpp # manual run with the real network and yt-dlp
│ └── CMakeLists.txt
├── LICENSE # GPL-3.0
└── README.md
Layering rule: core/ knows nothing about widgets, ui/ never spawns processes
directly. core/ + ui/ build into the static library flacore_lib, so the
tests link the very same code the app runs. Playlist owns the state and emits
signals; pages only render it and report user intents.
An honest list — these are real, not hypothetical:
- Playlist is in memory. No M3U import/export, no persistence between runs.
- No shuffle / repeat / queue.
- No media keys, no MPRIS, no tray icon.
- No packaging. No AppImage, Flatpak, MSI or
.desktopfile yet. - The "glass" is not a real backdrop filter. Qt Widgets cannot blur what is behind a widget, so panels are translucent and the backdrop image itself is blurred. Looks close, costs nothing.
- Tags are read for FLAC/MP3/WAV only. M4A/AAC/OGG show the file name.
- YouTube may be unreachable from your network (it is from Russia without a
proxy). Use the SoundCloud source, or add
--proxytoyt-dlp's own config. - Charts come from public, undocumented endpoints (Deezer, the Apple Marketing Tools RSS feed). They need no API key — and that is also their weakness: the formats can change without notice, and the endpoints can be blocked.
- SoundCloud charts are read through
yt-dlp. SoundCloud answers 404 tosoundcloud.com/chartsfrom some regions (Russia included), so that shelf shows an error there; the Deezer and Apple shelves keep working. - The feed is not personalised. No likes, no listening history, no recommendations — just charts.
- auto-advance and a proper transport state (
refreshTransport(),EndOfMedia) -
PlaylistModel : QAbstractListModel+QListView(drag & drop, roles) - tag and cover reading (FLAC/MP3/WAV), accent from the cover palette
- theme system: packages, tokens, own CSS, escape hatch — see
docs/THEMES.md - Discover section: live charts (Deezer / Apple Music / SoundCloud via yt-dlp)
- personalised feed: likes, history, recommendations
- 30-second previews without leaving the Discover page (they currently play in the main player bar)
- M3U save/load, shuffle, repeat
- Download playlist URLs and add all downloaded tracks to the library
- Theme presets, custom color editors, JSON configs and background images
- Feedback link to GitHub Issues
- download queue instead of one job at a time
- MPRIS2 + media keys, tray icon
- GitHub Actions: build on Linux + the four test binaries
- packaging: AppImage / Flatpak / Windows installer
«yt-dlp не найден» — the binary is not in PATH. Set the full path in the
yt-dlp section on the left (or Меню → Настройки yt-dlp…). On Windows
pip install puts it into
%LOCALAPPDATA%\Programs\Python\Python3xx\Scripts, which is often not in PATH.
Download works, FLAC save fails — no ffmpeg. Install it or point to its
folder in the settings dialog. The error text from yt-dlp appears under the
progress bar, usually ffmpeg not found.
«ERROR: Unable to download API page … [WinError 10054]» — the site is blocked
or reset by your ISP. YouTube is not reachable from some regions; use SoundCloud,
or configure a proxy in ~/.config/yt-dlp/config (--proxy http://host:port).
MP3 plays, WebM/Opus stays silent — the Qt Multimedia backend cannot decode
it. On Linux install qt6-multimedia-ffmpeg; on Windows prefer the m4a source
(the app already asks for bestaudio[ext=m4a] first).
Could not find a package configuration file provided by "Qt6" — pass
-DCMAKE_PREFIX_PATH=<Qt dir>, e.g. /ucrt64, C:/Qt/6.8.3/msvc2022_64, or the
parent of /usr/lib/cmake/Qt6. With MSYS2 the value is /ucrt64 inside the
MSYS2 shell.
CXX compiler identification is unknown on Windows — Visual Studio without
the Windows SDK, or no compiler at all. Use the MSYS2 route above.
Charts stay empty / «Deezer недоступен» — the app could not reach the chart
sources. Check the internet, a proxy/VPN, or run with FLACORE_OFFLINE=1 if you
want the app to stay off the network on purpose. The SoundCloud shelf failing with
a 404 while Deezer works means SoundCloud is blocked for your region, not a bug.
A chart row plays the wrong track or fails — the row is turned into an
artist - title search on the source chosen on the YouTube tab. If the first hit
is DRM-protected, the app automatically tries the next candidates (up to three)
and then the other source. If everything fails, use Открыть страницу трека and
paste the link into the search field instead.
Progress stays at 0 % — yt-dlp did not report total_bytes_estimate
(common for HLS). The bar stays in busy mode and the final path still arrives;
that is expected.
- Build and run the tests before opening a PR (
ctest --test-dir build). - Keep the layering (
core/↔ui/) and put new logic incore/so it can be tested without a GUI. - UI strings may be Russian, but keep identifiers and comments consistent with the file you touch.
Bug reports are welcome with: OS, Qt version, yt-dlp --version, the exact
command from the log, and what you expected.
FLACORE is a player. It ships no content and hosts nothing. The yt-dlp integration is a convenience wrapper around a third-party tool: you are responsible for what you download, for complying with the terms of service of the sites you use, and with the copyright law of your country. Do not use it to redistribute copyrighted material.
GPL-3.0 — see LICENSE.
Локальный музыкальный плеер на C++17 / Qt 6. Играет вашу фонотеку и тянет музыку с YouTube, SoundCloud и ещё 1000+ сайтов через yt-dlp: поиск, мгновенное прослушивание или сохранение в библиотеку FLAC — всё в одном окне.
Статус: 0.4.2 — ранняя версия, всё ещё ломается. В разделе «Обзор» появились живые чарты (Deezer, Apple Music, SoundCloud). Перед тем как ждать поведения foobar2000, прочитайте Ограничения.
Склонируйте FLACORE, соберите его и добавьте в меню приложений:
sudo pacman -S --needed base-devel cmake desktop-file-utils qt6-base \
qt6-multimedia qt6-multimedia-ffmpeg yt-dlp ffmpeg
git clone https://github.com/kiruimaru/FLACORE.git
cd FLACORE
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release \
-DCMAKE_INSTALL_PREFIX="$HOME/.local"
cmake --build build -j"$(nproc)"
cmake --install build
update-desktop-database "$HOME/.local/share/applications"Нажмите Super+Alt+Space, найдите FLACORE и нажмите Enter. В Omarchy
сочетание Super+Space открывает главное меню, а Super+Alt+Space — меню
приложений.
- Локальная музыка: выберите
Файл → Открыть файлы, затем дважды нажмите на трек в плейлисте. После его окончания автоматически начнётся следующий. - Поиск музыки онлайн: откройте вкладку
YouTube, найдите трек и нажмите Слушать, чтобы включить его, или В библиотеку, чтобы сохранить. - Запуск из терминала: выполните
flacore.
yt-dlp нужен для поиска и скачивания музыки онлайн. ffmpeg используется
при сохранении аудио в выбранном формате. Сборку в других Linux-дистрибутивах
и Windows смотрите в разделе Сборка.
- Быстрый старт
- Возможности
- Требования
- Сборка
- Использование
- Как работает интеграция с yt-dlp
- Настройки
- Тесты
- Структура проекта
- Ограничения
- Планы
- Решение проблем
- Лицензия
Локальное воспроизведение
- FLAC, MP3, WAV, OGG, M4A, AAC через Qt Multimedia
- Открытие сразу нескольких файлов и перетаскивание файлов в список
- Теги читаются (FLAC/MP3/WAV): название, исполнитель, альбом, длительность, обложка
- Play / пауза / стоп / следующий / предыдущий, перемотка перетаскиванием, громкость
- Автопереход на следующий трек, понятные ошибки на битых файлах
- Двойной клик по строке плейлиста запускает трек; горячие клавиши
Ctrl+O,Space,Ctrl+←/→
Оформление и интерфейс
- Стеклянная раскладка: своя шапка окна, разделы слева, плавающая панель плеера, живой фон, который реагирует на акцент
- Темы — это пакеты:
theme.json+ необязательныйtheme.qss+assets/, пять встроенных (liquid-glass,midnight,carbon,sugar-cloud,neon), свои кладутся в папку тем и выбираются в «Оформление → Тема» - Настраивается всё: акцент (в том числе из обложки трека), фоновое изображение из файла или по ссылке, шрифт и его масштаб, скругление, плотность стекла, размытие, анимации, режим производительности
- Свой CSS поверх темы, применяется сразу, с токенами (
@accent,@radius,@font-sans, …) и стабильными хуками видаQWidget[dataUi="player"] - Если стиль сломал интерфейс:
Ctrl+Alt+Shift+Cили запуск с--no-custom-css - Поиск-фильтр в шапке, всплывающие сообщения вместо строки состояния
- Полное описание: docs/THEMES.md
Онлайн (yt-dlp)
- Поиск по YouTube или SoundCloud на вкладке
YouTube(15 результатов) - Вставка ссылки — трек без поиска, URL распознаётся автоматически
- «Слушать» — лучший аудиопоток скачивается в локальный кэш и сразу играет; повторное нажатие переиспользует уже скачанный файл
- «В библиотеку» — извлечение аудио в FLAC (по умолчанию), MP3, Opus или M4A с вшиванием метаданных; трек сразу попадает в плейлист
- Живой прогресс (проценты, скорость, ETA), кнопка отмены и понятные ошибки вместо молчаливого отказа
Обзор — живая подборка
Обзор— первый раздел слева: полки с живыми чартами из открытых источников, без регистрации и без API-ключей- Чарт Deezer — топ по всему миру или по жанру (17 жанров: поп, рэп, электронная, танцевальная, рок, R&B, джаз, классика, металл, русская музыка и другие), по 30 треков
- Чарт Apple Music — самые прослушиваемые или новинки по стране (США, Великобритания, Германия, Франция, Россия)
- Чарт SoundCloud — читается через
yt-dlp(--flat-playlist); если SoundCloud недоступен (из России он отвечает 404), полка честно об этом пишет, а не притворяется пустой - В строках видны исполнитель, длительность и источник; обложки докачиваются в
фоне и кладутся в кэш
covercache, поэтому страница открывается мгновенно - Правый клик по строке: превью на 30 секунд сразу (его отдают Deezer и Apple), слушать полностью или сохранить в библиотеку через yt-dlp, открыть страницу трека, скопировать «исполнитель — название»
- «Слушать» и «В библиотеку» из чарта работают через вкладку
YouTube: строка превращается в поисковый запрос на выбранном источнике, первый живой результат скачивается в кэш и сразу играет. Если он под DRM или удалён, приложение само пробует следующие (до трёх) и переключает источник YouTube ↔ SoundCloud FLACORE_OFFLINE=1полностью отключает сеть — полки остаются пустыми, запросов нет- Движок лежит в
core/online/:Charts(ссылки, парсеры, справочники) иCoverLoader(асинхронные обложки с кэшем на диске) — тестируется без GUI
Под капотом
YtDlp— асинхронная обёртка надQProcess: без shell, без инъекций, интерфейс не блокируется- Один процесс за раз; на время работы элементы управления отключаются
- Библиотеки FFmpeg для сборки не нужны — вызываются исполняемые файлы
yt-dlpиffmpeg
| Что | Зачем | Версия |
|---|---|---|
| Компилятор C++ | сборка | C++17 (GCC 11+, Clang 14+, MSVC 2019+) |
| CMake | сборка | 3.21+ |
Qt 6: Core, Gui, Widgets, Multimedia, Network |
интерфейс, воспроизведение, загрузка фона по ссылке | 6.5+ (проверено на 6.12) |
yt-dlp |
поиск и скачивание | свежий (проверено 2026.08.19) |
бинарник ffmpeg |
только для сохранения/конвертации в FLAC/MP3/Opus/M4A | 4.x+ |
| бэкенд Qt Multimedia | собственно звук | qt6-multimedia-ffmpeg на Linux |
ffmpeg необязателен: прослушивание работает без него, потому что поток
кэшируется как есть. Сохранение в библиотеку в форматах FLAC/MP3/Opus/M4A
требует ffmpeg для обработки аудио. Для локального воспроизведения отдельный
бинарник ffmpeg не нужен.
Пакеты FFmpeg для разработки (libavcodec-dev и т.п.) не требуются. Если
всё же нужны — конфигурируйте с -DFLACORE_USE_FFMPEG_LIBS=ON.
Debian / Ubuntu
sudo apt install build-essential cmake qt6-base-dev qt6-multimedia-dev \
qt6-multimedia-ffmpeg
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j"$(nproc)"
./build/src/flacoreArch Linux
sudo pacman -S --needed base-devel cmake qt6-base qt6-multimedia
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j"$(nproc)"
./build/src/flacoreFedora
sudo dnf install gcc-c++ cmake qt6-qtbase-devel qt6-qtmultimedia-devel
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j"$(nproc)"
./build/src/flacoreWindows — запуск готового релиза (рекомендуется обычным пользователям)
Для запуска не нужны инструменты разработки:
| Что нужно делать | Что установить |
|---|---|
| Слушать файлы, которые уже есть на компьютере | Ничего дополнительно |
| Искать/скачивать с YouTube (полная актуальная поддержка) | Уже в ZIP релиза (yt-dlp.exe + Deno) |
| Искать/скачивать с SoundCloud | Уже в ZIP релиза (yt-dlp.exe) |
| Сохранять/конвертировать скачанное в FLAC, MP3, Opus или M4A | Уже в ZIP релиза (ffmpeg.exe + ffprobe.exe) |
| Собирать FLACORE из исходников | Git, инструменты C++ Visual Studio, Qt 6.8.3 MSVC 2022 x64, CMake |
В ZIP релиза уже есть переносимые yt-dlp.exe, Deno, FFmpeg и FFprobe в папке
tools, поэтому для поиска, скачивания и конвертации музыки не нужно отдельно
устанавливать Python, менеджер пакетов или эти инструменты. Для локального
воспроизведения FFmpeg не требуется.
- Откройте GitHub Releases и
скачайте
FLACORE-windows-x64.zipиз списка Assets у нужного релиза. Не скачивайте автоматически созданный архив Source code. - В Проводнике нажмите ZIP правой кнопкой и выберите Извлечь все. Извлеките
весь архив; не запускайте
flacore.exeпрямо внутри ZIP. - Найдите в распакованных файлах папку с
flacore.exe(он может быть во вложенной папкеRelease) и запустите его. Не удаляйте и не переносите отдельно от него остальные файлы и папки: там находятся Qt DLL и плагины.
Архив собран для 64-разрядной Windows и содержит файлы Qt и распространяемую среду Microsoft C++, добавленные при сборке релиза. Для запуска архива не нужно отдельно ставить Qt, Visual Studio, CMake, MSYS2 или Python. Локальную музыку можно слушать без дополнительных онлайн-инструментов.
Для YouTube и SoundCloud просто запустите FLACORE из распакованной папки
релиза. В ZIP уже находятся yt-dlp.exe, Deno, FFmpeg и FFprobe; FLACORE
находит их в соседней папке tools. Не переносите tools отдельно от
flacore.exe.
Если нужно вручную обновить инструменты, установите Python 3.10 или новее, откройте PowerShell в папке приложения и выполните:
py -3 setup_windows.py --forceСкрипт скачает официальные переносимые версии инструментов и проверит
опубликованные контрольные суммы. То же самое запускает двойной щелчок по
setup_windows.bat.
Готовый архив релиза уже содержит FFmpeg. Если используется старый архив или сборка из исходников, скачайте его вручную (это большой файл):
py -3 setup_windows.py --ffmpegЭто скачает ffmpeg.exe и ffprobe.exe в tools/ffmpeg/bin, откуда FLACORE
определит их автоматически. Также можно установить FFmpeg через winget install --id Gyan.FFmpeg -e; если программа не найдёт его сама, укажите папку
с ffmpeg.exe в разделе yt-dlp.
Если Windows сообщает об отсутствующей DLL VCRUNTIME или MSVCP, установите
последнюю Microsoft Visual C++ Redistributable для x64
и перезапустите FLACORE. Если SmartScreen сообщает о неизвестном издателе,
сначала убедитесь, что архив скачан со страницы GitHub Releases проекта: у
релиза нет цифровой подписи.
Windows — сборка из исходников через MSYS2 (проверено)
Установите MSYS2 и откройте оболочку UCRT64:
pacman -S --needed mingw-w64-ucrt-x86_64-gcc \
mingw-w64-ucrt-x86_64-cmake \
mingw-w64-ucrt-x86_64-ninja \
mingw-w64-ucrt-x86_64-qt6-base \
mingw-w64-ucrt-x86_64-qt6-multimedia
cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release \
-DCMAKE_PREFIX_PATH=/ucrt64
cmake --build build -j 8
./build/src/flacore.exeЧтобы запускать .exe вне оболочки MSYS2, рядом должны быть DLL Qt: либо
добавьте C:\msys64\ucrt64\bin в PATH, либо выполните
windeployqt build/src/flacore.exe.
Windows — сборка из исходников через Visual Studio
Если хотите самостоятельно скомпилировать FLACORE, сначала установите:
- Установите Git for Windows.
- Установите Visual Studio Community 2022 или Visual Studio Build Tools 2022. В Visual Studio Installer выберите компонент Разработка классических приложений на C++ и Windows 10/11 SDK. Проверьте, что также выбран компилятор MSVC v143 для x64/x86.
- Установите Qt 6.8.3 через
онлайн-установщик Qt. В списке Qt 6.8.3 отметьте комплект MSVC 2022
64-bit и модуль Qt Multimedia. Остальные необходимые модули (
Core,Gui,Widgets,Network) входят в этот комплект. Для этой сборки и компилятор, и Qt должны быть MSVC 2022 64-bit; вариант MinGW не подходит. - Установите CMake версии 3.21 или новее и
включите добавление CMake в
PATH.
Откройте Developer PowerShell for VS 2022 (или x64 Native Tools Command Prompt). Склонируйте проект и перейдите в его папку:
git clone https://github.com/kiruimaru/FLACORE.git
cd FLACOREЕсли Qt установлен не в C:\Qt, измените путь в переменной $Qt:
$Qt = "C:/Qt/6.8.3/msvc2022_64"
cmake -S . -B build -G "Visual Studio 17 2022" -A x64 `
"-DCMAKE_PREFIX_PATH=$Qt" -DFLACORE_BUILD_TESTS=ON
cmake --build build --config Release --parallel
ctest --test-dir build -C Release --output-on-failureЧтобы запускать собранную программу вне среды Qt, разверните необходимые Qt DLL из того же PowerShell:
& "$Qt\bin\windeployqt.exe" --release --compiler-runtime `
".\build\src\Release\flacore.exe"
.\build\src\Release\flacore.exeЭти шаги сборки не нужны, если вы скачали готовый ZIP релиза.
FreeBSD и другие Unix
CMake-файлы портируемы: поставьте qt6-base, qt6-multimedia, cmake и ninja
из портов/пакетов. Мейнтейнеры эту конфигурацию не тестировали.
Установка yt-dlp и ffmpeg
# yt-dlp
pipx install yt-dlp # или: pip install --user -U yt-dlp
sudo pacman -S yt-dlp # Arch
winget install yt-dlp.yt-dlp # Windows
winget install DenoLand.Deno # JavaScript runtime для полной поддержки YouTube
# ffmpeg (только для сохранения/конвертации в FLAC/MP3/Opus/M4A)
sudo apt install ffmpeg # Debian/Ubuntu
winget install Gyan.FFmpeg # WindowsЕсли yt-dlp не в PATH, укажите путь в приложении:
«Инструменты → Настройки yt-dlp…» (Tools → yt-dlp settings…).
Локальные файлы
File → Open Files(Ctrl+O) — выберите один или несколько аудиофайлов.- Двойной клик по строке на вкладке
Playlistили кнопка воспроизведения. - Перемотка — перетаскиванием ползунка; громкость — ползунком ниже кнопок.
Поиск и прослушивание онлайн
- Перейдите на вкладку
YouTube. - Выберите источник в выпадающем списке: YouTube или SoundCloud.
- Введите запрос и нажмите
Enter/ «Найти». В результатах видны название, автор и длительность. - Выберите строку и нажмите:
- «Слушать» — скачать в кэш и сразу включить;
- «В библиотеку» — сохранить в папку библиотеки (по умолчанию FLAC) и добавить трек в плейлист.
- Чтобы скачать плейлист целиком, вставьте его URL и включите «Плейлист целиком».
- «Отмена» прерывает текущее скачивание,
Ctrl+Qзакрывает приложение.
Если вставить в поле поиска прямую ссылку (https://…), поиск пропускается и
загружается именно этот трек.
Живая подборка
- Откройте раздел
Обзор(он первый и показывается при запуске). - Выберите жанр для Deezer или страну и ленту для Apple Music — полка обновляется сразу при смене списка, либо нажмите «Показать».
- «Обновить всё» перезагружает все полки, включая чарт SoundCloud.
- Выберите строку:
Enter/двойной клик — слушать полностью; правый клик — меню «▶ Превью 30 секунд», «Слушать полностью», «Сохранить в библиотеку», «Открыть страницу трека», «Скопировать „исполнитель — название“». - Полное воспроизведение идёт через вкладку
YouTube, там виден прогресс; плеер подхватывает файл сразу после скачивания.
Настройки
«Инструменты → Настройки yt-dlp…» — путь к yt-dlp, папка с ffmpeg, папка
библиотеки и формат сохранения (FLAC / MP3 320 / Opus / M4A). Диалог сразу
проверяет yt-dlp --version и показывает результат. «Инструменты → Открыть
папку библиотеки» открывает её в файловом менеджере.
«Вид → Тема» предлагает готовые темы, редакторы цветов «Хардкор» и
«Интерактивный», импорт/экспорт JSON-конфига и выбор фото фона. Кнопка
Feedback открывает GitHub Issues.
src/core/ytdlp/YtDlp.{h,cpp} — тонкая обёртка над CLI. Вот точные команды,
которые она собирает:
Поиск
yt-dlp "ytsearch15:<запрос>" --dump-single-json --flat-playlist --skip-download --no-warnings
yt-dlp "scsearch15:<запрос>" --dump-single-json --flat-playlist --skip-download --no-warnings
Одна ссылка
yt-dlp "<url>" --no-playlist --dump-single-json --flat-playlist --skip-download --no-warnings
Прослушивание (кэш, без перекодирования)
yt-dlp -f "bestaudio[ext=m4a]/bestaudio/best" \
--no-playlist --newline --no-warnings --progress \
--progress-template "download:FLACORE_PROGRESS %(progress._percent_str)s|%(progress.downloaded_bytes)s|%(progress.total_bytes_estimate)s|%(progress._speed_str)s|%(progress._eta_str)s" \
--print "after_move:FLACORE_FILE %(filepath)s" \
-o "<кэш>/%(title)s [%(id)s].%(ext)s" "<url>"
Сохранение в библиотеку
yt-dlp -f bestaudio/best -x --audio-format flac --audio-quality 0 \
--embed-metadata --add-metadata --ffmpeg-location "<папка ffmpeg>" \
--no-playlist --newline --no-warnings --progress \
--progress-template "download:FLACORE_PROGRESS ..." \
--print "after_move:FLACORE_FILE %(filepath)s" \
-o "<библиотека>/%(artist,uploader,channel)s - %(title)s.%(ext)s" "<url>"
Почему именно так:
m4aпредпочтителен для проигрывания: WMF-бэкенд в Windows не умеет WebM/Opus, а MP3/M4A/FLAC играются везде.--print after_move:filepath— единственный надёжный способ узнать итоговый путь после постобработки (-xменяет расширение и может переименовать файл).--progressпередаётся явно:--printвключает--quiet, который иначе съел бы строки прогресса.- Для дочернего процесса выставляются
PYTHONIOENCODING=utf-8иPYTHONUTF8=1, иначе на Windows ломаются кириллические названия.
Хранятся через QSettings, своего парсера конфигов нет:
| Ключ | Значение | По умолчанию |
|---|---|---|
ytdlp/binary |
полный путь к yt-dlp |
авто: PATH |
ytdlp/ffmpegDir |
папка с бинарником ffmpeg |
авто: PATH |
ytdlp/libraryDir |
куда сохраняет «В библиотеку» | ~/Music/FLACORE |
ytdlp/audioFormat |
flac / mp3 / opus / m4a |
flac |
Где это лежит:
- Linux:
~/.config/flacore.conf, кэш в~/.cache/flacore/ytdlp - Windows: реестр
HKEY_CURRENT_USER\Software\flacore, кэш в%LOCALAPPDATA%\flacore\cache\ytdlp
Две переменные окружения меняют поведение без правки настроек:
FLACORE_OFFLINE=1— не ходить в сеть вообще (полки чартов остаются пустыми). Используется тестами, пригодится на лимитированном трафике.FLACORE_LIVE_YTDLP=<путь>— путь кyt-dlpдля ручного живого прогона.
Удалите эти данные, чтобы сбросить приложение к состоянию «как после установки».
Сеть, настоящий yt-dlp и звуковое устройство не нужны — контракт CLI
проверяется на скомпилированной заглушке (tests/fake_ytdlp.cpp).
cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug
cmake --build build -j
ctest --test-dir build --output-on-failureЧто покрыто (пять тестовых бинарников, 304 проверок):
ytdlp_test— контракт CLI на скомпилированной заглушке: проверка доступности, разбор JSON (плейлист, прямая ссылка,uploader→channel, live-стримы),ytsearchпротивscsearch, прогресс и итоговый путь, ошибки, отменаmedia_test— чтение тегов на фикстурах, собранных байт за байтом (FLAC STREAMINFO + VORBIS_COMMENT + PICTURE, MP3 ID3v2 + кадр MPEG, WAV), метаданные в плейлисте, палитра из обложкиtheme_test— разбор и проверкаtheme.json, вывод токенов для тёмной и светлой темы, подстановка@токенов, аварийный разбор своего CSS, сборка итогового стиля (не остаётся неподставленных токенов), плюс проверки контраста по WCAG для каждой встроенной темыcharts_test— движок «Обзора» на фикстурах: ответы чартов Deezer и Apple (включая запасное фото исполнителя,durationInMillis,100x100bb→600x600bb), ответы с ошибкой и битый JSON, ссылки и ограничения источников, справочники жанров и стран, запросы «исполнитель — название», записи yt-dlp → строки чарта и чтение чарта SoundCloud через заглушку yt-dlpui_test(offscreen) — каркас окна, связь плейлиста с представлением, добавление/удаление/очистка, сдвиг индексов, применение всех встроенных тем на живом окне, свой CSS, аварийноеCtrl+Alt+Shift+C, полки «Обзора» на подставленных строках чарта (роли, длительности, маршрутизация «исполнитель — название», ссылка превью); тест заодно сохраняет скриншоты
Отключить тесты: -DFLACORE_BUILD_TESTS=OFF.
tests/live_probe.cpp собирается, но не регистрируется в ctest: ему нужны
настоящая сеть и настоящий yt-dlp. Он поднимает всё окно и проверяет то, что
фикстурами не проверить: приходят ли чарты Deezer и Apple, играет ли поток
превью, превращается ли строка чарта в скачанный файл в плейлисте и отвечает ли
чарт SoundCloud.
cd build/tests
FLACORE_LIVE_YTDLP=/path/to/yt-dlp ./live_probe.exeFLACORE/
├── CMakeLists.txt # поиск Qt6, опциональные libav*, тесты
├── src/
│ ├── main.cpp # QApplication, --no-custom-css, ThemeManager
│ ├── CMakeLists.txt # flacore_lib + qt_add_executable, -Wall -Wextra
│ ├── resources.qrc # встроенные темы (theme.json + theme.qss)
│ ├── core/
│ │ ├── media/ # MediaTags (теги FLAC/MP3/WAV, обложка), CoverPalette
│ │ ├── online/ # Charts (чарты Deezer/Apple, парсеры), CoverLoader
│ │ ├── player/Playlist.* # Track, список, текущий индекс, сигналы
│ │ └── ytdlp/
│ │ ├── YtDlpTypes.h # YtDlpResult, formatDuration()
│ │ └── YtDlp.* # QProcess: search/download/cancel
│ ├── themes/<id>/ # встроенные темы: theme.json + theme.qss
│ └── ui/
│ ├── MainWindow.* # каркас: шапка, сайдбар, страницы, панель плеера
│ ├── YouTubePanel.* # поиск, прогресс, кнопки «Слушать»/«В библиотеку»
│ ├── YtDlpSettingsForm.* # форма настроек yt-dlp (общая)
│ ├── YtDlpSettingsDialog.* # та же форма в виде диалога
│ ├── theme/ # Theme, StyleSheet, ThemeManager, ThemeUtil
│ ├── pages/ # страницы: обзор, библиотека, оформление, темы, yt-dlp
│ └── widgets/ # AuroraBackdrop, GlassPanel, CoverArt, SeekBar,
│ # TitleBar, PlayerBar, TrackDelegate, ShelfDelegate,
│ # Icons
├── themes/example/ # своя тема для копирования (см. docs/THEMES.md)
├── docs/THEMES.md # формат тем, токены, хуки, свой CSS
├── tests/
│ ├── fake_ytdlp.cpp # заглушка с тем же CLI-контрактом
│ ├── ytdlp_test.cpp # обёртка yt-dlp, без сети
│ ├── media_test.cpp # теги и палитра обложки на синтетических фикстурах
│ ├── theme_test.cpp # theme.json, токены, свой CSS
│ ├── charts_test.cpp # чарты, парсеры, записи yt-dlp (фикстуры)
│ ├── ui_test.cpp # интерфейс в offscreen + скриншоты
│ ├── live_probe.cpp # ручной прогон с настоящей сетью и yt-dlp
│ └── CMakeLists.txt
├── LICENSE # GPL-3.0
└── README.md
Правило слоёв: core/ ничего не знает о виджетах, ui/ никогда не запускает
процессы напрямую. core/ и ui/ собираются в статическую библиотеку
flacore_lib, поэтому тесты линкуют ровно тот же код, что и приложение.
Состоянием владеет Playlist и сообщает о нём сигналами; страницы только
показывают его и передают намерения пользователя.
Честный список — это реальные вещи, а не гипотетические:
- Плейлист живёт в памяти. Нет импорта/экспорта M3U, нет сохранения между запусками.
- Нет shuffle / repeat / очереди.
- Нет медиаклавиш, MPRIS и значка в трее.
- Нет упаковки. Ни AppImage, ни Flatpak, ни MSI, ни
.desktop. - «Стекло» — не настоящий backdrop-фильтр. Qt Widgets не умеет размывать то, что находится за виджетом, поэтому панели полупрозрачные, а размывается сама картинка фона. Выглядит близко, стоит дёшево.
- Теги читаются только для FLAC/MP3/WAV. M4A/AAC/OGG показывают имя файла.
- YouTube может быть недоступен из вашей сети (например, из России без
прокси). Используйте источник SoundCloud или добавьте
--proxyв конфиг самогоyt-dlp. - Чарты берутся из публичных недокументированных источников (Deezer, RSS Apple Marketing Tools). Ключ не нужен — в этом и слабость: форматы могут поменяться без предупреждения, а сами адреса — блокироваться.
- Чарт SoundCloud читается через
yt-dlp. Из ряда регионов (в том числе из России)soundcloud.com/chartsотвечает 404, поэтому эта полка показывает ошибку; полки Deezer и Apple при этом работают. - Подборка не персонализирована. Ни лайков, ни истории прослушиваний, ни рекомендаций — только чарты.
- автопереход и нормальное состояние транспорта (
refreshTransport(),EndOfMedia) -
PlaylistModel : QAbstractListModel+QListView(drag & drop, роли) - чтение тегов и обложек (FLAC/MP3/WAV), акцент из палитры обложки
- система тем: пакеты, токены, свой CSS, аварийный выход — см.
docs/THEMES.md - раздел «Обзор»: живые чарты (Deezer / Apple Music / SoundCloud через yt-dlp)
- персональная подборка: лайки, история, рекомендации
- превью на 30 секунд прямо на странице «Обзор» (сейчас играет в общей панели)
- сохранение/загрузка M3U, shuffle, repeat
- загрузка плейлиста целиком с добавлением треков в библиотеку
- готовые темы, редакторы цветов, JSON-конфиги и фото фона
- кнопка Feedback со ссылкой на GitHub Issues
- очередь скачивания вместо одной задачи
- MPRIS2 + медиаклавиши, значок в трее
- GitHub Actions: сборка на Linux + четыре тестовых бинарника
- упаковка: AppImage / Flatpak / установщик для Windows
«yt-dlp не найден» — бинарника нет в PATH. Укажите полный путь в разделе
«yt-dlp» слева (или «Меню → Настройки yt-dlp…»). На Windows pip install кладёт
его в %LOCALAPPDATA%\Programs\Python\Python3xx\Scripts, а этой папки часто нет
в PATH.
Скачивание идёт, сохранение в FLAC падает — нет ffmpeg. Установите его или
укажите папку в настройках. Текст ошибки yt-dlp показывается под полосой
прогресса, обычно там ffmpeg not found.
«ERROR: Unable to download API page … [WinError 10054]» — сайт заблокирован
или соединение сбрасывает провайдер. YouTube недоступен из ряда регионов;
используйте SoundCloud или пропишите прокси в ~/.config/yt-dlp/config
(--proxy http://host:port).
MP3 играет, а WebM/Opus молчит — бэкенд Qt Multimedia его не декодирует.
На Linux поставьте qt6-multimedia-ffmpeg; на Windows приложение и так
предпочитает m4a (bestaudio[ext=m4a]).
Could not find a package configuration file provided by "Qt6" — передайте
-DCMAKE_PREFIX_PATH=<папка Qt>, например /ucrt64,
C:/Qt/6.8.3/msvc2022_64 или родителя /usr/lib/cmake/Qt6. В MSYS2 значение —
/ucrt64 внутри оболочки MSYS2.
CXX compiler identification is unknown на Windows — Visual Studio без
Windows SDK либо компилятора нет вообще. Используйте путь через MSYS2.
Полки чартов пустые / «Deezer недоступен» — приложение не смогло связаться с
источниками чартов. Проверьте интернет, прокси/VPN, либо запускайте с
FLACORE_OFFLINE=1, если сеть не нужна осознанно. Если полка SoundCloud даёт 404,
а Deezer работает — это блокировка SoundCloud для вашего региона, а не ошибка.
Строка чарта играет не тот трек или не играет — строка превращается в поиск «исполнитель — название» на источнике, выбранном на вкладке YouTube. Если первый найденный трек под DRM, приложение само пробует следующие (до трёх), а затем другой источник. Если не вышло совсем — «Открыть страницу трека» и вставьте ссылку в поле поиска.
Прогресс стоит на 0 % — yt-dlp не сообщил total_bytes_estimate (частое
дело для HLS). Полоса остаётся в режиме «занято», итоговый путь всё равно
приходит — это нормально.
- Перед PR соберите проект и прогоните тесты (
ctest --test-dir build). - Соблюдайте слои (
core/↔ui/) и выносите новую логику вcore/, чтобы её можно было тестировать без GUI. - Строки интерфейса могут быть на русском, но идентификаторы и комментарии держите в стиле того файла, который правите.
В баг-репорте полезны: ОС, версия Qt, yt-dlp --version, точная команда из лога
и что вы ожидали увидеть.
FLACORE — это плеер. Он не содержит контента и ничего не раздаёт. Интеграция с yt-dlp — удобная обёртка над сторонним инструментом: вы сами отвечаете за то, что скачиваете, за соблюдение условий использования сайтов и законодательства об авторском праве своей страны. Не используйте приложение для распространения чужих материалов.
GPL-3.0 — см. LICENSE.
- @Kiruimaru — poopshit dev
- @nex1door — absolute vibe-coder and larper
- Claude — mf that ate my whole balance & tokens