Spooty

Spooty is a self‑hosted media ingestion service that bridges Spotify metadata with freely available audio streams on YouTube. Written in TypeScript, the application is split into a NestJS‑powered backend and an Angular frontend. The core workflow pulls track, album, or playlist information from the Spotify Web API, then queries YouTube’s public search endpoint to locate corresponding audio videos. The video is subsequently downloaded via youtube-dl or a similar library, and the resulting MP3 (or user‑selected format) is stored in a configurable local directory. This design keeps all heavy lifting on the client side while preserving Spotify’s legal boundaries, as Spooty never pulls data directly from Spotify’s proprietary audio streams.

Architecture & Technical Stack

• Backend – NestJS (Node.js v18) provides a modular, dependency‑injection‑friendly framework. Controllers expose REST endpoints for authentication (/api/callback), queue management, and status polling. Services orchestrate Spotify API calls (via spotify-web-api-node), YouTube search, and download pipelines. Redis is used as an in‑memory cache for token storage and request throttling, ensuring compliance with Spotify’s rate limits.
• Frontend – Angular (v16) delivers a SPA that consumes the NestJS API. It handles OAuth flow, playlist subscription UI, and real‑time progress updates through WebSockets or Server‑Sent Events.
• Database – No persistent relational DB is required; all state is held in Redis or flat JSON files. This lightweight approach simplifies deployment and scales horizontally by sharing the same Redis instance.
• Containerization – The project ships a ready‑to‑run Docker image (raiper34/spooty:latest). The container exposes port 3000, mounts a persistent downloads volume, and accepts environment variables for Spotify credentials and optional Redis connection strings.

Core Capabilities & Developer APIs

• OAuth Integration – Exposes /api/auth/spotify and /api/callback, enabling developers to embed Spotify authentication flows into custom UIs.
• Playlist & Album Subscriptions – REST endpoints (/api/subscriptions) allow automated polling of Spotify pages. New releases trigger queued downloads without manual intervention.
• Download Queue – A lightweight in‑memory queue (Redis list) processes download jobs serially, exposing status (/api/jobs/:id) and progress callbacks. Developers can hook into these endpoints to build dashboards or integrate with CI/CD pipelines.
• Webhook Support – Custom webhooks can be registered to receive notifications when a download completes, facilitating downstream processing (e.g., metadata tagging or cloud upload).
• Extensibility – The service architecture supports plug‑in modules. For instance, replacing the YouTube search module with a different audio source (SoundCloud, Bandcamp) only requires implementing the AudioSource interface.

Deployment & Infrastructure

Spooty’s minimal footprint makes it ideal for edge deployments (Docker Swarm, Kubernetes). The Docker image is ~300 MB, built on Alpine‑based Node. Scaling horizontally involves running multiple instances behind a load balancer; shared Redis ensures consistent queue distribution. Persistent storage is handled via bind mounts or cloud block volumes, allowing large media libraries without compromising performance.

Integration & Extensibility

Developers can extend Spooty in several ways:

• Custom Audio Source – Implement a new AudioSource that queries APIs like iTunes or Bandcamp, then register it via environment configuration.
• Metadata Enrichment – Hook into the post‑download pipeline to fetch album art from Spotify or Last.fm, embedding it in MP3 tags.
• Authentication Alternatives – Replace the default OAuth flow with a service account or JWT‑based system for enterprise use.
• CLI Wrapper – Expose the core logic as a Node library (spooty-core) so other applications can programmatically enqueue downloads.

Developer Experience

The codebase follows industry‑standard TypeScript linting and testing practices. Comprehensive Swagger documentation is auto‑generated from NestJS decorators, giving developers a ready API reference. The README and inline comments provide clear guidance on environment variables (SPOTIFY_CLIENT_ID, SPOTIFY_CLIENT_SECRET, REDIS_URL), making local development straightforward. Community support is modest but growing; issues are triaged quickly on GitHub, and the open‑source license (MIT) removes any legal barriers to modification.

Use Cases

• Personal Media Libraries – Users who own Spotify playlists can migrate them to a local MP3 collection for offline listening or backup.
• Podcast Aggregators – Automatically download new episodes from Spotify‑hosted shows and re‑serve them on a private server.
• Educational Institutions – Create curated audio libraries from Spotify courses or lecture playlists, ensuring compliance with licensing.
• CI/CD Pipelines – Integrate Spooty into build scripts that generate audio assets for web or mobile applications.

Advantages Over Alternatives

• Self‑Hosted Control – No reliance on third‑party services; data stays within the developer’s infrastructure.
• Open Source & MIT License – Free to modify, redistribute, or embed in proprietary products.
• Performance Optimizations – Built on NestJS’s efficient request handling and Redis caching, Spooty handles high‑volume queues with minimal latency.
• Minimal Dependencies – No heavyweight databases or external APIs beyond Spotify and YouTube, reducing attack surface and deployment complexity.
• Extensible Architecture – Plug‑in capable design allows future integration with new audio sources without rewriting core logic.

Spooty offers