enerthya.dev-audio-server 1.0.0

package/README.md

@@ -0,0 +1,5 @@
+# enerthya.dev-audio-server
+
+Part of the Enerthya audio system.
+
+See `src/index.js` for full API documentation.

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "enerthya.dev-audio-server",
+  "version": "1.0.0",
+  "description": "Enerthya Audio Server \u2014 Lavalink-compatible WebSocket audio server in Node.js. Uses enerthya.dev-audio-core for stream processing. Runs on port 80 (Shardcloud compatible).",
+  "main": "src/index.js",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "enerthya",
+    "audio",
+    "server",
+    "lavalink",
+    "websocket"
+  ],
+  "dependencies": {
+    "enerthya.dev-audio-core": "1.0.0",
+    "ws": "^8.18.0"
+  },
+  "scripts": {
+    "test": "node test.js"
+  }
+}

package/src/constants/index.js

@@ -0,0 +1,61 @@
+/**
+ * constants/index.js — Protocolo WebSocket do enerthya.dev-audio-server
+ * Compatível com o protocolo do Lavalink v4.
+ */
+
+// Opcodes Server → Client
+const Op = {
+  READY:         "ready",         // servidor pronto, retorna sessionId
+  PLAYER_UPDATE: "playerUpdate",  // posição atual + estado do player
+  STATS:         "stats",         // estatísticas do servidor
+  EVENT:         "event",         // eventos de track
+
+  // Opcodes Client → Server
+  PLAY:          "play",
+  STOP:          "stop",
+  PAUSE:         "pause",
+  SEEK:          "seek",
+  VOLUME:        "volume",
+  SKIP:          "skip",
+  QUEUE_ADD:     "queueAdd",
+  QUEUE_REMOVE:  "queueRemove",
+  QUEUE_CLEAR:   "queueClear",
+  QUEUE_SHUFFLE: "queueShuffle",
+  QUEUE_GET:     "queueGet",
+  DESTROY:       "destroy",
+  SEARCH:        "search",
+  LOAD:          "load",
+};
+
+const TrackEvent = {
+  START:     "TrackStartEvent",
+  END:       "TrackEndEvent",
+  EXCEPTION: "TrackExceptionEvent",
+  STUCK:     "TrackStuckEvent",
+};
+
+const EndReason = {
+  FINISHED:    "finished",
+  LOAD_FAILED: "loadFailed",
+  STOPPED:     "stopped",
+  REPLACED:    "replaced",
+  CLEANUP:     "cleanup",
+};
+
+const PlayerState = {
+  IDLE:    "IDLE",
+  PLAYING: "PLAYING",
+  PAUSED:  "PAUSED",
+  LOADING: "LOADING",
+};
+
+const Defaults = {
+  PORT:                    2333,
+  PASSWORD:                "enerthya",
+  VOLUME:                  100,
+  MAX_QUEUE_SIZE:          500,
+  STATS_INTERVAL_MS:       60_000,
+  PLAYER_UPDATE_MS:        5_000,
+};
+
+module.exports = { Op, TrackEvent, EndReason, PlayerState, Defaults };

package/src/index.js

@@ -0,0 +1,29 @@
+/**
+ * enerthya.dev-audio-server
+ *
+ * Servidor de áudio WebSocket da Enerthya.
+ * Equivalente ao Lavalink (Java) — implementado em Node.js.
+ *
+ * Uso standalone:
+ *   const { AudioServer } = require("enerthya.dev-audio-server");
+ *   new AudioServer({ password: "minha-senha", port: 2333 });
+ *
+ * Uso integrado na dashboard (porta 80 existente):
+ *   const { AudioServer } = require("enerthya.dev-audio-server");
+ *   new AudioServer({ password: process.env.AUDIO_PASSWORD, httpServer: expressApp });
+ */
+
+const { AudioServer }  = require("./server/AudioServer");
+const { GuildPlayer, RepeatMode } = require("./queue/GuildPlayer");
+const { Op, TrackEvent, EndReason, PlayerState, Defaults } = require("./constants");
+
+module.exports = {
+  AudioServer,
+  GuildPlayer,
+  RepeatMode,
+  Op,
+  TrackEvent,
+  EndReason,
+  PlayerState,
+  Defaults,
+};

package/src/queue/GuildPlayer.js

@@ -0,0 +1,238 @@
+/**
+ * queue/GuildPlayer.js — Player e fila por guild
+ *
+ * Gerencia estado de reprodução, fila de tracks e decode
+ * para uma guild específica. Usa enerthya.dev-audio-core para streams.
+ */
+
+const { EventEmitter } = require("events");
+const { AudioDecoder } = require("enerthya.dev-audio-core");
+const { PlayerState, EndReason, Defaults } = require("../constants");
+
+const RepeatMode = { NONE: "none", TRACK: "track", QUEUE: "queue" };
+
+class GuildPlayer extends EventEmitter {
+  /**
+   * @param {string} guildId
+   * @param {object} server — referência ao AudioServer
+   */
+  constructor(guildId, server) {
+    super();
+    this.guildId  = guildId;
+    this.server   = server;
+
+    this.queue    = [];
+    this.current  = null;
+    this.state    = PlayerState.IDLE;
+    this.repeat   = RepeatMode.NONE;
+    this.volume   = Defaults.VOLUME;
+    this.position = 0;
+    this.paused   = false;
+
+    this._decoder    = new AudioDecoder();
+    this._startedAt  = null;
+    this._pausedAt   = null;
+    this._updateInterval = null;
+
+    // Eventos do decoder
+    this._decoder.on("end",   ()    => this._onTrackEnd());
+    this._decoder.on("error", (err) => this._onTrackError(err));
+    this._decoder.on("data",  (chunk) => this.emit("audioData", chunk));
+  }
+
+  // ── Controles ─────────────────────────────────────────────────────────────
+
+  async play(track, opts = {}) {
+    if (!track) return;
+
+    this.state   = PlayerState.LOADING;
+    this.current = track;
+    this.position = opts.startTime || 0;
+
+    this.emit("trackStart", track);
+
+    try {
+      const { getAudioStream } = require("enerthya.dev-audio-core");
+      const stream = await getAudioStream(track);
+
+      this._decoder.start(stream, {
+        seek:   this.position,
+        volume: this.volume,
+      });
+
+      this.state      = PlayerState.PLAYING;
+      this.paused     = false;
+      this._startedAt = Date.now() - this.position;
+      this._startUpdateInterval();
+
+    } catch (err) {
+      this.state = PlayerState.IDLE;
+      this.emit("trackException", track, err.message);
+      this._playNext();
+    }
+  }
+
+  pause() {
+    if (this.state !== PlayerState.PLAYING) return;
+    this._decoder.stop();
+    this.paused    = true;
+    this.state     = PlayerState.PAUSED;
+    this._pausedAt = Date.now();
+    this._stopUpdateInterval();
+  }
+
+  resume() {
+    if (!this.paused || !this.current) return;
+    const pauseDuration = Date.now() - (this._pausedAt || Date.now());
+    this._startedAt = (this._startedAt || Date.now()) + pauseDuration;
+    this.paused  = false;
+    this.play(this.current, { startTime: this.position });
+  }
+
+  stop() {
+    this._decoder.stop();
+    this._stopUpdateInterval();
+    this.state    = PlayerState.IDLE;
+    this.current  = null;
+    this.position = 0;
+    this.paused   = false;
+    this.emit("playerStop");
+  }
+
+  skip() {
+    this._decoder.stop();
+    this._onTrackEnd(EndReason.REPLACED);
+  }
+
+  seek(positionMs) {
+    if (!this.current) return;
+    this.position = positionMs;
+    this._startedAt = Date.now() - positionMs;
+    const currentTrack = this.current;
+    this._decoder.stop();
+    this.play(currentTrack, { startTime: positionMs });
+  }
+
+  setVolume(vol) {
+    this.volume = Math.max(0, Math.min(1000, vol));
+    // Reinicia o decoder com novo volume se estiver tocando
+    if (this.state === PlayerState.PLAYING && this.current) {
+      const track = this.current;
+      const pos   = this.getPosition();
+      this._decoder.stop();
+      this.play(track, { startTime: pos });
+    }
+  }
+
+  // ── Fila ──────────────────────────────────────────────────────────────────
+
+  addToQueue(track) {
+    if (this.queue.length >= Defaults.MAX_QUEUE_SIZE) return false;
+    const toAdd = Array.isArray(track) ? track : [track];
+    this.queue.push(...toAdd.slice(0, Defaults.MAX_QUEUE_SIZE - this.queue.length));
+    return true;
+  }
+
+  removeFromQueue(index) {
+    if (index < 0 || index >= this.queue.length) return null;
+    return this.queue.splice(index, 1)[0];
+  }
+
+  clearQueue() {
+    this.queue = [];
+  }
+
+  shuffleQueue() {
+    for (let i = this.queue.length - 1; i > 0; i--) {
+      const j = Math.floor(Math.random() * (i + 1));
+      [this.queue[i], this.queue[j]] = [this.queue[j], this.queue[i]];
+    }
+  }
+
+  setRepeat(mode) {
+    if (Object.values(RepeatMode).includes(mode)) this.repeat = mode;
+  }
+
+  // ── Posição ───────────────────────────────────────────────────────────────
+
+  getPosition() {
+    if (!this._startedAt || this.paused) return this.position;
+    return Date.now() - this._startedAt;
+  }
+
+  // ── Internos ──────────────────────────────────────────────────────────────
+
+  _onTrackEnd(reason = EndReason.FINISHED) {
+    this._stopUpdateInterval();
+    const ended = this.current;
+
+    if (this.repeat === RepeatMode.TRACK && ended && reason === EndReason.FINISHED) {
+      this.play(ended);
+      return;
+    }
+
+    this.emit("trackEnd", ended, reason);
+    this._playNext();
+  }
+
+  _onTrackError(err) {
+    this._stopUpdateInterval();
+    this.emit("trackException", this.current, err.message);
+    this._playNext();
+  }
+
+  _playNext() {
+    if (this.queue.length === 0) {
+      this.state   = PlayerState.IDLE;
+      this.current = null;
+      this.emit("queueEnd");
+      return;
+    }
+
+    const next = this.queue.shift();
+
+    // Modo repeat queue — coloca a track anterior no fim
+    if (this.repeat === RepeatMode.QUEUE && this.current) {
+      this.queue.push(this.current);
+    }
+
+    this.play(next);
+  }
+
+  _startUpdateInterval() {
+    this._stopUpdateInterval();
+    this._updateInterval = setInterval(() => {
+      this.position = this.getPosition();
+      this.emit("playerUpdate", { position: this.position, state: this.state });
+    }, Defaults.PLAYER_UPDATE_MS);
+    if (this._updateInterval.unref) this._updateInterval.unref();
+  }
+
+  _stopUpdateInterval() {
+    if (this._updateInterval) {
+      clearInterval(this._updateInterval);
+      this._updateInterval = null;
+    }
+  }
+
+  destroy() {
+    this.stop();
+    this._decoder.removeAllListeners();
+    this.removeAllListeners();
+  }
+
+  toJSON() {
+    return {
+      guildId:  this.guildId,
+      state:    this.state,
+      current:  this.current,
+      queue:    this.queue,
+      repeat:   this.repeat,
+      volume:   this.volume,
+      position: this.getPosition(),
+      paused:   this.paused,
+    };
+  }
+}
+
+module.exports = { GuildPlayer, RepeatMode };

package/src/server/AudioServer.js

@@ -0,0 +1,344 @@
+/**
+ * server/AudioServer.js — Servidor WebSocket de áudio
+ *
+ * Equivalente ao servidor Lavalink em Java, mas em Node.js.
+ * Aceita conexões WebSocket de bots Discord autenticados por senha.
+ * Cada conexão representa um bot (identificado pelo userId do bot).
+ *
+ * Protocolo:
+ *   - Autenticação via header "Authorization" na abertura do WS
+ *   - Mensagens JSON com campo "op" definindo a operação
+ *   - Compatível com o protocolo do Lavalink v4
+ */
+
+const { WebSocketServer, WebSocket } = require("ws");
+const crypto   = require("crypto");
+const { GuildPlayer } = require("../queue/GuildPlayer");
+const { Op, TrackEvent, EndReason, PlayerState, Defaults } = require("../constants");
+const { loadItem } = require("enerthya.dev-audio-core");
+
+class AudioServer {
+  /**
+   * @param {object} opts
+   * @param {string}        [opts.password]       — senha de autenticação (padrão: "enerthya")
+   * @param {http.Server}   [opts.httpServer]      — servidor HTTP existente para attach (porta 80)
+   * @param {number}        [opts.port]            — porta standalone (padrão: 2333)
+   * @param {Function}      [opts.logger]          — função de log (padrão: console.log)
+   */
+  constructor(opts = {}) {
+    this.password  = opts.password || process.env.AUDIO_PASSWORD || Defaults.PASSWORD;
+    this.logger    = opts.logger   || console.log;
+
+    // sessions: sessionId → { ws, userId, players: Map<guildId, GuildPlayer> }
+    this.sessions  = new Map();
+
+    // Cria o WebSocket server
+    if (opts.httpServer) {
+      // Attach no servidor HTTP existente (porta 80 da dashboard)
+      this.wss = new WebSocketServer({ server: opts.httpServer, path: "/audio" });
+    } else {
+      // Standalone
+      const port = opts.port || Defaults.PORT;
+      this.wss = new WebSocketServer({ port, path: "/audio" });
+      this.logger(`[AudioServer] Rodando standalone na porta ${port}`);
+    }
+
+    this._setupWss();
+    this._startStatsInterval();
+  }
+
+  // ── Setup WebSocket ────────────────────────────────────────────────────────
+
+  _setupWss() {
+    this.wss.on("connection", (ws, req) => {
+      // Autenticação via header Authorization
+      const auth = req.headers["authorization"];
+      if (auth !== this.password) {
+        ws.close(4001, "Unauthorized");
+        return;
+      }
+
+      const userId    = req.headers["user-id"] || "unknown";
+      const sessionId = crypto.randomBytes(8).toString("hex");
+
+      const session = {
+        ws,
+        userId,
+        sessionId,
+        players: new Map(),
+        connectedAt: Date.now(),
+      };
+
+      this.sessions.set(sessionId, session);
+      this.logger(`[AudioServer] Conexão estabelecida — userId: ${userId} sessionId: ${sessionId}`);
+
+      // Envia READY
+      this._send(ws, {
+        op:        Op.READY,
+        resumed:   false,
+        sessionId,
+      });
+
+      ws.on("message", (data) => {
+        try {
+          const msg = JSON.parse(data.toString());
+          this._handleMessage(session, msg);
+        } catch (err) {
+          this.logger(`[AudioServer] Mensagem inválida: ${err.message}`);
+        }
+      });
+
+      ws.on("close", () => {
+        this.logger(`[AudioServer] Conexão encerrada — sessionId: ${sessionId}`);
+        // Destroi todos os players desta sessão
+        for (const player of session.players.values()) {
+          player.destroy();
+        }
+        this.sessions.delete(sessionId);
+      });
+
+      ws.on("error", (err) => {
+        this.logger(`[AudioServer] Erro WS — ${err.message}`);
+      });
+    });
+  }
+
+  // ── Handler de mensagens ───────────────────────────────────────────────────
+
+  async _handleMessage(session, msg) {
+    const { op, guildId } = msg;
+    if (!op) return;
+
+    switch (op) {
+
+      case Op.LOAD: {
+        const result = await loadItem(msg.query, {
+          limit:        msg.limit || 1,
+          requesterId:  session.userId,
+        }).catch((err) => ({ loadType: "error", tracks: [], error: err.message }));
+        this._send(session.ws, { op: "loadResult", guildId, result });
+        break;
+      }
+
+      case Op.SEARCH: {
+        const result = await loadItem(msg.query, {
+          limit: msg.limit || 5,
+          requesterId: session.userId,
+        }).catch(() => ({ loadType: "empty", tracks: [] }));
+        this._send(session.ws, { op: "searchResult", guildId, result });
+        break;
+      }
+
+      case Op.PLAY: {
+        if (!guildId || !msg.track) return;
+        const player = this._getOrCreatePlayer(session, guildId);
+
+        if (msg.noReplace && player.state === PlayerState.PLAYING) return;
+
+        // Adiciona à fila ou toca imediatamente
+        if (msg.addToQueue && (player.state === PlayerState.PLAYING || player.queue.length > 0)) {
+          player.addToQueue(msg.track);
+          this._send(session.ws, { op: "queueUpdated", guildId, queue: player.queue });
+        } else {
+          if (msg.track) {
+            player.clearQueue();
+            await player.play(msg.track, { startTime: msg.startTime || 0 });
+          }
+        }
+        break;
+      }
+
+      case Op.QUEUE_ADD: {
+        if (!guildId || !msg.track) return;
+        const player = this._getOrCreatePlayer(session, guildId);
+        player.addToQueue(msg.track);
+        this._send(session.ws, { op: "queueUpdated", guildId, queue: player.queue });
+        break;
+      }
+
+      case Op.STOP: {
+        const player = session.players.get(guildId);
+        if (player) player.stop();
+        break;
+      }
+
+      case Op.PAUSE: {
+        const player = session.players.get(guildId);
+        if (!player) return;
+        msg.pause ? player.pause() : player.resume();
+        this._send(session.ws, {
+          op: Op.PLAYER_UPDATE, guildId,
+          state: { position: player.getPosition(), paused: player.paused },
+        });
+        break;
+      }
+
+      case Op.SEEK: {
+        const player = session.players.get(guildId);
+        if (player && msg.position !== undefined) player.seek(msg.position);
+        break;
+      }
+
+      case Op.VOLUME: {
+        const player = session.players.get(guildId);
+        if (player && msg.volume !== undefined) player.setVolume(msg.volume);
+        break;
+      }
+
+      case Op.SKIP: {
+        const player = session.players.get(guildId);
+        if (player) player.skip();
+        break;
+      }
+
+      case Op.QUEUE_REMOVE: {
+        const player = session.players.get(guildId);
+        if (player && msg.index !== undefined) {
+          player.removeFromQueue(msg.index);
+          this._send(session.ws, { op: "queueUpdated", guildId, queue: player.queue });
+        }
+        break;
+      }
+
+      case Op.QUEUE_CLEAR: {
+        const player = session.players.get(guildId);
+        if (player) {
+          player.clearQueue();
+          this._send(session.ws, { op: "queueUpdated", guildId, queue: [] });
+        }
+        break;
+      }
+
+      case Op.QUEUE_SHUFFLE: {
+        const player = session.players.get(guildId);
+        if (player) {
+          player.shuffleQueue();
+          this._send(session.ws, { op: "queueUpdated", guildId, queue: player.queue });
+        }
+        break;
+      }
+
+      case Op.QUEUE_GET: {
+        const player = session.players.get(guildId);
+        this._send(session.ws, {
+          op: "queueResult",
+          guildId,
+          player: player ? player.toJSON() : null,
+        });
+        break;
+      }
+
+      case Op.DESTROY: {
+        const player = session.players.get(guildId);
+        if (player) {
+          player.destroy();
+          session.players.delete(guildId);
+        }
+        break;
+      }
+    }
+  }
+
+  // ── Player helpers ─────────────────────────────────────────────────────────
+
+  _getOrCreatePlayer(session, guildId) {
+    if (session.players.has(guildId)) return session.players.get(guildId);
+
+    const player = new GuildPlayer(guildId, this);
+
+    // Eventos do player → mensagens WS para o client
+    player.on("trackStart", (track) => {
+      this._send(session.ws, {
+        op:    Op.EVENT,
+        type:  TrackEvent.START,
+        guildId,
+        track,
+      });
+    });
+
+    player.on("trackEnd", (track, reason) => {
+      this._send(session.ws, {
+        op:    Op.EVENT,
+        type:  TrackEvent.END,
+        guildId,
+        track,
+        reason,
+      });
+    });
+
+    player.on("trackException", (track, error) => {
+      this._send(session.ws, {
+        op:    Op.EVENT,
+        type:  TrackEvent.EXCEPTION,
+        guildId,
+        track,
+        exception: { message: error, severity: "common" },
+      });
+    });
+
+    player.on("playerUpdate", ({ position }) => {
+      this._send(session.ws, {
+        op:    Op.PLAYER_UPDATE,
+        guildId,
+        state: { time: Date.now(), position, connected: true },
+      });
+    });
+
+    // Stream de áudio PCM → enviado via WS para o bot tocar com @discordjs/voice
+    player.on("audioData", (chunk) => {
+      if (session.ws.readyState === WebSocket.OPEN) {
+        session.ws.send(chunk); // Buffer binário — bot identifica pelo guildId atual
+      }
+    });
+
+    session.players.set(guildId, player);
+    return player;
+  }
+
+  // ── Stats ──────────────────────────────────────────────────────────────────
+
+  _startStatsInterval() {
+    const interval = setInterval(() => {
+      const stats = this._getStats();
+      for (const { ws } of this.sessions.values()) {
+        this._send(ws, { op: Op.STATS, ...stats });
+      }
+    }, Defaults.STATS_INTERVAL_MS);
+    if (interval.unref) interval.unref();
+  }
+
+  _getStats() {
+    const mem = process.memoryUsage();
+    let players = 0, playingPlayers = 0;
+    for (const session of this.sessions.values()) {
+      players += session.players.size;
+      for (const p of session.players.values()) {
+        if (p.state === PlayerState.PLAYING) playingPlayers++;
+      }
+    }
+    return {
+      players, playingPlayers,
+      memory: {
+        free:         Math.round((require("os").freemem())  / 1024 / 1024),
+        used:         Math.round(mem.heapUsed               / 1024 / 1024),
+        allocated:    Math.round(mem.heapTotal              / 1024 / 1024),
+        reservable:   Math.round(require("os").totalmem()   / 1024 / 1024),
+      },
+      cpu: { cores: require("os").cpus().length, systemLoad: require("os").loadavg()[0] },
+      uptime: Math.floor(process.uptime()),
+    };
+  }
+
+  // ── Utils ──────────────────────────────────────────────────────────────────
+
+  _send(ws, payload) {
+    if (ws && ws.readyState === WebSocket.OPEN) {
+      ws.send(JSON.stringify(payload));
+    }
+  }
+
+  /** Retorna estatísticas do servidor para uso externo */
+  getStats() { return this._getStats(); }
+}
+
+module.exports = { AudioServer };

package/test.js

@@ -0,0 +1,269 @@
+/**
+ * enerthya.dev-audio-server — test suite
+ * Run: node test.js
+ * Uses Node built-in assert only.
+ * Testa protocolo, constantes, GuildPlayer e estrutura do servidor.
+ * Não faz conexões reais de rede.
+ */
+
+const assert = require("assert");
+const { EventEmitter } = require("events");
+
+const {
+  Op,
+  TrackEvent,
+  EndReason,
+  PlayerState,
+  Defaults,
+  RepeatMode,
+} = require("./src/index");
+
+const { GuildPlayer } = require("./src/queue/GuildPlayer");
+
+let passed = 0;
+let failed = 0;
+
+function test(name, fn) {
+  try {
+    const result = fn();
+    if (result && typeof result.then === "function") {
+      result
+        .then(() => { console.log(`  ✅ ${name}`); passed++; })
+        .catch((err) => { console.error(`  ❌ ${name}\n     ${err.message}`); failed++; });
+      return;
+    }
+    console.log(`  ✅ ${name}`);
+    passed++;
+  } catch (err) {
+    console.error(`  ❌ ${name}\n     ${err.message}`);
+    failed++;
+  }
+}
+
+// ── Constantes / Protocolo ────────────────────────────────────────────────────
+
+console.log("\n── Protocolo / Constantes ────────────────────────────────────────────────────");
+
+test("Op contém todos os opcodes essenciais", () => {
+  const required = ["READY","PLAYER_UPDATE","STATS","EVENT","PLAY","STOP","PAUSE","SEEK","VOLUME","SKIP","DESTROY","LOAD","SEARCH"];
+  for (const op of required) {
+    assert.ok(Op[op], `Op.${op} deve existir`);
+  }
+});
+
+test("TrackEvent contém START, END, EXCEPTION, STUCK", () => {
+  assert.ok(TrackEvent.START);
+  assert.ok(TrackEvent.END);
+  assert.ok(TrackEvent.EXCEPTION);
+  assert.ok(TrackEvent.STUCK);
+});
+
+test("EndReason contém todos os motivos", () => {
+  assert.ok(EndReason.FINISHED);
+  assert.ok(EndReason.LOAD_FAILED);
+  assert.ok(EndReason.STOPPED);
+  assert.ok(EndReason.REPLACED);
+  assert.ok(EndReason.CLEANUP);
+});
+
+test("PlayerState contém IDLE, PLAYING, PAUSED, LOADING", () => {
+  assert.ok(PlayerState.IDLE);
+  assert.ok(PlayerState.PLAYING);
+  assert.ok(PlayerState.PAUSED);
+  assert.ok(PlayerState.LOADING);
+});
+
+test("Defaults.PORT é número positivo", () => {
+  assert.ok(typeof Defaults.PORT === "number");
+  assert.ok(Defaults.PORT > 0);
+});
+
+test("Defaults.PASSWORD é string não vazia", () => {
+  assert.ok(typeof Defaults.PASSWORD === "string");
+  assert.ok(Defaults.PASSWORD.length > 0);
+});
+
+test("Defaults.MAX_QUEUE_SIZE é número positivo", () => {
+  assert.ok(Defaults.MAX_QUEUE_SIZE > 0);
+});
+
+test("RepeatMode contém NONE, TRACK, QUEUE", () => {
+  assert.ok(RepeatMode.NONE  !== undefined);
+  assert.ok(RepeatMode.TRACK !== undefined);
+  assert.ok(RepeatMode.QUEUE !== undefined);
+  assert.notStrictEqual(RepeatMode.NONE,  RepeatMode.TRACK);
+  assert.notStrictEqual(RepeatMode.TRACK, RepeatMode.QUEUE);
+});
+
+// ── GuildPlayer — estrutura e fila ────────────────────────────────────────────
+
+console.log("\n── GuildPlayer ───────────────────────────────────────────────────────────────");
+
+function makeTrack(id, title = "Track") {
+  const { buildTrack } = require("enerthya.dev-audio-core");
+  return buildTrack({
+    identifier: id, title, author: "Autor",
+    uri: `https://youtube.com/watch?v=${id}`,
+    length: 180_000, sourceName: "youtube",
+  });
+}
+
+function makePlayer(guildId = "111") {
+  return new GuildPlayer(guildId, {});
+}
+
+test("GuildPlayer é instanciável", () => {
+  const p = makePlayer();
+  assert.ok(p instanceof EventEmitter);
+  assert.strictEqual(p.state,   PlayerState.IDLE);
+  assert.strictEqual(p.guildId, "111");
+});
+
+test("estado inicial correto", () => {
+  const p = makePlayer();
+  assert.strictEqual(p.state,    PlayerState.IDLE);
+  assert.strictEqual(p.current,  null);
+  assert.strictEqual(p.paused,   false);
+  assert.strictEqual(p.volume,   Defaults.VOLUME);
+  assert.deepStrictEqual(p.queue, []);
+});
+
+test("addToQueue adiciona track", () => {
+  const p = makePlayer();
+  const t = makeTrack("abc", "Song A");
+  p.addToQueue(t);
+  assert.strictEqual(p.queue.length, 1);
+  assert.strictEqual(p.queue[0].info.title, "Song A");
+});
+
+test("addToQueue com array adiciona múltiplas tracks", () => {
+  const p = makePlayer();
+  p.addToQueue([makeTrack("a"), makeTrack("b"), makeTrack("c")]);
+  assert.strictEqual(p.queue.length, 3);
+});
+
+test("removeFromQueue remove pelo índice", () => {
+  const p = makePlayer();
+  p.addToQueue([makeTrack("a", "A"), makeTrack("b", "B"), makeTrack("c", "C")]);
+  const removed = p.removeFromQueue(1);
+  assert.strictEqual(removed.info.title, "B");
+  assert.strictEqual(p.queue.length, 2);
+});
+
+test("removeFromQueue retorna null para índice inválido", () => {
+  const p = makePlayer();
+  assert.strictEqual(p.removeFromQueue(0),   null);
+  assert.strictEqual(p.removeFromQueue(-1),  null);
+  assert.strictEqual(p.removeFromQueue(999), null);
+});
+
+test("clearQueue limpa a fila", () => {
+  const p = makePlayer();
+  p.addToQueue([makeTrack("a"), makeTrack("b")]);
+  p.clearQueue();
+  assert.deepStrictEqual(p.queue, []);
+});
+
+test("shuffleQueue não perde tracks", () => {
+  const p = makePlayer();
+  const tracks = [makeTrack("a"), makeTrack("b"), makeTrack("c"), makeTrack("d"), makeTrack("e")];
+  p.addToQueue(tracks);
+  p.shuffleQueue();
+  assert.strictEqual(p.queue.length, 5);
+  // Todas as tracks ainda presentes (pelo identifier)
+  const ids = p.queue.map((t) => t.info.identifier).sort();
+  assert.deepStrictEqual(ids, ["a","b","c","d","e"]);
+});
+
+test("setRepeat aceita modos válidos", () => {
+  const p = makePlayer();
+  p.setRepeat(RepeatMode.TRACK);
+  assert.strictEqual(p.repeat, RepeatMode.TRACK);
+  p.setRepeat(RepeatMode.QUEUE);
+  assert.strictEqual(p.repeat, RepeatMode.QUEUE);
+  p.setRepeat(RepeatMode.NONE);
+  assert.strictEqual(p.repeat, RepeatMode.NONE);
+});
+
+test("setRepeat ignora modo inválido", () => {
+  const p = makePlayer();
+  p.setRepeat(RepeatMode.NONE);
+  p.setRepeat("INVALID_MODE");
+  assert.strictEqual(p.repeat, RepeatMode.NONE);
+});
+
+test("setVolume respeita limites 0–1000", () => {
+  const p = makePlayer();
+  p.setVolume(500);
+  assert.strictEqual(p.volume, 500);
+  p.setVolume(-100);
+  assert.strictEqual(p.volume, 0);
+  p.setVolume(9999);
+  assert.strictEqual(p.volume, 1000);
+});
+
+test("addToQueue respeita MAX_QUEUE_SIZE", () => {
+  const p = makePlayer();
+  // Cria MAX+10 tracks
+  const many = Array.from({ length: Defaults.MAX_QUEUE_SIZE + 10 }, (_, i) => makeTrack(String(i)));
+  p.addToQueue(many);
+  assert.ok(p.queue.length <= Defaults.MAX_QUEUE_SIZE, `fila não deve exceder ${Defaults.MAX_QUEUE_SIZE}`);
+});
+
+test("toJSON retorna estrutura correta", () => {
+  const p = makePlayer("999");
+  const json = p.toJSON();
+  assert.strictEqual(json.guildId, "999");
+  assert.ok("state"   in json);
+  assert.ok("current" in json);
+  assert.ok("queue"   in json);
+  assert.ok("volume"  in json);
+  assert.ok("paused"  in json);
+  assert.ok("repeat"  in json);
+});
+
+test("destroy não crasha", () => {
+  const p = makePlayer();
+  assert.doesNotThrow(() => p.destroy());
+});
+
+test("stop emite playerStop e reseta estado", () => {
+  const p = makePlayer();
+  let emitted = false;
+  p.on("playerStop", () => { emitted = true; });
+  p.stop();
+  assert.ok(emitted);
+  assert.strictEqual(p.state,   PlayerState.IDLE);
+  assert.strictEqual(p.current, null);
+});
+
+// ── AudioServer — estrutura ───────────────────────────────────────────────────
+
+console.log("\n── AudioServer (estrutura) ───────────────────────────────────────────────────");
+
+test("AudioServer é exportado corretamente", () => {
+  const { AudioServer } = require("./src/index");
+  assert.ok(typeof AudioServer === "function", "AudioServer deve ser uma classe/função");
+});
+
+test("AudioServer instancia com porta customizada", () => {
+  const { AudioServer } = require("./src/index");
+  let server;
+  assert.doesNotThrow(() => {
+    server = new AudioServer({ port: 9999, password: "test" });
+  });
+  // Fecha imediatamente após criar
+  if (server?.wss) server.wss.close();
+});
+
+// ── Resultado ─────────────────────────────────────────────────────────────────
+
+setTimeout(() => {
+  console.log(`\n── Resultado ─────────────────────────────────────────────────────────────────`);
+  console.log(`  ✅ ${passed} passed`);
+  if (failed > 0) {
+    console.error(`  ❌ ${failed} failed`);
+    process.exit(1);
+  }
+  console.log("  All tests passed.\n");
+}, 500);