Run the AudD Discord bot (deploy the official template)

AudD maintains an open-source Discord bot in Go, AudDMusic/DiscordBot. It identifies music from replied-to files and links, from a right-click menu action, and from live voice channels. This page is the operational path: clone it, configure two tokens, run it, invite it to a server, and keep it running on a small host.

This is the deploy-the-template route. If you want to build your own bot from scratch — to understand the audio capture, customize the commands, or write it in Node — follow Build a Discord bot that identifies songs in voice channels instead. That recipe teaches the moving parts; this page just gets the official bot live.

What you’ll deploy

A single Go binary that logs into Discord as your bot user and listens for a handful of triggers. When a trigger fires, it pulls the audio (from an attached file, a linked URL, or a live voice channel), sends it to AudD’s recognition API, and replies in the channel with the artist, title, and a shareable link.

The moving parts are:

The binary — built from the repo, runs as a long-lived process.
config.json — your Discord bot token, Discord application ID, and AudD api_token.
A Discord application — created in the Developer Portal, with the right intents and an invite link to your server.
A host — anywhere that keeps the process up: a small VPS, a container, or your own machine for testing.

The recognition call is AudD’s; everything else is Discord plumbing the bot already handles for you.

Prerequisites

An API token from dashboard.audd.io. The first 300 requests are free. Each recognition the bot performs spends one request.
A Discord application and bot token from the Discord Developer Portal.
The application’s Client ID (also called the application ID).
Go 1.21+ installed, to build the binary — or grab a precompiled binary from the repo’s GitHub Actions artifacts if you’d rather not build.
ffmpeg available on the host — the bot shells out to it to handle audio.
A host that can keep a process running.

Walkthrough

Step 1: Create the Discord application

In the Discord Developer Portal:

New Application, give it a name.
Open the Bot tab, Add Bot, and copy the token: this is your DiscordToken. Keep it secret; treat it like a password.
Still on the Bot tab, enable the Message Content Intent. The bot reads the content of messages it’s asked to identify, so this privileged intent is required.
Copy the Application ID (Client ID) from the General Information tab: this is your DiscordAppID.

The Message Content Intent is required. Without it, the bot can’t read the message you reply to and won’t see attached files or links. Enable it on the Bot tab before you invite the bot anywhere.

Step 2: Clone and configure

Clone the repo and create the config file. The bot reads a config.json next to the binary.

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

Create config.json with your three values:

{
  "AudDToken": "your-api-token",
  "DiscordToken": "your-discord-bot-token",
  "DiscordAppID": "your-discord-application-id"
}

AudDToken — your AudD api_token from the dashboard. Every recognition the bot does authenticates with this.
DiscordToken — the bot token from the Developer Portal’s Bot tab.
DiscordAppID — the application’s Client ID, used to register the slash commands.

The repo’s example config carries a few extra keys for advanced use — a server bind address and a SECRET_CALLBACK_TOKEN used when wiring up stream callbacks. You don’t need those for the basic identify-on-demand setup; the three keys above are enough to run the bot.

Step 3: Build and run

Build the binary and start it:

go build -v ./...
./discordBot

On a clean start the bot logs in to Discord and registers its slash commands. Leave the process running — it’s a daemon, not a one-shot.

If you’d rather not build, download a precompiled binary from the repo’s GitHub Actions artifacts, drop your config.json next to it, and run the binary directly.

Step 4: Invite the bot to a server

The bot has to be a member of your server before it can respond. Build an invite URL with your Client ID and the permissions it needs, then open it and pick a server you manage.

https://discord.com/api/oauth2/authorize
  ?client_id=YOUR_CLIENT_ID
  &scope=bot+applications.commands
  &permissions=3145728

scope=bot+applications.commands — both the bot membership and the slash commands.
The bot needs Connect and Speak voice permissions to join and record voice channels, plus the ability to read and send messages in the text channels where people will summon it. Adjust the permissions value in the portal’s OAuth2 URL generator to match what you want it to do.

Step 5: Use it

Once the bot is in your server, it responds to several triggers:

Reply with !song to a message that has an audio or video attachment, or a link — the bot identifies the music in it and replies.
Right-click a message → Apps → “Recognize This Song” — the menu action, the same recognition without typing a command.
!song @mention or the /song-vc slash command — the bot joins the voice channel you’re in, captures a few seconds, and identifies what’s playing.
!listen or the /listen slash command — the bot stays in the voice channel and keeps identifying songs as they play.
!here — prints the text channel IDs the bot can see, useful when setting up where it should post.

A successful identification posts the artist, title, and a shareable link. When nothing is recognized — a clip that’s mostly speech, or silence — the bot says so rather than erroring.

Hosting it

The bot is one long-running process. Anything that keeps a process up works.

A small VPS

Build (or copy a precompiled binary) onto the box, put config.json next to it, and run it under a process supervisor so it restarts on crash or reboot. A minimal systemd unit:

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

[Service]
WorkingDirectory=/opt/audd-discord
ExecStart=/opt/audd-discord/discordBot
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

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

Make sure ffmpeg is installed on the host (apt install ffmpeg on Debian / Ubuntu).

A container

Build the binary in one stage and run it on a small base image that already has ffmpeg. Mount or bake in the config.json, or supply the three values however your platform injects config. Keep one replica — running two copies of the same bot token causes Discord to fight over the gateway connection.

Run exactly one instance per bot token. Discord allows one gateway connection per bot. A second copy of the same DiscordToken causes both to disconnect and reconnect in a loop. Scale by sharding (a Discord concept), not by starting a second unsharded process with the same token.

Keeping it up

Restart on failure. Restart=always (systemd) or your platform’s restart policy. The bot reconnects to Discord on its own after a transient gateway drop, but a hard crash needs the supervisor to bring it back.
Watch the logs. The process logs login, command registration, and recognition failures. Tail them when something looks wrong.
Watch your AudD usage. Every identification spends one request. A busy server with !listen running in several voice channels adds up — check usage on the dashboard if a bill surprises you.

When recognition fails

The bot surfaces the common failure modes in-channel, but it helps to know what each one means when you’re reading logs:

No match — the audio was recognized-against but nothing matched (mostly speech, silence, or a track not in the database). Not an error; the bot replies that it couldn’t identify the song.
Authentication failure — a bad or missing AudDToken. The bot can’t recognize anything; fix the token in config.json and restart.
Quota / subscription limits — you’ve hit a request limit on your AudD account. Recognitions start failing until the limit resets or you raise it on the dashboard.
Discord intent missing — if the bot can’t read message content, it sees empty messages and never finds a file or link. Re-check the Message Content Intent on the Bot tab.

Going further

Build your own instead. To understand the audio capture, change the commands, or write it in another language, work through Build a Discord bot that identifies songs in voice channels — it builds the same idea from scratch in Node with @audd/sdk.
Identify a whole DJ set, not one track. The standard recognition the bot does returns one song per clip. To turn a continuous mix into a full tracklist, the enterprise endpoint returns every song — see Turn a DJ set or mix into a tracklist.
Understand which endpoint does what. See Standard, enterprise, or streams: how to choose.

Related