Beautiful Lyrics

Play your vault's audio files with Apple Music–style, syllable-synced lyrics in Obsidian. Beautiful Lyrics highlights lyrics word by word, renders background/duet lines, and presents it all as dark, readable text over the right sidebar's own transparent background.

The lyric renderer is a faithful integration of Apple Music Like Lyrics (AMLL). See Acknowledgements and License.

---

Features

• Syllable-synced ("word by word") lyric playback that follows the audio.
• Background and duet line support, mirroring the Apple Music presentation.
• Lyrics render as dark, readable text over the sidebar's own transparent background — lightweight, with no album-art or animated background.
• Right-sidebar player with play/pause and a seek scrubber.
• Energy-conscious rendering: the view idles when playback is paused or the sidebar is hidden.
• Correct rendering of complex scripts (for example Devanagari and other Indic scripts), not just Latin and CJK.
• Optional one-step fetching of synced lyrics from Apple Music.

This is a desktop-only plugin.

---

Installation

Manual install

1. Download main.js, manifest.json, and styles.css from a release.
2. Copy them into your vault at: <vault>/.obsidian/plugins/beautiful-lyrics/
3. In Obsidian, open Settings → Community plugins, refresh the list, and enable Beautiful Lyrics.

From source

npm install
npm run build

This produces main.js. Copy main.js, manifest.json, and styles.css into <vault>/.obsidian/plugins/beautiful-lyrics/ and enable the plugin as above. See CONTRIBUTING.md for the full development workflow.

---

Quick start

1. Place an audio file (for example song.mp3) somewhere in your vault.
2. Obtain synced lyrics as a JSON file. The easiest way is the Fetch lyrics command (requires an Apple Music token).
3. Create or open a note whose frontmatter points at both the audio file and the lyrics file (see Frontmatter contract).
4. Run Play current song to open the sidebar player.

---

Commands

Fetch lyrics

Opens a modal with Song, Artist, and an optional Album field. It searches Apple Music and saves the syllable-synced lyrics as a JSON file into your vault's attachment folder. It does not modify any note; the saved file name is reported so you can link it in a note's frontmatter (see Frontmatter contract).

This command requires an Apple Music token. See Getting an Apple Music token.

Play current song

Enabled only when the active note's frontmatter links both an audio file and a lyrics file. It opens the sidebar player and begins playback with synced lyrics. It is also available as a ribbon icon that appears only when the active note is playable.

---

Frontmatter contract

Beautiful Lyrics resolves what to play from the active note's frontmatter. It accepts both the YAML list form and the scalar form.

List form

---
lyrics:
  - "[[song.json]]"
attachments:
  - "[[song.mp3]]"
---

Scalar form

---
lyrics: "[[song.json]]"
attachments: "[[song.mp3]]"
---

Keys

Key	Required	Meaning
lyrics	Yes	The synced-lyrics JSON file.
attachments	Yes	The audio file. The first audio-typed link is used.

The property names are configurable under Settings → Frontmatter properties.

Play current song is enabled only when both lyrics and attachments resolve to real files.

---

Settings

Setting	Default	Notes
Subscriber token	empty	Optional Apple Music media-user-token. Only needed for Fetch lyrics. Stored securely (see below).
Storefront	empty	Optional two-letter code such as us, gb, or in. Auto-detected from your account when left empty.

Under Frontmatter properties, you can change which frontmatter keys the plugin reads:

Setting	Default	Reads
Lyrics property	lyrics	The synced-lyrics file.
Audio property	attachments	The audio file to play.

Fetched lyrics are written to Obsidian's own configured attachment folder (Settings → Files and links). There is no separate location setting.

The Apple Music token is stored in Obsidian's secret storage, not in plaintext.

---

Getting an Apple Music token

This is optional. A token is required only to fetch lyrics from Apple Music. Playing lyrics you have already saved needs no token at all — the Play current song command works entirely offline against files in your vault.

To use Fetch lyrics, supply your Apple Music media-user-token:

1. You need an active Apple Music subscription.
2. In a desktop browser, sign in at https://music.apple.com.
3. Open the browser developer tools (for example Cmd/Ctrl+Shift+I) and go to the Application (or Storage) tab → Cookies → https://music.apple.com.
4. Find the cookie named media-user-token and copy its value.
5. Paste it into Beautiful Lyrics settings → "Subscriber token".
6. The token is tied to your account and subscription and can expire. If fetching returns a 401 or 403 error, copy a fresh token and paste it again. The developer (Bearer) token is fetched automatically — you do not need to supply it.

Privacy

The token is stored in Obsidian's secret storage, which is local to your vault. The plugin only contacts Apple Music's API when you explicitly run Fetch lyrics. No requests are made during normal playback.

---

Troubleshooting

• "Play current song" is greyed out. The active note's frontmatter must resolve to both an audio file (attachments) and a lyrics file (lyrics).
• Fetch returns 401/403. Your media-user-token is missing or expired. Re-copy a fresh value (see above).
• Lyrics look invisible / wrong color. The lyrics use your theme's text colors; make sure you have not overridden them to match the background.

---

Acknowledgements

• Apple Music Like Lyrics (AMLL) (amll.dev) — the core lyric renderer, by the amll-dev project. Licensed under AGPL-3.0-only. See License.

Apple Music is a trademark of Apple Inc. This plugin is not affiliated with, sponsored by, or endorsed by Apple Inc.

---

License

The Beautiful Lyrics plugin source is released under the MIT License (see LICENSE).

Important — AGPL-3.0 applies to the distributed build. The AMLL core (@applemusic-like-lyrics/core) is licensed AGPL-3.0-only and is bundled into the distributed main.js. Because of that bundling, the distributed plugin build as a whole is subject to the terms of the AGPL-3.0. The plugin is open source and the corresponding source is available in this repository, so the source-availability obligations of the AGPL-3.0 are satisfied.