@tryforge/forge.music

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

• Installation
• Setup
  • Listening Events
    • Disallowed Events
  • Commands
    • Event Data: Types and Interfaces
      • Example
• Advices
• Tips
  • Adding support for YouTube
• 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.