To experience how this library works in a live environment, you can visit my personal website: 👉 sxrp.me
How it works: This website leverages the CSharpSpotiLyrics library under the hood (the LRPC-API project is private, but it runs on the latest version of CSharpSpotiLyrics at its core) to fetch and display the track currently playing on my Spotify account, the player state, and synced lyrics 24/7 in real-time on a dynamic interface (if it is not shown on site or inactive, I am probably sleeping :D)
You can ingest this repository instantly using: https://gitingest.com/s0rp/CSharpSpotiLyrics
- Interactive Documentation - Explore the full API reference, Canvas tutorials, and exception handling guides.
- AI & LLM Friendly Docs (llms.txt) - Clean, plain-text documentation optimized for Claude, ChatGPT, and Cursor agents.
The ultimate command-line Spotify synced lyrics downloader (
.lrc) built in C# and .NET.
CSharpSpotiLyrics is a professional C# command-line interface (CLI) application designed to retrieve, extract, and download synchronized time-coded lyrics (.lrc files) directly from Spotify.
Whether you need to batch-download lyrics for individual tracks, complete albums, public playlists, currently playing session tracks, or interactively select songs from your saved library, CSharpSpotiLyrics handles it seamlessly. It also features automatic local audio directory scanning to match ID3 metadata tags directly with Spotify's synced lyrics catalog.
You can inspect pre-downloaded synced .lrc file samples and album output structures directly inside the Examples/ directory in this repository.
⚠️ Disclaimer
This project is intended for educational purposes only. Accessing Spotify's internal APIs might violate their Terms of Service. Use this tool responsibly and at your own risk. The developers assume no liability for account restrictions or consequences resulting from its use. (Though, It has been in working my account for over a year and running continuously for 5–6 months; there are no issues at the moment.)
- Multi-Target Lyrics Retrieval: Download synced
.lrclyrics using Spotify Track, Album, or Playlist URLs and unique IDs. - Local Audio Metadata Matching: Scan local music folders, read audio file ID3 metadata tags, query Spotify automatically, and save synced
.lrcfiles alongside your local media. - Active Session Synchronization: Instantly fetch and save lyrics for the song currently playing on your active Spotify session.
- Interactive Library Mode: Interactively select and download lyrics from your saved library playlists and saved albums.
- Standardized LRC Formatting: Outputs clean, time-synced
.lrcfiles compatible with modern media players (e.g., VLC, Poweramp, Musicolet, Foobar2000). - Zero-Browser / Ultra-Lightweight Infrastructure: No heavy browser automation frameworks (such as Playwright or Selenium) required. Built entirely on top of the native .NET HTTP client and an optimized Regex engine for lightning-fast, cross-platform execution (Windows, Linux, macOS).
- Flexible Configuration Management: Dedicated
config.jsonfile to persist your default download directory andsp_dccookie. All options can be overridden dynamically via command-line flags. - Cache Management & Troubleshooting: Easily flush state caches (TOTP keys and dynamic GraphQL hashes) with a simple CLI argument to resolve connection or API sync errors.
- .NET SDK: .NET 6.0 SDK or later is required to build and run the source code. Download .NET SDK.
- Spotify
sp_dcCookie: A valid web player session cookie is required to authenticate API requests.
git clone https://github.com/s0rp/CSharpSpotiLyrics
cd CSharpSpotiLyrics
cd CSharpSpotiLyricsCLI
dotnet build -c Release
dotnet run -- [options] <url_or_path>
.\bin\Release\net8.0\CSharpSpotiLyricsCLI.exe [options] <url_or_path>
./bin/Release/net8.0/CSharpSpotiLyricsCLI [options] <url_or_path>
You can execute the utility directly via the .NET CLI or run the compiled binary under /bin/Release/ directly.
Before downloading lyrics, you must authenticate the CLI by saving your Spotify sp_dc web cookie to the application profile.
- Open your web browser and log in to open.spotify.com.
- Open your browser's Developer Tools (typically
F12orRight Click -> Inspect). - Navigate to the Application tab (Chrome/Edge) or Storage tab (Firefox).
- Expand the Cookies dropdown on the left and select
https://open.spotify.com. - Find the row named
sp_dcand copy its alphanumeric Value.
Security Warning: Your
sp_dctoken functions as your active session password. Keep it secure and never share it publicly.
Run the built-in interactive configuration tool:
dotnet run -- --config editThe interface will guide you to:
- Paste your copied
sp_dctoken. - Specify your default target directory where lyric files should be saved.
- Set other structural preferences (e.g.,
ForceDownloadbehaviors).
Note: The configuration directory varies based on your Operating System. The CLI will display the exact path of your config.json upon initialization.
# Using dotnet run
dotnet run -- [options] [<url_or_path>]
# Direct executable use (e.g., published binary)
./CSharpSpotiLyrics [options] [<url_or_path>]<url_or_path>: (Optional) Accepts a Spotify track/album/playlist URL or ID, or a local file directory path.
| Command / Option | Description |
|---|---|
-d, --directory <path> |
Temporarily overrides the download output folder for this execution. |
-f, --force |
Forces download, overwriting existing .lrc files in the output directory. |
-cl, --clearcache |
Deletes cache configurations (.SPOTIFYTOTP and .SPOTIFYHASH) to resolve sync errors. |
-u, --user <item> |
Interacts with your active library. Values: current, album, play. |
-c, --config <action> |
Launches configuration helper. Values: edit, reset, open. |
# Track URL
dotnet run -- "https://open.spotify.com/track/1DwscornXpj8fmOmYVlqZt"
# Album ID (URI Format)
dotnet run -- "spotify:album:7DIlfmw6CAE1J8tp2QqgAJ"
# Playlist Link (downloads all tracks inside)
dotnet run -- "https://open.spotify.com/playlist/1tlptlfM0epuPkqRbLHvdj"# Scan metadata in a local music folder and automatically download matching lyrics
dotnet run -- "/home/user/Music/MyAlbum"# Download lyrics for whatever is playing on your account right now
dotnet run -- --user current
# Interactively browse and select saved playlists from your profile
dotnet run -- --user play
# Interactively browse and download saved albums from your profile
dotnet run -- --user album# Force overwrite existing lyrics files
dotnet run -- --force "https://open.spotify.com/track/1DwscornXpj8fmOmYVlqZt"
# Clear temporary API hashes and TOTP keys to resolve bad request errors
dotnet run -- --clearcache "https://open.spotify.com/track/1DwscornXpj8fmOmYVlqZt"
# Open the directory containing config.json in your File Explorer
dotnet run -- --config openIf you encounter authentication or connection errors (e.g., 400 Bad Request during client startup):
- Ensure your
sp_dccookie hasn't expired. You can verify this by checking if you are still logged into the Spotify Web Player in your browser. - Run the application with the -cl / --clearcache option. This deletes temporary local tokens and cached files, forcing the client to re-authenticate from scratch and automatically retrieve fresh dynamic GraphQL hashes from Spotify.
- Development & C# Core Architecture: s0rp
- Workflow Rewriting & Code Arrangement: Dixiz 3A (MoE Project Neural Supervisor)
--
This is an independent open-source community project. It is not affiliated, associated, authorized, endorsed by, or in any way officially connected with Spotify AB, its artists, partners, or any of its subsidiaries or affiliates. The official Spotify website can be found at https://spotify.com. The name "Spotify" as well as related names, marks, emblems, and images are registered trademarks of Spotify AB.