Add new voice guides

Documentation/docfx.json

@@ -35,7 +35,7 @@
     ],
     "resource": [
       {
-        "files": [ "images/**", "robots.txt" ]
+        "files": [ "images/**", "sounds/**", "robots.txt" ]
       }
     ],
     "overwrite": [

Documentation/guides/toc.yml

@@ -22,6 +22,18 @@
       href: basic-concepts/sharding.md
     - name: Voice
       href: basic-concepts/voice.md
+- name: Voice
+  items:
+    - name: Overview
+      href: voice/index.md
+    - name: Voice Connection
+      href: voice/voice-connection.md
+    - name: Sending Voice
+      href: voice/sending-voice.md
+    - name: Receiving Voice
+      href: voice/receiving-voice.md
+    - name: Troubleshooting
+      href: voice/troubleshooting.md
 - name: Services
   items:
     - name: Introduction

Documentation/guides/voice/ReceivingVoice/Examples.cs

@@ -0,0 +1,73 @@
+using System.Threading.Channels;
+
+using NetCord.Gateway.Voice;
+
+namespace MyBot;
+
+internal static class Examples
+{
+    public static void VoiceReceiveEvent(VoiceClient voiceClient)
+    {
+        voiceClient.VoiceReceive += args =>
+        {
+            if (voiceClient.Cache.SsrcUsers.TryGetValue(args.Ssrc, out var userId))
+                Console.WriteLine($"Received audio from user {userId}");
+            else
+                Console.WriteLine($"Received audio from unknown user with SSRC {args.Ssrc}");
+
+            return default;
+        };
+    }
+
+    public static void VoiceReceiveEventAsyncHandler(VoiceClient voiceClient)
+    {
+        voiceClient.VoiceReceive += args =>
+        {
+            // You may consider renting a buffer
+            // from 'ArrayPool<T>' in a real application
+            var ownedFrame = args.Frame.ToArray();
+
+            return HandleAsync(ownedFrame, args.Ssrc);
+
+            static async ValueTask HandleAsync(byte[] frame, uint ssrc)
+            {
+                await Task.Delay(100); // Simulate async processing
+
+                Console.WriteLine($"Processed audio frame from SSRC {ssrc}");
+            }
+        };
+    }
+
+    public static async Task BufferingReceivedAudio(VoiceClient voiceClient)
+    {
+        // Configure the channel to drop frames when the buffer is full;
+        // 1000 frames means from 2.5 to 120 seconds of
+        // audio depending on the Opus frame duration;
+        // Dropping frames should generally never happen, but it is a good
+        // idea to handle it just in case to avoid running out of memory
+        var channel = Channel.CreateBounded<(byte[] Frame, uint? Timestamp)>(new BoundedChannelOptions(1000)
+        {
+            FullMode = BoundedChannelFullMode.DropWrite,
+        });
+
+        var writer = channel.Writer;
+
+        voiceClient.VoiceReceive += args =>
+        {
+            // You may consider renting a buffer from 'ArrayPool<T>' in a real application
+            var frame = args.Frame.ToArray();
+
+            return writer.WriteAsync((frame, args.Timestamp));
+        };
+
+        await foreach (var (frame, timestamp) in channel.Reader.ReadAllAsync())
+            Console.WriteLine($"Received audio frame of size {frame.Length} with timestamp {timestamp}");
+    }
+
+    public static void CreateOpusDecodeStream(Stream stream)
+    {
+        OpusDecodeStream opusDecodeStream = new(stream,
+                                                PcmFormat.Float,
+                                                VoiceChannels.Stereo);
+    }
+}

Documentation/guides/voice/ReceivingVoice/ReceivingVoice.csproj

@@ -0,0 +1,7 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\NetCord\NetCord.csproj" />
+  </ItemGroup>
+
+</Project>

Documentation/guides/voice/SendingVoice/Examples.cs

@@ -0,0 +1,74 @@
+using System.Diagnostics;
+
+using NetCord.Gateway.Voice;
+
+namespace MyBot;
+
+internal static class Examples
+{
+    public static void CreateVoiceStream(VoiceClient voiceClient)
+    {
+        var voiceStream = voiceClient.CreateVoiceStream();
+    }
+
+    public static void CreateVoiceStreamWithConfiguration(VoiceClient voiceClient)
+    {
+        var voiceStream = voiceClient.CreateVoiceStream(new VoiceStreamConfiguration
+        {
+            NormalizeSpeed = false,
+            FrameDuration = 60,
+        });
+    }
+
+    public static void CreateOpusEncodeStream(Stream voiceStream)
+    {
+        OpusEncodeStream opusEncodeStream = new(voiceStream,
+                                                PcmFormat.Float,
+                                                VoiceChannels.Stereo,
+                                                OpusApplication.Audio);
+    }
+
+    public static void CreateOpusEncodeStreamWithConfiguration(Stream voiceStream)
+    {
+        OpusEncodeStream opusEncodeStream = new(voiceStream,
+                                                PcmFormat.Float,
+                                                VoiceChannels.Stereo,
+                                                OpusApplication.Audio,
+                                                new OpusEncodeStreamConfiguration
+                                                {
+                                                    Segment = false,
+                                                    FrameDuration = 2.5f,
+                                                });
+    }
+
+    public static async Task FfmpegAsync(OpusEncodeStream opusEncodeStream, string input)
+    {
+        using var process = Process.Start(new ProcessStartInfo
+        {
+            FileName = "ffmpeg",
+            ArgumentList =
+            {
+                // Input file
+                "-i", input,
+                // Output format 32-bit float PCM with native endianness
+                "-f", BitConverter.IsLittleEndian ? "f32le" : "f32be",
+                // Sampling rate 48kHz
+                "-ar", "48000",
+                // 2 channels (stereo)
+                "-ac", "2",
+                // Output to stdout
+                "pipe:1",
+            },
+            RedirectStandardOutput = true,
+        })!;
+
+        var ffmpegOutput = process.StandardOutput.BaseStream;
+
+        // Copy the FFmpeg output directly to the OpusEncodeStream
+        await ffmpegOutput.CopyToAsync(opusEncodeStream);
+
+        // Flush the OpusEncodeStream to ensure all data is sent,
+        // appended by the silence frames to prevent audio interpolation
+        await opusEncodeStream.FlushAsync();
+    }
+}

Documentation/guides/voice/SendingVoice/SendingVoice.csproj

@@ -0,0 +1,7 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\NetCord\NetCord.csproj" />
+  </ItemGroup>
+
+</Project>

Documentation/guides/voice/Troubleshooting/Examples.cs

@@ -0,0 +1,31 @@
+using NetCord.Gateway;
+using NetCord.Gateway.Voice;
+
+namespace MyBot;
+
+internal static class Examples
+{
+    public static async Task LongerConnectionTimeoutAsync(GatewayClient client,
+                                                          ulong guildId,
+                                                          ulong channelId,
+                                                          VoiceClientConfiguration? configuration)
+    {
+        var voiceClient = await client.JoinVoiceChannelAsync(guildId, channelId, configuration, TimeSpan.FromSeconds(15));
+    }
+
+    public static async Task LongerExternalSocketAddressDiscoveryTimeoutAsync()
+    {
+        VoiceClientConfiguration configuration = new()
+        {
+            ExternalSocketAddressDiscoveryTimeout = TimeSpan.FromSeconds(15),
+        };
+    }
+
+    public static async Task KeepAliveAsync(VoiceClient voiceClient, CancellationToken cancellationToken)
+    {
+        using PeriodicTimer timer = new(TimeSpan.FromSeconds(30));
+
+        while (await timer.WaitForNextTickAsync(cancellationToken))
+            await voiceClient.SendDatagramAsync(ReadOnlyMemory<byte>.Empty, cancellationToken);
+    }
+}

Documentation/guides/voice/Troubleshooting/Troubleshooting.csproj

@@ -0,0 +1,7 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\NetCord\NetCord.csproj" />
+  </ItemGroup>
+
+</Project>