distube 3.0.7 → 3.1.0

package/dist/DisTube.d.ts

@@ -1,20 +1,20 @@
 import { TypedEmitter } from "tiny-typed-emitter";
-import { DisTubeHandler, DisTubeVoiceManager, Options, Playlist, Queue, QueueManager, SearchResult } from ".";
-import type { Client, GuildMember, Message, StageChannel, TextChannel, VoiceChannel } from "discord.js";
-import type { CustomPlugin, DisTubeEvents, DisTubeOptions, ExtractorPlugin, Filters, GuildIDResolvable, Song } from ".";
+import { DisTubeHandler, DisTubeVoiceManager, Options, Playlist, Queue, QueueManager, SearchResult, Song } from ".";
+import type { Client, GuildMember, GuildTextBasedChannel, Message, VoiceBasedChannel } from "discord.js";
+import type { CustomPlugin, DisTubeEvents, DisTubeOptions, ExtractorPlugin, Filters, GuildIDResolvable } from ".";
 /**
  * DisTube class
  * @extends EventEmitter
  */
 export declare class DisTube extends TypedEmitter<DisTubeEvents> {
-    handler: DisTubeHandler;
-    options: Options;
-    client: Client;
-    queues: QueueManager;
-    voices: DisTubeVoiceManager;
-    extractorPlugins: ExtractorPlugin[];
-    customPlugins: CustomPlugin[];
-    filters: Filters;
+    readonly handler: DisTubeHandler;
+    readonly options: Options;
+    readonly client: Client;
+    readonly queues: QueueManager;
+    readonly voices: DisTubeVoiceManager;
+    readonly extractorPlugins: ExtractorPlugin[];
+    readonly customPlugins: CustomPlugin[];
+    readonly filters: Filters;
     /**
      * Create a new DisTube class.
      * @param {Discord.Client} client Discord.JS client
@@ -30,33 +30,68 @@ export declare class DisTube extends TypedEmitter<DisTubeEvents> {
      */
     constructor(client: Client, otp?: DisTubeOptions);
     /**
-     * Shorthand method for {@link DisTube#playVoiceChannel}
-     * @returns {Promise<void>}
-     * @param {Discord.Message} message A message from guild channel
+     * Play / add a song or playlist from url. Search and play a song if it is not a valid url.
+     *
+     * @param {Discord.BaseGuildVoiceChannel} voiceChannel The voice channel will be joined
      * @param {string|Song|SearchResult|Playlist} song URL | Search string |
      * {@link Song} | {@link SearchResult} | {@link Playlist}
      * @param {Object} [options] Optional options
      * @param {boolean} [options.skip=false] Skip the playing song (if exists) and play the added song/playlist instantly
      * @param {boolean} [options.unshift=false] Add the song/playlist to the beginning of the queue
      * (after the playing song if exists)
+     * @param {Discord.GuildMember} [options.member] Requested user (default is your bot)
+     * @param {Discord.BaseGuildTextChannel} [options.textChannel] Default {@link Queue#textChannel}
+     * @param {Discord.Message} [options.message] Called message (For built-in search events. If this is a {@link https://developer.mozilla.org/en-US/docs/Glossary/Falsy|falsy value}, it will play the first result instead)
+     * @param {*} [options.metadata] Optional metadata that can be attached to the song/playlist will be played,
+     * This is useful for identification purposes when the song/playlist is passed around in events.
+     * See {@link Song#metadata} or {@link Playlist#metadata}
      * @example
      * client.on('message', (message) => {
      *     if (!message.content.startsWith(config.prefix)) return;
      *     const args = message.content.slice(config.prefix.length).trim().split(/ +/g);
      *     const command = args.shift();
      *     if (command == "play")
-     *         distube.play(message, args.join(" "));
+     *         distube.play(message.member.voice?.channel, args.join(" "), {
+     *             member: message.member,
+     *             textChannel: message.channel,
+     *             message
+     *         });
      * });
+     * @returns {Promise<void>}
      */
-    play(message: Message, song: string | Song | SearchResult | Playlist, options?: {
+    play(voiceChannel: VoiceBasedChannel, song: string | Song | SearchResult | Playlist | null, options: {
         skip?: boolean;
         unshift?: boolean;
+        member?: GuildMember;
+        textChannel?: GuildTextBasedChannel;
+        message?: Message;
+        metadata?: any;
     }): Promise<void>;
     /**
      * Play / add a song or playlist from url. Search and play a song if it is not a valid url.
-     * Emit {@link DisTube#addList}, {@link DisTube#addSong} or {@link DisTube#playSong} after executing
+     *
+     * @param {Discord.Message} message A message from guild channel
+     * @param {string|Song|SearchResult|Playlist} song URL | Search string |
+     * {@link Song} | {@link SearchResult} | {@link Playlist}
+     * @param {Object} [options] Optional options
+     * @param {boolean} [options.skip=false] Skip the playing song (if exists) and play the added song/playlist instantly
+     * @param {boolean} [options.unshift=false] Add the song/playlist to the beginning of the queue
+     * (after the playing song if exists)
+     * @param {*} [options.metadata] Optional metadata that can be attached to the song/playlist will be played,
+     * This is useful for identification purposes when the song/playlist is passed around in events.
+     * See {@link Song#metadata} or {@link Playlist#metadata}
+     * @deprecated Message parameter is deprecated, use VoiceChannel instead. See {@link DisTube#play}
+     */
+    play(message: Message<true>, song: string | Song | SearchResult | Playlist, options: {
+        skip?: boolean;
+        unshift?: boolean;
+        metadata?: any;
+    }): Promise<void>;
+    /**
+     * Play / add a song or playlist from url. Search and play a song if it is not a valid url.
+     *
      * @returns {Promise<void>}
-     * @param {Discord.VoiceChannel|Discord.StageChannel} voiceChannel The voice channel will be joined
+     * @param {Discord.BaseGuildVoiceChannel} voiceChannel The voice channel will be joined
      * @param {string|Song|SearchResult|Playlist} song URL | Search string |
      * {@link Song} | {@link SearchResult} | {@link Playlist}
      * @param {Object} [options] Optional options
@@ -64,21 +99,50 @@ export declare class DisTube extends TypedEmitter<DisTubeEvents> {
      * @param {boolean} [options.unshift=false] Add the song/playlist to the beginning of the queue
      * (after the playing song if exists)
      * @param {Discord.GuildMember} [options.member] Requested user (default is your bot)
-     * @param {Discord.TextChannel} [options.textChannel] Default {@link Queue#textChannel} (if the queue wasn't created)
+     * @param {Discord.BaseGuildTextChannel} [options.textChannel] Default {@link Queue#textChannel}
      * @param {Discord.Message} [options.message] Called message (For built-in search events. If this is a {@link https://developer.mozilla.org/en-US/docs/Glossary/Falsy|falsy value}, it will play the first result instead)
+     * @param {*} [options.metadata] Optional metadata that can be attached to the song/playlist will be played,
+     * This is useful for identification purposes when the song/playlist is passed around in events.
+     * See {@link Song#metadata} or {@link Playlist#metadata}
+     * @deprecated Use {@link DisTube#play} instead
      */
-    playVoiceChannel(voiceChannel: VoiceChannel | StageChannel, song: string | Song | SearchResult | Playlist | null, options?: {
+    playVoiceChannel(voiceChannel: VoiceBasedChannel, song: string | Song | SearchResult | Playlist | null, options?: {
         skip?: boolean;
         unshift?: boolean;
         member?: GuildMember;
-        textChannel?: TextChannel;
+        textChannel?: GuildTextBasedChannel;
         message?: Message;
+        metadata?: any;
     }): Promise<void>;
     /**
-     * <info>Shorthand method of {@link DisTubeHandler#createCustomPlaylist} and {@link DisTube#playVoiceChannel}
+     * Create a custom playlist
+     * @returns {Promise<Playlist>}
+     * @param {Array<string|Song|SearchResult>} songs Array of url, Song or SearchResult
+     * @param {Object} [options] Optional options
+     * @param {Discord.GuildMember} [options.message] A message from guild channel | A guild member
+     * @param {Object} [options.properties={}] Additional properties such as `name`
+     * @param {boolean} [options.parallel=true] Whether or not fetch the songs in parallel
+     * @param {*} [options.metadata] Metadata
+     * @example
+     * const songs = ["https://www.youtube.com/watch?v=xxx", "https://www.youtube.com/watch?v=yyy"];
+     * const playlist = await distube.createCustomPlaylist(songs, {
+     *     member: message.member,
+     *     properties: { name: "My playlist name" },
+     *      parallel: true
+     * });
+     * distube.play(voiceChannel, playlist, { ... });
+     */
+    createCustomPlaylist(songs: (string | Song | SearchResult)[], options?: {
+        member?: GuildMember;
+        properties?: Record<string, any>;
+        parallel?: boolean;
+        metadata?: any;
+    }): Promise<Playlist>;
+    /**
+     * <info>Shorthand method of {@link DisTube#createCustomPlaylist} and {@link DisTube#play}
      *
      * If you doesn't have a user message (interaction,...),
-     * see {@link DisTubeHandler#createCustomPlaylist} example</info>
+     * see {@link DisTube#createCustomPlaylist} example</info>
      *
      * Play or add array of video urls.
      * {@link DisTube#event:playSong} or {@link DisTube#event:addList} will be emitted
@@ -87,27 +151,24 @@ export declare class DisTube extends TypedEmitter<DisTubeEvents> {
      * @returns {Promise<void>}
      * @param {Discord.Message} message A message from guild channel
      * @param {Array<string|Song|SearchResult>} songs Array of url, Song or SearchResult
-     * @param {Object} [properties={}] Additional properties such as `name`
+     * @param {Object} [properties={}] Additional properties for playlist such as `name`
      * @param {Object} [options] Optional options
      * @param {boolean} [options.skip=false] Skip the playing song (if exists) and play the added song/playlist instantly
      * @param {boolean} [options.unshift=false] Add the song/playlist to the beginning of the queue
      * (after the playing song if exists)
      * @param {boolean} [options.parallel=true] Whether or not fetch the songs in parallel
-     * @example
-     *     const songs = ["https://www.youtube.com/watch?v=xxx", "https://www.youtube.com/watch?v=yyy"];
-     *     distube.playCustomPlaylist(message, songs, { name: "My playlist name" });
-     *     // Fetching custom playlist sequentially (reduce lag for low specs)
-     *     distube.playCustomPlaylist(message, songs, { name: "My playlist name" }, false, false);
+     * @deprecated Use {@link DisTube#createCustomPlaylist} and {@link DisTube#play} instead
      */
-    playCustomPlaylist(message: Message, songs: Array<string | Song | SearchResult>, properties?: any, options?: {
+    playCustomPlaylist(message: Message<true>, songs: Array<string | Song | SearchResult>, properties?: Record<string, any>, options?: {
         skip?: boolean;
         unshift?: boolean;
         parallel?: boolean;
+        metadata?: any;
     }): Promise<void>;
     /**
-     * Search for a song.
-     * You can customize how user answers instead of send a number.
-     * Then use {@link DisTube#play} or {@link DisTube#playVoiceChannel} to play it.
+     * Search for a song. You can customize how user answers instead of send a number.
+     * Then use {@link DisTube#play} to play it.
+     *
      * @param {string} string The string search for
      * @param {Object} options Search options
      * @param {number} [options.limit=10] Limit the results
@@ -347,10 +408,10 @@ export declare class DisTube extends TypedEmitter<DisTubeEvents> {
     /**
      * Emit error event
      * @param {Error} error error
-     * @param {Discord.TextChannel?} channel Text channel where the error is encountered.
+     * @param {Discord.BaseGuildTextChannel} [channel] Text channel where the error is encountered.
      * @private
      */
-    emitError(error: Error, channel?: TextChannel): void;
+    emitError(error: Error, channel?: GuildTextBasedChannel): void;
 }
 export default DisTube;
 /**
@@ -390,7 +451,7 @@ export default DisTube;
  * Emitted when DisTube encounters an error.
  *
  * @event DisTube#error
- * @param {Discord.TextChannel} channel Text channel where the error is encountered.
+ * @param {Discord.BaseGuildTextChannel} channel Text channel where the error is encountered.
  * @param {Error} error The error encountered
  * @example
  * distube.on("error", (channel, error) => channel.send(
@@ -451,7 +512,7 @@ export default DisTube;
  */
 /**
  * Emitted when {@link DisTubeOptions|DisTubeOptions.searchSongs} bigger than 0,
- * and song param of {@link DisTube#playVoiceChannel} is invalid url.
+ * and song param of {@link DisTube#play} is invalid url.
  * DisTube will wait for user's next message to choose a song manually.
  * <info>{@link https://support.google.com/youtube/answer/7354993|Safe search} is enabled
  * if {@link DisTubeOptions}.nsfw is disabled and the message's channel is not a nsfw channel.</info>

package/dist/DisTube.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DisTube.d.ts","sourceRoot":"","sources":["../src/DisTube.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"DisTube.d.ts","sourceRoot":"","sources":["../src/DisTube.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAEL,cAAc,EACd,mBAAmB,EAGnB,OAAO,EACP,QAAQ,EACR,KAAK,EACL,YAAY,EACZ,YAAY,EACZ,IAAI,EAQL,MAAM,GAAG,CAAC;AACX,OAAO,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,qBAAqB,EAAE,OAAO,EAAe,iBAAiB,EAAE,MAAM,YAAY,CAAC;AACtH,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,eAAe,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,GAAG,CAAC;AAIlH;;;GAGG;AACH,qBAAa,OAAQ,SAAQ,YAAY,CAAC,aAAa,CAAC;IACtD,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,mBAAmB,CAAC;IACrC,QAAQ,CAAC,gBAAgB,EAAE,eAAe,EAAE,CAAC;IAC7C,QAAQ,CAAC,aAAa,EAAE,YAAY,EAAE,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B;;;;;;;;;;;;OAYG;gBACS,MAAM,EAAE,MAAM,EAAE,GAAG,GAAE,cAAmB;IAsDpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACG,IAAI,CACR,YAAY,EAAE,iBAAiB,EAC/B,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,YAAY,GAAG,QAAQ,GAAG,IAAI,EACpD,OAAO,EAAE;QACP,IAAI,CAAC,EAAE,OAAO,CAAC;QACf,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,MAAM,CAAC,EAAE,WAAW,CAAC;QACrB,WAAW,CAAC,EAAE,qBAAqB,CAAC;QACpC,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,QAAQ,CAAC,EAAE,GAAG,CAAC;KAChB,GACA,OAAO,CAAC,IAAI,CAAC;IAChB;;;;;;;;;;;;;;OAcG;IACG,IAAI,CACR,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,EACtB,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,YAAY,GAAG,QAAQ,EAC7C,OAAO,EAAE;QAAE,IAAI,CAAC,EAAE,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,EAAE,GAAG,CAAA;KAAE,GAC7D,OAAO,CAAC,IAAI,CAAC;IA6GhB;;;;;;;;;;;;;;;;;;OAkBG;IACG,gBAAgB,CACpB,YAAY,EAAE,iBAAiB,EAC/B,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,YAAY,GAAG,QAAQ,GAAG,IAAI,EACpD,OAAO,GAAE;QACP,IAAI,CAAC,EAAE,OAAO,CAAC;QACf,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,MAAM,CAAC,EAAE,WAAW,CAAC;QACrB,WAAW,CAAC,EAAE,qBAAqB,CAAC;QACpC,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,QAAQ,CAAC,EAAE,GAAG,CAAC;KACX,GACL,OAAO,CAAC,IAAI,CAAC;IAKhB;;;;;;;;;;;;;;;;;OAiBG;IACG,oBAAoB,CACxB,KAAK,EAAE,CAAC,MAAM,GAAG,IAAI,GAAG,YAAY,CAAC,EAAE,EACvC,OAAO,GAAE;QACP,MAAM,CAAC,EAAE,WAAW,CAAC;QACrB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QACjC,QAAQ,CAAC,EAAE,OAAO,CAAC;QACnB,QAAQ,CAAC,EAAE,GAAG,CAAC;KACX,GACL,OAAO,CAAC,QAAQ,CAAC;IA4BpB;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,kBAAkB,CACtB,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,EACtB,KAAK,EAAE,KAAK,CAAC,MAAM,GAAG,IAAI,GAAG,YAAY,CAAC,EAC1C,UAAU,GAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAM,EACpC,OAAO,GAAE;QAAE,IAAI,CAAC,EAAE,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,EAAE,GAAG,CAAA;KAAO,GACtF,OAAO,CAAC,IAAI,CAAC;IAsChB;;;;;;;;;;;OAWG;IACG,MAAM,CACV,MAAM,EAAE,MAAM,EACd,OAAO,GAAE;QAAE,IAAI,CAAC,EAAE,OAAO,GAAG,UAAU,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAA;KAAO,GACrG,OAAO,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;IAuB/B;;;;;;;;;;;;;;;;;OAiBG;IACH,QAAQ,CAAC,KAAK,EAAE,iBAAiB,GAAG,KAAK,GAAG,SAAS;IAIrD;;;;;OAKG;IACH,KAAK,CAAC,KAAK,EAAE,iBAAiB,GAAG,KAAK;IAMtC;;;;;OAKG;IACH,MAAM,CAAC,KAAK,EAAE,iBAAiB,GAAG,KAAK;IAMvC;;;;;;;;;;;;;;;OAeG;IACH,IAAI,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAM7C;;;;;;;;;;;;;;OAcG;IACH,SAAS,CAAC,KAAK,EAAE,iBAAiB,EAAE,OAAO,EAAE,MAAM,GAAG,KAAK;IAM3D;;;;;;;;;;;;;;;OAeG;IACH,IAAI,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAM7C;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAMjD;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,KAAK,CAAC;IAMjD;;;;;;;;;;;;;;;;;OAiBG;IACH,IAAI,CAAC,KAAK,EAAE,iBAAiB,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC;IAM3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;IACH,aAAa,CAAC,KAAK,EAAE,iBAAiB,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM;IAM9D;;;;;;;;;;;;;;;OAeG;IACH,cAAc,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO;IAOjD;;;;OAIG;IACH,cAAc,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAMvD;;;;;;;;;;;;;;;;;OAiBG;IACH,SAAS,CAAC,KAAK,EAAE,iBAAiB,EAAE,MAAM,EAAE,MAAM,GAAG,KAAK,EAAE,KAAK,UAAQ,GAAG,KAAK,CAAC,MAAM,CAAC;IAMzF;;;;;;;;;;;;;OAaG;IACH,IAAI,CAAC,KAAK,EAAE,iBAAiB,EAAE,IAAI,EAAE,MAAM,GAAG,KAAK;IAOnD;;;;;OAKG;IACH,SAAS,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC,EAAE,qBAAqB,GAAG,IAAI;CAe/D;AAED,eAAe,OAAO,CAAC;AAEvB;;;;;;;;;;GAUG;AAEH;;;;;;;;;;GAUG;AAEH;;;;;;;;;;GAUG;AAEH;;;;;;;;;;GAUG;AAEH;;;;;;;;GAQG;AAEH;;;;;;;;;;GAUG;AAEH;;;;;;;;GAQG;AAEH;;;;;;;;;;;;;GAaG;AAEH;;;;;;;;GAQG;AAEH;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;;;;;;;;GAUG;AAEH;;;;;;;;;;;GAWG;AAEH;;;;;;;;GAQG;AAEH;;;;;GAKG;AAEH;;;;;GAKG;AAEH;;;;;;GAMG"}

package/dist/DisTube.js

@@ -9,6 +9,7 @@ const ytsr_1 = __importDefault(require("@distube/ytsr"));
 const util_1 = require("./util");
 const tiny_typed_emitter_1 = require("tiny-typed-emitter");
 const _1 = require(".");
+// TODO: remove deprecated stuff on the next major version
 /**
  * DisTube class
  * @extends EventEmitter
@@ -83,70 +84,39 @@ class DisTube extends tiny_typed_emitter_1.TypedEmitter {
          */
         this.customPlugins = this.options.plugins.filter((p) => p.type === "custom");
     }
-    /**
-     * Shorthand method for {@link DisTube#playVoiceChannel}
-     * @returns {Promise<void>}
-     * @param {Discord.Message} message A message from guild channel
-     * @param {string|Song|SearchResult|Playlist} song URL | Search string |
-     * {@link Song} | {@link SearchResult} | {@link Playlist}
-     * @param {Object} [options] Optional options
-     * @param {boolean} [options.skip=false] Skip the playing song (if exists) and play the added song/playlist instantly
-     * @param {boolean} [options.unshift=false] Add the song/playlist to the beginning of the queue
-     * (after the playing song if exists)
-     * @example
-     * client.on('message', (message) => {
-     *     if (!message.content.startsWith(config.prefix)) return;
-     *     const args = message.content.slice(config.prefix.length).trim().split(/ +/g);
-     *     const command = args.shift();
-     *     if (command == "play")
-     *         distube.play(message, args.join(" "));
-     * });
-     */
-    async play(message, song, options = {}) {
-        if (!song)
-            throw new _1.DisTubeError("INVALID_TYPE", ["string", "Song", "SearchResult", "Playlist"], song, "song");
-        if (!(0, _1.isMessageInstance)(message))
-            throw new _1.DisTubeError("INVALID_TYPE", "Discord.Message", message, "message");
-        if (typeof options !== "object" || Array.isArray(options)) {
-            throw new _1.DisTubeError("INVALID_TYPE", "object", options, "options");
+    async play(voiceChannel, song, options = {}) {
+        var _a, _b;
+        if ((0, _1.isMessageInstance)(voiceChannel)) {
+            process.emitWarning("Passing Message for DisTube#play is deprecated, use VoiceBasedChannel instead.", "DeprecationWarning");
+            const message = voiceChannel;
+            if (!song)
+                throw new _1.DisTubeError("INVALID_TYPE", ["string", "Song", "SearchResult", "Playlist"], song, "song");
+            if (!(0, _1.isMessageInstance)(message))
+                throw new _1.DisTubeError("INVALID_TYPE", "Discord.Message", message, "message");
+            if (typeof options !== "object" || Array.isArray(options)) {
+                throw new _1.DisTubeError("INVALID_TYPE", "object", options, "options");
+            }
+            const textChannel = message.channel;
+            const { skip, unshift, metadata } = Object.assign({ skip: false, unshift: false }, options);
+            const member = message.member;
+            const vc = member.voice.channel;
+            if (!vc)
+                throw new _1.DisTubeError("NOT_IN_VOICE");
+            return this.play(vc, song, {
+                member,
+                textChannel,
+                skip,
+                message,
+                unshift,
+                metadata,
+            });
         }
-        const textChannel = message.channel;
-        const { skip, unshift } = Object.assign({ skip: false, unshift: false }, options);
-        const member = message.member;
-        const voiceChannel = member.voice.channel;
-        if (!voiceChannel)
-            throw new _1.DisTubeError("NOT_IN_VOICE");
-        await this.playVoiceChannel(voiceChannel, song, {
-            member,
-            textChannel,
-            skip,
-            message,
-            unshift,
-        });
-    }
-    /**
-     * Play / add a song or playlist from url. Search and play a song if it is not a valid url.
-     * Emit {@link DisTube#addList}, {@link DisTube#addSong} or {@link DisTube#playSong} after executing
-     * @returns {Promise<void>}
-     * @param {Discord.VoiceChannel|Discord.StageChannel} voiceChannel The voice channel will be joined
-     * @param {string|Song|SearchResult|Playlist} song URL | Search string |
-     * {@link Song} | {@link SearchResult} | {@link Playlist}
-     * @param {Object} [options] Optional options
-     * @param {boolean} [options.skip=false] Skip the playing song (if exists) and play the added song/playlist instantly
-     * @param {boolean} [options.unshift=false] Add the song/playlist to the beginning of the queue
-     * (after the playing song if exists)
-     * @param {Discord.GuildMember} [options.member] Requested user (default is your bot)
-     * @param {Discord.TextChannel} [options.textChannel] Default {@link Queue#textChannel} (if the queue wasn't created)
-     * @param {Discord.Message} [options.message] Called message (For built-in search events. If this is a {@link https://developer.mozilla.org/en-US/docs/Glossary/Falsy|falsy value}, it will play the first result instead)
-     */
-    async playVoiceChannel(voiceChannel, song, options = {}) {
-        var _a;
         if (!(0, _1.isSupportedVoiceChannel)(voiceChannel))
             throw new _1.DisTubeError("NOT_SUPPORTED_VOICE");
         if (typeof options !== "object" || Array.isArray(options)) {
             throw new _1.DisTubeError("INVALID_TYPE", "object", options, "options");
         }
-        const { textChannel, member, skip, message, unshift } = Object.assign({
+        const { textChannel, member, skip, message, unshift, metadata } = Object.assign({
             member: voiceChannel.guild.me,
             skip: false,
             unshift: false,
@@ -158,32 +128,33 @@ class DisTube extends tiny_typed_emitter_1.TypedEmitter {
             if (typeof song === "string") {
                 for (const plugin of this.customPlugins) {
                     if (await plugin.validate(song)) {
-                        return plugin.play(voiceChannel, song, member, textChannel, skip, unshift);
+                        return plugin.play(voiceChannel, song, options);
                     }
                 }
             }
             let queue = this.getQueue(voiceChannel);
-            const queuing = queue && !queue.taskQueue.hasResolveTask;
+            const queuing = !!queue && !queue.taskQueue.hasResolveTask;
             if (queuing)
                 await (queue === null || queue === void 0 ? void 0 : queue.taskQueue.queuing(true));
             try {
                 if (song instanceof _1.SearchResult && song.type === "playlist")
                     song = song.url;
-                if (typeof song === "string" && ytpl_1.default.validateID(song))
-                    song = await this.handler.resolvePlaylist(member, song);
+                if (typeof song === "string" && ytpl_1.default.validateID(song)) {
+                    song = await this.handler.resolvePlaylist(song, { member, metadata });
+                }
                 if (typeof song === "string" && !(0, util_1.isURL)(song)) {
                     if (!message)
                         song = (await this.search(song, { limit: 1 }))[0];
                     else
                         song = await this.handler.searchSong(message, song);
                 }
-                song = await this.handler.resolveSong(member, song);
+                song = await this.handler.resolveSong(song, { member, metadata });
                 if (!song)
                     return;
                 if (song instanceof _1.Playlist) {
-                    await this.handler.handlePlaylist(voiceChannel, song, textChannel, skip, unshift);
+                    await this.handler.handlePlaylist(voiceChannel, song, { textChannel, skip, unshift });
                 }
-                else if (!this.options.nsfw && song.age_restricted && !(textChannel === null || textChannel === void 0 ? void 0 : textChannel.nsfw)) {
+                else if (!this.options.nsfw && song.age_restricted && !((_a = textChannel) === null || _a === void 0 ? void 0 : _a.nsfw)) {
                     throw new _1.DisTubeError("NON_NSFW");
                 }
                 else {
@@ -196,7 +167,7 @@ class DisTube extends tiny_typed_emitter_1.TypedEmitter {
                             this.emit("addSong", queue, song);
                     }
                     else {
-                        const newQueue = await this.handler.createQueue(voiceChannel, song, textChannel);
+                        const newQueue = await this.queues.create(voiceChannel, song, textChannel);
                         if (newQueue instanceof _1.Queue) {
                             if (this.options.emitAddSongWhenCreatingQueue)
                                 this.emit("addSong", newQueue, song);
@@ -214,7 +185,7 @@ class DisTube extends tiny_typed_emitter_1.TypedEmitter {
             if (!(e instanceof _1.DisTubeError)) {
                 try {
                     e.name = "PlayError";
-                    e.message = `${((_a = song) === null || _a === void 0 ? void 0 : _a.url) || song}\n${e.message}`;
+                    e.message = `${((_b = song) === null || _b === void 0 ? void 0 : _b.url) || song}\n${e.message}`;
                 }
                 catch { }
             }
@@ -222,10 +193,79 @@ class DisTube extends tiny_typed_emitter_1.TypedEmitter {
         }
     }
     /**
-     * <info>Shorthand method of {@link DisTubeHandler#createCustomPlaylist} and {@link DisTube#playVoiceChannel}
+     * Play / add a song or playlist from url. Search and play a song if it is not a valid url.
+     *
+     * @returns {Promise<void>}
+     * @param {Discord.BaseGuildVoiceChannel} voiceChannel The voice channel will be joined
+     * @param {string|Song|SearchResult|Playlist} song URL | Search string |
+     * {@link Song} | {@link SearchResult} | {@link Playlist}
+     * @param {Object} [options] Optional options
+     * @param {boolean} [options.skip=false] Skip the playing song (if exists) and play the added song/playlist instantly
+     * @param {boolean} [options.unshift=false] Add the song/playlist to the beginning of the queue
+     * (after the playing song if exists)
+     * @param {Discord.GuildMember} [options.member] Requested user (default is your bot)
+     * @param {Discord.BaseGuildTextChannel} [options.textChannel] Default {@link Queue#textChannel}
+     * @param {Discord.Message} [options.message] Called message (For built-in search events. If this is a {@link https://developer.mozilla.org/en-US/docs/Glossary/Falsy|falsy value}, it will play the first result instead)
+     * @param {*} [options.metadata] Optional metadata that can be attached to the song/playlist will be played,
+     * This is useful for identification purposes when the song/playlist is passed around in events.
+     * See {@link Song#metadata} or {@link Playlist#metadata}
+     * @deprecated Use {@link DisTube#play} instead
+     */
+    async playVoiceChannel(voiceChannel, song, options = {}) {
+        process.emitWarning("DisTube#playVoiceChannel is deprecated, use DisTube#play instead.", "DeprecationWarning");
+        return this.play(voiceChannel, song, options);
+    }
+    /**
+     * Create a custom playlist
+     * @returns {Promise<Playlist>}
+     * @param {Array<string|Song|SearchResult>} songs Array of url, Song or SearchResult
+     * @param {Object} [options] Optional options
+     * @param {Discord.GuildMember} [options.message] A message from guild channel | A guild member
+     * @param {Object} [options.properties={}] Additional properties such as `name`
+     * @param {boolean} [options.parallel=true] Whether or not fetch the songs in parallel
+     * @param {*} [options.metadata] Metadata
+     * @example
+     * const songs = ["https://www.youtube.com/watch?v=xxx", "https://www.youtube.com/watch?v=yyy"];
+     * const playlist = await distube.createCustomPlaylist(songs, {
+     *     member: message.member,
+     *     properties: { name: "My playlist name" },
+     *      parallel: true
+     * });
+     * distube.play(voiceChannel, playlist, { ... });
+     */
+    async createCustomPlaylist(songs, options = {}) {
+        const { member, properties, parallel, metadata } = Object.assign({ parallel: true }, options);
+        if (!Array.isArray(songs))
+            throw new _1.DisTubeError("INVALID_TYPE", "Array", songs, "songs");
+        if (!songs.length)
+            throw new _1.DisTubeError("EMPTY_ARRAY", "songs");
+        const filteredSongs = songs.filter(song => song instanceof _1.Song || (song instanceof _1.SearchResult && song.type === "video") || (0, util_1.isURL)(song));
+        if (!filteredSongs.length)
+            throw new _1.DisTubeError("NO_VALID_SONG");
+        if (member && !(0, _1.isMemberInstance)(member)) {
+            throw new _1.DisTubeError("INVALID_TYPE", "Discord.Member", member, "options.member");
+        }
+        if (!filteredSongs.length)
+            throw new _1.DisTubeError("NO_VALID_SONG");
+        let resolvedSongs;
+        if (parallel) {
+            const promises = filteredSongs.map((song) => this.handler.resolveSong(song, { member, metadata }).catch(() => undefined));
+            resolvedSongs = (await Promise.all(promises)).filter((s) => !!s);
+        }
+        else {
+            const resolved = [];
+            for (const song of filteredSongs) {
+                resolved.push(await this.handler.resolveSong(song, { member, metadata }).catch(() => undefined));
+            }
+            resolvedSongs = resolved.filter((s) => !!s);
+        }
+        return new _1.Playlist(resolvedSongs, { member, properties, metadata });
+    }
+    /**
+     * <info>Shorthand method of {@link DisTube#createCustomPlaylist} and {@link DisTube#play}
      *
      * If you doesn't have a user message (interaction,...),
-     * see {@link DisTubeHandler#createCustomPlaylist} example</info>
+     * see {@link DisTube#createCustomPlaylist} example</info>
      *
      * Play or add array of video urls.
      * {@link DisTube#event:playSong} or {@link DisTube#event:addList} will be emitted
@@ -234,24 +274,22 @@ class DisTube extends tiny_typed_emitter_1.TypedEmitter {
      * @returns {Promise<void>}
      * @param {Discord.Message} message A message from guild channel
      * @param {Array<string|Song|SearchResult>} songs Array of url, Song or SearchResult
-     * @param {Object} [properties={}] Additional properties such as `name`
+     * @param {Object} [properties={}] Additional properties for playlist such as `name`
      * @param {Object} [options] Optional options
      * @param {boolean} [options.skip=false] Skip the playing song (if exists) and play the added song/playlist instantly
      * @param {boolean} [options.unshift=false] Add the song/playlist to the beginning of the queue
      * (after the playing song if exists)
      * @param {boolean} [options.parallel=true] Whether or not fetch the songs in parallel
-     * @example
-     *     const songs = ["https://www.youtube.com/watch?v=xxx", "https://www.youtube.com/watch?v=yyy"];
-     *     distube.playCustomPlaylist(message, songs, { name: "My playlist name" });
-     *     // Fetching custom playlist sequentially (reduce lag for low specs)
-     *     distube.playCustomPlaylist(message, songs, { name: "My playlist name" }, false, false);
+     * @deprecated Use {@link DisTube#createCustomPlaylist} and {@link DisTube#play} instead
      */
     async playCustomPlaylist(message, songs, properties = {}, options = {}) {
+        var _a, _b, _c;
+        process.emitWarning("DisTube#playCustomPlaylist is deprecated, use DisTube#createCustomPlaylist and DisTube#play instead.", "DeprecationWarning");
         try {
             if (typeof options !== "object" || Array.isArray(options)) {
                 throw new _1.DisTubeError("INVALID_TYPE", "object", options, "options");
             }
-            const { skip, unshift, parallel } = Object.assign({
+            const { skip, unshift, parallel, metadata } = Object.assign({
                 skip: false,
                 unshift: false,
                 parallel: true,
@@ -261,8 +299,16 @@ class DisTube extends tiny_typed_emitter_1.TypedEmitter {
             if (queuing)
                 await (queue === null || queue === void 0 ? void 0 : queue.taskQueue.queuing(true));
             try {
-                const playlist = await this.handler.createCustomPlaylist(message, songs, properties, parallel);
-                await this.handler.handlePlaylist(message, playlist, message.channel, skip, unshift);
+                const playlist = await this.createCustomPlaylist(songs, {
+                    member: (_a = message.member) !== null && _a !== void 0 ? _a : undefined,
+                    properties,
+                    parallel,
+                    metadata,
+                });
+                const voice = (_c = (_b = message.member) === null || _b === void 0 ? void 0 : _b.voice) === null || _c === void 0 ? void 0 : _c.channel;
+                if (!voice)
+                    throw new _1.DisTubeError("NOT_IN_VOICE");
+                await this.play(voice, playlist, { textChannel: message.channel, skip, unshift, metadata });
             }
             finally {
                 if (queuing)
@@ -274,9 +320,9 @@ class DisTube extends tiny_typed_emitter_1.TypedEmitter {
         }
     }
     /**
-     * Search for a song.
-     * You can customize how user answers instead of send a number.
-     * Then use {@link DisTube#play} or {@link DisTube#playVoiceChannel} to play it.
+     * Search for a song. You can customize how user answers instead of send a number.
+     * Then use {@link DisTube#play} to play it.
+     *
      * @param {string} string The string search for
      * @param {Object} options Search options
      * @param {number} [options.limit=10] Limit the results
@@ -605,7 +651,7 @@ class DisTube extends tiny_typed_emitter_1.TypedEmitter {
     /**
      * Emit error event
      * @param {Error} error error
-     * @param {Discord.TextChannel?} channel Text channel where the error is encountered.
+     * @param {Discord.BaseGuildTextChannel} [channel] Text channel where the error is encountered.
      * @private
      */
     emitError(error, channel) {
@@ -662,7 +708,7 @@ exports.default = DisTube;
  * Emitted when DisTube encounters an error.
  *
  * @event DisTube#error
- * @param {Discord.TextChannel} channel Text channel where the error is encountered.
+ * @param {Discord.BaseGuildTextChannel} channel Text channel where the error is encountered.
  * @param {Error} error The error encountered
  * @example
  * distube.on("error", (channel, error) => channel.send(
@@ -723,7 +769,7 @@ exports.default = DisTube;
  */
 /**
  * Emitted when {@link DisTubeOptions|DisTubeOptions.searchSongs} bigger than 0,
- * and song param of {@link DisTube#playVoiceChannel} is invalid url.
+ * and song param of {@link DisTube#play} is invalid url.
  * DisTube will wait for user's next message to choose a song manually.
  * <info>{@link https://support.google.com/youtube/answer/7354993|Safe search} is enabled
  * if {@link DisTubeOptions}.nsfw is disabled and the message's channel is not a nsfw channel.</info>