Skip to content
← All work

P—11 Case study · Tools & automation

Spotify Widget for macOS

Role

Developer

Status

completed

Started

Feb 2026

Last activity

Feb 2026

Stack

6 technologies

Overview

A learning-focused macOS widget that integrates with the Spotify Web API via OAuth 2.0 to display and control currently playing music. Built as a utility project to explore OAuth Authorization Code Flow, automatic token refresh mechanisms, and REST API integration patterns. The widget retrieves real-time playback state (track title, artist, album art, progress), enables play/pause/skip controls, and displays recently played tracks. Note: This is a learning/utility project exploring Spotify API integration patterns — not a production-grade macOS widget.

Outcomes

OAuth 2.0

Auth Flow

60min

Token Refresh

5s

Poll Interval

2

Python files

Impact

  1. 01Implemented full OAuth 2.0 Authorization Code Flow with Spotify Web API including automatic token refresh
  2. 02Built Flask web server handling login redirect, callback token exchange, and real-time currently-playing retrieval
  3. 03Designed stateless two-file architecture separating OAuth handshake from API consumption logic
  4. 04Enabled cross-platform compatibility via PyAutoGUI with macOS-specific and Windows-specific hotkey support

Features

01

OAuth 2.0 Flow

Authorization Code Flow with PKCE — handles login redirect, callback token exchange, and automatic token refresh every 60 minutes

02

Spotify Web API

REST API integration for currently-playing, playback control (play/pause/skip), recently played, and user profile endpoints

03

Desktop Widget

PyAutoGUI-powered overlay widget with macOS and Windows hotkey support for seamless media control

04

Flask Auth Server

Lightweight Flask server handling the OAuth callback, token storage, and API proxy requests

05

Stateless Architecture

Two-file design cleanly separates OAuth handshake logic from Spotify API consumption — saves tokens as JSON

06

Token Refresh Pipeline

Automatic 401 detection triggers token refresh using refresh_token — seamless uninterrupted playback tracking

Architecture

Stateless two-file architecture: (1) spotify_oauth.py handles the OAuth 2.0 Authorization Code Flow — redirects user to Spotify login, exchanges authorization code for access/refresh tokens, and automatically refreshes expired tokens. (2) spotify_widget.py consumes the Spotify Web API using stored tokens — polls /v1/me/player/currently-playing every 5 seconds, displays track info in a PyAutoGUI overlay, and supports media control via keyboard shortcuts. No database required — tokens stored as JSON in user config directory.

Stack

PythonSwiftFlaskRequestsSpotify Web APIOAuth 2.0

Development log

  1. · Started

    Spotify now-playing widget for macOS

    Two-file Python widget for Spotify login, token refresh, and now-playing tracking. I made it because the built-in macOS widget was not to my liking.

Next case study →