Live Trans

Real-time translation of Spotify song lyrics. Display synchronized translations of foreign language songs as they play.

Features

• Detects currently playing Spotify track
• Fetches time-synchronized lyrics from Spotify
• Translates lyrics to English using Claude AI
• Displays original and translated lyrics in real-time in your terminal
• Highlights current line based on playback position

Prerequisites

• Spotify Premium account
• Anthropic API key for Claude (get one here)

Installation

Pre-built Binaries (Recommended)

macOS/Linux:

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/Crazytieguy/live-trans/releases/latest/download/live-trans-installer.sh | sh

Windows (PowerShell):

irm https://github.com/Crazytieguy/live-trans/releases/latest/download/live-trans-installer.ps1 | iex

Homebrew (macOS):

brew install Crazytieguy/tap/live-trans

Cargo (from source):

cargo install live-trans

Or download pre-built binaries from GitHub Releases.

Usage

1. Run the app:

live-trans

2. On first run:

   • Enter your Anthropic API key when prompted (saved for future runs)
   • Authorize Spotify in your browser
   • Copy the redirect URL and paste it back into the terminal

3. Start playing a song on Spotify

4. Enjoy synchronized lyrics with translations!

How It Works

1. Configuration: API key stored in OS-specific config directory, prompts on first run
2. Authentication: Spotify OAuth with embedded credentials, tokens cached locally
3. Detection: Uses Spotify Web API to detect currently playing track
4. Lyrics: Fetches time-synchronized lyrics via librespot's SpClient API
5. Translation: Translates lyrics using Claude AI for high-quality, context-aware translations
6. Caching: Translated lyrics cached to disk in OS-specific cache directory
7. Display: Real-time synchronized display with highlighted current line

Notes

• Requires Spotify Premium
• Only works with songs that have time-synchronized lyrics
• Spotify credentials are embedded (no setup needed)
• API key and OAuth tokens cached - configure once, use forever
• Translated lyrics persisted to disk - replay songs instantly
• Config/cache stored in OS-appropriate directories (see Technical Details)
• Polls Spotify every 500ms for smooth synchronization

Troubleshooting

No lyrics found:

• Not all songs have synchronized lyrics on Spotify
• Try a different song

Claude API error:

• Verify your API key by checking the config file (see file locations below)
• Ensure you have credits available in your Anthropic account
• Delete the config file and re-run to enter a new API key

Spotify authentication issues:

• Try removing the Spotify token cache file and re-authenticating
• Make sure you paste the complete redirect URL

File locations:

• macOS: ~/Library/Application Support/com.live-trans.live-trans/ (config), ~/Library/Caches/com.live-trans.live-trans/ (cache)
• Linux: ~/.config/live-trans/ (config), ~/.cache/live-trans/ (cache)
• Windows: %APPDATA%\live-trans\ (config), %LOCALAPPDATA%\live-trans\ (cache)

Technical Details

Code Quality

• Rust 2024 edition - Latest language features and improvements
• Zero clippy warnings - Clean, idiomatic Rust throughout
• Type-safe - Uses SpotifyId type for proper track identification
• No unwraps - Proper error handling with contextual messages
• Latest dependencies - All crates updated to current stable versions

Architecture

• Embedded credentials - Spotify API credentials included, no user setup required
• OS-native storage - Config and cache files stored in platform-appropriate directories
• Official APIs - Uses librespot's SpClient::get_lyrics() instead of manual HTTP
• Smart caching - OAuth tokens and translated lyrics persisted to disk
• Auto token refresh - Automatically refreshes expired OAuth tokens
• Efficient polling - 500ms update interval for smooth synchronization
• Clean separation - Modular design: config, spotify, lyrics, translation, display

License

MIT