# nmwplays/liquid-lyrics architecture

> Architecture diagram of the GitHub repository nmwplays/liquid-lyrics, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nmwplays/liquid-lyrics
- Repository: https://github.com/nmwplays/liquid-lyrics

## Overview

Liquid Lyrics is a Spicetify extension that adds synchronized lyrics and related listening interfaces to Spotify. Its main user workflow is opening the lyrics view, following timed or classic lyrics, and tailoring the presentation; users can also edit and save lyrics locally. The README documents settings, romanization, backgrounds, fullscreen and cinema modes, a media player, a sidebar card, and theme adaptation. The only source file is liquid-lyrics.js, so feature nodes share that path; with no source excerpts, edges reflect documented behavior only.

Main entry points: [`liquid-lyrics.js`](https://github.com/nmwplays/liquid-lyrics/blob/main/liquid-lyrics.js) (Settings menu)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_lyrics["Lyrics experience"]
  node_lyrics_view["Lyrics view<br/>[liquid-lyrics.js]"]
  node_lyric_display["Synced display<br/>[liquid-lyrics.js]"]
  node_romanization["Romanization<br/>[liquid-lyrics.js]"]
  node_sync_editor["Sync editor<br/>[liquid-lyrics.js]"]
  node_local_edits[("Local edits<br/>[liquid-lyrics.js]")]
end

subgraph group_presentation["Presentation modes"]
  node_fullscreen["Fullscreen mode<br/>[liquid-lyrics.js]"]
  node_cinema["Cinema mode<br/>[liquid-lyrics.js]"]
  node_backgrounds["Background effects<br/>[liquid-lyrics.js]"]
  node_media_player["Media player<br/>[liquid-lyrics.js]"]
  node_sidebar_card["Sidebar card<br/>[liquid-lyrics.js]"]
end

subgraph group_customization["Customization"]
  node_settings["Settings menu<br/>[liquid-lyrics.js]"]
  node_theme_adaptation["Theme adaptation<br/>[liquid-lyrics.js]"]
end

node_listener(("Listener"))
node_spotify(("Spotify"))

node_listener -->|"opens"| node_lyrics_view
node_lyrics_view -->|"shows lyrics"| node_lyric_display
node_listener -->|"opens"| node_settings
node_settings -->|"configures"| node_backgrounds
node_settings -->|"configures"| node_media_player
node_settings -->|"configures"| node_sidebar_card
node_settings -->|"configures"| node_fullscreen
node_listener -->|"toggles"| node_romanization
node_listener -->|"edits lyrics"| node_sync_editor
node_sync_editor -->|"saves locally"| node_local_edits
node_listener -->|"enters"| node_fullscreen
node_listener -->|"enters"| node_cinema
node_spotify -->|"hosts"| node_lyrics_view
node_spotify -->|"hosts"| node_sidebar_card
node_spotify -->|"provides theme"| node_theme_adaptation

click node_lyrics_view "https://github.com/nmwplays/liquid-lyrics/blob/main/liquid-lyrics.js"
click node_lyric_display "https://github.com/nmwplays/liquid-lyrics/blob/main/liquid-lyrics.js"
click node_romanization "https://github.com/nmwplays/liquid-lyrics/blob/main/liquid-lyrics.js"
click node_sync_editor "https://github.com/nmwplays/liquid-lyrics/blob/main/liquid-lyrics.js"
click node_local_edits "https://github.com/nmwplays/liquid-lyrics/blob/main/liquid-lyrics.js"
click node_fullscreen "https://github.com/nmwplays/liquid-lyrics/blob/main/liquid-lyrics.js"
click node_cinema "https://github.com/nmwplays/liquid-lyrics/blob/main/liquid-lyrics.js"
click node_backgrounds "https://github.com/nmwplays/liquid-lyrics/blob/main/liquid-lyrics.js"
click node_media_player "https://github.com/nmwplays/liquid-lyrics/blob/main/liquid-lyrics.js"
click node_sidebar_card "https://github.com/nmwplays/liquid-lyrics/blob/main/liquid-lyrics.js"
click node_settings "https://github.com/nmwplays/liquid-lyrics/blob/main/liquid-lyrics.js"
click node_theme_adaptation "https://github.com/nmwplays/liquid-lyrics/blob/main/liquid-lyrics.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_lyrics_view,node_lyric_display,node_romanization,node_sync_editor,node_local_edits toneBlue
class node_fullscreen,node_cinema,node_backgrounds,node_media_player,node_sidebar_card toneAmber
class node_settings,node_theme_adaptation toneMint
class node_listener,node_spotify toneIndigo
```

## Components

### Lyrics experience

- [Lyrics view](https://github.com/nmwplays/liquid-lyrics/blob/main/liquid-lyrics.js): `liquid-lyrics.js`
- [Synced display](https://github.com/nmwplays/liquid-lyrics/blob/main/liquid-lyrics.js): `liquid-lyrics.js`
- [Romanization](https://github.com/nmwplays/liquid-lyrics/blob/main/liquid-lyrics.js): `liquid-lyrics.js`
- [Sync editor](https://github.com/nmwplays/liquid-lyrics/blob/main/liquid-lyrics.js): `liquid-lyrics.js`
- [Local edits](https://github.com/nmwplays/liquid-lyrics/blob/main/liquid-lyrics.js): `liquid-lyrics.js`

### Presentation modes

- [Fullscreen mode](https://github.com/nmwplays/liquid-lyrics/blob/main/liquid-lyrics.js): `liquid-lyrics.js`
- [Cinema mode](https://github.com/nmwplays/liquid-lyrics/blob/main/liquid-lyrics.js): `liquid-lyrics.js`
- [Background effects](https://github.com/nmwplays/liquid-lyrics/blob/main/liquid-lyrics.js): `liquid-lyrics.js`
- [Media player](https://github.com/nmwplays/liquid-lyrics/blob/main/liquid-lyrics.js): `liquid-lyrics.js`
- [Sidebar card](https://github.com/nmwplays/liquid-lyrics/blob/main/liquid-lyrics.js): `liquid-lyrics.js`

### Customization

- [Settings menu](https://github.com/nmwplays/liquid-lyrics/blob/main/liquid-lyrics.js): `liquid-lyrics.js`
- [Theme adaptation](https://github.com/nmwplays/liquid-lyrics/blob/main/liquid-lyrics.js): `liquid-lyrics.js`

### Other components

- **Listener**
- **Spotify**

## Connections

- Listener → Lyrics view: opens (evidence: `README.md`)
- Lyrics view → Synced display: shows lyrics (evidence: `README.md`)
- Listener → Settings menu: opens (evidence: `README.md`)
- Settings menu → Background effects: configures (evidence: `README.md`)
- Settings menu → Media player: configures (evidence: `README.md`)
- Settings menu → Sidebar card: configures (evidence: `README.md`)
- Settings menu → Fullscreen mode: configures (evidence: `README.md`)
- Listener → Romanization: toggles (evidence: `README.md`)
- Listener → Sync editor: edits lyrics (evidence: `README.md`)
- Sync editor → Local edits: saves locally (evidence: `README.md`)
- Listener → Fullscreen mode: enters (evidence: `README.md`)
- Listener → Cinema mode: enters (evidence: `README.md`)
- Spotify → Lyrics view: hosts (evidence: `README.md`)
- Spotify → Sidebar card: hosts (evidence: `README.md`)
- Spotify → Theme adaptation: provides theme (evidence: `README.md`)
