Theme SDK

The Now Playing Theme SDK (nowplaying-theme-sdk) is a standalone development environment for creating custom overlay themes. Overlays are what appear in OBS — the visual track card with artist, title, and artwork that viewers see. The SDK provides a live preview harness, the React components shared with the production overlay, and the animation hooks that let themes respond smoothly when tracks change.

What the SDK Provides

• A local dev harness — a Next.js app with hot reload that renders your theme against mock track data, so you can iterate visually without connecting to the live pipeline.
• Mock tracks — a curated set of realistic track objects covering different artwork aspect ratios, missing fields, and long text for truncation testing.
• Base components — BaseOverlay, AlbumArt, and text utilities with built-in animation lifecycles.
• Theme registration — a registerTheme API for exposing your theme to the live overlay renderer once deployed.

The Theme Render Model

Each theme is a React component that receives a ThemeRenderProps object:

Prop	Type	Meaning
title	string	Track title, after enrichment
artist	string	Artist name, after enrichment
label	string	Album or record label
artworkUrl	string	CDN-served artwork URL
isAnimating	boolean	True during enter/exit transitions
phase	'enter' | 'visible' | 'exit'	Current animation phase

Themes use the phase and isAnimating flags to run entrance and exit animations in response to track changes. The BaseOverlay component handles the state transitions so that themes can focus on the visual design.

Animation Lifecycle

When a new track arrives, the overlay goes through three phases:

1. Exit — the previous track animates out.
2. Enter — the new track animates in.
3. Visible — the new track is on screen until the next change.

The SDK provides timing hooks so that long text, artwork crossfades, and text-reveal animations can be coordinated with the underlying state machine.

Workflow

A typical theme development session:

1. Scaffold a new theme in the SDK.
2. Run the local dev server and open the preview.
3. Iterate on visuals using the mock track data.
4. Test against edge cases (long titles, missing artwork, long artist lists).
5. Export the theme and submit it to the main Now Playing web app for deployment, where it becomes available to users as an overlay option.

Where Themes Run in Production

In production, a theme is a React component bundled into the Now Playing web app at apps/web. When a viewer’s OBS browser source opens an overlay URL, the server renders the user’s selected theme and streams track updates via Server-Sent Events. The theme component receives props identical to the ones it sees in the SDK, so a theme that works locally also works live.

Why a Separate SDK?

Bundling theme development into the main web app would tie every theme iteration to a full web build. Running themes in a dedicated SDK package keeps iteration fast, avoids cross-contamination between unrelated themes, and keeps the main web app lean.