Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -131,6 +131,7 @@ out

# Custom
.replit
index.js
replit.nix
__dump__
__test__
Expand Down
7 changes: 7 additions & 0 deletions .prettierignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
# Ignore artifacts:
dist
types
docs
metadata
__test__
__dump__
6 changes: 6 additions & 0 deletions .prettierrc
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
{
"trailingComma": "es5",
"tabWidth": 4,
"semi": false,
"singleQuote": true
}
163 changes: 82 additions & 81 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,131 +1,163 @@
<img src="https://i.imgur.com/Ew9MXaP.jpeg" align="right" height=100 alt="isologo" />
<img src="https://i.imgur.com/Ew9MXaP.jpeg" align="right" height=100 width=100 alt="isologo" />

# ForgeMusic
An standard music library tailored for [ForgeScript](https://npmjs.com/package/@tryforge/forgescript).

A standard music library tailored for [ForgeScript](https://npmjs.com/package/@tryforge/forgescript).

<a href="https://github.com/tryforge/ForgeDB/"><img src="https://img.shields.io/github/package-json/v/tryforge/ForgeMusic/main?label=@tryforge/forge.music&color=5c16d4" alt="@tryforge/forge.music"></a>
<a href="https://github.com/tryforge/ForgeScript/"><img src="https://img.shields.io/github/package-json/v/tryforge/ForgeScript/main?label=@tryforge/forgescript&color=5c16d4" alt="@tryforge/forgescript"></a>
<a href="https://discord.gg/hcJgjzPvqb"><img src="https://img.shields.io/discord/739934735387721768?logo=discord" alt="Discord"></a>

-----
---

## Features

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

----
---

## Contents

1. [Installation](#installation)
2. [Setup](#setup)
1. [Listening Events](#listening-events)
1. [Listening Events](#listening-events)
1. [Disallowed Events](#disallowed-events)
2. [Commands](#commands)
1. [Event Data: Types and Interfaces](#event-data-types-and-interfaces)
1. [Example](#example)
2. [Commands](#commands)
1. [Event Data: Types and Interfaces](#event-data-types-and-interfaces)
1. [Example](#example)
3. [Advices](#advices)
4. [Tips](#tips)
1. [Adding support for YouTube](#adding-support-for-youtube)
5. [Contributors](#contributors)
----
4. [Contributors](#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");
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: []
});
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**.

### Listening Events

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");
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
]
});
GuildQueueEvent.Error,
],
})
```

Current setup must look like this.

```js
const { ForgeMusic, GuildQueueEvent } = require("@tryforge/forge.music");
const { ForgeMusic, GuildQueueEvent } = require('@tryforge/forge.music')
const music = new ForgeMusic({
events: [
GuildQueueEvent.PlayerFinish,
GuildQueueEvent.PlayerStart,
GuildQueueEvent.PlayerError,
GuildQueueEvent.Error
]
});
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.

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

// Loading from a path tree.
music.commands.load("./path/to/commands");
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](https://github.com/tryforge/ForgeScript/blob/main/src%2Fnative%2Fvariable%2Fenv.ts)).
The following, is a list of event with its accessible properties.

- [AudioFiltersUpdate](https://github.com/tryforge/ForgeMusic/blob/main/src%2Fevents%2FaudioFiltersUpdate.ts)
- `queue`: [GuildQueue](https://discord-player.js.org/docs/discord-player/class/GuildQueue)
- `oldFilters`: [FiltersName](https://discord-player.js.org/docs/discord-player/type/FiltersName)
- `newFilters`: [FiltersName](https://discord-player.js.org/docs/discord-player/type/FiltersName)
- [AudioTrackAdd](https://github.com/tryforge/ForgeMusic/blob/main/src%2Fevents%2FaudioTrackAdd.ts)
- `queue`: [GuildQueue](https://discord-player.js.org/docs/discord-player/class/GuildQueue)
- `track`: [Track](https://discord-player.js.org/docs/discord-player/class/Track)
- `queue`: [GuildQueue](https://discord-player.js.org/docs/discord-player/class/GuildQueue)
- `track`: [Track](https://discord-player.js.org/docs/discord-player/class/Track)
- [AudioTrackRemove](https://github.com/tryforge/ForgeMusic/blob/main/src%2Fevents%2FaudioTrackRemove.ts)
- `queue`: [GuildQueue](https://discord-player.js.org/docs/discord-player/class/GuildQueue)
- `track`: [Track](https://discord-player.js.org/docs/discord-player/class/Track)
- `queue`: [GuildQueue](https://discord-player.js.org/docs/discord-player/class/GuildQueue)
- `track`: [Track](https://discord-player.js.org/docs/discord-player/class/Track)
- [BiquadFiltersUpdate](https://github.com/tryforge/ForgeMusic/blob/main/src%2Fevents%2FbiquadFiltersUpdate.ts)
- `queue`: [GuildQueue](https://discord-player.js.org/docs/discord-player/class/GuildQueue)
- `oldFilters`: [BiquadFilters](https://discord-player.js.org/docs/discord-player/type/BiquadFilters)
- `newFilters`: [BiquadFilters](https://discord-player.js.org/docs/discord-player/type/BiquadFilters)
- `queue`: [GuildQueue](https://discord-player.js.org/docs/discord-player/class/GuildQueue)
- `oldFilters`: [BiquadFilters](https://discord-player.js.org/docs/discord-player/type/BiquadFilters)
- `newFilters`: [BiquadFilters](https://discord-player.js.org/docs/discord-player/type/BiquadFilters)
- [ChannelPopulate](https://github.com/tryforge/ForgeMusic/blob/main/src%2Fevents%2FchannelPopulate.ts)
- `queue`: [GuildQueue](https://discord-player.js.org/docs/discord-player/class/GuildQueue)
- [Connection](https://github.com/tryforge/ForgeMusic/blob/main/src%2Fevents%2Fconnection.ts)
Expand Down Expand Up @@ -158,23 +190,23 @@ The following, is a list of event with its accessible properties.
- `track`: [Track](https://discord-player.js.org/docs/discord-player/class/Track)
- [PlayerFinish](https://github.com/tryforge/ForgeMusic/blob/main/src%2Fevents%2FplayerFinish.ts)
- `queue`: [GuildQueue](https://discord-player.js.org/docs/discord-player/class/GuildQueue)
- `track`: [Track](https://discord-player.js.org/docs/discord-player/class/Track)
- `track`: [Track](https://discord-player.js.org/docs/discord-player/class/Track)
- [PlayerPause](https://github.com/tryforge/ForgeMusic/blob/main/src%2Fevents%2FplayerPause.ts)
- `queue`: [GuildQueue](https://discord-player.js.org/docs/discord-player/class/GuildQueue)
- [PlayerResume](https://github.com/tryforge/ForgeMusic/blob/main/src%2Fevents%2FplayerResume.ts)
- `queue`: [GuildQueue](https://discord-player.js.org/docs/discord-player/class/GuildQueue)
- [PlayerSkip](https://github.com/tryforge/ForgeMusic/blob/main/src%2Fevents%2FplayerSkip.ts)
- `queue`: [GuildQueue](https://discord-player.js.org/docs/discord-player/class/GuildQueue)
- `track`: [Track](https://discord-player.js.org/docs/discord-player/class/Track)
- `reason`: [TrackSkipReason]()
- `description`: string
- `track`: [Track](https://discord-player.js.org/docs/discord-player/class/Track)
- `reason`: [TrackSkipReason]()
- `description`: string
- [PlayerStart](https://github.com/tryforge/ForgeMusic/blob/main/src%2Fevents%2FplayerStart.ts)
- `queue`: [GuildQueue](https://discord-player.js.org/docs/discord-player/class/GuildQueue)
- `track`: [Track](https://discord-player.js.org/docs/discord-player/class/Track)
- `queue`: [GuildQueue](https://discord-player.js.org/docs/discord-player/class/GuildQueue)
- `track`: [Track](https://discord-player.js.org/docs/discord-player/class/Track)
- [PlayerTrigger](https://github.com/tryforge/ForgeMusic/blob/main/src%2Fevents%2FplayerTrigger.ts)
- `queue`: [GuildQueue](https://discord-player.js.org/docs/discord-player/class/GuildQueue)
- `track`: [Track](https://discord-player.js.org/docs/discord-player/class/Track)
- `reason`: [PlayerTriggeredReason](https://discord-player.js.org/docs/discord-player/type/PlayerTriggeredReason)
- `queue`: [GuildQueue](https://discord-player.js.org/docs/discord-player/class/GuildQueue)
- `track`: [Track](https://discord-player.js.org/docs/discord-player/class/Track)
- `reason`: [PlayerTriggeredReason](https://discord-player.js.org/docs/discord-player/type/PlayerTriggeredReason)
- [QueueCreate](https://github.com/tryforge/ForgeMusic/blob/main/src%2Fevents%2FqueueCreate.ts)
- `queue`: [GuildQueue](https://discord-player.js.org/docs/discord-player/class/GuildQueue)
- [QueueDelete](https://github.com/tryforge/ForgeMusic/blob/main/src%2Fevents%2FqueueDelete.ts)
Expand All @@ -183,53 +215,22 @@ The following, is a list of event with its accessible properties.
- `queue`: [GuildQueue](https://discord-player.js.org/docs/discord-player/class/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
### Default Extractors
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
});
```
### 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.
```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.
[![tryforge/ForgeMusic](https://contrib.rocks/image?repo=tryforge/ForgeMusic)](https://github.com/tryforge/ForgeMusic)
Loading