Audiq

A Discord music suggestion bot with slash commands, auto-generated song cards and multi-language support.

Table of Contents

1. About The Project
2. Features
3. Getting Started
   • Prerequisites
   • Installation
4. Docker Deployment
5. Configuration
6. Commands
7. Localization
8. Credits
9. License

About The Project

Audiq is a Discord bot built for music communities. It lets users suggest songs via slash commands, generates attractive card previews for each suggestion, and posts them into a configured channel.

The bot uses a centralized dictionary for all user-facing text, making it easy to add new languages and keep command descriptions, replies, and error messages in one place.

Audiq currently supports the following streaming and music content platforms:

• Spotify
• YouTube
• YouTube Music
• SoundCloud

(back to top)

Features

• Global slash command registration for Discord
• Dynamic language selection through environment variables
• Centralized text dictionary (src/config/dictionary.json)

(back to top)

Getting Started

Prerequisites

• Node.js (v18+ recommended)
• npm

Installation

1. Clone the repository:

   git clone https://github.com/estaniel/discord-music-suggest-bot.git
   cd discord-music-suggest-bot

2. Install dependencies:

   npm install

3. Create a Discord application and bot:

   • Open the Discord Developer Portal
   • Click New Application
   • Go to Bot, click Add Bot
   • Copy the bot token for the next step

4. Create a .env file in the project root:

   DISCORD_TOKEN=your_bot_token_here
   CLIENT_ID=your_application_client_id_here
   LANGUAGE=en_US

5. Invite the bot to your server:

   • In the Developer Portal, go to OAuth2 > URL Generator
   • Select scopes: bot, applications.commands
   • Select bot permissions: View Channels, Send Messages, Manage Channels (optional for setup checks)
   • Use the generated URL to add the bot to your server

6. Deploy slash commands globally:

   npm run deploy

7. Start the bot:

   npm start

Docker Deployment

If you prefer to run Audiq with Docker, this repository includes a Dockerfile and docker-compose.yml.

1. Make sure you have a .env file in the project root with the required values.
2. Build the Docker image:

   docker build -t audiq .

3. Start the container:

   docker compose up -d --build

The compose setup mounts ./src/config into the container so src/config/data.json is persisted on the host.

To stop the bot:

docker compose down

(back to top)

Configuration

The bot stores the configured music channel in src/config/data.json after /setup is run.

Use /setup channel:#your-channel to set the destination channel for suggestions.

If src/config/data.json does not exist, it will be created automatically.

(back to top)

Commands

• /setup channel:#channel

  • Configures the channel where suggestion cards will be posted.
  • Requires the user to have MANAGE_CHANNELS permission.

• /suggest link:<song-url> [vote:true/false]

  • Suggests a song by URL or link.
  • Generates a visual song card and posts it to the configured channel.
  • Optional vote parameter: when set to true (default), adds a 💎 reaction to the suggestion card for voting/rating.

• /ping

  • Replies with the current Discord API latency.

• /help

  • Shows the list of available slash commands.

(back to top)

Localization

Audiq supports multiple languages through the LANGUAGE environment variable.

Example:

LANGUAGE=es_UY npm start

The default value is en_US. The current dictionary file is located at src/config/dictionary.json and includes:

• en_US — English
• es_UY — Uruguayan Spanish

You can add additional locales by extending this JSON file and using the new language code in the environment.

(back to top)

Credits

This project is built with:

• discord.js for Discord bot interactions
• dotenv for environment variable management
• node-html-to-image for generating PNG cards
• colorthief for palette extraction
• play-dl for music metadata extraction
• soundcloud-scraper for SoundCloud support
• sharp for image processing dependencies

Special thanks to the open source community for the tools and libraries that make this possible.

(back to top)

License

Distributed under the MIT License. See LICENSE.txt for more information.

(back to top)