auralis-sdk 0.4.2 → 0.5.0

package/dist/index.d.cts

@@ -118,6 +118,20 @@ interface PlayerHost {
     dropPlayer(guildId: bigint): void;
 }
 type AutoplayHook = (player: Player) => Promise<Track | null>;
+/** Named EQ presets accepted by {@link Player.setEqualizer}. */
+type EqPreset = "flat" | "bassboost" | "soft" | "nightcore" | "vaporwave" | "earrape" | "treble" | "karaoke";
+/** Portable snapshot of a player's queue state, produced by {@link Player.export}
+ * and consumed by {@link Player.restore}. Safe to JSON.stringify / store. */
+interface SerializedPlayer {
+    version: 1;
+    guildId: string;
+    queue: Track[];
+    history: Track[];
+    current: Track | null;
+    loop: LoopMode;
+    volume: number;
+    paused: boolean;
+}
 declare class Player {
     private host;
     queue: Track[];
@@ -155,6 +169,9 @@ declare class Player {
     private maxPositionMs;
     /** Alternate-upload attempts spent on the current dead track. */
     private recoverAttempts;
+    /** Wall-clock time (ms) when the last PLAYER_UPDATE position was received.
+     * Used by the {@link positionMs} interpolating getter. */
+    private _positionTimestamp;
     constructor(host: PlayerHost, guildId: Snowflake);
     handleVoiceServerUpdate(data: VoiceServerUpdate): void;
     handleVoiceStateUpdate(data: VoiceStateUpdate): void;
@@ -180,8 +197,8 @@ declare class Player {
      * concurrent triggers — the idle check runs inside the serialized section, so
      * exactly one caller wins and the rest see `current !== null` and no-op. */
     private startIfIdle;
-    play(query: string | Track, requester?: number): Promise<Track[]>;
-    add(query: string | Track, requester?: number): Promise<Track[]>;
+    play(query: string | Track, requester?: Snowflake): Promise<Track[]>;
+    add(query: string | Track, requester?: Snowflake): Promise<Track[]>;
     skip(): Promise<void>;
     stop(): Promise<void>;
     pause(): Promise<void>;
@@ -198,18 +215,68 @@ declare class Player {
     /** Reorder the queue: move the track at `from` to `to`. No-op on bad indices. */
     move(from: number, to: number): void;
     /** Resolve `query` and insert it at `index` (clamped) instead of appending. */
-    insert(index: number, query: string | Track, requester?: number): Promise<Track[]>;
+    insert(index: number, query: string | Track, requester?: Snowflake): Promise<Track[]>;
     /** Batch-enqueue several queries/tracks in order. Failed resolves are skipped. */
-    addMany(queries: (string | Track)[], requester?: number): Promise<Track[]>;
+    addMany(queries: (string | Track)[], requester?: Snowflake): Promise<Track[]>;
     /** Skip forward to queue position `index`, discarding the ones in between. */
     jump(index: number): Promise<void>;
     /** Replay the previous track (from history), pushing the current one back on. */
     previous(): Promise<void>;
     /** Convenience EQ: bass boost in dB (0 clears). Built on {@link setFilters}. */
     setBassBoost(gainDb: number): Promise<void>;
-    /** Convenience speed/pitch (nightcore/vaporwave): `rate` 1.0 = normal. */
+    /** Convenience speed/pitch (nightcore/vaporwave): `rate` 1.0 = normal.
+     * Uses `atempo` for tempo and `asetrate` for pitch shift — both evaluated
+     * in JS so the filter string contains literal numbers, not expressions. */
     setSpeed(rate: number): Promise<void>;
     nowPlaying(): Track | null;
+    /** Enqueue a track or query to play immediately after the current one.
+     * Unlike `insert(0, ...)`, this is an explicit "play next" intent — it
+     * always inserts at position 0 regardless of queue state and starts
+     * playback if the player is idle. */
+    playNext(query: string | Track, requester?: Snowflake): Promise<Track[]>;
+    /** Remove all duplicate tracks from the queue (keeps first occurrence).
+     * Uniqueness is determined by `encoded` token. Returns the number removed. */
+    dedupe(): number;
+    /** Find all tracks in the queue whose title or author contains `query`
+     * (case-insensitive). Returns `[index, track]` pairs so callers can remove
+     * or jump to a result by index. */
+    find(query: string): [number, Track][];
+    /** Total duration of all queued tracks in milliseconds. Streams count as 0.
+     * Does not include the currently playing track. */
+    get totalDurationMs(): number;
+    /** Interpolated playback position in milliseconds. Between `PLAYER_UPDATE`
+     * frames this advances using wall-clock time so progress bars stay smooth.
+     * Returns 0 if nothing is playing or the player is paused. */
+    get positionMs(): number;
+    /** Serialize current queue, history, loop mode and volume into a plain object
+     * that can be JSON-stringified and stored. Restore with {@link Player.restore}. */
+    export(): SerializedPlayer;
+    /** Restore queue/history/loop/volume from a previously exported snapshot.
+     * Does NOT auto-start playback — call `startIfIdle()` or let the next
+     * voice event trigger it. */
+    restore(snapshot: SerializedPlayer): void;
+    /** Apply a named EQ preset. `"flat"` clears all filters.
+     *
+     * | preset      | effect                                     |
+     * |-------------|---------------------------------------------|
+     * | flat        | no filters (passthrough)                   |
+     * | bassboost   | heavy bass boost (+8 dB)                   |
+     * | soft        | gentle bass lift (+3 dB)                   |
+     * | nightcore   | speed+pitch up (1.3×)                      |
+     * | vaporwave   | speed+pitch down (0.8×)                    |
+     * | earrape     | extreme distortion / clipping (use wisely) |
+     * | treble      | high-frequency boost (+6 dB)               |
+     * | karaoke     | basic vocal removal                        |
+     */
+    setEqualizer(preset: EqPreset): Promise<void>;
+    /** Reverse the current queue order in-place. */
+    reverse(): void;
+    /** Remove all tracks from the queue that were requested by `requesterId`. */
+    removeBy(requesterId: Snowflake): number;
+    /** Peek at the next N tracks without mutating state. Defaults to 5. */
+    peek(n?: number): Track[];
+    /** Returns true if nothing is queued and nothing is playing. */
+    get idle(): boolean;
     disconnect(): Promise<void>;
     /** Append to history, evicting the oldest past `historyLimit` (leak guard). */
     private pushHistory;
@@ -268,6 +335,10 @@ interface ClientEvents {
         failed: Track;
         alternate: Track;
     }];
+    /** Emitted when a new Player is created via {@link Client.getPlayer}. */
+    playerCreated: [player: Player];
+    /** Emitted when a player is fully torn down via {@link Player.disconnect}. */
+    playerDestroyed: [guildId: bigint];
 }
 interface Client {
     on<K extends keyof ClientEvents>(event: K, listener: (...args: ClientEvents[K]) => void): this;
@@ -295,6 +366,13 @@ declare class Client extends EventEmitter implements PlayerHost {
     lastStats: Record<string, unknown> | null;
     constructor(baseUrl: string, token: string, opts?: ClientOptions);
     start(): Promise<void>;
+    /** Resolves once the client fires `ready` or `resumed`. If it is already
+     * connected it resolves on the next tick. Rejects after `timeoutMs` (default
+     * 30 s) so callers don't hang forever on a bad URL/token. */
+    waitForReady(timeoutMs?: number): Promise<void>;
+    /** Gracefully disconnect every active player then close the WebSocket.
+     * Prefer this over `close()` when you want clean backend teardown. */
+    destroy(): Promise<void>;
     close(): Promise<void>;
     /** Emit "error" without the Node EventEmitter footgun: an unlistened "error"
      * throws and would crash the host process, so fall back to a console warning. */
@@ -303,7 +381,8 @@ declare class Client extends EventEmitter implements PlayerHost {
     players(): Player[];
     dropPlayer(guildId: bigint): void;
     loadTracks(identifier: string): Promise<LoadResult>;
-    /** `ytsearch:`-prefix a bare query and return the hits (empty on miss). */
+    /** `ytsearch:`-prefix a bare query and return the hits. Throws `LoadError` on
+     * a server-side error so callers aren't silently handed an empty array. */
     search(query: string): Promise<Track[]>;
     private get wsUrl();
     private openSocket;
@@ -311,6 +390,7 @@ declare class Client extends EventEmitter implements PlayerHost {
      * position/volume/paused are accurate again. Per-player failures are ignored. */
     private resyncPlayers;
     private subscribeAll;
+    private subscribeGuild;
     private send;
     private handleFrame;
 }
@@ -338,4 +418,4 @@ declare class NotConnected extends AuralisError {
 declare class LoadError extends AuralisError {
 }
 
-export { APIError, AuralisError, AuthError, type AutoplayHook, Client, type ClientEvents, type ClientOptions, EndReason, LoadError, type LoadResult, LoadType, LoopMode, NotConnected, Player, type PlayerHost, type PlayerState, REST, RateLimited, type Snowflake, type Track, type VoiceServerUpdate, type VoiceStateUpdate, endReasonAdvances };
+export { APIError, AuralisError, AuthError, type AutoplayHook, Client, type ClientEvents, type ClientOptions, EndReason, type EqPreset, LoadError, type LoadResult, LoadType, LoopMode, NotConnected, Player, type PlayerHost, type PlayerState, REST, RateLimited, type SerializedPlayer, type Snowflake, type Track, type VoiceServerUpdate, type VoiceStateUpdate, endReasonAdvances };

package/dist/index.d.ts

@@ -118,6 +118,20 @@ interface PlayerHost {
     dropPlayer(guildId: bigint): void;
 }
 type AutoplayHook = (player: Player) => Promise<Track | null>;
+/** Named EQ presets accepted by {@link Player.setEqualizer}. */
+type EqPreset = "flat" | "bassboost" | "soft" | "nightcore" | "vaporwave" | "earrape" | "treble" | "karaoke";
+/** Portable snapshot of a player's queue state, produced by {@link Player.export}
+ * and consumed by {@link Player.restore}. Safe to JSON.stringify / store. */
+interface SerializedPlayer {
+    version: 1;
+    guildId: string;
+    queue: Track[];
+    history: Track[];
+    current: Track | null;
+    loop: LoopMode;
+    volume: number;
+    paused: boolean;
+}
 declare class Player {
     private host;
     queue: Track[];
@@ -155,6 +169,9 @@ declare class Player {
     private maxPositionMs;
     /** Alternate-upload attempts spent on the current dead track. */
     private recoverAttempts;
+    /** Wall-clock time (ms) when the last PLAYER_UPDATE position was received.
+     * Used by the {@link positionMs} interpolating getter. */
+    private _positionTimestamp;
     constructor(host: PlayerHost, guildId: Snowflake);
     handleVoiceServerUpdate(data: VoiceServerUpdate): void;
     handleVoiceStateUpdate(data: VoiceStateUpdate): void;
@@ -180,8 +197,8 @@ declare class Player {
      * concurrent triggers — the idle check runs inside the serialized section, so
      * exactly one caller wins and the rest see `current !== null` and no-op. */
     private startIfIdle;
-    play(query: string | Track, requester?: number): Promise<Track[]>;
-    add(query: string | Track, requester?: number): Promise<Track[]>;
+    play(query: string | Track, requester?: Snowflake): Promise<Track[]>;
+    add(query: string | Track, requester?: Snowflake): Promise<Track[]>;
     skip(): Promise<void>;
     stop(): Promise<void>;
     pause(): Promise<void>;
@@ -198,18 +215,68 @@ declare class Player {
     /** Reorder the queue: move the track at `from` to `to`. No-op on bad indices. */
     move(from: number, to: number): void;
     /** Resolve `query` and insert it at `index` (clamped) instead of appending. */
-    insert(index: number, query: string | Track, requester?: number): Promise<Track[]>;
+    insert(index: number, query: string | Track, requester?: Snowflake): Promise<Track[]>;
     /** Batch-enqueue several queries/tracks in order. Failed resolves are skipped. */
-    addMany(queries: (string | Track)[], requester?: number): Promise<Track[]>;
+    addMany(queries: (string | Track)[], requester?: Snowflake): Promise<Track[]>;
     /** Skip forward to queue position `index`, discarding the ones in between. */
     jump(index: number): Promise<void>;
     /** Replay the previous track (from history), pushing the current one back on. */
     previous(): Promise<void>;
     /** Convenience EQ: bass boost in dB (0 clears). Built on {@link setFilters}. */
     setBassBoost(gainDb: number): Promise<void>;
-    /** Convenience speed/pitch (nightcore/vaporwave): `rate` 1.0 = normal. */
+    /** Convenience speed/pitch (nightcore/vaporwave): `rate` 1.0 = normal.
+     * Uses `atempo` for tempo and `asetrate` for pitch shift — both evaluated
+     * in JS so the filter string contains literal numbers, not expressions. */
     setSpeed(rate: number): Promise<void>;
     nowPlaying(): Track | null;
+    /** Enqueue a track or query to play immediately after the current one.
+     * Unlike `insert(0, ...)`, this is an explicit "play next" intent — it
+     * always inserts at position 0 regardless of queue state and starts
+     * playback if the player is idle. */
+    playNext(query: string | Track, requester?: Snowflake): Promise<Track[]>;
+    /** Remove all duplicate tracks from the queue (keeps first occurrence).
+     * Uniqueness is determined by `encoded` token. Returns the number removed. */
+    dedupe(): number;
+    /** Find all tracks in the queue whose title or author contains `query`
+     * (case-insensitive). Returns `[index, track]` pairs so callers can remove
+     * or jump to a result by index. */
+    find(query: string): [number, Track][];
+    /** Total duration of all queued tracks in milliseconds. Streams count as 0.
+     * Does not include the currently playing track. */
+    get totalDurationMs(): number;
+    /** Interpolated playback position in milliseconds. Between `PLAYER_UPDATE`
+     * frames this advances using wall-clock time so progress bars stay smooth.
+     * Returns 0 if nothing is playing or the player is paused. */
+    get positionMs(): number;
+    /** Serialize current queue, history, loop mode and volume into a plain object
+     * that can be JSON-stringified and stored. Restore with {@link Player.restore}. */
+    export(): SerializedPlayer;
+    /** Restore queue/history/loop/volume from a previously exported snapshot.
+     * Does NOT auto-start playback — call `startIfIdle()` or let the next
+     * voice event trigger it. */
+    restore(snapshot: SerializedPlayer): void;
+    /** Apply a named EQ preset. `"flat"` clears all filters.
+     *
+     * | preset      | effect                                     |
+     * |-------------|---------------------------------------------|
+     * | flat        | no filters (passthrough)                   |
+     * | bassboost   | heavy bass boost (+8 dB)                   |
+     * | soft        | gentle bass lift (+3 dB)                   |
+     * | nightcore   | speed+pitch up (1.3×)                      |
+     * | vaporwave   | speed+pitch down (0.8×)                    |
+     * | earrape     | extreme distortion / clipping (use wisely) |
+     * | treble      | high-frequency boost (+6 dB)               |
+     * | karaoke     | basic vocal removal                        |
+     */
+    setEqualizer(preset: EqPreset): Promise<void>;
+    /** Reverse the current queue order in-place. */
+    reverse(): void;
+    /** Remove all tracks from the queue that were requested by `requesterId`. */
+    removeBy(requesterId: Snowflake): number;
+    /** Peek at the next N tracks without mutating state. Defaults to 5. */
+    peek(n?: number): Track[];
+    /** Returns true if nothing is queued and nothing is playing. */
+    get idle(): boolean;
     disconnect(): Promise<void>;
     /** Append to history, evicting the oldest past `historyLimit` (leak guard). */
     private pushHistory;
@@ -268,6 +335,10 @@ interface ClientEvents {
         failed: Track;
         alternate: Track;
     }];
+    /** Emitted when a new Player is created via {@link Client.getPlayer}. */
+    playerCreated: [player: Player];
+    /** Emitted when a player is fully torn down via {@link Player.disconnect}. */
+    playerDestroyed: [guildId: bigint];
 }
 interface Client {
     on<K extends keyof ClientEvents>(event: K, listener: (...args: ClientEvents[K]) => void): this;
@@ -295,6 +366,13 @@ declare class Client extends EventEmitter implements PlayerHost {
     lastStats: Record<string, unknown> | null;
     constructor(baseUrl: string, token: string, opts?: ClientOptions);
     start(): Promise<void>;
+    /** Resolves once the client fires `ready` or `resumed`. If it is already
+     * connected it resolves on the next tick. Rejects after `timeoutMs` (default
+     * 30 s) so callers don't hang forever on a bad URL/token. */
+    waitForReady(timeoutMs?: number): Promise<void>;
+    /** Gracefully disconnect every active player then close the WebSocket.
+     * Prefer this over `close()` when you want clean backend teardown. */
+    destroy(): Promise<void>;
     close(): Promise<void>;
     /** Emit "error" without the Node EventEmitter footgun: an unlistened "error"
      * throws and would crash the host process, so fall back to a console warning. */
@@ -303,7 +381,8 @@ declare class Client extends EventEmitter implements PlayerHost {
     players(): Player[];
     dropPlayer(guildId: bigint): void;
     loadTracks(identifier: string): Promise<LoadResult>;
-    /** `ytsearch:`-prefix a bare query and return the hits (empty on miss). */
+    /** `ytsearch:`-prefix a bare query and return the hits. Throws `LoadError` on
+     * a server-side error so callers aren't silently handed an empty array. */
     search(query: string): Promise<Track[]>;
     private get wsUrl();
     private openSocket;
@@ -311,6 +390,7 @@ declare class Client extends EventEmitter implements PlayerHost {
      * position/volume/paused are accurate again. Per-player failures are ignored. */
     private resyncPlayers;
     private subscribeAll;
+    private subscribeGuild;
     private send;
     private handleFrame;
 }
@@ -338,4 +418,4 @@ declare class NotConnected extends AuralisError {
 declare class LoadError extends AuralisError {
 }
 
-export { APIError, AuralisError, AuthError, type AutoplayHook, Client, type ClientEvents, type ClientOptions, EndReason, LoadError, type LoadResult, LoadType, LoopMode, NotConnected, Player, type PlayerHost, type PlayerState, REST, RateLimited, type Snowflake, type Track, type VoiceServerUpdate, type VoiceStateUpdate, endReasonAdvances };
+export { APIError, AuralisError, AuthError, type AutoplayHook, Client, type ClientEvents, type ClientOptions, EndReason, type EqPreset, LoadError, type LoadResult, LoadType, LoopMode, NotConnected, Player, type PlayerHost, type PlayerState, REST, RateLimited, type SerializedPlayer, type Snowflake, type Track, type VoiceServerUpdate, type VoiceStateUpdate, endReasonAdvances };

package/dist/index.js

@@ -27,12 +27,12 @@ var LoadError = class extends AuralisError {
 };
 
 // src/types.ts
-var BIG_TAG = "__BIG__";
+var BIG_TAG = "||BIGINT||";
 function snowflakeStringify(obj) {
   return JSON.stringify(
     obj,
     (_k, v) => typeof v === "bigint" ? `${BIG_TAG}${v}${BIG_TAG}` : v
-  ).replace(new RegExp(`"${BIG_TAG}(\\d+)${BIG_TAG}"`, "g"), "$1");
+  ).replace(/"\|\|BIGINT\|\|(\d+)\|\|BIGINT\|\|"/g, "$1");
 }
 var LoopMode = /* @__PURE__ */ ((LoopMode2) => {
   LoopMode2["Off"] = "off";
@@ -141,6 +141,9 @@ var Player = class {
   maxPositionMs = 0;
   /** Alternate-upload attempts spent on the current dead track. */
   recoverAttempts = 0;
+  /** Wall-clock time (ms) when the last PLAYER_UPDATE position was received.
+   * Used by the {@link positionMs} interpolating getter. */
+  _positionTimestamp = 0;
   // --- voice plumbing ---------------------------------------------------
   handleVoiceServerUpdate(data) {
     this.voiceServer = { token: data.token, endpoint: data.endpoint };
@@ -166,6 +169,7 @@ var Player = class {
    * spotted, and clears the recovery counter once a track is genuinely playing. */
   applyState(state) {
     this.state = state;
+    this._positionTimestamp = Date.now();
     if (state.positionMs > this.maxPositionMs) this.maxPositionMs = state.positionMs;
     if (this.maxPositionMs > this.deadStreamThresholdMs) this.recoverAttempts = 0;
   }
@@ -314,6 +318,7 @@ var Player = class {
     const prev = this.history.pop();
     if (!prev) return;
     if (this.current !== null) this.queue.unshift(this.current);
+    this.current = null;
     this.queue.unshift(prev);
     await this.advance(true);
   }
@@ -321,17 +326,139 @@ var Player = class {
   async setBassBoost(gainDb) {
     await this.setFilters(gainDb === 0 ? null : `bass=g=${gainDb}`);
   }
-  /** Convenience speed/pitch (nightcore/vaporwave): `rate` 1.0 = normal. */
+  /** Convenience speed/pitch (nightcore/vaporwave): `rate` 1.0 = normal.
+   * Uses `atempo` for tempo and `asetrate` for pitch shift — both evaluated
+   * in JS so the filter string contains literal numbers, not expressions. */
   async setSpeed(rate) {
     const r = Math.max(0.5, Math.min(2, rate));
-    await this.setFilters(r === 1 ? null : `atempo=${r},asetrate=48000*${r}`);
+    await this.setFilters(r === 1 ? null : `atempo=${r},asetrate=${48e3 * r}`);
   }
   nowPlaying() {
     return this.current;
   }
+  /** Enqueue a track or query to play immediately after the current one.
+   * Unlike `insert(0, ...)`, this is an explicit "play next" intent — it
+   * always inserts at position 0 regardless of queue state and starts
+   * playback if the player is idle. */
+  async playNext(query, requester) {
+    return this.insert(0, query, requester);
+  }
+  /** Remove all duplicate tracks from the queue (keeps first occurrence).
+   * Uniqueness is determined by `encoded` token. Returns the number removed. */
+  dedupe() {
+    const seen = /* @__PURE__ */ new Set();
+    const before = this.queue.length;
+    this.queue = this.queue.filter((t) => {
+      if (seen.has(t.encoded)) return false;
+      seen.add(t.encoded);
+      return true;
+    });
+    return before - this.queue.length;
+  }
+  /** Find all tracks in the queue whose title or author contains `query`
+   * (case-insensitive). Returns `[index, track]` pairs so callers can remove
+   * or jump to a result by index. */
+  find(query) {
+    const q = query.toLowerCase();
+    return this.queue.reduce((acc, t, i) => {
+      if (t.title.toLowerCase().includes(q) || t.author.toLowerCase().includes(q)) {
+        acc.push([i, t]);
+      }
+      return acc;
+    }, []);
+  }
+  /** Total duration of all queued tracks in milliseconds. Streams count as 0.
+   * Does not include the currently playing track. */
+  get totalDurationMs() {
+    return this.queue.reduce((sum, t) => sum + (t.isStream ? 0 : t.lengthMs), 0);
+  }
+  /** Interpolated playback position in milliseconds. Between `PLAYER_UPDATE`
+   * frames this advances using wall-clock time so progress bars stay smooth.
+   * Returns 0 if nothing is playing or the player is paused. */
+  get positionMs() {
+    if (!this.state.playing || this.state.paused) return this.state.positionMs;
+    const elapsed = Date.now() - this._positionTimestamp;
+    return Math.min(
+      this.state.positionMs + elapsed,
+      this.current?.lengthMs ?? this.state.positionMs + elapsed
+    );
+  }
+  /** Serialize current queue, history, loop mode and volume into a plain object
+   * that can be JSON-stringified and stored. Restore with {@link Player.restore}. */
+  export() {
+    return {
+      version: 1,
+      guildId: String(this.guildId),
+      queue: this.queue.map((t) => ({ ...t })),
+      history: this.history.map((t) => ({ ...t })),
+      current: this.current ? { ...this.current } : null,
+      loop: this.loop,
+      volume: this.volume,
+      paused: this.paused
+    };
+  }
+  /** Restore queue/history/loop/volume from a previously exported snapshot.
+   * Does NOT auto-start playback — call `startIfIdle()` or let the next
+   * voice event trigger it. */
+  restore(snapshot) {
+    this.queue = snapshot.queue.map((t) => ({ ...t }));
+    this.history = snapshot.history.map((t) => ({ ...t }));
+    this.current = snapshot.current ? { ...snapshot.current } : null;
+    this.loop = snapshot.loop;
+    this.volume = snapshot.volume;
+    this.paused = snapshot.paused;
+  }
+  /** Apply a named EQ preset. `"flat"` clears all filters.
+   *
+   * | preset      | effect                                     |
+   * |-------------|---------------------------------------------|
+   * | flat        | no filters (passthrough)                   |
+   * | bassboost   | heavy bass boost (+8 dB)                   |
+   * | soft        | gentle bass lift (+3 dB)                   |
+   * | nightcore   | speed+pitch up (1.3×)                      |
+   * | vaporwave   | speed+pitch down (0.8×)                    |
+   * | earrape     | extreme distortion / clipping (use wisely) |
+   * | treble      | high-frequency boost (+6 dB)               |
+   * | karaoke     | basic vocal removal                        |
+   */
+  async setEqualizer(preset) {
+    const graphs = {
+      flat: null,
+      bassboost: "bass=g=8",
+      soft: "bass=g=3",
+      nightcore: `atempo=1.3,asetrate=${Math.round(48e3 * 1.3)}`,
+      vaporwave: `atempo=0.8,asetrate=${Math.round(48e3 * 0.8)}`,
+      earrape: "acrusher=level_in=8:level_out=18:bits=8:mode=log:aa=1",
+      treble: "treble=g=6",
+      karaoke: "pan=stereo|c0=c0-c1|c1=c1-c0"
+    };
+    await this.setFilters(graphs[preset]);
+  }
+  /** Reverse the current queue order in-place. */
+  reverse() {
+    this.queue.reverse();
+  }
+  /** Remove all tracks from the queue that were requested by `requesterId`. */
+  removeBy(requesterId) {
+    const id = String(requesterId);
+    const before = this.queue.length;
+    this.queue = this.queue.filter((t) => String(t.extras.requester) !== id);
+    return before - this.queue.length;
+  }
+  /** Peek at the next N tracks without mutating state. Defaults to 5. */
+  peek(n = 5) {
+    return this.queue.slice(0, n);
+  }
+  /** Returns true if nothing is queued and nothing is playing. */
+  get idle() {
+    return this.current === null && this.queue.length === 0;
+  }
   async disconnect() {
     this.queue = [];
     this.current = null;
+    this.history = [];
+    this.paused = false;
+    this.volume = 100;
     if (this.created) await this.host.rest.destroyPlayer(this.guildId);
     this.created = false;
     this.voiceServer = null;
@@ -469,7 +596,7 @@ var Player = class {
 };
 
 // src/rest.ts
-var DEFAULT_TIMEOUT_MS = 8e3;
+var DEFAULT_TIMEOUT_MS = 16e3;
 var RETRYABLE_STATUS = /* @__PURE__ */ new Set([502, 503]);
 var BACKOFF_MS = [200, 500];
 var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
@@ -630,6 +757,38 @@ var Client = class extends EventEmitter {
     this.closed = false;
     this.openSocket();
   }
+  /** Resolves once the client fires `ready` or `resumed`. If it is already
+   * connected it resolves on the next tick. Rejects after `timeoutMs` (default
+   * 30 s) so callers don't hang forever on a bad URL/token. */
+  waitForReady(timeoutMs = 3e4) {
+    return new Promise((resolve, reject) => {
+      if (this.hasConnected) {
+        resolve();
+        return;
+      }
+      const onReady = () => {
+        clearTimeout(timer);
+        resolve();
+      };
+      const onResumed = () => {
+        clearTimeout(timer);
+        resolve();
+      };
+      const timer = setTimeout(() => {
+        this.off("ready", onReady);
+        this.off("resumed", onResumed);
+        reject(new Error("[auralis] waitForReady timed out"));
+      }, timeoutMs);
+      this.once("ready", onReady);
+      this.once("resumed", onResumed);
+    });
+  }
+  /** Gracefully disconnect every active player then close the WebSocket.
+   * Prefer this over `close()` when you want clean backend teardown. */
+  async destroy() {
+    await Promise.allSettled(this.players().map((p) => p.disconnect()));
+    await this.close();
+  }
   async close() {
     this.closed = true;
     if (this.heartbeatTimer) {
@@ -657,6 +816,8 @@ var Client = class extends EventEmitter {
     if (!p) {
       p = new Player(this, id);
       this.playersMap.set(id, p);
+      this.subscribeGuild(id);
+      this.emit("playerCreated", p);
     }
     return p;
   }
@@ -665,16 +826,22 @@ var Client = class extends EventEmitter {
   }
   dropPlayer(guildId) {
     this.playersMap.delete(guildId);
+    this.emit("playerDestroyed", guildId);
   }
   // --- metadata convenience --------------------------------------------
   loadTracks(identifier) {
     return this.rest.loadTracks(identifier);
   }
-  /** `ytsearch:`-prefix a bare query and return the hits (empty on miss). */
+  /** `ytsearch:`-prefix a bare query and return the hits. Throws `LoadError` on
+   * a server-side error so callers aren't silently handed an empty array. */
   async search(query) {
     const first = query.split(" ", 1)[0];
     const ident = first.includes(":") ? query : `ytsearch:${query}`;
-    return (await this.loadTracks(ident)).tracks;
+    const result = await this.loadTracks(ident);
+    if (result.loadType === "error" /* Error */) {
+      throw new LoadError(result.error ?? `search failed for: ${query}`);
+    }
+    return result.tracks;
   }
   // --- websocket --------------------------------------------------------
   get wsUrl() {
@@ -733,6 +900,14 @@ var Client = class extends EventEmitter {
       });
     }
   }
+  subscribeGuild(guildId) {
+    if (this.ws?.readyState === WebSocket.OPEN) {
+      this.send({
+        op: "SUBSCRIBE",
+        d: { guilds: [String(guildId)] }
+      });
+    }
+  }
   send(payload) {
     if (this.ws?.readyState === WebSocket.OPEN) this.ws.send(JSON.stringify(payload));
   }
@@ -768,6 +943,9 @@ var Client = class extends EventEmitter {
     }
     if (op === "STATS") {
       this.lastStats = d;
+      const eventName2 = EVENT_OPS[op];
+      if (eventName2) this.emit(eventName2, null, d);
+      return;
     }
     const guildId = d.guild_id != null ? BigInt(d.guild_id) : null;
     const player = guildId !== null ? this.playersMap.get(guildId) : void 0;