Folia: a full-screen lyrics player for Netease, KuGou, Navidrome and local files

What Folia is trying to fix about lyrics playback

Most players treat lyrics as a scrolling text panel bolted onto the side of the album art. Folia inverts that. The README describes it as an online music player centred on full-screen immersive lyrics playback, and the repository's theme previews (Fume, Lumi, Cad, Pat, Cappella, Tilt, Diorama, Pendolo) are all full-window text layouts rather than list views. The stated goal is lyrics that look like a text PV, the typographic music videos common in Japanese and Chinese pop, while still reflowing to different window sizes.

The audience is narrow but real. It is for people who already have a source of music: a Navidrome instance, a folder of local audio files, or an account on Netease Cloud Music, KuGou or QQ Music. Folia does not try to be your library manager. It reads metadata, sidecar lyrics files and cover art, and it will fill in gaps from Netease, QQ Music or KuGou, falling back in that order according to the README. If your problem is "I have the songs, I want the lyrics to be the point," Folia is aimed at you. If your problem is "I need to organise 40,000 files," it is not.

How the lyrics pipeline and the stage view fit together

The interesting mechanism is the lyric source chain. For local tracks, Folia reads audio metadata and looks for a sidecar file with the same name in the same directory, and the README lists the formats it recognises: .lrc, .vtt, .ttml, .qrc, .yrc and .krc, plus LRC embedded inside the audio file. It also states support for the enhanced word-by-word format produced by LDDC, which matters because per-syllable timing is what makes the animated themes possible at all. A plain LRC with line-level timestamps gives you a much duller animation.

When no local lyrics exist, matching falls back through Netease, then QQ Music, then KuGou. The README is explicit that matches can be wrong and that you can pick a different candidate manually, restore the original local metadata from first import, or merge and split artist and album entities. That last part is the tell: Folia has an entity model for artists and albums, and automatic matching can corrupt it, so the escape hatches exist.

There is a second input path worth knowing about. Folia can connect to a local Now Playing service and use an external player's track, timeline and lyrics to drive its stage view and full-screen rendering. In that mode Folia is a renderer, not a player. The repository also contains a stage-client.html entry and a stage:client script, which suggests the stage view is separable from the main app shell.

Installing Folia and importing a first local track

There are two supported shapes. Desktop users download an installer from the Releases page, or use the AUR package folia-major-bin on Arch, or a community Flatpak listed on Flatpark. The README notes that the desktop build bundles its runtime, so it is the closest thing to install-and-go. Web users deploy to Vercel or Cloudflare from the buttons in the README, or self-host with the Docker Compose stack under deploy/docker.

If you want to run the source tree, the package manifest requires Node 24 or newer and the dev server is Vite. The postinstall step runs patch-package, so do not skip it.

npm install
npm run dev

Before that, copy the environment example and point it at whatever you have. The example file ships with Netease pointed at a local API on port 3000, and leaves the KuGou and QQ base URLs empty because Electron starts an embedded QQ Music API itself.

cp .env.example .env
# VITE_NETEASE_API_BASE=http://localhost:3000
# VITE_AI_PROVIDER=google
# GEMINI_API_KEY=your_gemini_api_key_here

For a first real use, open the app, import a local folder, and let the matcher run. The README says local index information is stored locally and file contents are not uploaded, which is the behaviour to verify on your own deployment: watch the network panel while a folder scans, and confirm that only metadata queries leave the machine. If a track matches the wrong song, the documented recovery is to select a different candidate or restore the first-import metadata rather than re-importing the file.

The QQ Music login requirement and other deployment constraints

The README documents a real constraint that is easy to miss. On Vercel and Cloudflare, QQ Music no longer needs a separate always-on API instance: you set VITE_QQ_API_BASE to /api/qq and configure QQ_SESSION_SECRET as a server-side secret, deliberately without the VITE_ prefix. In that serverless form, the README states the deployment only supports WeChat QR login and that you must sign in before playback. Cloudflare can add a Durable Object to enable QQ QR login as well. Those are not equivalent deployments, and picking one silently removes a login method.

The second constraint is the secure context. The README ties local music directory access to trusted HTTPS, and the deployment docs cover NAS reverse proxies and certificate requirements. A plain HTTP self-host on a LAN address may load the interface and still fail to read your music folder. That is a browser platform rule, not a Folia bug, but it shapes where you can host the web build.

AI theme generation is a third dependency. It is optional, but the feature that generates backgrounds and visual parameters from a song's mood and lyrics needs a provider key: Gemini by default, or an OpenAI-compatible endpoint with OPENAI_API_KEY, OPENAI_API_URL and OPENAI_API_MODEL. The example file notes that the app defaults to deepseek-v4-flash for api.deepseek.com if you leave the model blank. Without a key, the animated themes still work; the generated colour themes do not.

Where Folia is the wrong tool

Folia is a browser-technology application at heart. The web build is a PWA, and the README's mobile advice is to deploy the web version and add it to the home screen from Chrome for Android or iOS Safari. Packing the web build into an Android APK with Capacitor is described as something for users with some technical background, with a separate example repository. There is no first-party mobile app.

The heavier limitation is dependence on external services for the online half of the product. Netease, KuGou and QQ Music are third-party APIs, and the repository even carries a QQ diagnostics page and a manual probe script for Netease, which tells you the maintainers expect these endpoints to break and need investigating. If you want a player that works identically with the network unplugged, Folia's local mode does that, but you lose matching, covers and AI themes. And if you want a headless server that streams to many clients, Folia is the wrong shape: it renders lyrics on the client, and the optional sync-server only synchronises appearance settings and the AI theme library, not your music.

How Folia differs from Navidrome plus a Subsonic client

The natural comparison is a Navidrome server paired with a Subsonic-compatible client such as one of the many mobile or desktop players in that ecosystem. The approaches differ at the layer where the work happens. Navidrome owns the library, does the scanning, transcoding and streaming, and exposes a stable API; the client is a thin view over it. Folia inverts that: it is the client, it can read a Navidrome library as one of its sources, and the substantial engineering sits in lyric acquisition, timing and rendering.

That difference decides your choice. If you want one canonical library that every device reads from, Navidrome plus a Subsonic client is the architecture that gives it to you, and Folia is a front end you can point at the same server when you want the animated lyrics. If you want the lyrics to be the product, Folia is doing work the Subsonic clients generally do not: sidecar format coverage including .qrc, .yrc and .krc, word-by-word timing, manual match correction, and an external Now Playing input so another player can drive the visuals. Note that Folia's sync-server is not a substitute for Navidrome. It stores appearance settings and AI themes, not audio.

Maintenance, licensing and what an upgrade costs you

The repository is not archived, and the last push was on 2026-09-15, so the codebase is moving. The release list shows three channels in the same week: a stable v0.7.7 tagged Realeco, a Limo nightly build, and a Cielo canary from a work-in-progress branch. That structure is worth reading before you pin a version. If you deploy the stable tag you get fewer surprises; if you track a nightly or canary you are opting into branch builds whose names literally include WIP.

Upgrade cost is dominated by the API base URLs, not the application code. The environment example defines VITE_NETEASE_API_BASE, VITE_KUGOU_API_BASE and VITE_QQ_API_BASE, and the README's QQ section shows that the correct value for those variables depends on your host. A version bump that changes how QQ authentication is wired will show up as a broken login rather than a build error, so keep your .env under version control separately from the source tree.

Folia is licensed AGPL-3.0, and the package manifest marks the package private. The AGPL's network clause is the part that matters for a self-hosted web deployment: if you modify the code and let other people use it over a network, the licence's source-availability terms apply. That is a description of the licence, not legal advice, and if you plan to run a modified Folia for other users you should read the licence text or ask someone qualified.

Editorial conclusion

Folia suits people who already have a music source (a Navidrome server, a folder of local files, or a Netease or KuGou account) and who care more about how lyrics look on a large screen than about library management. Skip it if you need an offline player with no API dependencies, since the online sources and AI themes both call out to services you have to configure yourself. Before adopting it, check three things: whether your deployment target is Vercel, Cloudflare or Docker, since the QQ Music login flow differs between them; whether you can serve the app over trusted HTTPS, because the documentation ties local music directory access to a secure context; and whether AGPL-3.0 fits how you intend to distribute any modified build.

Frequently asked questions

Official sources

1. chthollyphile/folia-major on GitHub
2. License: AGPL-3.0
3. Project website
4. README
5. Releases