auralis-sdk 0.4.3 → 0.5.1

package/dist/index.cjs

@@ -75,12 +75,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";
@@ -189,6 +189,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 };
@@ -214,6 +217,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;
   }
@@ -362,6 +366,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);
   }
@@ -369,17 +374,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;
@@ -410,10 +537,13 @@ var Player = class {
       if (this.current !== null) this.pushHistory(this.current);
       return this.queue.shift();
     }
-    if (this.loop === "queue" /* Queue */ && this.history.length > 0) {
-      this.queue = [...this.history, ...this.current ? [this.current] : []];
-      this.history = [];
-      return this.queue.shift() ?? null;
+    if (this.loop === "queue" /* Queue */) {
+      const cycle = [...this.history, ...this.current ? [this.current] : []];
+      if (cycle.length > 0) {
+        this.queue = cycle;
+        this.history = [];
+        return this.queue.shift() ?? null;
+      }
     }
     if (this.autoplay !== null) return this.autoplay(this);
     return null;
@@ -425,14 +555,27 @@ var Player = class {
     return this.serialize(() => this.advanceInner(forced));
   }
   async advanceInner(forced = false) {
-    const next = await this.nextTrack(forced);
-    if (next === null) {
-      this.current = null;
-      if (this.created) await this.host.rest.stop(this.guildId);
-      this.host.emit("queueEnd", this);
-      return;
+    for (let attempts = this.queue.length + 1; attempts >= 0; attempts--) {
+      const next = await this.nextTrack(forced);
+      if (next === null) {
+        this.current = null;
+        if (this.created) await this.host.rest.stop(this.guildId);
+        this.host.emit("queueEnd", this);
+        return;
+      }
+      try {
+        await this.playTrack(next);
+        return;
+      } catch (e) {
+        if (e instanceof NotConnected) {
+          this.queue.unshift(next);
+          throw e;
+        }
+        this.current = null;
+        forced = true;
+        this.host.emit("trackException", this, { track: next, error: String(e) });
+      }
     }
-    await this.playTrack(next);
   }
   async playTrack(track) {
     if (!this.connected) throw new NotConnected(`guild ${this.guildId} has no voice connection`);
@@ -678,6 +821,38 @@ var Client = class extends import_node_events.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) {
@@ -705,6 +880,8 @@ var Client = class extends import_node_events.EventEmitter {
     if (!p) {
       p = new Player(this, id);
       this.playersMap.set(id, p);
+      this.subscribeGuild(id);
+      this.emit("playerCreated", p);
     }
     return p;
   }
@@ -713,16 +890,22 @@ var Client = class extends import_node_events.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() {
@@ -781,6 +964,14 @@ var Client = class extends import_node_events.EventEmitter {
       });
     }
   }
+  subscribeGuild(guildId) {
+    if (this.ws?.readyState === import_ws.default.OPEN) {
+      this.send({
+        op: "SUBSCRIBE",
+        d: { guilds: [String(guildId)] }
+      });
+    }
+  }
   send(payload) {
     if (this.ws?.readyState === import_ws.default.OPEN) this.ws.send(JSON.stringify(payload));
   }
@@ -816,6 +1007,9 @@ var Client = class extends import_node_events.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;