chthollyphile/folia-major

Folia is an online and local music player built around a full-screen, animated lyric stage. It suits listeners who care more about lyric presentation than about a plain library browser, and who are willing to accept that the project is a visual showcase first. It ships as an Electron desktop app for Windows, macOS and Linux, and as a Node.js web version that can be deployed or used as a PWA on mobile.

What it does

After a search by song, artist or album, Folia plays the track and loads cover art and lyrics. Local audio files can also be imported; the README says the index stays local and file contents are not uploaded. Local songs can be automatically matched to online lyrics and covers, with manual correction when a match is wrong. Files in the same directory with matching names in .lrc, .vtt, .ttml, .qrc, .yrc or .krc formats are picked up, as is embedded LRC, and LDDC-style enhanced word-by-word lyrics are supported. Through a separate local Now Playing service, an external player's track, timeline and lyrics can drive Folia's stage view.

Sources include NetEase Cloud Music, Kugou, QQ Music, Navidrome and a local library; the desktop build adds Bilibili's 波点, YouTube Music, Spotify and 汽水音乐. Multiple full-screen lyric themes provide different typography and adjustable parameters, and the layout adapts to window size.

How the visuals are produced

Two mechanisms carry the experience. AI theme generation derives background and visual parameters from a song's mood and lyric content, so themes are song-specific rather than fixed presets. On desktop, the experimental Folium mod system can add lyric animation modes, background types, overlays on the playback page, progress-bar buttons and markers, and commands; mods run as trusted code and must be confirmed in a native window before enabling, and again after files change. The mod marketplace labels signed mods as officially certified, reviewed-but-unsigned mods as preview, and unsigned third-party mods as unverified; unverified mods can still be used. Mods are off by default and desktop-only.

Requirements and limits

• Desktop: an installer from Releases; AUR and a community Flatpak are alternative Linux paths.
• Web: a Node.js 24 or later environment for self-hosting, or one-click Vercel/Cloudflare deployment. Local-music directory access in a self-hosted setup depends on a trusted HTTPS context, and the deployment docs cover the NAS reverse-proxy and certificate requirements.
• QQ Music on Vercel/Cloudflare: requires VITE_QQ_API_BASE=/api/qq plus a server-side QQ_SESSION_SECRET, and login is required before playback; WeChat and phone QQ QR login are supported, with the phone QQ variant needing qq-music-api 3.3.3 or later.
• Mobile: the recommended route is PWA install from a deployed web build; the two Android ports are third-party community projects with feature differences from the official PC version.
• Optional sync: appearance settings and the AI theme library can be synced across devices through a self-hosted sync-server (Cloudflare Workers/D1, Docker, or Node.js with SQLite), configured with a server address and SYNC_TOKEN.

Licensing

The code is AGPL-3.0. The README states that the repository and source are for personal study, technical exchange and non-profit testing, and that the project was developed with extensive AI assistance, so subtle issues may remain. Streaming audio, lyrics and cover art belong to their respective rights holders, and the README places responsibility for any copyright issues arising from redistribution on the user.

Project source and documentation