PlaySched - Spotify Playlist Scheduler

A comprehensive project combining a web application for scheduling Spotify playlist playback and a command-line tool for direct Spotify control, history management, and data synchronization. Born from the frustration of using Amazon Alexa’s terrible music scheduling interface, this project provides a superior solution using Spotify’s robust API and better audio equipment.

🚀 Project Overview

PlaySched addresses a specific but common need: automated music scheduling that actually works well. Rather than fighting with voice assistant interfaces, this system provides both web-based scheduling and powerful command-line tools for managing Spotify playback across devices.

Key Components

• 🖥️ Web Application (playsched.py): User-friendly interface for playlist scheduling
• ⌨️ Command-Line Tools (play_spotify_playlist.py): Direct terminal-based Spotify control
• 📊 Data Management: Local SQLite storage for history and synchronization
• 🔒 Security: OAuth 2.0 authentication with HTTPS support
• ⏰ Scheduling: APScheduler-based automation with timezone support

🛠️ Technical Architecture

Web Application Features

Authentication & Security:

• Spotify OAuth 2.0 integration with secure token management
• HTTPS-only operation with custom certificate support
• Session management and secure cookie handling

Playlist Management:

• Browse and filter personal Spotify playlists
• Real-time device discovery via Spotify Connect
• Playlist search and organization capabilities

Advanced Scheduling:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# Example scheduling logic
schedule_config = {
    'playlist': 'spotify:playlist:37i9dQ...',
    'device': 'My Speakers',
    'start_time': '07:00',
    'stop_time': '09:00', 
    'days': ['monday', 'tuesday', 'wednesday'],
    'volume': 65,
    'shuffle': True,
    'timezone': 'Europe/Paris'
}

Schedule Management:

• View all schedules sorted by next run time
• Manual trigger (“Play Now”) functionality
• Pause/Resume schedule controls
• Edit and duplicate existing schedules
• Comprehensive deletion with confirmation

Command-Line Interface

Device & Playlist Operations:

1
2
3
4
5
6
7
8

# List available Spotify Connect devices
python play_spotify_playlist.py --list-devices

# Browse your playlists
python play_spotify_playlist.py --list-playlists

# Play specific playlist on device
python play_spotify_playlist.py --device "My Speakers" --playlist "Chill Mix"

History & Data Management:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

# Update local playback history from Spotify
python play_spotify_playlist.py --update-history

# Sync all playlists and tracks locally
python play_spotify_playlist.py --sync-playlists

# Export data in multiple formats
python play_spotify_playlist.py --export-data my_data.xlsx  # Excel
python play_spotify_playlist.py --export-data my_data.csv   # CSV
python play_spotify_playlist.py --export-data my_data.json  # JSON

🎯 Key Features

Scheduling Capabilities

• Flexible Timing: Start/stop times with optional recurrence
• Day Selection: Specific days of the week or one-time execution
• Device Targeting: Automatic Spotify Connect device detection
• Volume Control: Set playback volume per schedule
• Shuffle Mode: Enable/disable shuffle for each schedule
• Timezone Support: Proper handling of DST and timezone conversions

Data Synchronization

• Local Storage: SQLite database for offline access to playlist data
• History Tracking: Recently played tracks with local time conversion
• Sync Management: Marks removed content without deletion
• Export Options: Excel, CSV, and JSON export formats
• Data Integrity: Comprehensive error handling and validation

Security Implementation

• HTTPS Enforcement: Required for Spotify API callbacks
• Custom Certificates: Script-generated CA and server certificates
• Token Management: Secure OAuth token caching and refresh
• Environment Variables: Sensitive data stored in .env files

📊 Technical Implementation

Database Schema

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

-- Schedules table for web app
CREATE TABLE schedules (
    id INTEGER PRIMARY KEY,
    playlist_uri TEXT,
    device_name TEXT,
    start_time TEXT,
    stop_time TEXT,
    days TEXT,
    volume INTEGER,
    shuffle BOOLEAN,
    timezone TEXT,
    active BOOLEAN
);

-- History tracking
CREATE TABLE playback_history (
    id INTEGER PRIMARY KEY,
    track_uri TEXT,
    played_at DATETIME,
    playlist_context TEXT
);

-- Synced playlist data
CREATE TABLE synced_playlists (
    id TEXT PRIMARY KEY,
    name TEXT,
    owner TEXT,
    track_count INTEGER,
    last_synced DATETIME,
    removed BOOLEAN DEFAULT 0
);

Flask Application Structure

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

# Core application setup with HTTPS
app = Flask(__name__)
app.config['SECRET_KEY'] = os.getenv('SECRET_KEY')

# Spotify API integration
sp_oauth = SpotifyOAuth(
    client_id=os.getenv('SPOTIPY_CLIENT_ID'),
    client_secret=os.getenv('SPOTIPY_CLIENT_SECRET'),
    redirect_uri=os.getenv('SPOTIPY_REDIRECT_URI'),
    scope='user-modify-playback-state user-read-playback-state playlist-read-private'
)

# APScheduler configuration
scheduler = BackgroundScheduler(timezone=UTC)
scheduler.start()

🔧 Installation & Setup

Prerequisites

• Python 3.8+ with pip or conda
• OpenSSL for certificate generation
• Spotify Account (regular or Premium)
• Spotify Developer App credentials

Quick Start

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

# Clone repository
git clone https://github.com/storizzi/playsched
cd playsched

# Setup virtual environment
python -m venv venv
source venv/bin/activate  # Linux/macOS
# or .\venv\Scripts\activate  # Windows

# Install dependencies
pip install -r requirements.txt

# Configure environment
cp .env-sample .env
# Edit .env with your Spotify credentials

# Generate HTTPS certificates
chmod +x generate_certs.sh
./generate_certs.sh

# Run application
flask run --host=0.0.0.0 --port=9093

Spotify Developer Setup

1. Register Application: Visit Spotify Developer Dashboard
2. Configure Callback: Add https://127.0.0.1:9093/callback to Redirect URIs
3. Copy Credentials: Client ID and Client Secret to .env file
4. Set Permissions: Required scopes for playback control

💡 Problem-Solving Approach

Original Challenge

The project originated from frustration with Amazon Alexa’s music scheduling interface:

• Cumbersome voice commands for time-based music control
• Limited playlist management capabilities
• Poor user interface for schedule modification
• Inferior audio quality compared to dedicated speakers

Technical Solution

• Better Interface: Web-based scheduling with visual playlist selection
• Superior Audio: Utilizes existing high-quality speakers via Spotify Connect
• Flexible Control: Both GUI and CLI interfaces for different use cases
• Data Ownership: Local storage and export capabilities
• Extensibility: Modular design allows for future enhancements

🔮 Roadmap & Future Development

Planned Features (v0.2.x)

• Multiple user support with authentication
• Advanced scheduling patterns (monthly, yearly)
• Playlist analysis and recommendation engine
• Mobile-responsive interface improvements
• Real-time playback status monitoring

Advanced Features (v1.0+)

• Smart home integration (Home Assistant, etc.)
• Machine learning-based scheduling suggestions
• Multi-room audio coordination
• Advanced analytics and listening insights
• Plugin architecture for extensibility

Technical Improvements

• Docker containerization for easy deployment
• Database migration system
• Enhanced error handling and logging
• Performance optimizations for large playlist collections
• Integration testing suite

📈 Impact & Usage

Personal Productivity

• Daily Automation: Seamless morning and evening music routines
• Device Management: Effortless switching between audio devices
• Data Insights: Understanding of listening patterns and preferences

Technical Achievements

• API Integration: Comprehensive Spotify Web API implementation
• Scheduling Logic: Robust timezone and DST handling
• Security Implementation: Production-ready HTTPS and OAuth flow
• Data Management: Efficient SQLite operations with export capabilities

Community Value

• Open Source: MIT licensed for community contribution
• Documentation: Comprehensive setup and usage guides
• Modularity: Reusable components for other Spotify projects

🛠️ Technologies & Dependencies

Core Technologies

• Backend: Python 3.8+, Flask web framework
• Database: SQLite with optimized queries
• Authentication: Spotipy OAuth 2.0 wrapper
• Scheduling: APScheduler with timezone support
• Security: pyOpenSSL for HTTPS certificates

Key Libraries

1
2
3
4
5
6
7
8
9

# requirements.txt highlights
Flask==2.3.2                # Web framework
spotipy==2.22.1             # Spotify API wrapper
APScheduler==3.10.1         # Background job scheduling
pytz==2023.3               # Timezone handling
python-dotenv==1.0.0       # Environment configuration
pyOpenSSL==23.2.0          # HTTPS certificate generation
pandas==2.0.3              # Data export functionality
openpyxl==3.1.2           # Excel export support

Development Tools

• Version Control: Git with semantic versioning
• Code Style: PEP 8 compliance with automated formatting
• Documentation: Markdown with comprehensive examples
• Testing: Manual testing with planned automated test suite

📚 Resources

• GitHub Repository - Complete source code and documentation
• Contact - Questions, feedback, and collaboration
• Storizzi - Professional development and consulting services

Current Version: v0.1.1 (June 2025) - Ready for production use with ongoing enhancements planned.

PlaySched represents the intersection of practical problem-solving, robust technical implementation, and user-centered design - transforming a daily frustration into a seamless, automated experience.