franciscosbf/icebeat repository overview

⁠🧊 IceBeat

A music player Discord bot powered by Lavalink⁠.

1. Commands⁠
   1.1. Bot Owner⁠
   1.2. Server Related⁠
   
2. Configuration Description & Example⁠
   
3. Running With Docker⁠
   3.1. Docker Compose Example⁠
   
4. Manual Database Setup⁠
   

⁠Commands

There're two command groups. Owner commands are restricted to the bot operator, while the remaining ones are installed on whitelisted servers. In short, the sole purpose of whitelisting a server is to restrict the computing resources demanded by the bot, as it targets environments where hardware is a limiting factor (e.g., Raspberry PI).

⁠Bot Owner

Bot Owner commands are used to manage the whitelist and can only be executed via direct messages.

Issuing /whitelist without additional parameters lists the subcommands described above. <server> parameter can be either the server name or ID (the latter is preferred).

⁠Server Related

There's a subset of commands that only the server owner and members of an assigned role are allowed to execute: /shuffle, /loop, /volume, /filter, /presence stay and /presence leave. Apart from those, /staff set and /staff unset let the server owner to register or remove such role. If a role isn't defined, only the server owner can execute the restricted commands.

• /play Requests something to play
  • Arguments
    • query Youtube/Spotify link or normal search as if you were on YouTube; it supports autocompletion when searching (links are ignored by this little feature)
• /stop Stops the player
• /resume Resumes the player
• /skip Skips the current track
• /peek Removes enqueued track and starts playing it
  • Arguments
    • track track position in queue; autocompletion will display the track name after entering the position or search name result
• /move Changes track position in queue
  • Arguments
    • from current track position in queue; autocompletion will display the track name after entering the position or search name result
    • to queue position where the track should be moved.
• /jump Skips to a queued track
  • Arguments
    • position track position in queue; autocompletion will display the track name after entering the position or search name result
• /pop Removes track from queue
  • Arguments
    • position track position in queue; autocompletion will display the track name after entering the position or search name result
• /seek Seeks to a given position in the track
  • Arguments
    • position track position like in the YouTube video player, for example 5:38
• /current Displays current track
• /queue Lists queued tracks
• /clear Removes all queued tracks
• /leave Disconnects the bot from the voice channel
• /shuffle Toggles queue's shuffle mode
• /loop Toggles queue's loop mode
• /volume Changes player volume
  • Arguments
    • level volume level (the higher, the worst); only allows values between 0 and 100, included
• /filter Sets player filter
  • Arguments
    • name filter name; allowed values: normal, bassboost, pop, soft, treblebass, eightd, karaoke, vaporwave and nightcore
• /presence Changes player volume
  • Subcommands
    • stay Bot won’t leave the voice channel when the queue's empty
    • leave Bot will leave the voice channel when the queue's empty
• /staff Changes player volume
  • Subcommands
    • set Sets staff role
      • Arguments
        • role staff role
    • unset Removes staff role (only the server owner will be allowed to configure the player)
    • commands Lists staff commands
• /player Displays player info

⁠Configuration Description & Example

Configuration is written using the INI file⁠ format.

[bot]
# Discord token
token = token code
# Bot description displayed in its profile
description = anything you want
# Bot activity displayed in its profile
activity = anything you want

[player]
# Max number of enqueued tracks
queue_size = 100

[lavalink]
# Node name
name = anything you want
# Node host
host = localhost
# Node port
port = 2333
# Node password
password = str
# Node region code to assign
region = str

[database]
# SQLite file
uri = icebeat.db

[cache]
# Max number of cached entries
entries = 100
# Time to live in seconds per cache entry
ttl = 3600

[commands]
# Number of command calls per second before triggering cooldown
coolwdown_rate = 10
# Commands cooldown in secconds
cooldown_time = 10

Command cooldown is applied per server. Therefore, calling different commands by multiple users in a short period of time may trigger cooldown.

⁠Running With Docker

Fetch the image by executing:

docker push franciscosbf/icebeat:latest

Don't forget to mount the required configuration and database volumes under the /bot path. See Docker Compose Example⁠ below.

⁠Docker Compose Example

services:
  icebeat:
    image: franciscosbf/icebeat:latest
    container_name: icebeat
    restart: unless-stopped
    volumes:
      - ./config.ini:/bot/config.ini
      - ./icebeat.db:/bot/icebeat.db
# From now on, this is just meant to showcase how
# you can configure Lavalink with Docker Compose.
    networks:
      - bot
    depends_on:
      - lavalink
  lavalink:
    image: ghcr.io/lavalink-devs/lavalink:4-alpine
    container_name: lavalink
    restart: unless-stopped
    environment:
      - _JAVA_OPTIONS=-Xmx512M
    volumes:
      - ./application.yml:/opt/Lavalink/application.yml
      - ./plugins/:/opt/Lavalink/plugins/
    networks:
      - bot
networks:
  bot:
    name: bot

For more information on running Lavalink with Docker Compose, see the guide here⁠.

⁠Manual Database Setup

Database migrations located in db/migrations are required to create the tables. The setup below uses migrate⁠ to write tables to an empty file. In order to use migrate with the SQLite driver, you need to have a Go⁠ compiler installed.

# migrate installation
go install -tags 'sqlite' github.com/golang-migrate/migrate/v4/cmd/[email protected]

# Create database file
touch icebeat.db

# Create tables
migrate -source file://db/migrations -database sqlite://icebeat.db up

# Remove tables
migrate -source file://db/migrations -database sqlite://icebeat.db down