SongTracker Documentation
A personal iOS app I built to automatically track and log my music listening history using Cloudflare Workers and modern web technologies.
Table of Contents
Introduction
SongTracker is a simple iOS application that tracks the music I listen to. Before discussing the technical details, I'd like to explain why I created this app and why it won't be publicly released.
I built SongTracker for two primary reasons. First, back in 2023, some friends and I used an app that tracked our songs and shared them with each other. I never liked that app and found it poorly designed, so I told myself I'd create a better, free version someday. Second, I often enjoy sharing my Song of the Day (SOTD) with friends, and SongTracker felt like a natural extension of that habit.
That said, this app will never be available on the App Store. I built it solely for my own use, and it's nowhere near ready for public release. More importantly, SongTracker uses the iOS framework MPMusicPlayerController, which Apple considers a security risk. Any app that relies on it would be rejected from the App Store. Since I'm only installing it on my personal iPhone, though, I'm free to use it as much as I like.
While the app isn't on the App Store, the iOS app code is freely available to download and use. You could set up your own instance with your own API endpoints. However, please note that the Worker configuration and backend code cannot be shared as it contains confidential information and security measures specific to my implementation.
System Architecture
The architecture of my SongTracker app is intentionally simple, focusing on reliability and personal use rather than scalability or multi-user support.
1. iOS Application (Client)
The iOS app serves as the data collection point, continuously monitoring my music playback.
Key Components
- •Background Operation: Uses silent audio playback (silence.mp3)
- •Implements background fetch and processing capabilities
- •Maintains active audio session with .mixWithOthers and .allowAirPlay options
Core Functionality
- •MediaPlayer framework monitors system music playback
- •AVFoundation handles background audio session
- •Background tasks scheduled every 60 seconds
- •Real-time song detection through MPMusicPlayerController
Data Flow
- 1.Detects when a song changes through MPMusicPlayerController
- 2.Extracts song title and artist information
- 3.Formats data into JSON payload
{
"song": "Song Title",
"artist": "Artist Name"
}Sends POST request with:
- Content-Type: application/json
- X-API-Key header for authentication
2. Cloudflare Worker (API)
Acts as the intermediary service layer, processing and storing song data.
Authentication
- •Uses API key validation (X-API-Key header)
- •Configured through Cloudflare Workers dashboard
Endpoints
- •POST / - Accepts song data
- •GET / - Retrieves song history
Data Processing
- •Validates incoming requests
- •Adds timestamp to song data
- •Stores data in Cloudflare KV storage
- •Returns success/error responses
3. Frontend Website
Displays tracked songs in a user-friendly interface.
Features
- •Real-time song history display
- •Timestamp information
- •Clean, modern UI
System Integration Flow
Song Detection & Transmission
- 1.User plays music → iOS app detects change → Extracts song info → Formats JSON payload
- 2.iOS app → POST request → Cloudflare Worker validates → Stores in KV storage
- 3.Website → Fetches from Worker API → Processes data → Displays to user
Security Measures
- •API key authentication
- •Sensitive config files excluded from git
- •HTTPS for all communications
- •Cloudflare's built-in DDoS protection
Configuration Requirements
iOS App:
- • Config.swift with API endpoint and key
- • Background mode capabilities
- • Media library permissions
Cloudflare Worker:
- • API key configuration
- • KV storage binding
- • CORS settings for website access
Website:
- • API endpoint configuration
- • Periodic refresh settings
iOS Application
Core Technologies
- Swift 5.5+
Primary programming language
- SwiftUI
For user interface components
- MediaPlayer Framework
For accessing currently playing songs
- Background Processing
For continuous operation
Key Components
Song Detection System
- •Uses MPMusicPlayerController.systemMusicPlayer for system-wide media playback access
- •Observes MPMusicPlayerControllerNowPlayingItemDidChange notifications
- •Falls back to MPNowPlayingInfoCenter when necessary
Background Operation
- •Uses silent audio playback to maintain background operation
- •Configures audio session for background processing
- •Implements proper notification handling
Network Communication
- •HTTP POST requests to the Worker API endpoint
- •JSON encoding of song data
- •Error handling and retry logic
Required Permissions
- •com.apple.security.personal-information.music-library
- •Background audio capability for continuous operation
API & Backend
Cloudflare Workers Implementation
The backend is built on Cloudflare Workers, a serverless platform that runs JavaScript code globally. It's combined with KV storage for persistence.
- •TypeScript
- •Cloudflare Workers
- •Cloudflare KV Storage
POST / (Store Song)
Purpose: Record a newly playing song
Request Body:
{
"song": "Song Title",
"artist": "Artist Name",
"timestamp": 1679580000000
}GET / (Retrieve Song History)
Purpose: Get all tracked songs
Response:
HTML page with formatted song history
Data Storage
Songs are stored in Cloudflare KV with the following structure:
{
"song": "Song Title",
"artist": "Artist Name",
"timestamp": 1679580000000
}Website Integration
Current Status
The website integration is still a work in progress. While the core functionality of song detection and API communication is complete, I'm still working on the design and implementation of how this data will be displayed on my website. My main focus was on getting the iOS app and backend working reliably first.
The current implementation provides a simple endpoint that returns my listening history, which I plan to enhance with a more polished UI in the future.
Privacy & Security
Security Measures
API Security
- •HTTPS-only endpoints
- •Rate limiting on all endpoints
- •CORS policy implementation
Data Storage
- •Encrypted at rest in my private Cloudflare KV namespace
- •Regular cleanup of old entries
Learnings & Takeaways
Technical Growth
- •Gained deep understanding of iOS background processing and its limitations
- •Learned to work with Apple's MediaPlayer framework and its intricacies
- •Explored serverless architecture with Cloudflare Workers
Project Management
- •Importance of starting small and focusing on core functionality first
- •Value of building for personal use rather than trying to please everyone
- •Benefits of iterative development and continuous testing
Personal Insights
- •Sometimes the best solutions come from personal pain points
- •Not every app needs to be on the App Store to be valuable
- •The importance of documentation, even for personal projects
Future Applications
The knowledge gained from this project, particularly around background processing and media detection in iOS, has opened up possibilities for other personal automation projects. The experience with Cloudflare Workers has also provided a solid foundation for building other serverless applications.