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.

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

Default Extractors

The base framework provides some base music sources you can use. You must load them like follows.

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

Adding Support for YouTube

ForgeMusic by default does not provide support for streaming from YouTube. You must install discord-player-youtubei and then require YoutubeiExtractor from it.

npm install discord-player-youtubei

then, do the following step.

const { DefaultExtractors, 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
    ],
    includeExtractors: DefaultExtractors
});

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.