@jubbio/voice 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Jubbio Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,257 @@
+<p align="center">
+  <img src="https://jubbio.com/logo.png" alt="Jubbio" width="120" />
+</p>
+
+<h1 align="center">@jubbio/voice</h1>
+
+<p align="center">
+  <strong>Voice library for Jubbio bots</strong>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@jubbio/voice"><img src="https://img.shields.io/npm/v/@jubbio/voice?color=blue" alt="npm"></a>
+  <a href="https://github.com/jubbio/jubbio.js/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="License"></a>
+  <img src="https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen" alt="Node.js">
+</p>
+
+---
+
+## Installation
+
+```bash
+npm install @jubbio/voice
+```
+
+## Features
+
+- 🎵 **Audio Playback** - Play local files or stream from URLs
+- 📺 **YouTube Support** - Built-in yt-dlp integration
+- 🔊 **LiveKit Backend** - High-quality, low-latency audio
+- ⏯️ **Playback Controls** - Play, pause, stop, volume
+- 📊 **Easy Queue Management** - Build music bots easily
+
+## Quick Start
+
+```typescript
+import { Client, GatewayIntentBits } from '@jubbio/core';
+import { 
+  joinVoiceChannel, 
+  createAudioPlayer, 
+  createAudioResourceFromUrl,
+  AudioPlayerStatus 
+} from '@jubbio/voice';
+
+const client = new Client({
+  intents: [
+    GatewayIntentBits.Guilds,
+    GatewayIntentBits.GuildVoiceStates
+  ]
+});
+
+client.on('interactionCreate', async (interaction) => {
+  if (!interaction.isCommand()) return;
+  
+  if (interaction.commandName === 'play') {
+    const url = interaction.options.getString('url', true);
+    const voiceChannel = interaction.member?.voice?.channelId;
+    
+    if (!voiceChannel) {
+      return interaction.reply('❌ Join a voice channel first!');
+    }
+    
+    // Join voice channel
+    const connection = joinVoiceChannel({
+      channelId: voiceChannel,
+      guildId: interaction.guildId!,
+      adapterCreator: client.voice.adapters.get(interaction.guildId!)!
+    });
+    
+    // Create player and play
+    const player = createAudioPlayer();
+    const resource = createAudioResourceFromUrl(url);
+    
+    connection.subscribe(player);
+    player.play(resource);
+    
+    // Handle playback end
+    player.on('stateChange', (oldState, newState) => {
+      if (newState.status === AudioPlayerStatus.Idle) {
+        console.log('Playback finished!');
+      }
+    });
+    
+    await interaction.reply('🎵 Now playing!');
+  }
+});
+
+client.login(process.env.BOT_TOKEN);
+```
+
+## API Reference
+
+### joinVoiceChannel(options)
+
+Join a voice channel and return a `VoiceConnection`.
+
+```typescript
+const connection = joinVoiceChannel({
+  channelId: '123456789',        // Voice channel ID
+  guildId: '987654321',          // Guild ID
+  adapterCreator: adapter,       // From client.voice.adapters
+  selfMute: false,               // Join muted (default: false)
+  selfDeaf: false                // Join deafened (default: false)
+});
+```
+
+### createAudioPlayer(options?)
+
+Create an `AudioPlayer` instance.
+
+```typescript
+const player = createAudioPlayer({
+  behaviors: {
+    noSubscriber: 'pause'  // 'pause' | 'play' | 'stop'
+  }
+});
+```
+
+### createAudioResource(input, options?)
+
+Create an `AudioResource` from a file path.
+
+```typescript
+const resource = createAudioResource('/path/to/audio.mp3', {
+  metadata: { title: 'My Song' }
+});
+```
+
+### createAudioResourceFromUrl(url, options?)
+
+Create an `AudioResource` from a URL (YouTube, SoundCloud, etc.).
+
+```typescript
+const resource = createAudioResourceFromUrl('https://youtube.com/watch?v=...', {
+  metadata: { title: 'YouTube Video' }
+});
+```
+
+### probeAudioInfo(url)
+
+Get information about an audio URL.
+
+```typescript
+const info = await probeAudioInfo('https://youtube.com/watch?v=...');
+console.log(info.title);     // Video title
+console.log(info.duration);  // Duration in seconds
+console.log(info.thumbnail); // Thumbnail URL
+```
+
+## Player Controls
+
+```typescript
+// Play
+player.play(resource);
+
+// Pause
+player.pause();
+
+// Resume
+player.unpause();
+
+// Stop
+player.stop();
+
+// Check status
+if (player.state.status === AudioPlayerStatus.Playing) {
+  console.log('Currently playing!');
+}
+```
+
+## Connection Controls
+
+```typescript
+// Disconnect
+connection.disconnect();
+
+// Destroy (cleanup)
+connection.destroy();
+
+// Check status
+if (connection.state.status === VoiceConnectionStatus.Ready) {
+  console.log('Connected!');
+}
+```
+
+## Events
+
+### AudioPlayer Events
+
+```typescript
+player.on('stateChange', (oldState, newState) => {
+  console.log(`${oldState.status} -> ${newState.status}`);
+});
+
+player.on('error', (error) => {
+  console.error('Player error:', error);
+});
+```
+
+### VoiceConnection Events
+
+```typescript
+connection.on('stateChange', (oldState, newState) => {
+  if (newState.status === VoiceConnectionStatus.Disconnected) {
+    console.log('Disconnected from voice channel');
+  }
+});
+
+connection.on('error', (error) => {
+  console.error('Connection error:', error);
+});
+```
+
+## Status Enums
+
+### AudioPlayerStatus
+
+| Status | Description |
+|--------|-------------|
+| `Idle` | Not playing anything |
+| `Buffering` | Loading audio |
+| `Playing` | Currently playing |
+| `Paused` | Playback paused |
+| `AutoPaused` | Paused (no subscribers) |
+
+### VoiceConnectionStatus
+
+| Status | Description |
+|--------|-------------|
+| `Connecting` | Establishing connection |
+| `Ready` | Connected and ready |
+| `Disconnected` | Disconnected |
+| `Destroyed` | Connection destroyed |
+| `Signalling` | Exchanging connection info |
+
+## Requirements
+
+- **Node.js** 18.0.0 or higher
+- **FFmpeg** installed and in PATH
+- **yt-dlp** installed (for YouTube support)
+
+### Installing Dependencies
+
+```bash
+# Ubuntu/Debian
+sudo apt install ffmpeg
+pip install yt-dlp
+
+# macOS
+brew install ffmpeg yt-dlp
+
+# Windows
+# Download from ffmpeg.org and yt-dlp GitHub releases
+```
+
+## License
+
+MIT © [Jubbio Team](https://jubbio.com)

package/dist/AudioPlayer.d.ts

@@ -0,0 +1,84 @@
+import { EventEmitter } from 'events';
+import { CreateAudioPlayerOptions, AudioPlayerState } from './types';
+import { AudioResource } from './AudioResource';
+import { VoiceConnection } from './VoiceConnection';
+/**
+ * Audio player for playing audio resources
+ */
+export declare class AudioPlayer extends EventEmitter {
+    /** Current player state */
+    state: AudioPlayerState;
+    /** Player options */
+    private options;
+    /** Subscribed voice connections */
+    private subscriptions;
+    /** Current audio resource */
+    private currentResource;
+    /** FFmpeg process */
+    private ffmpegProcess;
+    /** LiveKit audio source and track */
+    private audioSource;
+    private audioTrack;
+    /** Frame queue and playback state */
+    private frameQueue;
+    private playbackTimeout;
+    private leftoverBuffer;
+    private isPublished;
+    /** High-resolution timing */
+    private nextFrameTime;
+    private isPlaybackLoopRunning;
+    private ffmpegDone;
+    /** Buffer statistics */
+    private bufferUnderruns;
+    private framesPlayed;
+    constructor(options?: CreateAudioPlayerOptions);
+    /**
+     * Play an audio resource
+     */
+    play(resource: AudioResource): void;
+    /**
+     * Pause playback
+     */
+    pause(): boolean;
+    /**
+     * Unpause playback
+     */
+    unpause(): boolean;
+    /**
+     * Stop playback
+     */
+    stop(force?: boolean): boolean;
+    /**
+     * Subscribe a voice connection to this player
+     * @internal
+     */
+    subscribe(connection: VoiceConnection): void;
+    /**
+     * Unsubscribe a voice connection from this player
+     * @internal
+     */
+    unsubscribe(connection: VoiceConnection): void;
+    /**
+     * Called when a connection becomes ready
+     * @internal
+     */
+    onConnectionReady(connection: VoiceConnection): void;
+    private startPlayback;
+    private setupAudioTrack;
+    private startFFmpeg;
+    /**
+     * High-resolution frame scheduling using hrtime
+     * This provides much more accurate timing than setInterval
+     */
+    private scheduleNextFrame;
+    /**
+     * Process and send a single audio frame
+     */
+    private processFrame;
+    private cleanup;
+    private setState;
+}
+/**
+ * Create an audio player
+ */
+export declare function createAudioPlayer(options?: CreateAudioPlayerOptions): AudioPlayer;