Run a Reddit music-recognition bot (the AudD RedditBot template)

AudD runs u/auddbot, a Reddit bot that answers “what’s this song?” on posts and comments by recognizing the music in linked videos and livestreams. The bot is open source in Go at AudDMusic/RedditBot. This page explains how the bot works and how to deploy your own instance: clone it, configure your Reddit API credentials and AudD token, run it, and host it.

This is a deploy-the-template page, not a build-from-scratch tutorial. It points you at the official bot and the config it expects, and explains the one AudD concept that matters for it: why linked Reddit media goes to the enterprise endpoint, not the standard one.

How the bot works

The bot is a long-running process that watches Reddit and reacts to summons. The loop is:

Watch comments and mentions. The bot streams new comments (and replies to its username) across the subreddits it operates on. It matches each one against a configurable list of Triggers — phrases like “what’s the song” — and ignores anything matching its AntiTriggers.
Find the media. When a comment triggers, the bot resolves the media URL to recognize: the linked video, the post’s media, or a livestream URL associated with the thread.
Send it to AudD. It posts that media URL to AudD’s recognition API, which fetches and fingerprints the audio.
Reply with the result. On a match it replies in-thread with the song — artist, title, and a link. It applies score gates (CommentsMinScore, LiveStreamMinScore) so it only answers when confident, and stays quiet otherwise.

The recognition step is the only AudD call. Everything around it — streaming comments, parsing triggers, posting replies — is Reddit API work the bot already implements.

Reddit media is usually long, so the bot leans on the enterprise endpoint. A standard recognition call is for a short audio clip with a 10 MB cap. A linked Reddit video or a livestream is arbitrary length, so the enterprise endpoint is the right tool: it chunks the media server-side and finds the song inside it. See Standard, enterprise, or streams: how to choose.

What you’ll deploy

A single Go binary, configured with a config.json, that logs into Reddit as your bot account and runs the watch-trigger-recognize-reply loop above. You supply Reddit API credentials, an AudD api_token, and the lists of triggers and subreddits the bot should operate on.

Prerequisites

An API token from dashboard.audd.io. The enterprise endpoint must be enabled on your account for the bot to recognize long linked media — contact [email protected] if you’re unsure whether it’s on.
A Reddit account for the bot to post as.
A Reddit “script” app registered at reddit.com/prefs/apps, which gives you a client ID and client secret.
Go 1.21+ to build the binary.
A host that keeps a process running.

Walkthrough

Step 1: Register a Reddit app

At reddit.com/prefs/apps, create an app of type script. Reddit gives you:

a client ID (the short string under the app name),
a client secret.

You’ll also need the bot account’s username and password, and a descriptive user agent string (Reddit requires a unique, identifying user agent on every request — something like reddit-music-bot/1.0 by u/your-bot-account).

Use a unique, honest user agent. Reddit rate-limits and blocks generic or spoofed user agents aggressively. Set UserAgent to a string that names your bot and your contact; vague or borrowed user agents get throttled.

Step 2: Clone and configure

Clone the repo and fill in its config.json.

git clone https://github.com/AudDMusic/RedditBot
cd RedditBot

The config carries the Reddit credentials, the AudD token, and the behavior knobs. The keys that matter for a basic deployment:

{
  "ClientID": "your-reddit-client-id",
  "ClientSecret": "your-reddit-client-secret",
  "UserAgent": "reddit-music-bot/1.0 by u/your-bot-account",
  "BotPasswords": { "your-bot-account": "your-bot-password" },
  "AudDToken": "your-api-token",
  "Triggers": ["whats the song", "what is the song", "what's that song"],
  "AntiTriggers": ["has been automatically removed"],
  "CommentsMinScore": 0,
  "LiveStreamMinScore": 0,
  "IgnoreSubreddits": [],
  "SubredditsBannedOn": []
}

ClientID, ClientSecret, UserAgent — your Reddit script-app credentials and identifying user agent.
BotPasswords — an object keyed by bot account username, with that account’s password as the value. The bot signs in as these accounts to post replies.
AudDToken — your AudD api_token. Every recognition authenticates with it.
Triggers / AntiTriggers — the phrases that summon the bot and the phrases that suppress it. Tune these to your community’s language.
CommentsMinScore / LiveStreamMinScore — the minimum match score the bot requires before it replies, separately for recognitions from regular media and from livestreams. Raise these to make the bot quieter and more conservative. See Choosing a score threshold.
IgnoreSubreddits / SubredditsBannedOn — subreddits the bot stays out of.

The config also has operational keys for the public deployment — MaxTriggerTextLength, ReplySettings, ApprovedOn, DontPostPatreonLinkOn, DontUseFormattingOn, and a RavenDSN for error reporting. The defaults are fine for your own instance; leave them unless you have a reason to change them.

Step 3: Build and run

go build -v ./...
./RedditBot

The bot authenticates to Reddit, starts streaming comments, and begins answering triggers in the subreddits it’s allowed to operate on. Leave the process running — it’s a daemon.

A useful first test: from your bot account or a test account, post a comment matching one of your Triggers as a reply to a post that links a video with music. The bot should resolve the video URL, recognize it, and reply with the song within a few seconds to a minute, depending on the media length.

Hosting it

The bot is one long-running process. Keep it up the same way you’d keep any daemon up.

A small VPS

Build the binary (or copy it over), put config.json next to it, and run it under a supervisor. A minimal systemd unit:

[Unit]
Description=AudD Reddit bot
After=network-online.target

[Service]
WorkingDirectory=/opt/audd-reddit
ExecStart=/opt/audd-reddit/RedditBot
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

sudo systemctl enable --now audd-reddit
journalctl -u audd-reddit -f   # tail the logs

A container

Build the binary and run it on a small base image. Mount or inject the config.json. Run a single instance per bot account — two copies racing on the same comment stream will double-reply and burn requests recognizing the same media twice.

One instance per bot account. Two processes signed in as the same account see the same comment stream and both answer. That double-posts replies and doubles your AudD usage. If you need more throughput, partition by subreddit across instances rather than running duplicates on the same set.

Keeping it up

Restart on failure. Restart=always brings it back after a crash. The bot handles transient Reddit and network blips, but a hard crash needs the supervisor.
Respect Reddit’s rate limits. The bot paces its own calls, but an honest UserAgent and a single instance per account keep you on the right side of Reddit’s throttling. Getting rate-limited or shadow-blocked usually traces back to a generic user agent or duplicate processes.
Watch your AudD usage. Every recognition spends a request, and enterprise meters per 12 seconds of audio processed — long linked videos and livestreams cost more than a short clip. Check usage on the dashboard, and see Enterprise cost optimization for how to keep it bounded.

When recognition fails

What the bot does, and what the failure modes mean:

No match / below threshold — the media was recognized-against but nothing scored high enough (a track not in the database, or audio dominated by speech). The bot stays quiet rather than guessing. Tune CommentsMinScore / LiveStreamMinScore if it’s too quiet or too noisy.
Authentication failure — a bad or missing AudDToken. Recognitions stop working; fix the token and restart.
Enterprise not enabled — if the enterprise endpoint isn’t enabled on your account, recognizing long linked media fails with a subscription error. Email [email protected] to enable it.
Quota limits — you’ve hit a request limit on your AudD account; recognitions fail until it resets or you raise it on the dashboard.
Reddit auth / rate-limit errors — wrong credentials, a banned account, or throttling. These surface in the logs as Reddit API errors, separate from any AudD failure.

Going further

Understand the endpoint choice. Why linked media goes to enterprise and a short clip goes to standard: Standard, enterprise, or streams: how to choose.
Tune confidence. The *MinScore knobs map directly onto AudD’s match score — see Choosing a score threshold.
Keep enterprise cost bounded. Long videos and livestreams meter per 12 seconds; Enterprise cost optimization covers limit, every, and skip.

Related