lucent-updates

KO | EN

gitlite — search

#tensorflow #react-native #shell #animation #reactjs #computer-vision #llm #awesome #codex #agent

(★ 9)

Open-source Windows desktop liquid-glass lyrics overlay with automatic media-session detection, synchronized lyrics, and shared listening.

File Explorer

ZIP Download

- - bug_report.yml
  - feature_request.yml
  - player_compatibility.yml
- - ci.yml
  - codeql.yml
- dependabot.yml
- pull_request_template.md
- icon.ico
- icon.png
- installer.nsh
- logo.html
- make-icon.cjs
- - 2026-08-31-playback-localization.md
- ARCHITECTURE.md
- CODEX_FOR_OSS_APPLICATION_NOTES.md
- FINAL_VERIFICATION.md
- GITHUB_SETTINGS_TO_APPLY.md
- GITHUB_SOURCE_SPLIT_PLAN.md
- HANDOFF_NOTES.md
- MAINTAINER_MANUAL_CHECKLIST.md
- MAINTAINER_WORKFLOW.md
- OSS_READINESS_REVIEW.md
- PLAYER_INTEGRATION.md
- credentialStore.cjs
- localPlaylistStore.cjs
- main.cjs
- musicProvider.cjs
- ncmcdp.cjs
- netease.cjs
- preload.cjs
- privacyService.cjs
- room.cjs
- smtc.cjs
- updateService.cjs
- lucent-cat-sprite.png
- catPoses.cjs
- catRender.cjs
- makeCatSprite.cjs
- png.cjs
- releasePreflight.cjs
- stageUpdateFeed.cjs
- activeSessionResolver.cjs
- configStore.cjs
- consoleState.cjs
- defaults.json
- desktopSourceLiveness.cjs
- internalPlayerState.cjs
- liquidWorkbench.cjs
- lyricMirror.cjs
- mediaSession.cjs
- nativeUiLocale.cjs
- playbackCoordinator.cjs
- playbackSource.cjs
- playerErrors.cjs
- playerPolicy.cjs
- progressInput.cjs
- resourceCache.cjs
- roomClock.cjs
- roomPolicy.cjs
- roomReconnect.cjs
- roomStyle.cjs
- smtcClock.cjs
- songLifecycle.cjs
- songSwitch.cjs
- stateMigration.cjs
- styleOffer.cjs
- systemLocale.cjs
- trackIdentity.cjs
- trackMatching.cjs
- updateConfig.cjs
- windowLifecycle.cjs
- windowStateRelay.cjs
- - lucent-avatar.png
  - lucent-cover.svg
- - Capsule.jsx
  - DecorationCanvas.jsx
  - GlassSheen.jsx
  - SongTransitionLayer.jsx
- - decorationRuntime.js
  - decorativeParticles.js
- - console-overrides.json
  - console-ui.json
  - de-DE.json
  - en-US.json
  - es-ES.json
  - fr-FR.json
  - it-IT.json
  - ja-JP.json
  - ko-KR.json
  - pt-BR.json
  - ru-RU.json
  - zh-CN.json
  - zh-TW.json
- App.jsx
- appearanceModel.js
- artworkCache.js
- AudioService.jsx
- audioSpectrum.js
- brandAssets.js
- consoleFeedback.js
- consoleNavigation.js
- consolePlayer.js
- consolePreviewFit.js
- consoleShellModel.js
- ConsoleWindow.jsx
- coverPalette.js
- defaults.js
- frameAssets.js
- homeCat.js
- i18n.js
- idleCapsule.js
- lyrics.js
- main.jsx
- oceanWavePhysics.js
- onboardingState.js
- overlayBridge.js
- pauseBreath.js
- pillMouse.js
- playerErrors.js
- quickPresets.js
- roomClockRuntime.js
- roomInvite.js
- runtimeMessage.js
- songDisplay.js
- songTransition.js
- styles.css
- titleLayout.js
- useCardTilt.js
- usePillMouse.js
- useRoom.js
- useSharedState.js
- activeSessionResolver.test.cjs
- activeSessionWiring.test.cjs
- appearanceModel.test.mjs
- artworkCache.test.mjs
- artworkPriority.test.cjs
- audioServiceWiring.test.mjs
- audioSpectrum.test.mjs
- backendMessageCoverage.test.mjs
- brandAssets.test.mjs
- card3dRoomLayout.test.mjs
- ciRuntime.test.cjs
- clickTargets.test.mjs
- clickThrough.test.mjs
- compactPlayer.test.mjs
- compactPlayerWiring.test.mjs
- configStore.test.cjs
- consoleFeedback.test.mjs
- consoleFeedbackRuntime.test.mjs
- consoleMotionRuntime.test.mjs
- consoleNavigation.test.mjs
- consoleOverlayVisibility.test.cjs
- consolePlayerNullSafety.test.mjs
- consolePreviewFit.test.mjs
- consoleShell.test.mjs
- consoleShellRuntime.test.mjs
- consoleState.test.cjs
- consoleStatusRailLayout.test.mjs
- consoleSurface.test.mjs
- consoleUiI18n.test.mjs
- consoleUiLocales.test.mjs
- coverPalette.test.mjs
- credentialStore.test.cjs
- decorationRuntime.test.mjs
- decorativeParticles.test.mjs
- desktopIdleRuntime.test.cjs
- desktopSourceLiveness.test.cjs
- electronAudioPlaybackSmoke.cjs
- electronInternalLyricsSmoke.cjs
- electronInternalPlayerSmoke.cjs
- electronIpcFuzzSmoke.mjs
- electronLyricLayoutSmoke.cjs
- electronPhase1Smoke.cjs
- electronPlaybackSourceSmoke.cjs
- electronPlaylistSmoke.cjs
- electronRoomReconnectSmoke.cjs
- electronShatterQa.cjs
- externalMetadataSafety.test.mjs
- frameAssets.test.mjs
- homeCat.test.mjs
- i18n.test.mjs
- idleCapsule.test.mjs
- internalPlayerLyrics.test.cjs
- internalPlayerQueue.test.cjs
- internalPlayerRebuild.test.cjs
- internalPlayerState.test.cjs
- liquidWorkbench.test.cjs
- liquidWorkbenchRuntime.test.mjs
- localPlaylistStore.test.cjs
- longLanguageLayout.test.mjs
- lyricLayout.test.mjs
- lyricMirror.test.cjs
- mainModuleResolution.test.cjs
- mediaSession.test.cjs
- mediaSpecConformance.test.cjs
- musicProvider.test.cjs
- nativeUiLocale.test.cjs
- ncmcdpBinding.integration.test.cjs
- neteaseLyrics.test.cjs
- neteasePlayback.test.cjs
- neteasePlaylists.test.cjs
- normalizedPlaybackState.test.cjs
- oceanWave.test.mjs
- oceanWavePhysics.test.mjs
- onboardingState.test.mjs
- pauseBreath.test.mjs
- pillMouse.test.mjs
- playbackCoordinator.test.cjs
- playbackMainWiring.test.cjs
- playbackSource.test.cjs
- playbackSourceWiring.test.cjs
- playbackTransitionIsolation.test.cjs
- playbackUiI18n.test.mjs
- playerErrors.test.cjs
- playerPolicy.test.cjs
- playerUiI18n.test.mjs
- playlistWiring.test.mjs
- privacyService.test.cjs
- privacyWiring.test.mjs
- progressColour.test.mjs
- progressColourConfig.test.cjs
- progressInput.test.cjs
- progressRuntime.test.mjs
- quickPresets.test.mjs
- releasePreflight.test.cjs
- resourceCache.test.cjs
- resourceCacheWiring.test.cjs
- retiredAppearanceSettings.test.mjs
- roomAddress.test.cjs
- roomAddressChoice.test.cjs
- roomClock.test.cjs
- roomClockProtocol.test.cjs
- roomClockRenderer.test.mjs
- roomCommands.test.cjs
- roomHostReady.test.cjs
- roomInvite.test.mjs
- roomLeave.test.mjs
- roomMessageHardening.test.cjs
- roomOffers.test.cjs
- roomPolicy.test.cjs
- roomQueueWiring.test.mjs
- roomReconnect.test.cjs
- roomStyle.test.cjs
- roomSyncWiring.test.mjs
- runtimeMessage.test.mjs
- seekBehaviour.test.mjs
- settingsHints.test.mjs
- smtcClock.test.cjs
- smtcWiring.test.cjs
- songDisplay.test.mjs
- songLifecycle.test.cjs
- songSearchLayout.test.mjs
- songSwitch.test.cjs
- songTransition.test.mjs
- spectrumVisualWiring.test.mjs
- stageUpdateFeed.test.cjs
- stateMigration.test.cjs
- statePersistence.test.cjs
- styleOffer.test.cjs
- systemLocale.test.cjs
- trackIdentity.test.cjs
- trackIdentityWiring.test.cjs
- trackMatching.test.cjs
- trackMatchingWiring.test.cjs
- updateConfig.test.cjs
- updateErrorRedaction.test.cjs
- updateService.test.cjs
- updateWiring.test.mjs
- windowLifecycle.test.cjs
- windowStateRelay.test.cjs
- workbenchPreview.test.mjs
.gitignore
CHANGELOG.md
CODE_OF_CONDUCT.md
CONTRIBUTING.md
electron-builder.config.cjs
electron-builder.config.factory.cjs
index.html
LICENSE
package-lock.json
package.json
README.md
ROADMAP.md
SECURITY.md
SUPPORT.md
vite.config.js

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

# Project Badges

CI Visit
CodeQL Visit

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

**An open-source Windows desktop lyrics overlay and media-session integration project.**
Lucent detects which media session is actually playing on your PC, normalizes its metadata and
artwork, resolves synchronized lyrics, and renders them in a customizable liquid-glass overlay
that floats above your desktop.

Lucent is both an end-user desktop app and a working example of cross-player media-state
integration on Windows.

---

## What it does

### Lyrics overlay
- A single **liquid-glass capsule** that floats above the desktop, always on top, click-through optional.
- **Real-time synchronized lyrics** that follow the actual playback position.
- **Karaoke word-by-word highlighting** when the provider supplies word-timed lyrics (NetEase YRC).
- **Bilingual lyrics** — original plus translation on a second line.
- Extensive appearance control: glass material, background, blur, tint, corner radius, typography,
  progress-bar animations, decorative particle effects, and a spinning vinyl with artist artwork.
- **Quick presets** and **saved appearance profiles** that capture a complete visual configuration.

### Automatic playback detection
Lucent does not target a single hard-coded player. It scans **all Windows media sessions**
(SMTC/GSMTC), normalizes them into one shape, and arbitrates which one is genuinely active:

| Source ID | Player |
| --- | --- |
| `internal-player` | Lucent's built-in player |
| `desktop-netease` | NetEase Cloud Music desktop |
| `desktop-spotify` | Spotify desktop |
| `desktop-youtube-music` | YouTube Music (PWA or Chromium browser) |
| `desktop-generic` | Any other player exposing enough media-session metadata |

Source IDs are stable internal identifiers and never change with UI language.

When another player becomes the real active source, Lucent switches to it automatically without
losing lyric sync or reloading artwork unnecessarily.

### Room sync (LAN)
Everyone on the same local network can watch the same subtitle line. The host plays the music;
members follow. Only the lyric timeline and playback state are synchronized — **no audio is
streamed**, so bandwidth stays minimal.

### Other
- Song search, now-playing view and playback controls for the built-in player.
- Album artwork and artist images, with caching so routine position updates never cause flicker.
- Settings persist automatically and survive restarts.
- Auto update through GitHub Releases.

---

## Requirements

- **Windows 10 or 11.** Lucent relies on the Windows `GlobalSystemMediaTransportControls` API, so
  it is Windows-only by design.
- Node.js 22.12+ and npm, if you are building from source.

---

## Install

Download the latest installer from the [Releases](../../releases) page and run it.

To build from source, see [Development](#development).

---

## Basic usage

1. Start Lucent. The control console opens; the desktop capsule appears when you close or collapse it.
2. Start playing music in any supported player.
3. Lucent detects the active session and shows synchronized lyrics in the capsule.

| Action | How |
| --- | --- |
| Move the capsule | Drag it with the left mouse button |
| Open the console | Right-click the capsule, or `Ctrl+Alt+S` |
| Toggle click-through | `Ctrl+Alt+L`, or the console toggle |
| Play / pause | Click the capsule, or `Ctrl+Alt+Space` |

The console has six pages: **Home, Play, Appearance, Room, Settings, Help**.

### Precise NetEase sync

For NetEase Cloud Music, Lucent can mirror the exact line the desktop app is highlighting, which is
more accurate than reconstructing a timeline. This requires the NetEase desktop app to be running
with its lyrics page open. Without it, Lucent falls back to normal timeline synchronization.

---

## Development

```bash
npm ci
npm test
npm run build
npm run dev
```

- `npm run dev` starts the Vite dev server and the Electron windows together.
- `npm test` runs the full suite with the Node.js built-in test runner. There is no external test
  framework and no network access required.
- `npm run build` produces the renderer bundle in `dist/`.

Packaging is gated behind a release preflight check:

```bash
npm run release:check
npm run dist
```

`npm run dist` deliberately refuses to produce a build that could be mistaken for an official
release unless the required release signals are configured. Those signals are packaging safeguards;
they do not replace written licensing agreements with any music service.

See [CONTRIBUTING.md](CONTRIBUTING.md) for the full contributor workflow, including how to add a
player adapter.

Architecture is documented in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md), and player integration in
[docs/PLAYER_INTEGRATION.md](docs/PLAYER_INTEGRATION.md).

---

## Privacy

Lucent runs locally. It does not collect listening history, personal song history, IP addresses, or
device identifiers, and it has no analytics backend.

- Music metadata is read from Windows media sessions on your own machine.
- Lyrics and artwork are fetched from the relevant music provider only for the track being played.
- Room sync sends the lyric timeline and playback state to peers **you** connect to on your local
  network, and nothing else.
- NetEase credentials, when you choose to sign in, are stored encrypted through the OS credential
  facilities and never leave the machine.

---

## Known limitations

These are real constraints, not future work:

- **Windows only.** The media-session APIs Lucent depends on do not exist on macOS or Linux.
- **Precise NetEase mirroring depends on the NetEase desktop UI.** If that app changes its markup,
  mirroring can break and Lucent falls back to timeline sync.
- **`backdrop-filter` cannot sample desktop pixels.** A transparent overlay window has nothing
  behind it to refract, so the glass displacement effect is subtle unless the capsule has a
  background of its own (album art, tint, or frost).
- **Not every track has lyrics**, and metadata from generic players is often too sparse to match a
  song confidently. Lucent shows media information without forcing an incorrect lyric match.
- **Translation quality still needs native-speaker review.** Lucent ships eleven languages and
  switches instantly. All visible console UI, including appearance, help, onboarding, playback,
  rooms, and the promotional preview, goes through the translation system. Actual song titles,
  artist names, and other provider metadata remain in the language returned by the provider.
  The shipped translations were not written by native speakers, so corrections are welcome.

---

## Contributing

Contributions are welcome — bug reports, player compatibility reports, and pull requests.
Start with [CONTRIBUTING.md](CONTRIBUTING.md) and [SUPPORT.md](SUPPORT.md).

Security issues should follow [SECURITY.md](SECURITY.md) rather than a public issue.

## License

[MIT](LICENSE).

lucent-updates

File Explorer

# Use via CDN

# Project Badges

Was this content helpful?

Recent Feedback

Download README