How tomato6966/lavalink-client works
Project type and purpose
• This is an open-source TypeScript library (“lavalink-client”) that integrates Discord bots (via discord.js) with Lavalink v4 audio servers.
• It provides a high-level Manager API, Player abstraction, queue management (with pluggable stores like in-memory or Redis), filter/equalizer support, event hooks, and helper utilities.
• The repo also contains:
• A documentation site under /docs (built with Astro + MDX).
• A “testBot” example showing how to integrate and exercise all features.
Top-level directory analysis
• /src: core library code, organized into:
• Manager layer: LavalinkManager.ts, NodeManager.ts, etc.
• Player layer: Player.ts, Queue.ts, Filters.ts.
• Types + utilities.
• /testBot: example Discord bot, with its own commands, event handlers, custom queue store/watcher, and env/config.
• /docs: static site source showing guides, version logs, API reference.
• CI/workflow files (.github/workflows/*), lint/config, project root package.json and tsconfig.json.
Key insights from README
• Manager ⇄ NodeManager ⇄ Lavalink server (WebSocket + REST).
• Discord.js client ⇄ Manager (raw voice events) ⇄ Discord Gateway/Sharding.
• Queue store is pluggable: default in-memory or custom (e.g. Redis).
• Extensive event emissions for player, track, queue, node lifecycle, debugging, lyrics, filters, sponsorblock plugin, etc.
• Emphasis on “automated handlings” (skip on errors, auto-reconnect, auto-destroy, resuming).
Main components
• Client Application (Discord.js Bot)
• Gateway Shard(s)
• Raw Voice/Message events → lavalink-client
• Lavalink-Client Library
• LavalinkManager (public API)
• NodeManager (manages WS connections to one or more Lavalink nodes)
• Player Instances + FilterManager + Queue (and QueueStore abstraction)
• CustomSearches module
• EventBus (emits player/node/queue events)
• External Systems
• Lavalink v4 Node(s) (WebSocket + REST endpoints)
• Optional Redis (custom QueueStore)
• Discord Gateway & Voice WebSocket
• Documentation site (Astro) — separate build pipeline
Relationships & data flows
• Bot sends raw Discord voice payloads → LavalinkManager.sendRawData() → NodeManager → Lavalink WS
• Bot calls createPlayer(), player.play(), player.queue.add(), etc. → LavalinkManager → NodeManager REST → Lavalink server
• Lavalink WS sends stats, track updates, events → NodeManager → LavalinkManager → Player + EventBus → Bot callback handlers
• QueueStore (memory or Redis): Player.queue.utils.sync() ↔ Redis for persistence or cross-shard sync
• CustomSearches (BandCamp, LavaSrc, LavaSearch) hit Lavalink REST search or external APIs, return Track objects
Architectural patterns & design principles
• Event-Driven: every state change emits strongly typed events to user code
• Layered Abstraction:
• Public API (LavalinkManager)
• Node management (WebSocket/REST orchestration)
• Player abstraction (connect/disconnect, play, pause, filters)
• Queue abstraction (pluggable stores, change watchers)
• Plugin-style extensibility: custom queue stores, queue watchers, custom search modules
• Separation of concerns: core library vs. example bot vs. documentation
• Public API (LavalinkManager)
• NodeManager (WS + REST handlers)
• Player instances (FilterManager, Queue)
• Utilities (CustomSearches, Utils)
• Discord Gateway → Bot (events) → LavalinkManager.sendRawData() → NodeManager → Lavalink WS
• Bot API calls (play(), queue.add()) → LavalinkManager → NodeManager REST → Lavalink REST
• NodeManager events → LavalinkManager → Bot callbacks
• Queue.sync → Redis (optional path)
• Player.search → CustomSearch modules → Lavalink REST or external API