AudD for Twitch streamers — AudD resources

If you stream with music — a DJ set, a “just chatting” with tunes in the background, a radio-style channel — AudD can tell you and your viewers what’s playing in real time, and keep a record of it. This page is for Twitch streamers and the people who build their overlays and bots. You point AudD at your channel, it recognizes songs off the live audio as they play, and you get each match delivered to your backend to display, log, or both.

AudD is a music-recognition HTTP API backed by a database of 160 million songs. Its audio-streams API ingests a live stream continuously and fingerprints the audio, so you don’t capture or upload anything yourself — you register the channel once and consume the matches.

What you can do

The two things streamers tend to want from music recognition are a display (“what’s this song?”) and a record (“what did I play during that VOD?”). Both come from the same stream subscription.

Show the currently-playing song to viewers. AudD recognizes songs off your live audio and delivers each match — artist, title, album, song_link — so an overlay or a panel can render “now playing.” Pass callbacks=before and the match arrives the moment a song starts, which is what a live display needs.
Point AudD straight at your channel with a shortcut. You don’t need to dig up a raw media URL. The streams API accepts a twitch:<channel> shortcut as the stream URL — AudD resolves and ingests the channel’s live audio. (It also takes youtube:<video_id>, youtube-ch:<channel_id>, and direct HLS / Icecast / m3u8 URLs, if you stream elsewhere too.)
Keep a log of every song played. Each match carries a timestamp and, on the default (after-song) callback, a play_length. Persist them and you have a timestamped record of what played during a session — a “recently played” history strip for viewers, and a log you can review afterward.
Check your sets against music-policy risk. Many streamers care about avoiding muted VODs and channel strikes when copyrighted tracks end up in a recording. A play log tells you, factually, which recordings were in a given stream and when — so you can spot a track you’d rather not have used and edit or mute that segment of the VOD before it becomes a problem. AudD identifies what played; what you do about it is your call (this isn’t legal advice).
Drive an overlay without writing a frontend. AudD hosts an embeddable widget at widget.audd.tech that renders the last recognized song (and optionally a history strip) directly from a stream subscription. Drop it into an OBS browser source, or build your own overlay against your backend.
Consume matches whether or not you run a server. AudD POSTs a callback to a URL you host (the recommended path), or you hold open a longpoll connection when you can’t expose a public URL — a laptop behind NAT, a browser. Pick whichever fits your setup.

The streams API needs your real token, not the test token. Audio streams are a paid add-on; the public test token works only on the standard recognition endpoint, not on streams. Get your token at dashboard.audd.io.

Where to start

Build a now-playing widget for a livestream is the end-to-end recipe: set the account callback URL, add your stream, receive matches via callback or longpoll, and drop in a self-contained HTML/JS overlay for OBS. It uses the twitch:<channel> shortcut and the ?thumb cover-art trick.
Show recognized music on a Twitch stream focuses on the Twitch side specifically — subscribing a channel and rendering matches in an overlay or a Twitch Extension panel.
Callbacks vs. longpoll explains the two ways to receive matches and how to choose: a hosted webhook versus holding a connection open, and why the account needs a callback URL set either way.
Public database vs. your custom catalog covers what AudD matches against — the 160M-track public database versus a private catalog of your own tracks — relevant if you stream your own music.

Code teaser

This registers your Twitch channel with AudD using the twitch:<channel> shortcut and asks for matches at song start, so a now-playing display updates the instant a track begins. Set the account callback URL once first; see the recipe for the receiving server.

import { AudD } from "@audd/sdk";

const audd = new AudD(process.env.AUDD_API_TOKEN!); // dashboard.audd.io

// Per-account, set once: where AudD POSTs every match on the account.
await audd.streams.setCallbackUrl(
  "https://your-app.example.com/audd-callback",
  { returnMetadata: ["apple_music", "spotify"] }, // optional streaming links
);

// Subscribe your Twitch channel. radioId is your handle for this stream.
await audd.streams.add({
  url: "twitch:monstercat",
  radioId: 1,
  callbacks: "before", // deliver at song START — best for "now playing"
});

Once the stream is added, AudD POSTs a match to your callback URL each time a song starts. The body names the recording and links it on lis.tn; appending ?thumb to that song_link gives you the cover image for the overlay:

{
  "status": "success",
  "result": {
    "radio_id": 1,
    "timestamp": "2020-04-13 10:31:43",
    "results": [
      {
        "artist": "Alan Walker, A$AP Rocky",
        "title": "Live Fast (PUBGM)",
        "album": "Live Fast (PUBGM)",
        "score": 100,
        "song_link": "https://lis.tn/LiveFastPUBGM"
      }
    ]
  }
}

Cache the latest match per radio_id for your overlay, and append every match to a list for your play log. The now-playing widget recipe has the full callback receiver, the longpoll alternative, and a copy-paste OBS overlay.

A before callback has no play_length. AudD reports total played time only once a song finishes, so the default (after-song) callback carries play_length and before does not. For a live display that’s fine; for a precise play-duration log, use the default callback timing instead.

Related