Spotify CLI Lyrics Fetcher

A Node.js TypeScript command-line application for fetching lyrics for your currently playing Spotify songs.

What This Skill Does

This skill helps you build and maintain a CLI tool that:

Architecture

The application follows a service-based architecture with clear separation of concerns:

Core Services

1. **SpotifyService**: Handles all Spotify-related operations

- OAuth 2.0 authentication flow

- Token management and refresh

- Fetching currently playing track information

2. **LyricsService**: Manages lyrics retrieval

- Primary source: lyrics.ovh (free, no API key required)

- Secondary source: MusixMatch (requires API key for enhanced features)

- Fallback: Genius search suggestions

CLI Commands

Implementation Instructions

Step 1: Project Setup

Set up a TypeScript Node.js project with the following structure:

```

src/

services/

SpotifyService.ts # Spotify API integration

LyricsService.ts # Lyrics fetching logic

commands/

auth.ts # Authentication command

current.ts # Current song command

search.ts # Search command

status.ts # Status command

index.ts # CLI entry point

types.ts # TypeScript type definitions

```

Step 2: Required Dependencies

Install the following packages:

Step 3: Environment Configuration

Create a `.env` file with required variables:

```

SPOTIFY_CLIENT_ID=<from Spotify Developer Dashboard>

SPOTIFY_CLIENT_SECRET=<from Spotify Developer Dashboard>

SPOTIFY_REDIRECT_URI=http://localhost:8888/callback

LYRICS_API_KEY=<optional MusixMatch API key>

```

Users must register an application at [Spotify Developer Dashboard](https://developer.spotify.com/dashboard) to obtain client credentials.

Step 4: Spotify Authentication Flow

Implement OAuth 2.0 Authorization Code Flow:

1. Generate authorization URL with required scopes (`user-read-currently-playing`, `user-read-playback-state`)

2. Launch local callback server on port 8888

3. Exchange authorization code for access token

4. Store tokens securely (consider using system keychain or encrypted file)

5. Implement token refresh logic before expiration

Step 5: Lyrics Fetching Strategy

Implement a waterfall approach for lyrics retrieval:

1. **Primary**: Query lyrics.ovh API (free, no authentication)

- Endpoint: `https://api.lyrics.ovh/v1/{artist}/{song}`

- No rate limiting concerns

2. **Secondary**: Query MusixMatch API if API key is provided

- More accurate and feature-rich

- Requires API key from MusixMatch developer portal

3. **Fallback**: Provide Genius search URL

- When no lyrics are found, generate a search link

- Format: `https://genius.com/search?q={song}+{artist}`

Step 6: Error Handling

Implement comprehensive error handling for:

Provide clear, actionable error messages to users.

Step 7: TypeScript Types

Define interfaces for:

Step 8: CLI Interface

Use Commander.js to create an intuitive CLI:

Step 9: Testing Considerations

While not required, consider:

Usage Examples

```bash

First-time setup

spotify-lyrics auth

Get lyrics for currently playing song

spotify-lyrics current

Search for specific song

spotify-lyrics search "Bohemian Rhapsody" "Queen"

Check authentication status

spotify-lyrics status

```

Important Notes

Constraints