Community themes for Better Lyrics.
Open the Better Lyrics extension options → Themes tab → Browse Themes to explore and install themes directly.
Want to add your theme to the store? Follow these steps:
Scaffold a new theme instantly with the CLI:
npx create-bl-theme@latest my-themeThis creates a ready-to-use theme with all required files. You can also validate your theme before submitting:
npx create-bl-theme@latest validate ./my-themeYour theme repo must include these files:
your-theme-repo/
├── metadata.json # Theme info (required)
├── style.css # Your CSS (required)
├── DESCRIPTION.md # Rich description (optional - takes precedence over metadata.json)
├── cover.png # Cover image (optional - first image used if missing)
├── shader.json # Shader config (optional)
└── images/ # Screenshots (required - at least one)
├── 1.png
└── 2.png
{
"id": "your-unique-theme-id",
"title": "Your Theme Name",
"description": "A brief description of your theme and what makes it unique.",
"creators": ["your-github-username"],
"minVersion": "2.0.5.6",
"hasShaders": false,
"version": "1.0.0",
"tags": ["dark", "minimal", "colorful"],
"images": ["1.png", "2.png"]
}| Field | Required | Description |
|---|---|---|
| id | Yes | Unique identifier (lowercase, hyphens allowed) |
| title | Yes | Display name |
| description | * | What your theme does (*required unless DESCRIPTION.md exists) |
| creators | Yes | Array of GitHub usernames |
| minVersion | Yes | Minimum Better Lyrics version required |
| hasShaders | Yes | Whether theme includes shader.json |
| version | Yes | Your theme's version (semver) |
| tags | No | Searchable tags |
| images | Yes | Filenames in the images/ folder (first image used as cover if no cover.png) |
For richer descriptions with markdown formatting, create a DESCRIPTION.md file in your repo root:
A beautiful dark theme with smooth animations.
## Features
- Custom gradient backgrounds
- Smooth lyric transitions
- **Rich sync** word-by-word highlighting
## Installation Notes
This theme works best with the album art background enabled.Benefits:
- Full markdown support with headers, lists, images, and more
- GitHub renders the file nicely in your repo
- Easier to maintain longer descriptions
Note: If both DESCRIPTION.md and the description field in metadata.json exist, DESCRIPTION.md takes precedence.
Open a Submit theme issue, enter your repo, and submit. A pull request gets opened and checked for you. Once a maintainer merges it, your theme is live.
Install the GitHub App to automatically publish updates when you push:
Once installed, just bump the version in your metadata.json and push - your theme updates automatically!
You set two version fields in metadata.json. version is your theme's release number. minVersion is the lowest Better Lyrics version your theme needs to work.
The store keeps your older builds, not just the newest one. When you raise minVersion in a release, the previous build stays available for people who are still on an older extension and can't run the new one yet. Anyone new enough gets your latest build.
That makes raising minVersion safe. You can use newer extension features in your latest build without breaking people who haven't updated, because they keep the last build that worked for them instead of being handed one that won't run.
You don't list builds or write any compatibility range. Bump version, set minVersion, push. The store figures out which build each user gets.
For example, if you ship 1.7.6 needing 2.2.0.0, then later ship 2.0.0 needing 2.5.0.0:
- Someone on extension
2.3can't run2.0.0, so they keep getting1.7.6. - Someone on extension
2.6gets2.0.0.
- Test your theme with the latest Better Lyrics version
- Include at least one screenshot in the images/ folder
- Use 16:9 aspect ratio for images (1280x720 recommended)
- Keep your description concise but informative
- Don't include malicious or obfuscated CSS
Add an install count/rating badge to your theme's README:
[](https://github.com/your-username/your-theme-repo)
[](https://github.com/your-username/your-theme-repo)Replace your-theme-id with the id from your metadata.json & your-username/your-theme-repo with your GitHub repo path.
You can customize the badge with shields.io query parameters like &style=for-the-badge or &labelColor=black.
Users can also install themes directly from any GitHub repo URL via Install from URL in the extension, no submission required.
Themes are maintained by their respective creators. Check individual theme repositories for licensing information.