smusic-discord 1.0.0

package/README.md

@@ -0,0 +1,107 @@
+# smusic-discord
+
+A fast, reliable, and extensible Node.js package built with Bun to resolve music sources (YouTube, SoundCloud, direct URLs) and return a stream compatible with Discord voice bots using `@discordjs/voice`.
+
+## Installation
+
+You must use Bun.
+
+```bash
+bun add smusic-discord
+```
+
+## Features
+
+- **Fast Metadata Resolution:** Uses `play-dl` for quick resolution.
+- **Multiple Source Support:** Works out-of-the-box with YouTube, SoundCloud, and Direct Audio URLs.
+- **Search Support:** Natively search YouTube if the input is a query instead of a URL.
+- **Discord Compatibility:** Provides a Node.js Readable stream ready to be used with `@discordjs/voice`.
+- **Fallback Strategy for YouTube:** Employs multiple fallback layers (`play-dl` -> `ytdl-core` -> `yt-dlp`) to ensure playback consistency.
+- **Built-in Caching:** Prevents redundant metadata API calls by caching resolved tracks.
+
+## Usage
+
+### Example Discord Bot Setup
+
+```typescript
+import { resolve, search } from 'smusic-discord';
+import { createAudioResource, createAudioPlayer, joinVoiceChannel } from '@discordjs/voice';
+import { Client, GatewayIntentBits, Message } from 'discord.js';
+
+const client = new Client({
+    intents: [
+        GatewayIntentBits.Guilds,
+        GatewayIntentBits.GuildMessages,
+        GatewayIntentBits.MessageContent,
+        GatewayIntentBits.GuildVoiceStates,
+    ],
+});
+
+client.on('messageCreate', async (message: Message) => {
+    if (!message.content.startsWith('!play') || !message.member?.voice.channel) return;
+
+    const query = message.content.replace('!play ', '');
+
+    // Join VC
+    const connection = joinVoiceChannel({
+        channelId: message.member.voice.channel.id,
+        guildId: message.guildId!,
+        adapterCreator: message.guild!.voiceAdapterCreator,
+    });
+
+    try {
+        // Resolve the query or URL
+        const track = await resolve(query);
+        console.log(`Now playing: ${track.title}`);
+
+        // Get the audio stream
+        const stream = await track.stream();
+
+        // Play it using discordjs/voice
+        const resource = createAudioResource(stream);
+        const player = createAudioPlayer();
+
+        player.play(resource);
+        connection.subscribe(player);
+    } catch (error) {
+        console.error('Failed to play track:', error);
+    }
+});
+
+client.login('YOUR_BOT_TOKEN');
+```
+
+## API Documentation
+
+### `resolve(input: string): Promise<Track>`
+
+Resolves a given URL or attempts a Youtube search if it's plain text. Returns a `Track` object.
+
+### `search(query: string): Promise<Track>`
+
+Forces a search on YouTube and returns the first result as a `Track`.
+
+### `Track` Object
+
+```typescript
+interface Track {
+    title: string;
+    url: string;
+    duration: number; // in seconds
+    thumbnail?: string;
+    source: string; // 'youtube', 'soundcloud', 'direct', etc.
+
+    stream(): Promise<Readable>;
+}
+```
+
+## Build and Publish
+
+```bash
+bun build src/index.ts --outdir dist --target node
+bun publish
+```
+
+## License
+
+MIT