Refactor voice receiving (#283)

* Refactor voice receiving

* Add DoNotParallelize attribute to idle timeout tests

* Fix a test

* Update BufferedVoiceReceiveHandlerTests to support async operations

* Improve tests and the buffered handler

* feat: Enhance voice handling with loss correction capabilities

- Updated VoiceReceiveEventArgs to include a canCorrectLoss flag for better loss management.
- Modified OpusDecoder methods to accept a decodeFec parameter for handling forward error correction.
- Adjusted OpusDecodeStream to utilize the new OpusDecoder methods.
- Enhanced VoiceClient to invoke events with loss correction information.
- Refactored VoiceReceiveData to use flags for packet status, including canCorrectLoss.
- Updated BufferedVoiceReceiveHandlerTests to validate new loss correction behavior.
- Added tests for canCorrectLoss scenarios to ensure proper handling of lost packets.
- Adjusted VoiceCommands to utilize updated decoding logic for handling voice frames.

* Correct (I believe) logic for handling lost packets in BufferedVoiceReceiveHandler

* Refactor

* Update buffered voice receive handler

* Improve voice receive handler

* Add FEC support

* Add FEC handling to BufferedVoiceReceiveHandlerTests

* Improve EvictLostFrames and rewrite and improve tests

* Refactor VoiceReceiveEventArgs and LostVoiceReceiveEventArgs for clarity and improved FEC handling; update VoiceCommands to streamline lost frame handling

* Refactor test voice commands

* Replace delegate with Action for VoiceReceive event in VoiceReceiveHandler

* Remove commented-out code and unnecessary console output in VoiceClient and BufferedVoiceReceiveHandler

* Remove unused using directive from BufferedVoiceReceiveHandler

* Optimize buffered voice receive handler state allocations

* Refactor window and buffer range checks in BufferedVoiceReceiveHandler for clarity and correctness

* Rename stop timer to timeout timer and improve datagram length validation in VoiceClient

* Refactor BufferedVoiceReceiveHandler to use VoiceReceiveData for improved clarity and data handling

* Remove BufferedVoiceReceiveHandler

* Cleanup

* Simplify voice receive event args

* Abandon VoiceReceiveHandler

* Fix voice guide snippet

* Remove allow unsafe blocks from NetCord.Test.csproj

* Make voice receiving exception safe against malformed payloads (hopefully)

* Skip decryption when there is no VoiceReceive event handler and remove a useless extension range check

* Fix voice receive logging and refactor

* Add a new line

* Add a comment to ReceiveVoice in guide snippet

* Make IP Discovery mandatory

* Optimize logging

* Improve a guides snippet comment and refactor VoiceClient slightly

Author: KubaZ2

Documentation/guides/basic-concepts/Voice/VoiceModule.cs

@@ -129,7 +129,6 @@ public async Task<string> EchoAsync()
             voiceState.ChannelId.GetValueOrDefault(),
             new VoiceClientConfiguration
             {
-                ReceiveHandler = new VoiceReceiveHandler(), // Required to receive voice
                 Logger = new ConsoleLogger(),
             });
 
@@ -141,14 +140,9 @@ public async Task<string> EchoAsync()
 
         voiceClient.VoiceReceive += args =>
         {
-            // If the timestamp is null, the packet was lost.
-            // We skip it, which mirrors the packet loss to the echo recipients.
-            if (args.Timestamp is not { } timestamp)
-                return default;
-
-            // Pass current user voice directly to SendAsync to create echo
+            // Send the received voice back if the received voice is from the user that invoked the command
             if (voiceClient.Cache.SsrcUsers.TryGetValue(args.Ssrc, out var voiceUserId) && voiceUserId == userId)
-                voiceClient.SendVoice(args.SequenceNumber, timestamp, args.Frame);
+                voiceClient.SendVoice(args.SequenceNumber, args.Timestamp, args.Frame);
 
             return default;
         };

Documentation/guides/basic-concepts/voice.md

@@ -13,4 +13,4 @@ Follow the [installation guide](installing-native-dependencies.md) to install th
 [!code-cs[VoiceModule.cs](Voice/VoiceModule.cs#L13-L110)]
 
 ### Receiving Voice
-[!code-cs[VoiceModule.cs](Voice/VoiceModule.cs#L112-L158)]
+[!code-cs[VoiceModule.cs](Voice/VoiceModule.cs#L112-L152)]

NetCord/Gateway/Voice/EventArgs/VoiceReceiveEventArgs.cs

@@ -1,26 +1,35 @@
+using System.Runtime.InteropServices;
+
 namespace NetCord.Gateway.Voice;
 
-public readonly ref struct VoiceReceiveEventArgs(byte[]? buffer, int frameIndex, int frameLength, uint ssrc, uint? timestamp, ushort sequenceNumber)
+[StructLayout(LayoutKind.Auto)]
+public readonly ref struct VoiceReceiveEventArgs
 {
-    internal readonly byte[]? _buffer = buffer;
+    public VoiceReceiveEventArgs(ReadOnlySpan<byte> frame, uint ssrc, uint timestamp, ushort sequenceNumber)
+    {
+        Frame = frame;
+        Ssrc = ssrc;
+        Timestamp = timestamp;
+        SequenceNumber = sequenceNumber;
+    }
 
     /// <summary>
     /// The voice frame data.
     /// </summary>
-    public ReadOnlySpan<byte> Frame => new(_buffer, frameIndex, frameLength);
+    public readonly ReadOnlySpan<byte> Frame { get; }
 
     /// <summary>
     /// The synchronization source (SSRC) of the sender of the voice frame.
     /// </summary>
-    public uint Ssrc => ssrc;
+    public readonly uint Ssrc { get; }
 
     /// <summary>
-    /// The timestamp of the voice frame. <see langword="null"/> when the frame was lost.
+    /// The timestamp of the voice frame.
     /// </summary>
-    public uint? Timestamp => timestamp;
+    public readonly uint Timestamp { get; }
 
     /// <summary>
     /// The sequence number of the voice frame.
     /// </summary>
-    public ushort SequenceNumber => sequenceNumber;
+    public readonly ushort SequenceNumber { get; }
 }

NetCord/Gateway/Voice/IVoiceReceiveHandler.cs

@@ -33,12 +33,13 @@ public OpusDecoder(VoiceChannels channels)
     /// <param name="data">Input payload. Use <see langword="null"/> to indicate packet loss.</param>
     /// <param name="pcm">Output signal.</param>
     /// <param name="frameSize">Number of samples per channel in the output signal.</param>
+    /// <param name="decodeFec">Whether to decode using forward error correction data, if available.</param>
     /// <returns>The number of decoded samples per channel.</returns>
-    public int Decode(ReadOnlySpan<byte> data, Span<byte> pcm, int frameSize)
+    public int Decode(ReadOnlySpan<byte> data, Span<byte> pcm, int frameSize, bool decodeFec)
     {
         ValidatePcm(pcm.Length, frameSize, PcmFormat.Short, _channels, nameof(pcm));
 
-        int result = OpusDecode(_decoder, data, data.Length, pcm, frameSize, 0);
+        int result = OpusDecode(_decoder, data, data.Length, pcm, frameSize, decodeFec ? 1 : 0);
 
         ValidateResult(result);
 
@@ -51,10 +52,11 @@ public int Decode(ReadOnlySpan<byte> data, Span<byte> pcm, int frameSize)
     /// <param name="data">Input payload. Use <see langword="null"/> to indicate packet loss.</param>
     /// <param name="pcm">Output signal.</param>
     /// <param name="frameSize">Number of samples per channel in the output signal.</param>
+    /// <param name="decodeFec">Whether to decode using forward error correction data, if available.</param>
     /// <returns>The number of decoded samples per channel.</returns>
-    public int Decode(ReadOnlySpan<byte> data, Span<short> pcm, int frameSize)
+    public int Decode(ReadOnlySpan<byte> data, Span<short> pcm, int frameSize, bool decodeFec)
     {
-        return Decode(data, MemoryMarshal.AsBytes(pcm), frameSize);
+        return Decode(data, MemoryMarshal.AsBytes(pcm), frameSize, decodeFec);
     }
 
     /// <summary>
@@ -63,12 +65,13 @@ public int Decode(ReadOnlySpan<byte> data, Span<short> pcm, int frameSize)
     /// <param name="data">Input payload. Use <see langword="null"/> to indicate packet loss.</param>
     /// <param name="pcm">Output signal.</param>
     /// <param name="frameSize">Number of samples per channel in the output signal.</param>
+    /// <param name="decodeFec">Whether to decode using forward error correction data, if available.</param>
     /// <returns>The number of decoded samples per channel.</returns>
-    public int DecodeFloat(ReadOnlySpan<byte> data, Span<byte> pcm, int frameSize)
+    public int DecodeFloat(ReadOnlySpan<byte> data, Span<byte> pcm, int frameSize, bool decodeFec)
     {
         ValidatePcm(pcm.Length, frameSize, PcmFormat.Float, _channels, nameof(pcm));
 
-        int result = OpusDecodeFloat(_decoder, data, data.Length, pcm, frameSize, 0);
+        int result = OpusDecodeFloat(_decoder, data, data.Length, pcm, frameSize, decodeFec ? 1 : 0);
 
         ValidateResult(result);
 
@@ -81,10 +84,11 @@ public int DecodeFloat(ReadOnlySpan<byte> data, Span<byte> pcm, int frameSize)
     /// <param name="data">Input payload. Use <see langword="null"/> to indicate packet loss.</param>
     /// <param name="pcm">Output signal.</param>
     /// <param name="frameSize">Number of samples per channel in the output signal.</param>
+    /// <param name="decodeFec">Whether to decode using forward error correction data, if available.</param>
     /// <returns>The number of decoded samples per channel.</returns>
-    public int DecodeFloat(ReadOnlySpan<byte> data, Span<float> pcm, int frameSize)
+    public int DecodeFloat(ReadOnlySpan<byte> data, Span<float> pcm, int frameSize, bool decodeFec)
     {
-        return DecodeFloat(data, MemoryMarshal.AsBytes(pcm), frameSize);
+        return DecodeFloat(data, MemoryMarshal.AsBytes(pcm), frameSize, decodeFec);
     }
 
     public void Dispose()

NetCord/Gateway/Voice/NullVoiceReceiveHandler.cs

@@ -36,12 +36,12 @@ public OpusDecodeStream(Stream next, PcmFormat format, VoiceChannels channels, b
 
     private int Decode(ReadOnlySpan<byte> data, Span<byte> pcm)
     {
-        return _decoder.Decode(data, pcm, _frameSize);
+        return _decoder.Decode(data, pcm, _frameSize, false);
     }
 
     private int DecodeFloat(ReadOnlySpan<byte> data, Span<byte> pcm)
     {
-        return _decoder.DecodeFloat(data, pcm, _frameSize);
+        return _decoder.DecodeFloat(data, pcm, _frameSize, false);
     }
 
     public override async ValueTask WriteAsync(ReadOnlyMemory<byte> buffer, CancellationToken cancellationToken = default)