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.
``bash
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.
`js
const { ForgeMusic } = require("@tryforge/forge.music");
`
As it is required, now you are allowed to create an instance of it.
`js
const music = new ForgeMusic({
events: []
});
`
Now, extension is defined and ready to be attached to the client.
`js
const client = new ForgeClient({
extensions: [music],
// ...client options
});
`
> [!CAUTION]
> Your ForgeClient instance requires the following intent in order for ForgeMusic to work: GuildVoiceStates.

$3

ForgeMusic provides a simple interface to declare the events to listen to.
First, we need to require the GuildQueueEvent enumerator.
`js
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.
`js
const music = new ForgeMusic({
events: [
GuildQueueEvent.PlayerFinish,
GuildQueueEvent.PlayerStart,
GuildQueueEvent.PlayerError,
GuildQueueEvent.Error
]
});
`
Current setup must look like this.
`js
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

$3

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.
`js
// 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[]](https://discord-player.js.org/docs/discord-player/type/PCMFilters)
- newFilters: [PCMFilters[]](https://discord-player.js.org/docs/discord-player/type/PCMFilters)
- EmptyChannel
- queue: GuildQueue
- EmptyQueue
- queue: GuildQueue
- EqualizerUpdate
- queue: GuildQueue
- oldFilters: [EqualizerBand[]](https://discord-player.js.org/docs/%40discord-player%2Fequalizer/type/EqualizerBand)
- newFilters: [EqualizerBand[]](https://discord-player.js.org/docs/%40discord-player%2Fequalizer/type/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
`js
{
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

$3

The base framework provides some base music sources you can use. You must load them like follows.
`js
const { DefaultExtractors } = require("@tryforge/forge.music");
const music = new ForgeMusic({
// ...
includeExtractors: DefaultExtractors
});
`

$3

ForgeMusic by default does not provide support for streaming from YouTube.
You must install discord-player-youtubei and then require YoutubeiExtractor from it.
`bash
npm install discord-player-youtubei
`
then, do the following step.
`js
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.
`js
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.