ryanlink 1.0.2 → 2.0.0

package/README.md

@@ -1,19 +1,18 @@
 <div align="center">
-  <img alt="Ryanlink" src="assets/ryanlink.jpeg" width="120" />
+  <img alt="ryanlink" src="assets/ryanlink.png" width="120" />
   
   # Ryanlink
   
-  A modern, feature-rich Lavalink client for Node.js with TypeScript support
+  A modern, high-performance audio client for Node.js, Bun, and Deno.
   
   <br/>
   
   [![NPM Version](https://img.shields.io/npm/v/ryanlink?style=flat&logo=npm)](https://www.npmjs.com/package/ryanlink)
   [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
   [![Node Version](https://img.shields.io/node/v/ryanlink)](https://nodejs.org)
-  [![TypeScript](https://img.shields.io/badge/TypeScript-5.3+-blue.svg?logo=typescript)](https://www.typescriptlang.org/)
-  [![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/ryanwtf7/ryanlink/coverage.yml?branch=master&label=tests)](https://github.com/ryanwtf7/ryanlink/actions)
+  [![TypeScript](https://img.shields.io/badge/TypeScript-5.4+-blue.svg?logo=typescript)](https://www.typescriptlang.org/)
   
-  [Documentation](https://ryanwtf7.github.io/ryanlink) • [NPM Package](https://www.npmjs.com/package/ryanlink) • [GitHub](https://github.com/ryanwtf7/ryanlink)
+  [Documentation](https://ryanwtf7.github.io/ryanlink/) • [NPM Package](https://www.npmjs.com/package/ryanlink) • [GitHub](https://github.com/ryanwtf7/ryanlink)
 
 </div>
 
@@ -21,36 +20,20 @@
 
 ## Overview
 
-Ryanlink is a powerful Lavalink client library designed to simplify music bot development for Discord. Built with modern TypeScript and featuring a unique architecture, it provides an intuitive interface for managing audio playback, queues, and advanced audio processing.
+**Ryanlink** is a premium, feature-rich lavalink-v4 wrapper designed for speed, flexibility, and developer experience. It provides a robust architecture for Discord music bots with first-class TypeScript support and cross-runtime compatibility.
 
 ### Key Features
 
-- **Modern Lavalink v4 Support** - Full compatibility with the latest Lavalink API
-- **Cross-Runtime Compatibility** - Works seamlessly with Node.js, Bun, and Deno
-- **Professional Audio Processing** - 17 built-in EQ presets for instant audio enhancement
-- **Advanced Queue Management** - Sort, filter, search, and manipulate tracks with ease
-- **Powerful Extensions System** - Autoplay, Lyrics, SponsorBlock, FairPlay, and Persistence
-- **Type-Safe** - Complete TypeScript definitions with full IntelliSense support
-- **Production Ready** - Comprehensive error handling, automatic reconnection, and session management
-- **Flexible Architecture** - Feature-based organization for better maintainability
+- **Lavalink v4 Protocol** - Full support for the latest lavalink features and filters.
+- **Cross-Runtime Ready** - Optimized for **Node.js**, **Bun**, and **Deno**.
+- **Flexible Queue Stores** - Use the default in-memory store or bring your own (Redis, databases, etc.).
+- **High-Performance Audio** - Native fetch, efficient memory management, and parallel track loading.
+- **Professional Filters** - Built-in EQ presets and custom DSP filters (Bassboost, Nightcore, etc.).
+- **Smart Automation** - Optional auto-pause on mute and instant filter application via `instaFixFilter`.
+- **Strictly Type-Safe** - 100% TypeScript with advanced module augmentation support.
+- **Dynamic Metadata** - Real-time access to library version and package information.
 
-### Supported Platforms
-
-Ryanlink supports audio from 20+ streaming platforms through LavaSrc integration:
-
-<div align="center">
-
-| Platform     | Support | Platform  | Support | Platform     | Support |
-| ------------ | ------- | --------- | ------- | ------------ | ------- |
-| YouTube      | ✓       | Spotify   | ✓       | Apple Music  | ✓       |
-| SoundCloud   | ✓       | Deezer    | ✓       | Tidal        | ✓       |
-| Bandcamp     | ✓       | Twitch    | ✓       | Amazon Music | ✓       |
-| Yandex Music | ✓       | JioSaavn  | ✓       | Pandora      | ✓       |
-| Qobuz        | ✓       | Audiomack | ✓       | Mixcloud     | ✓       |
-| Anghami      | ✓       | Audius    | ✓       | Gaana        | ✓       |
-| Instagram    | ✓       | Shazam    | ✓       | Direct URLs  | ✓       |
-
-</div>
+---
 
 ## Installation
 
@@ -58,398 +41,142 @@ Ryanlink supports audio from 20+ streaming platforms through LavaSrc integration
 # npm
 npm install ryanlink
 
-# yarn
-yarn add ryanlink
+# bun
+bun add ryanlink
 
 # pnpm
 pnpm add ryanlink
-
-# bun
-bun add ryanlink
 ```
 
-### Deno
-
-```typescript
-import { RyanlinkPlayer } from "npm:ryanlink@latest";
-```
+---
 
 ## Quick Start
 
 ```typescript
-import { Client } from "discord.js";
-import { RyanlinkPlayer } from "ryanlink";
-
-const client = new Client({ intents: ["Guilds", "GuildVoiceStates"] });
-
-const player = new RyanlinkPlayer({
-    nodes: [
-        {
-            name: "main",
-            host: "localhost",
-            port: 2333,
-            password: "youshallnotpass",
-            secure: false,
-        },
-    ],
-    forwardVoiceUpdate: async (guildId, payload) => {
-        const guild = client.guilds.cache.get(guildId);
-        if (guild) guild.shard.send(payload);
+import { Client, GatewayIntentBits } from 'discord.js'
+import { RyanlinkManager } from 'ryanlink'
+
+const client = new Client({
+  intents: [GatewayIntentBits.Guilds, GatewayIntentBits.GuildVoiceStates],
+})
+
+client.ryanlink = new RyanlinkManager({
+  nodes: [
+    {
+      name: 'main',
+      host: 'localhost',
+      port: 2333,
+      authorization: 'youshallnotpass',
+      secure: false,
     },
-});
+  ],
+  sendToShard: (guildId, payload) => {
+    client.guilds.cache.get(guildId)?.shard.send(payload)
+  },
+  client: {
+    id: process.env.CLIENT_ID,
+    username: 'RyanlinkBot',
+  },
+})
 
-client.on("ready", async () => {
-    await player.init(client.user.id);
-    console.log(`${client.user.tag} is ready!`);
-});
+client.on('ready', () => {
+  client.ryanlink.init({ ...client.user })
+  console.log(`${client.user.tag} is online and connected to ryanlink`)
+})
 
-client.on("raw", (packet) => {
-    player.voices.handleDispatch(packet);
-});
+client.on('raw', (packet) => {
+  client.ryanlink.provideVoiceUpdate(packet)
+})
 
-client.login("YOUR_BOT_TOKEN");
+client.login('YOUR_BOT_TOKEN')
 ```
 
-## Core Concepts
-
-### Playing Music
+---
 
-```typescript
-// Play from URL or search query
-const queue = await player.play("Never Gonna Give You Up", {
-    guildId: interaction.guildId,
-    voiceId: interaction.member.voice.channelId,
-    textId: interaction.channelId,
-});
-
-// Play from direct URL
-await player.play("https://open.spotify.com/track/...", {
-    guildId: interaction.guildId,
-    voiceId: interaction.member.voice.channelId,
-});
-
-// Search with specific source
-const results = await player.search("ytsearch:Rick Astley");
-```
+## Core Usage
 
-### Queue Management
+### Playing Audio
 
 ```typescript
-const queue = player.getQueue(guildId);
-
-// Basic controls
-await queue.pause();
-await queue.resume();
-await queue.stop();
-await queue.skip();
-await queue.previous();
+const player = client.ryanlink.createPlayer({
+  guildId: interaction.guildId,
+  voiceChannelId: interaction.member.voice.channelId,
+  textChannelId: interaction.channelId,
+})
 
-// Volume control
-await queue.setVolume(0.5); // 50%
+const res = await player.search('Never Gonna Give You Up', interaction.user)
+player.queue.add(res.tracks[0])
 
-// Repeat modes
-await queue.setRepeatMode("track"); // Repeat current track
-await queue.setRepeatMode("queue"); // Repeat entire queue
-await queue.setRepeatMode("off"); // No repeat
+if (!player.playing) await player.play()
 
-// Shuffle
-await queue.shuffle();
-await queue.shuffle(true); // Include previous tracks
-
-// Seek
-await queue.seek(60000); // Seek to 1 minute
+console.log(`Added: ${res.tracks[0].info.title}`)
 ```
 
-### Advanced Queue Operations
+### Queue Controls
 
 ```typescript
-// Sort tracks
-await queue.sortBy("duration", "desc");
-await queue.sortBy("title", "asc");
-await queue.sortBy((a, b) => a.duration - b.duration);
-
-// Filter tracks
-const longTracks = queue.filterTracks({
-    duration: { min: 180000 }, // 3+ minutes
-});
-
-const rockTracks = queue.filterTracks({
-    title: "rock",
-});
-
-// Find specific track
-const track = queue.findTrack({ title: "Never Gonna" });
-
-// Move tracks
-await queue.move(5, 0); // Move track at index 5 to front
-
-// Remove tracks
-await queue.remove(3); // Remove track at index 3
+const player = client.ryanlink.players.get(guildId)
 
-// Get track range
-const nextTen = queue.getTracks(0, 10);
+await player.pause()
+await player.resume()
+await player.skip()
+await player.setVolume(50) // 0 - 100
+player.setRepeatMode('queue') // "off" | "track" | "queue"
 ```
 
 ### Audio Filters
 
 ```typescript
-// Apply EQ preset
-await queue.filters.setEQPreset("BassboostHigh");
-await queue.filters.setEQPreset("Rock");
-await queue.filters.setEQPreset("Nightcore");
-
-// Get available presets
-const presets = queue.filters.getEQPresetNames();
-// ["BassboostEarrape", "BassboostHigh", "BassboostMedium", "BassboostLow",
-//  "Rock", "Classic", "Pop", "Electronic", "Gaming", "Nightcore",
-//  "Vaporwave", "TrebleBass", "HighQuality", "BetterMusic", "FullSound",
-//  "Soft", "TV", "Radio", "Normalization"]
-
-// Custom filters
-await queue.filters.apply({
-    equalizer: [
-        { band: 0, gain: 0.2 },
-        { band: 1, gain: 0.15 },
-    ],
-    timescale: { speed: 1.5, pitch: 1.2 },
-    volume: 1.0,
-});
-
-// Individual filter control
-await queue.filters.set("timescale", { speed: 1.5 });
-await queue.filters.delete("timescale");
-await queue.filters.clear();
-```
-
-## Extensions
-
-### Autoplay Extension
-
-Automatically plays related tracks when the queue ends.
-
-```typescript
-import { AutoplayExtension } from "ryanlink";
-
-const player = new RyanlinkPlayer({
-    plugins: [
-        new AutoplayExtension({
-            enabled: true,
-            maxHistory: 50,
-            sources: {
-                spotify: true,
-                youtube: true,
-                youtubemusic: true,
-                soundcloud: false,
-            },
-        }),
-    ],
-});
-```
-
-### Lyrics Extension
-
-Fetch synchronized lyrics from multiple sources.
-
-```typescript
-import { LyricsExtension } from "ryanlink";
-
-const player = new RyanlinkPlayer({
-    plugins: [
-        new LyricsExtension({
-            sources: ["lrclib", "genius", "musixmatch"],
-            cache: true,
-        }),
-    ],
-});
-
-// Get lyrics
-const lyrics = await queue.getLyrics();
-```
-
-### SponsorBlock Extension
-
-Skip sponsored segments in YouTube videos.
-
-```typescript
-import { SponsorBlockExtension } from "ryanlink";
-
-const player = new RyanlinkPlayer({
-    plugins: [
-        new SponsorBlockExtension({
-            categories: ["sponsor", "intro", "outro", "selfpromo"],
-            autoSkip: true,
-        }),
-    ],
-});
-```
-
-### FairPlay Extension
+// Apply professional EQ presets
+await player.filterManager.setEQ([
+  { band: 0, gain: 0.25 },
+  { band: 1, gain: 0.25 },
+])
 
-Limit tracks per user for fair queue distribution.
-
-```typescript
-import { FairPlayExtension } from "ryanlink";
-
-const player = new RyanlinkPlayer({
-    plugins: [
-        new FairPlayExtension({
-            maxPerUser: 3,
-            enforceLimit: true,
-        }),
-    ],
-});
+// Custom Timescale via filterManager
+await player.filterManager.setFilters({
+  timescale: { speed: 1.2, pitch: 1.1 },
+})
 ```
 
-### Persistence Extension
+---
 
-Save and restore queues across bot restarts.
+## Diagnostic Metadata
 
-```typescript
-import { PersistenceExtension } from "ryanlink";
-
-const player = new RyanlinkPlayer({
-    plugins: [
-        new PersistenceExtension({
-            autoSave: true,
-            saveInterval: 60000, // 1 minute
-        }),
-    ],
-});
-```
-
-## Events
+Access library information dynamically:
 
 ```typescript
-// Track events
-player.on("trackStart", (queue, track) => {
-    console.log(`Now playing: ${track.title}`);
-});
-
-player.on("trackFinish", (queue, track, reason) => {
-    console.log(`Finished: ${track.title} (${reason})`);
-});
-
-player.on("trackError", (queue, track, error) => {
-    console.error(`Error: ${error.message}`);
-});
-
-player.on("trackStuck", (queue, track, threshold) => {
-    console.warn(`Track stuck: ${track.title}`);
-});
-
-// Queue events
-player.on("queueCreate", (queue) => {
-    console.log(`Queue created for guild ${queue.guildId}`);
-});
-
-player.on("queueFinish", (queue) => {
-    console.log("Queue finished!");
-});
-
-player.on("queueDestroy", (queue, reason) => {
-    console.log(`Queue destroyed: ${reason}`);
-});
-
-// Node events
-player.on("nodeConnect", (node, reconnects) => {
-    console.log(`Node ${node.name} connected`);
-});
-
-player.on("nodeReady", (node, resumed, sessionId) => {
-    console.log(`Node ${node.name} ready`);
-});
-
-player.on("nodeDisconnect", (node, code, reason) => {
-    console.log(`Node ${node.name} disconnected`);
-});
-
-player.on("nodeError", (node, error) => {
-    console.error(`Node error: ${error.message}`);
-});
-```
-
-## TypeScript Support
-
-Ryanlink is built with TypeScript and provides complete type definitions.
+import { version } from 'ryanlink'
 
-### Module Augmentation
-
-Extend types for custom data:
-
-```typescript
-declare module "ryanlink" {
-    interface QueueContext {
-        textChannelId: string;
-        requesterId: string;
-    }
-
-    interface CommonUserData {
-        id: string;
-        username: string;
-        requestedAt: number;
-    }
-
-    interface CommonPluginInfo {
-        customField?: string;
-    }
-}
+console.log(`Ryanlink v${version}`)
 ```
 
-## Requirements
-
-- **Node.js**: 18.0.0 or higher
-- **Bun**: 1.0.0 or higher
-- **Deno**: 1.30.0 or higher
-- **Lavalink**: 4.0.0 or higher
+---
 
 ## Architecture
 
-Ryanlink uses a feature-based architecture for better organization:
+Ryanlink is organized into modular features for maximum maintainability:
 
-```
-src/
-├── core/          # Player and plugin system
-├── lavalink/      # Lavalink connection and HTTP client
-├── audio/         # Queue, tracks, and filters
-├── voice/         # Voice connection management
-├── extensions/    # Built-in extensions
-├── config/        # Configuration and constants
-├── utils/         # Utility functions
-└── types/         # TypeScript definitions
-```
+- `src/` - Core library source files including:
+  - `core/Manager.ts` - Main entry point
+  - `node/Node.ts` - Connection and REST interfaces
+  - `audio/Player.ts` - Audio playback and queue controller
+  - `audio/Queue.ts` - Advanced track management
 
-## Performance
+---
 
-- **Efficient Memory Usage** - Optimized data structures and caching
-- **Fast Track Loading** - Parallel track resolution
-- **Minimal Overhead** - Native fetch API, no unnecessary dependencies
-- **Smart Reconnection** - Automatic recovery with exponential backoff
+## Requirements
 
-## Contributing
+- **Lavalink**: 4.0.0+
+- **Node.js**: 18.0.0+ (Support for Bun/Deno)
+- **TypeScript**: 5.4+ (Standardized)
 
-Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests.
+---
 
 ## License
 
-This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.
-
-## Acknowledgements
-
-Ryanlink was inspired by and builds upon concepts from:
-
-- [distube](https://github.com/skick1234/DisTube) - Player-queue design patterns
-- [discord.js](https://github.com/discordjs/discord.js) - Manager-cache architecture
-- [Hoshimi](https://github.com/Ganyu-Studios/Hoshimi) - Module augmentation patterns
-- [discolink](https://github.com/execaman/discolink) - Modern Lavalink client design
-
-## Support
-
-- [Documentation](https://ryanwtf7.github.io/ryanlink)
-- [GitHub Issues](https://github.com/ryanwtf7/ryanlink/issues)
-- [GitHub Discussions](https://github.com/ryanwtf7/ryanlink/discussions)
-
----
+Licensed under the **Apache License 2.0**. See the [LICENSE](LICENSE) file for more information.
 
 <div align="center">
-  Made with ❤️ by RY4N
+  Made with care by RY4N
 </div>