Folia serves animated lyrics from five kinds of music library
Folia connects 5 library paths: local files, Navidrome, NetEase Cloud Music, KuGou, and QQ Music. Its stage views animate synchronized words, covers, colors, and full-screen compositions. Local sidecar lyrics may be LRC, VTT, TTML, QRC, YRC, or KRC, and Folia can fall back across online sources when matching a track. Gemini and OpenAI-compatible services can generate themes from a song's mood and words.
That range lives in a sizable TypeScript application. commit e51454c contained 1,759 files, roughly 300,560 source lines, and a 31.8 MB checkout. It includes an Electron desktop build, a Vite web app, a sync server, music-provider adapters, and Docker Compose deployment material. The main documentation is Chinese. The measured tree has no English README, although package resources include an English interface locale. English-only teams should account for translation during setup and support.
What happened when we ran it
Our measurement setup installed Folia in 52 seconds. Npm added 1,061 packages and occupied 1,099 MB on disk. The checkout used 3 CPUs and 8 GB of RAM inside an unprivileged Node 22 container with no secrets. Installation completed successfully, and the build finished successfully in 13 seconds. The repository scan found 9 CI workflow files and a tests directory, but no top-level Dockerfile.
Vitest completed in 59 seconds: 3,272 tests passed, 0 failed, and 1 was skipped out of 3,273. Npm audit reported 5 known vulnerabilities, split into 1 high, 3 moderate, and 1 low, with none critical. Those results describe commit e51454c in our fresh Debian sandbox. They do not measure playback quality, browser compatibility, media-provider reliability, or rendering speed.
A web deployment needs provider services and trusted HTTPS
The source instructions require Node.js 24 or newer, despite our supplied sandbox image being Node 22 for the measured run. Local development starts with npm and an environment file, but a useful web player also needs a NetEase Cloud Music API address. KuGou requires its own web API. QQ can use the included serverless endpoint on Vercel or Cloudflare with a session secret, or a standing Node service for the fuller login path. AI themes add Gemini or OpenAI-compatible credentials.
A self-hosted stack is therefore larger than the 1,099 MB dependency directory suggests. The Compose setup has a gateway, backend, music APIs, and an optional sync server. Sync uses SQLite and a bearer token. AI keys stay in the backend container according to the deployment guide. If you only want local playback, the desktop package avoids much of this wiring. If you want browser access for several people, plan provider availability, secret rotation, persistent volumes, and updates as separate jobs.
Local folders work in the desktop app or a compatible secure browser
Folia's web folder import has 2 hard requirements: a secure browser context and File System Access API support. Its Docker guide says plain HTTP on a LAN disables folder import, dependable PWA installation, OPFS cover storage, device selection, and standard clipboard access. Trusted HTTPS fixes the secure-context requirement, but it cannot make Firefox or Safari implement a missing directory API. Desktop Chromium or the Electron app is the safer choice for a large local collection.
The 31.8 MB checkout supports packaged Windows, macOS, and Linux targets, but packaging still has sharp edges. The v0.7.7 release says macOS builds lack Apple signing and notarization, so Gatekeeper may label the app damaged and require a manual override. An open Windows report for versions 0.7.4 and 0.7.7 shows Electron's GPU process repeatedly crashing at startup; the thread had suggested checks, but the reporter said a driver update did not resolve it. That is one report, not a measured failure rate.
The README's commercial restriction conflicts with the AGPL label
GitHub and package metadata identify Folia as AGPL-3.0. The README adds narrower language: it calls the source suitable for personal study, technical exchange, and non-profit testing, and tells readers not to use it commercially. Those statements are hard to reconcile from the repository alone. A business should get clarification before distributing the app, offering a hosted copy, or building a paid product around it. The music and lyric providers also bring their own copyright and account terms.
Activity is current rather than inferred from a tag. GitHub showed a push on September 11, 2026, 2,324 stars, and 14 combined open issues and pull requests. Stable release v0.7.7 arrived on September 9. The repository has 9 CI workflow files, and our run passed all 3,272 executed tests. Recent threads include maintainer replies about startup trouble and onboarding, while Spotify support and its Windows-focused pull request remain open. That mix points to active work and visible unfinished edges.
Choose Folia for lyric presentation, not general media management
Folia connects 5 library paths, while Feishin and Navidrome focus on conventional self-hosted library playback. Feishin is the closer comparison when you already run Navidrome or Jellyfin and want a conventional music client. Navidrome itself is the better starting point when the missing piece is a server that organizes and streams a personal library to several clients. Jellyfin fits households that want one server for music, films, and television. Folia makes synchronized lyrics the main screen.
Our 52-second install, 13-second build, and 3,272 passing tests make Folia easy to justify as a technical trial. The 1,061-package dependency tree, 5 audit findings, provider setup, Chinese-first documentation, and unsigned macOS release make production adoption a more deliberate choice. For a personal lyric display or Navidrome companion, those costs may be acceptable. A commercial operator should stop at the conflicting usage language, and a Spotify-first listener should wait until support is merged and documented.