Grit

Grit: Version Control Meets Music Playlists

What if you could manage your playlists the way developers manage code? Grit brings git-style version control to music, letting you track changes, commit updates, and sync across Spotify and YouTube—all from your terminal.

The Problem: Playlist Chaos

Playlists are living documents. You add tracks, remove the ones that no longer fit, reorder for better flow. But there's no history. No way to see what your playlist looked like last month. No undo when you accidentally delete that perfect song.

Music platforms treat playlists as static lists. Grit treats them as versioned repositories.

Core Architecture: Git Semantics for Audio

Grit implements familiar version control concepts:

Repository Model: Each playlist becomes a local repository with full commit history. Initialize with grit init, stage changes with grit add, and commit when ready. The mental model is identical to git—if you know one, you know the other.

Multi-Platform Sync: Under the hood, Grit maintains a unified data model that abstracts over Spotify and YouTube APIs. Push your local changes to either platform, or pull remote changes to stay in sync.

Offline-First Design: All operations work locally first. Network calls only happen on explicit push/pull commands. This means you can curate playlists on a flight and sync when you land.

The Terminal UI Player

Beyond version control, Grit includes a full-featured TUI music player:

• Progress tracking with visual playback bar
• Keyboard controls for play, pause, skip, and seek
• Real-time lyrics via LRCLIB integration
• Device selection for Spotify Connect devices
• Resume playback from exactly where you left off

The TUI is built with Ratatui, providing a responsive interface that feels native to the terminal.

Technical Implementation

Rust for Performance: Playlist operations need to feel instant. Rust's zero-cost abstractions mean staging 500 tracks happens in milliseconds, not seconds.

Async I/O with Tokio: API calls to Spotify and YouTube are network-bound. Tokio's async runtime keeps the UI responsive while fetching metadata and syncing changes.

Structured Command System: Commands are organized into logical groups:

• Auth: auth, logout, whoami
• Playlist: init, list, switch
• Staging: search, add, remove, move
• Version Control: commit, push, pull, revert, diff, log

Workflow Example

bashCopy
# Initialize from existing Spotify playlist
grit init --spotify "https://open.spotify.com/playlist/..."

# Search and add new tracks
grit search "artist:Radiohead"
grit add 3  # Add track #3 from search results

# Review changes
grit diff

# Commit and push
grit commit -m "Added Radiohead tracks for late night coding"
grit push

Why This Matters

Playlists are personal. They capture moods, memories, and moments. Losing a carefully curated playlist to an accidental deletion or platform migration is genuinely frustrating.

Grit gives you control. Your playlists live locally as structured data, versioned and backed up. The platforms become just another remote—useful for playback, but not the source of truth.

Current Status

Grit is in active development with core functionality working. The version control system, TUI player, and Spotify integration are solid. YouTube support and additional features are in progress.