Genius Lyrics Downloader for Obsidian

A Python tool with a dark-themed GUI that bulk-downloads song lyrics from Genius.com and saves them as organized markdown files with rich metadata for use in Obsidian vaults.

Features

• Album-based organization - Groups songs by album into single markdown files
• Singles handling - Songs without an album are collected into a dedicated Singles.md file with automatic de-duplication
• YAML frontmatter - Includes metadata (artist, album, release date, year, album art)
• Enhanced credits - Producer, songwriter, and featured artist information per song
• Pageview stats - Genius popularity counts included per song
• Incremental updates - Skips already-downloaded albums so re-runs only fetch new content
• Cancellable downloads - Cancel button stops the process cleanly between songs
• Live progress - Shows [1/47] per-song progress during downloads
• Lyrics cleanup - Strips trailing Genius artifacts (Embed, You might also like)
• Smart filtering - Excludes remixes, live versions, edits, and other variations (configurable)
• Section headers - Preserves song structure markers like [Chorus], [Verse], etc. (toggleable)
• Windows-safe filenames - Sanitizes special characters for cross-platform compatibility
• Bulk download - Process multiple artists in a single run

Installation

Prerequisites

• Python 3.7+
• A Genius API token (free)

Setup

1. Clone the repo and install dependencies:

   pip install -r requirements.txt

2. Get your Genius API token:

   • Go to https://genius.com/api-clients
   • Sign up or log in
   • Create a new API client
   • Copy your "Client Access Token"

3. Configure your .env file:

   Copy .env.example to .env and fill in your token:

   GENIUS_TOKEN=your_token_here
   OUTPUT_DIR=C:\path\to\your\obsidian\vault
   

Usage

Launch the GUI:

python genius_lyrics_downloader.py

Or directly:

python gui.py

The interface lets you:

1. Set or browse for an output directory (defaults to OUTPUT_DIR from .env)
2. Enter one or more artist names (one per line)
3. Set a song limit (0 = full discography)
4. Expand Settings to adjust excluded terms, toggle section headers, or change API delay
5. Click Download to start, or Cancel to abort mid-run

Output Structure

[Artist Name]/
├── 2006 - Waiter "You Vultures!".md
├── 2007 - Church Mouth.md
├── 2008 - Censored Colors.md
├── 2017 - Woodstock.md
└── Singles.md

Example File Format

Filename: 2017 - Woodstock.md

---
artist: Portugal. The Man
album: Woodstock
release_date: 2017-03-02
year: 2017
album_art: https://images.genius.com/...
---

# Feel It Still

**Featuring:** John Gourley | **Produced by:** John Hill | **Written by:** John Gourley, Zach Carothers | **Views:** 5,432,100

[Verse 1]
Can't keep my hands to myself
Think I'll dust 'em off, put 'em back up on the shelf
...

---

Singles file: Singles.md

---
artist: Portugal. The Man
album: Singles
type: singles
---

# Some Unreleased Track

**Written by:** John Gourley | **Views:** 12,300

[Verse 1]
...

---

Configuration

All settings are managed via the .env file and the GUI Settings panel.

.env file

Variable	Description	Default
GENIUS_TOKEN	Your Genius API access token (required)	-
OUTPUT_DIR	Default output directory	Current directory
EXCLUDED_TERMS	Comma-separated terms to filter out	Remix,Live,Edit,Acoustic,...
REMOVE_SECTION_HEADERS	Strip [Chorus]/[Verse] markers	false
SLEEP_TIME	Seconds between API requests	3.0

GUI Settings panel

Click Settings in the GUI to adjust per-run:

• Skip existing album files - Enabled by default for incremental updates. Uncheck to re-download everything.
• Excluded terms - One per line. Songs matching these terms are filtered out.
• Remove section headers - Strip [Chorus], [Verse], etc. from lyrics.
• API delay - Seconds to wait between requests (increase if rate-limited).

Troubleshooting

Connection Errors

If you get Remote end closed connection without response:

• Try using a song limit to download in smaller batches
• Increase the API delay in Settings
• Wait a few minutes and retry

Missing Release Dates

Some albums on Genius don't have complete metadata. The script will:

• Create filenames without year if unavailable
• Omit the release_date field from YAML if not found

Rate Limiting

The script includes built-in rate limiting protection:

• Configurable delay between song requests (default 3 seconds)
• Exponential backoff retry (10s, 20s, 30s)
• 3 automatic retries on connection failures

Contributing

Contributions are welcome! Feel free to:

• Report bugs
• Suggest features
• Submit pull requests

License

MIT License - feel free to use and modify as needed.

Acknowledgments

• Built with LyricsGenius by John W. Miller
• GUI built with CustomTkinter
• Lyrics data from Genius.com

Disclaimer

This tool is for personal use only. Please respect Genius.com's Terms of Service and rate limits. Do not use this tool to scrape large amounts of data for commercial purposes.