Voice Laravel Package

Getting Started

Start by installing the package via Composer: composer require discord-php/voice. This package is a low-level voice client extension for DiscordPHP — it’s not a standalone library. You must first use team-reflex/discord-php as your core Discord client and attach voice capabilities via this package.

The first use case is joining a voice channel to play or stream audio (e.g., music bot, voice assistant, notification bot). Minimal setup:

1. Create a Discord instance with appropriate intents (GUILD_VOICE_STATES, GUILD_VOICE_EVENTS, and potentially GUILD_MESSAGES).
2. Use the DiscordVoice class (provided by this package) to connect to a voice channel:

   use Discord\Discord;
   use Discord\Voice\DiscordVoice;
   use Discord\Parts\Channel\Channel;
   
   $discord = new Discord([...]);
   $discord->on('ready', function (Discord $discord) {
       // Get a text channel to confirm, and a voice channel to join
       $textChannel = $discord->channels->get('id', '123...');
       $voiceChannel = $discord->channels->get('id', '456...'); // Must be GUILD_VOICE
   
       $voice = new DiscordVoice($discord);
       $connection = yield $voice->join($voiceChannel);
       // ... proceed to play audio
   });
   $discord->run();
   

3. Ensure you meet all voice requirements: PHP ≥8.0 (64-bit), ext-sodium, and FFmpeg installed on the system.

Begin with the examples/ folder — especially voice-player.php, which demonstrates streaming local files and YouTube URLs via FFmpeg.

Implementation Patterns

• Async Streaming: Voice communication is fully async and promise-based. Audio streams are handled via ffmpeg subprocesses (FFMpegStream), not raw buffers. Use:

  $stream = new FFMpegStream('https://example.com/audio.mp3');
  $connection->play($stream);
  

• Dynamic Audio Sources: Implement AudioProvider interface for custom sources (e.g., in-memory MP3, live mic via ffmpeg -f alsa), then pass to $connection->play($provider).
• Event-Driven Control: Listen to events on the voice connection:

  $connection->on('end', function () {
      echo "Playback finished.\n";
  });
  $connection->on('error', function (\Throwable $e) {
      error_log("Voice error: {$e->getMessage()}");
  });
  

• Multiple Connections: Join multiple channels concurrently by creating separate DiscordVoice instances per guild — voice connections are not shared across guilds or channels.
• Real-time Processing: Use RawAudioProvider with manual Opus encoding (if needed) for low-latency features like voice modulators or filters. Leverage OpusEncoder class from Sop\Audio\Opus.

Integration Tip: Wrap voice logic in a service class (e.g., VoiceManager) to reuse logic across commands or events. Inject Discord and cache voice connections per guild ID.

Gotchas and Tips

• FFmpeg Path & Flags: On Windows, ensure ffmpeg is in PATH. Often, explicit args help: use FFMpegStream::fromFile('file.mp3', ['-re']) for reliable streaming.
• Memory & Stability: Voice connections keep FFmpeg subprocesses open — always await $connection->stop() on shutdown. Add gc_collect_cycles() after large playback sessions.
• Sodium Extension Required: PHP throws cryptic errors if ext-sodium is missing (not auto-confirmed by Composer). Verify with extension_loaded('sodium').
• 64-bit Enforced: Running 32-bit PHP (e.g., on older WAMP/XAMPP) fails silently on voice connection — DiscordVoice checks this and throws \RuntimeException.
• SSL on Windows: If bot crashes before ready event, TLS handshake may fail. Fix: set openssl.cafile in php.ini to cacert.pem.
• Rate Limits & Voice Pings: The voice protocol expects keepalives — the library handles this internally, but don’t block the event loop (e.g., sleep() inside on('ready')).
• Debugging: Enable verbose FFmpeg logging via $stream->setFfmpegLogLevel('info') to troubleshoot format/codec issues.
• Opus Fallback: Since v8.0.4, optional OpusFfi decoding is used by default — disable via DiscordVoice::$preferOpusFfi = false if debugging packet loss. Prefer ext-libsodium for best performance.