User Accounts & Guest Mode

Now Playing uses a userId-primary identity model. Every user has a single userId that is generated once and persisted forever, and all other identifiers (Twitch, Google, Discord, etc.) attach to that userId as linked accounts. This design is what makes guest mode work: a user can start using the app without any signup, and when they sign in later, their existing data is preserved automatically.

The userId Is Forever

Your userId is created the first time you open the desktop app or visit the web dashboard. Once created it never changes — not when you sign in, not when you log out, not when you link or unlink OAuth providers, not when you reset your overlay URL. It is the stable foundation for your track history, settings, and overlay URLs.

   userId: a1b2c3d4e5f6g7h8
      │
      ├── Track history
      ├── Overlay URLs
      ├── Settings & preferences
      └── Linked accounts (0 or more)
           ├── Twitch
           ├── Google
           └── ...

Where It Is Stored

Surface	Storage Location
Desktop app	~/Library/Application Support/Now Playing 3/auth.json (macOS) / %AppData%/Now Playing 3/auth.json (Windows)
Web dashboard	HTTP-only secure cookie
Overlay URL	Derived token embedded in the URL

Guest Mode

When you use Now Playing without signing in, you are a guest user. A guest account is fully functional:

• Track display, on-air detection, and overlay delivery all work.
• Track history is saved and persists across restarts.
• Overlay customisation, themes, and settings are saved.
• All connectors (Rekordbox, Serato, MIDI, etc.) are available.

The only things a guest cannot do are features that require a verified identity — for example, migrating your account to another device, or features gated behind a subscription.

Signing In Later

When a guest signs in with an OAuth provider (Twitch or Google) for the first time, the provider’s account is linked to the existing userId. No data is lost, no new account is created, and the overlay URL does not change. This is one of the most important properties of the identity model: the decision to sign in is never a migration hazard.

If you sign in on a second device that was previously a separate guest, the two userIds cannot be merged automatically. The second device adopts the signed-in userId, and its guest-only data stays with the original guest account. In practice this is rare because most users sign in on their primary device before adding a second.

OAuth Providers

Provider	Status	Primary Use
Twitch	Active	Sign-in, chat bot authorisation
Google	Implemented	Sign-in (UI currently disabled)

OAuth tokens for linked accounts are stored server-side and used to post to Twitch chat, authorise API calls, and deliver account-gated features. Tokens are refreshed automatically using the provider’s refresh flow.

What Identity Is Used For

Use	Identifier Used
Socket.IO authentication from desktop	userId
SSE subscription for overlay delivery	userId derived from overlay token
Track history lookup	userId
Twitch chat delivery	Linked Twitch account
Subscription entitlement checks	userId

What Happens If You Sign Out

Signing out clears the session cookie in the browser but does not delete the userId or any data. Signing back in reconnects to the same userId.

On desktop, signing out resets the auth.json file. If you sign in to the same account after, data is preserved. If you do not sign in, the desktop generates a new guest userId and effectively starts over.

Why Design It This Way

This model avoids a lot of the friction that authentication usually creates:

• Zero-signup onboarding. A new user is productive in seconds.
• No data loss on sign-up. Signing in never wipes what came before.
• Stable overlay URLs. URLs are tied to userId, not to OAuth accounts, so rotating or disconnecting a provider never breaks an overlay in OBS.
• Simple server logic. The server only ever needs to resolve userId; the OAuth details are metadata.