ForgeMusic

An standard music library tailored for ForgeScript.

---

Features

• Easy to use API.
• Various amount of events.
• Support for various filters.
• Support for most audio providers.

---

Contents

1. Installation
2. Setup
   1. Listening Events
      1. Disallowed Events
   2. Commands
      1. Event Data: Types and Interfaces
         1. Example
3. Advices
4. Tips
   1. Adding support for YouTube
5. Contributors

---

Installation

In your project, navigate to your terminal and write the following command.

npm install @tryforge/forge.music

If you are using another package manager than npm, Google how to install Node.js dependencies.

---

Setup

Now, you must require the ForgeMusic class in your main file.

const { ForgeMusic } = require("@tryforge/forge.music");

As it is required, now you are allowed to create an instance of it.

// Without options.
const music = new ForgeMusic();

// With options.
const music = new ForgeMusic({
    events: []
});

Now, extension is defined and ready to be attached to the client.

const client = new ForgeClient({
    extensions: [music],
    // ...client options
});

Caution

Your ForgeClient instance requires the following intent in order for ForgeMusic to work: GuildVoiceStates.

Listening Events

ForgeMusic provides a simple interface to declare the events to listen to. First, we need to require the GuildQueueEvent enumerator.

const { ForgeMusic, GuildQueueEvent } = require("@tryforge/forge.music");

As it is required, now you must pass an array of values of this enumerator under events property in ForgeMusic constructor.

const music = new ForgeMusic({
    events: [
        GuildQueueEvent.PlayerFinish,
        GuildQueueEvent.PlayerStart,
        GuildQueueEvent.PlayerError,
        GuildQueueEvent.Error
    ]
});

Current setup must look like this.

const { ForgeMusic, GuildQueueEvent } = require("@tryforge/forge.music");
const music = new ForgeMusic({
    events: [
        GuildQueueEvent.PlayerFinish,
        GuildQueueEvent.PlayerStart,
        GuildQueueEvent.PlayerError,
        GuildQueueEvent.Error
    ]
});

const client = new ForgeClient({
    extensions: [music],
    // ...client options
});

Disallowed Events

The following events are not supported by the extension.

• VoiceStateUpdate
• WillAutoPlay
• WillPlayTrack

Commands

To add event commands, ForgeMusic provides an integrated command manager to take care of this. You must define your commands after your ForgeClient definition to prevent errors.

// Adding directly.
music.commands.add({
    name: "commandName",
    type: GuildQueueEvent.PlayerStart,
    code: "$log[A track started playing.]"
});

// Loading from a path tree.
music.commands.load("./path/to/commands");

Event Data: Types and Interfaces

In each music event, you can access to that event data using the JSON Dump ($env). The following, is a list of event with its accessible properties.

• AudioFiltersUpdate
  • queue: GuildQueue
  • oldFilters: FiltersName
  • newFilters: FiltersName
• AudioTrackAdd
  • queue: GuildQueue
  • track: Track
• AudioTrackRemove
  • queue: GuildQueue
  • track: Track
• BiquadFiltersUpdate
  • queue: GuildQueue
  • oldFilters: BiquadFilters
  • newFilters: BiquadFilters
• ChannelPopulate
  • queue: GuildQueue
• Connection
  • queue: GuildQueue
• ConnectionDestroyed
  • queue: GuildQueue
• Debug
  • queue: GuildQueue
  • message: string
• Disconnect
  • queue: GuildQueue
• DSPUpdate
  • queue: GuildQueue
  • oldFilters: PCMFilters[]
  • newFilters: PCMFilters[]
• EmptyChannel
  • queue: GuildQueue
• EmptyQueue
  • queue: GuildQueue
• EqualizerUpdate
  • queue: GuildQueue
  • oldFilters: EqualizerBand[]
  • newFilters: EqualizerBand[]
• Error
  • queue: GuildQueue
  • error: Error
• PlayerError
  • queue: GuildQueue
  • error: Error
  • track: Track
• PlayerFinish
  • queue: GuildQueue
  • track: Track
• PlayerPause
  • queue: GuildQueue
• PlayerResume
  • queue: GuildQueue
• PlayerSkip
  • queue: GuildQueue
  • track: Track
  • reason: TrackSkipReason
  • description: string
• PlayerStart
  • queue: GuildQueue
  • track: Track
• PlayerTrigger
  • queue: GuildQueue
  • track: Track
  • reason: PlayerTriggeredReason
• QueueCreate
  • queue: GuildQueue
• QueueDelete
  • queue: GuildQueue
• VolumeChange
  • queue: GuildQueue
  • oldVolume: number
  • newVolume: number

Example

{
    name: "myCommand",
    type: GuildQueueEvent.PlayerStart,
    code: "$!sendMessage[$env[queue;metadata;text;id];A track started playing.]"
}

Advices

• You must add the following events to the extension in order to work properly.
  • GuildQueueEvent.Error
  • GuildQueueEvent.PlayerError

Tips

Adding Support for YouTube

ForgeMusic by default provides support for streaming from YouTube, but the native method is not stable as intended. For this, you must omit the registration of the default YouTube Extractor by doing the following step. You must install discord-player-youtubei and then require YoutubeiExtractor from it.

npm install discord-player-youtubei

then, do the following step.

const { ForgeMusic, GuildQueueEvent } = require("@tryforge/forge.music");
const { YoutubeiExtractor } = require("discord-player-youtubei");
const music = new ForgeMusic({
    events: [
        GuildQueueEvent.AudioTrackAdd,
        GuildQueueEvent.Connection,
        GuildQueueEvent.PlayerError,
        GuildQueueEvent.Error
    ],
    extractorsLoadFilter: (extractor) => extractor !== "YouTubeExtractor"
});

With the previous step done, register the YoutubeiExtractor into the extension registry.

music.player.extractors.register(YoutubeiExtractor, {});

And now, you're ready to use YouTube provider as smooth as possible.

Contributors

Many thanks for the contributors for making this extension the best choice out there.