Cue - CLI Spotify Controller

A unified CLI application for controlling Spotify playback with timed sessions, intelligent queuing, and network support.

Features

• Smart Playback: Play tracks, albums, artists, playlists, or genres with duration control
• Timed Sessions: Set playback duration (30s, 5m, 2h, etc.) with automatic stop
• Queue Management: Build and manage playback queues
• Listening Modes: Focus, party, workout, sleep, and custom modes
• Network Control: Client-server architecture for remote control
• Playback History: Track what you've played with Spotify integration
• Volume & Device Control: Manage volume and switch between Spotify devices

Quick Start

# Install dependencies
pip install -r requirements-dev.txt

# Set up Spotify credentials
export SPOTIFY_CLIENT_ID="your_client_id"
export SPOTIFY_CLIENT_SECRET="your_client_secret"

# Check setup
python scripts/check_setup.py

# Run tests
python -m pytest tests/

# Try the CLI
python -m cue --help
python -m cue health

Usage Examples

# Basic playback
cue play "Bohemian Rhapsody"
cue play "Bohemian Rhapsody" 3m
cue play album "Dark Side of the Moon" 1h

# Modes
cue focus 2h
cue party 3h
cue workout 45m

# Queue management
cue queue add "Hotel California"
cue queue list
cue queue clear

# Status and control
cue status
cue skip
cue stop
cue vol 70

Architecture

• cue/core/: Shared utilities (config, database, models, duration parsing)
• cue/cli/: Command-line interface and client functionality
• cue/server/: Flask web server for network control
• tests/: Integration tests
• scripts/: Development and setup utilities
• packaging/: RPM spec and systemd service files

Development

# Run all tests
python -m pytest tests/ -v

# Install in development mode
pip install -e .

# Check setup and dependencies
python scripts/check_setup.py

# Simple test runner (no pytest required)
python scripts/run_tests.py

Documentation

See docs/ directory for detailed documentation:

• CONSOLIDATION_PLAN.md: Architecture and migration details
• TESTING.md: Testing guide and dependency info

Requirements

• Python 3.8+
• Spotify Premium account
• Required packages: click, requests, flask, spotipy
• Optional: pytest (for development)

License

See LICENSE file for details.