Mirasaki Music Bot

A free, open-source JavaScript music bot created with discord.js and discord-player. Complete (45+ commands) with persistent settings, effects, filters, auto-play, DJ-roles, and so much more.

SoundCloud • Apple Music • Vimeo • ReverbNation • Discord Attachments

⭐ It's free, open-source, and self-host - meaning you're in full control

This project was created and open-sourced by Mirasaki Development. That means it's publicly available for anyone to grab and use in any way you want (MIT licensed). This project will never be monetized, every feature will always be free. All we need to keep adding new functionality and modules is some GitHub stars. Join the absolute legends below by clicking that Star button in the top-right of your screen, it doesn't cost you anything and means the world to us ❤️

📜 Table of Contents

• Showcase
• Features
• Demo
• Installation & Usage
  • Prerequisites
  • Docker
  • Node
• Configuration
• Discord Permissions
• Client Permissions
• Support
• Legal Notice

🎥 Showcase

Click to view

Note: We no longer support YouTube and Spotify due to their Terms of Service. We have a TypeScript rewrite planned that will focus heavily on local media libraries and playlists. Please don't create support inquiries for YouTube and Spotify streaming.

🤩 Features (non-exhaustive)

• Easy installation
• Settings with persistency
• 60+ total audio filters
• Multiple server support
• Vote skip
• Search, play, and lyrics autocomplete enabled
• Search play buttons
• DJ Roles
• Dedicated music channels
• Thread sessions
• Auto-play (24/7)
• Biquad filter + Equalizer
• 4 Repeat/loop modes
• Full track history
• Slash commands and modern Discord components
• Lyrics
• Volume (persistent)
• Full playback control
  • with over 20 player-control commands like
  • /pause
  • /skip-to
  • /swap-songs
  • and so much more
• Save songs by sending it to your DMs

🎁 Demo

Don't take our word for it, though. Instead, you should just see for yourself in our support server.

🔨 Installation & Usage

Prerequisites

• FFmpeg or Avconv
  • Windows: download source
  • Linux: packages
  • macOS: static builds
  • Directly supported through Docker
  • If you're having trouble installing FFmpeg, you can try ffmpeg-static, by running npm install ffmpeg-static - this is a last resort and not recommended - we do NOT provide support for this!
• A Discord Bot account
  1. Head over to the page linked above
  2. Click "New Application" in the top right
  3. Give it a cool name and click "Create"
  4. Click "Bot" in the left hand panel
  5. Click "Add Bot" -> "Yes, do it!"
  6. Click "Reset Token" and copy it to your clipboard, you will need it later
• NodeJS (if you're running as a plain NodeJS app)
  1. Head over to the download page
  2. Download the latest LTS build available for your OS
  3. Be sure to check the box that says "Automatically install the necessary tools" when you're running the installation wizard

Run as a Docker container (preferred)

The quickest and easiest way to host/use this bot is by deploying it inside of a Docker container.

A docker compose file is included for your convenience

1. Clone this repository: git clone https://github.com/Mirasaki/mirasaki-music-bot.git
2. Navigate inside the new folder: cd mirasaki-music-bot
3. Rename /.env.example to .env and provide your environmental variables
   • Windows users often experience issues with this file, if you're getting errors that the env file can't be found, or Expected path argument to be of type string - check out this timestamped video
4. Rename /config.example.js to config.js (required) and go through your bot configuration (optional)
5. Build the project: docker build --tag mirasaki-music-bot .
6. Start the bot: docker run -it --env-file .env --name my-mirasaki-music-bot mirasaki-music-bot

Run as a plain NodeJS app

You can also clone this repository or download a release, and host the project directly. You will need Node/NodeJS (Be sure to check the box that says "Automatically install the necessary tools" when you're running the installation wizard)

1. Head over to the download page
   • Alternatively, clone this repository by using git clone https://github.com/Mirasaki/mirasaki-music-bot.git and skip to step 4 if you have Git installed
2. Download either the zip or zip.gz source code
3. Extract it using your favorite zip tool
4. Open a new console/terminal/shell window in the newly created project folder
5. Run npm install to install all dependencies
6. Rename /.env.example to .env and configure your environmental variables
   • Windows users often experience issues with this file, if you're getting errors that the env file can't be found, or Expected path argument to be of type string - check out this timestamped video
7. Rename /config.example.js to config.js (required) and go through your bot configuration (optional)
8. Use the command node . to start the application, or alternatively:
   • npm run pm2:start to keep the process alive in the background with PM2, suitable for production environments. (npm i -g pm2 to install)
   • npm run start:dev if you have nodemon installed for automatic restarts on changes, suitable for development environments

🛠️ Configuration (optional - alternatively configurable with commands)

All configuration is done in /config.js. Multiple Discord servers are supported. The configuration file is created during the installation and usage steps. Below is detailed information on what the settings do.

{
  // Note: all the default# properties all configurable by commands
  // This is here so that you can configure everything in one go
  // without having to figure out different commands,
  // if you're not comfortable editing this, use the commands

  // Note: default# properties only take affect the first time
  // playback is initialized in your server/guild

  // Between 0 and 100
  // 100 is obnoxiously loud and will f*** your ears
  defaultVolume: 5,

  // The default repeat mode
  // 0 - Off | Don't repeat
  // 1 - Track | Repeat current track, always - until skipped
  // 2 - Queue | Repeat the entire queue, finished songs get added back at the end of the current queue
  // 3 - Autoplay | Autoplay recommended music when queue is empty
  //
  // 3 = 24/7 autoplay/continuous radio if uninterrupted - only use if you have
  // bandwidth for days
  defaultRepeatMode: 0,

  // Amount of seconds to stay in the voice channel
  // when playback is finished
  // Default: 2 minutes
  defaultLeaveOnEndCooldown: 120,

  // Should the bot leave the voice-channel if there's no other members
  defaultLeaveOnEmpty: true,

  // Time amount of seconds to stay in the voice channel
  // when channel is empty/no other members aside from bot
  // Only active when leaveOnEmpty is true
  // Default: 2 minutes
  defaultLeaveOnEmptyCooldown: 120,

  // When true, will create a thread when the voice session is first initialized
  // and continue to send music/queue events in that thread instead of flooding
  // the channel
  defaultUseThreadSessions: true,

  // When true, and defaultUseThreadSessions is true, will only allow commands involving
  // the current session to be used in the created session Thread channel
  defaultThreadSessionStrictCommandChannel: true,

  // Plugins/Music source extractors
  plugins: {
    fileAttachments: true,
    soundCloud: true,
    appleMusic: true,
    vimeo: true,
    reverbNation: true,
  },

  // Bot activity
  presence: {
    // One of online, idle, invisible, dnd
    status: 'online',
    activities: [
      {
        name: '/play',
        // One of Playing, Streaming, Listening, Watching
        type: 'Listening'
      }
    ]
  },

  // Permission config
  permissions: {
    // Bot Owner, highest permission level (5)
    ownerId: '290182686365188096',

    // Bot developers, second to highest permission level (4)
    developers: [ '' ]
  },

  // The Discord server invite to your Support server
  supportServerInviteLink: 'https://discord.gg/mirasaki',

  // Additional permissions that are considered required when generating
  // the bot invite link with /invite
  permissionsBase: [
    PermissionsBitField.Flags.ViewChannel,
    PermissionsBitField.Flags.SendMessages,
    PermissionsBitField.Flags.SendMessagesInThreads
  ]
}

🟣 Discord Permissions

This is not the permission level required to execute actions or run commands, like User, Moderator or Administrator

Invite the bot to your server by navigating to the following URL (replace YOUR_CLIENT_ID with DISCORD_CLIENT_ID from the /.env file):

https://discord.com/api/oauth2/authorize?client_id=YOUR_CLIENT_ID&permissions=0&scope=bot%20applications.commands

Any command can be used without any Discord permissions, as long as the bot is invited to your server with the bot and applications.commands scopes. You can use the template url above, or alternatively, generate an invite link in the Discord Developer Portal (Your App > OAuth2 > URL Generator > scopes: bot + applications.commands)

For the bot to be able to join your Voice Channel, it will need the View Channel, Connect and Speak permissions.

The bot needs the View Channel, Send Messages, and Embed Links in any channel where playback is initialized to be able to send event notifications to that channel.

🟢 Client Permissions

These are permission levels that are used internally by the bot to determine the permission level of any given user and determine which commands they can use. Available permissions levels are:

You can modify Moderators, Administrators, Developers and Bot Owners in /config.js, this is optional

• 0 - User - This is the default permission levels, everyone has this this - doesn't have access to any dangerous commands
• 1 - Moderator - Unused in this bot. Anyone that has the Discord permissions Kick Members and Ban Members is considered a Moderator
• 2 - Administrator - The Administrator permission level is the highest permission level that can be assigned through Discord. Anyone with the Discord permission Administrator is considered an Administrator internally and will have access to powerful commands like /clear-queue
• 3 - Server Owner - This is the permission level of your Discord server owner, only 1 person can have this at any given time. Used to make sure server owners have a snowflake permission level internally 🙏 Doesn't currently have any exclusive commands, but you can choose to restrict commands to this permission level as needed
• 4 - Developer - This is for members that develop on the bot, has access to dev utilities like /eval and /exec. This permission level can do almost everything, including evaluating arbitrary code on your host machine - use with caution!
• 5 - Bot Owner - Bypasses every permission bit and level check, has access to every command and command.

You can modify required permission levels to execute commands in the command files by setting the permLevel property. Let's take a look at an example /src/commands/ file:

module.exports = new ChatInputCommand({
  // Inside of the ChatInputCommand({
  // Can be set to User, Moderator, Administrator, Server Owner, Developer, Bot Owner
  // Support IntelliSense/auto-complete
  permLevel: 'Administrator',
  // ... other properties
  run: async (client, interaction) => {
    // The commands #run/execute function
  }
});

Support

Join our support server if you need any further assistance, have feature suggestion or have any other feedback

Open source, self-hosted, and MIT licensed, meaning you're in full control.