feat(voice): enhance audio processing with PCM file playback and CRC optimization

Author: alexandre433

src/Discord/Voice/Dave/MediaCryptoService.php

@@ -72,11 +72,6 @@ public function encrypt(string $frame, ?int $ssrc): string
             return '';
         }
 
-        $this->logger->debug('Encrypted outgoing DAVE frame.', [
-            'protocol_version' => $protocolVersion,
-            'frame_length' => strlen($encrypted),
-        ]);
-
         return $encrypted;
     }
 

src/Discord/Voice/Helpers/Buffer.php

@@ -217,6 +217,13 @@ public function close(): void
         }
 
         $this->closed = true;
+
+        // Reject any reads still waiting — the stream is gone and no more data will arrive.
+        foreach ($this->reads as [$deferred]) {
+            $deferred->reject(new \RuntimeException('Buffer closed'));
+        }
+        $this->reads = [];
+
         $this->emit('close');
     }
 }

src/Discord/Voice/OggPage.php

@@ -137,27 +137,59 @@ public static function fromBuffer(Buffer $buffer, ?int $timeout = -1): PromiseIn
     }
 
     /**
-     * Compute the Ogg-specific CRC-32 checksum.
+     * Precomputed 256-entry CRC lookup table (Ogg polynomial 0x04C11DB7).
+     * Populated once on first use via {@see buildCrcTable()}.
+     *
+     * @var int[]|null
+     */
+    private static ?array $crcTable = null;
+
+    /**
+     * Build the 256-entry CRC lookup table for polynomial 0x04C11DB7.
+     *
+     * @return int[]
+     */
+    private static function buildCrcTable(): array
+    {
+        $table = [];
+        for ($i = 0; $i < 256; $i++) {
+            $crc = $i << 24;
+            for ($j = 0; $j < 8; $j++) {
+                $crc = ($crc & 0x80000000)
+                    ? (($crc << 1) ^ 0x04C11DB7) & 0xFFFFFFFF
+                    : ($crc << 1) & 0xFFFFFFFF;
+            }
+            $table[$i] = $crc;
+        }
+
+        return $table;
+    }
+
+    /**
+     * Compute the Ogg-specific CRC-32 checksum using a precomputed lookup table.
      *
      * Uses polynomial 0x04C11DB7 with an initial value of 0 and no final XOR,
      * which differs from the standard CRC-32 used by PHP's crc32().
      *
+     * The lookup table reduces the inner 8-iteration bit loop to a single
+     * array access per byte, significantly reducing CPU time on the event loop.
+     *
      * @param string $data Raw page bytes with the 4-byte checksum field zeroed out.
      *
      * @return int The computed CRC-32 value.
      */
     private static function oggCrc32(string $data): int
     {
+        if (self::$crcTable === null) {
+            self::$crcTable = self::buildCrcTable();
+        }
+
         $crc = 0;
-        for ($i = 0; $i < strlen($data); $i++) {
-            $crc ^= (ord($data[$i]) << 24);
-            for ($j = 0; $j < 8; $j++) {
-                if ($crc & 0x80000000) {
-                    $crc = (($crc << 1) ^ 0x04C11DB7) & 0xFFFFFFFF;
-                } else {
-                    $crc = ($crc << 1) & 0xFFFFFFFF;
-                }
-            }
+        $len = strlen($data);
+        $table = self::$crcTable;
+
+        for ($i = 0; $i < $len; $i++) {
+            $crc = ($table[(($crc >> 24) ^ ord($data[$i])) & 0xFF] ^ ($crc << 8)) & 0xFFFFFFFF;
         }
 
         return $crc;

src/Discord/Voice/OggStream.php

@@ -122,7 +122,7 @@ public function getPacket(): PromiseInterface
     private function parsePackets(): PromiseInterface
     {
         return new Promise(function ($resolve, $reject) {
-            OggPage::fromBuffer($this->buffer, timeout: 0)->then(function ($page) use ($resolve) {
+            OggPage::fromBuffer($this->buffer, timeout: -1)->then(function ($page) use ($resolve) {
                 $packets = [];
                 $partial = $this->leftover;
                 foreach ($page->iterPackets() as [$data, $complete]) {
@@ -136,7 +136,8 @@ private function parsePackets(): PromiseInterface
 
                 $resolve($packets);
             }, function (\Exception $e) use ($resolve, $reject) {
-                if ($e instanceof BufferTimedOutException) {
+                if ($e instanceof BufferTimedOutException || str_contains($e->getMessage(), 'Buffer closed')) {
+                    // Buffer is exhausted — signal EOF to the caller.
                     $resolve(null);
                 } else {
                     $reject($e);

src/Discord/Voice/Processes/Ffmpeg.php

@@ -73,7 +73,7 @@ public static function encode(
         ?array $preArgs = null
     ): Process {
         $flags = [
-            '-protocol_whitelist', 'http,https,tcp,tls,crypto,pipe',
+            '-protocol_whitelist', 'file,http,https,tcp,tls,crypto,pipe',
             '-i', escapeshellarg($filename ?? 'pipe:0'),
             '-map_metadata', '-1',
             '-f', 'opus',

src/Discord/Voice/VoiceClient.php

@@ -471,6 +471,10 @@ public static function checkForExecutable(string $executable): ?string
     /**
      * Plays a file/url on the voice stream.
      *
+     * FFmpeg is used to decode the file, so any format ffmpeg supports is accepted
+     * (e.g. WAV, OGG Opus, MP3, FLAC). Raw PCM files (.pcm) are NOT supported here
+     * because ffmpeg cannot auto-detect the format — use {@see playPcmFile()} instead.
+     *
      * @param string $file     The file/url to play.
      * @param int    $channels Deprecated, Discord only supports 2 channels.
      *
@@ -595,7 +599,42 @@ public function playRawStream($stream, int $channels = 2, int $audioRate = 48000
     }
 
     /**
-     * Plays an Ogg Opus stream.
+     * Plays a raw PCM file on the voice stream.
+     *
+     * This is a convenience wrapper around {@see playRawStream()} for files saved
+     * as raw signed 16-bit little-endian PCM (e.g. recordings produced by
+     * {@see record()} with {@see RecordingFormat::PCM}).
+     *
+     * @param string $path      Absolute or relative path to the raw PCM file.
+     * @param int    $channels  Number of audio channels (default: 2 = stereo).
+     * @param int    $audioRate Sample rate in Hz (default: 48000).
+     *
+     * @throws FileNotFoundException     if the file does not exist.
+     * @throws \RuntimeException         if the file cannot be opened or audio is already playing.
+     *
+     * @return PromiseInterface
+     */
+    public function playPcmFile(string $path, int $channels = 2, int $audioRate = 48000): PromiseInterface
+    {
+        $deferred = new Deferred();
+
+        if (! file_exists($path)) {
+            $deferred->reject(new FileNotFoundException("Could not find the file \"{$path}\"."));
+
+            return $deferred->promise();
+        }
+
+        $handle = fopen($path, 'rb');
+        if ($handle === false) {
+            $deferred->reject(new \RuntimeException("Could not open file for reading: \"{$path}\"."));
+
+            return $deferred->promise();
+        }
+
+        return $this->playRawStream($handle, $channels, $audioRate);
+    }
+
+    /**
      *
      * @param resource|Process|Stream $stream The Ogg Opus stream to be sent.
      *
@@ -644,6 +683,7 @@ public function playOggStream($stream): PromiseInterface
 
         $this->buffer = new RealBuffer();
         $stream->on('data', fn ($d) => $this->buffer->write($d));
+        $stream->on('end', fn () => $this->buffer->end());
 
         /** @var OggStream */
         $ogg = null;