Improve troubleshooting guide

Author: KubaZ2

Documentation/guides/voice/Troubleshooting/Examples.cs

@@ -0,0 +1,23 @@
+using NetCord.Gateway;
+using NetCord.Gateway.Voice;
+
+namespace MyBot;
+
+internal static class Examples
+{
+    public static async Task ConnectWithLongerTimeoutAsync(GatewayClient client,
+                                                           ulong guildId,
+                                                           ulong channelId,
+                                                           VoiceClientConfiguration? configuration)
+    {
+        var voiceClient = await client.JoinVoiceChannelAsync(guildId, channelId, configuration, TimeSpan.FromSeconds(10));
+    }
+
+    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>

Documentation/guides/voice/troubleshooting.md

@@ -1,13 +1,61 @@
 # Troubleshooting
 
-Sometimes, you may encounter issues when working with audio.
+Working with audio can sometimes introduce unexpected issues. Below are common problems and their corresponding troubleshooting steps to help you resolve them.
 
-Below you can find some common issues, as well as some troubleshooting steps you can take to resolve them.
+## Missing Native Dependencies
+
+If you encounter a @System.DllNotFoundException, it usually indicates missing or incompatible native dependencies. Refer to the [Native Dependencies](../basic-concepts/installing-native-dependencies.md) guide for steps on resolving this.
+
+---
+
+## Timeout When Connecting to Voice
+
+If you experience a @System.TimeoutException when connecting to a voice channel, it typically stems from one of the following issues:
+
+### Missing Permissions
+Ensure the bot has the @NetCord.Permissions.Connect permission in the target voice channel.
+
+### Channel Capacity
+Check if the voice channel is full; the bot needs an available slot to join.
+
+### Already Connected
+Verify that the bot isn't already active in the channel it is trying to join.
+
+### Slow Network Connection
+@NetCord.Gateway.Voice.GatewayClientExtensions.JoinVoiceChannelAsync* has a default timeout of 2 seconds, which might be too brief for slower networks. You can extend this timeout (e.g., to 10 seconds) as shown below:
+[!code-cs[Join Voice Channel with Extended Timeout](Troubleshooting/Examples.cs#L13)]
+
+---
+
+## Audio Not Playing
+
+If the bot connects to a voice channel but no audio is heard, verify the following:
+
+### Missing Permissions
+Ensure the bot has the @NetCord.Permissions.Speak permission in the voice channel. The bot will appear as muted to other users if it lacks this permission.
+
+### Speaking State
+Make sure to call @NetCord.Gateway.Voice.VoiceClient.EnterSpeakingStateAsync* with the correct @NetCord.Gateway.Voice.SpeakingFlags before sending audio.
+
+---
 
 ## Failed to Get External Socket Address
 
-If you see the error "Failed to get the external socket address. Aborting the client." in your logs, it means that something blocks the IP Discovery response from Discord. This can be caused by various reasons, such as firewall settings or router configurations. If you encounter this issue, try using for example your mobile phone's hotspot to see if the issue is related to your router configuration. If it works on the hotspot, you may need to check your router's settings.
+If you see the error `Failed to get the external socket address. Aborting the client.` in your logs, something is blocking the IP Discovery request or response. 
+
+This is typically caused by firewall restrictions or router configurations. To diagnose whether it's a local network issue, try connecting the bot through a different network, such as a mobile hotspot.
+
+---
+
+## Receiving Audio Stops After Some Time
+
+If audio suddenly cuts out after working normally for a while, consider these common causes:
+
+### UDP Flood Protection
+Your firewall or router might be blocking UDP packets due to a built-in flood protection feature. Try disabling this feature in your router settings, or temporarily switch to a mobile hotspot to see if the issue is strictly related to your router's configuration.
 
-## Audio Stops After Some Time
+### Closed UDP Socket
+Sockets can sometimes close automatically, especially if the bot is listening without transmitting any audio. You can prevent this by adjusting your firewall/NAT settings or by implementing a keep-alive mechanism. 
 
-If you receive audio for some time and then it suddenly stops, it may be caused by your router blocking the packets after some time. This can be caused by the router's UDP flood protection. You can try disabling this feature in your router's settings to see if it resolves the issue.
+Sending a small, empty data packet at regular intervals will ensure the UDP connection stays open, as demonstrated below:
+[!code-cs[Keep Alive](Troubleshooting/Examples.cs#L18-L21)]

NetCord.slnx

@@ -61,6 +61,7 @@
     <Project Path="Documentation/guides/voice/Voice/Voice.csproj" />
     <Project Path="Documentation/guides/voice/VoiceSetup/VoiceSetup.csproj" />
     <Project Path="Documentation/guides/voice/VoiceConnection/VoiceConnection.csproj" />
+    <Project Path="Documentation/guides/voice/Troubleshooting/Troubleshooting.csproj" />
   </Folder>
   <Folder Name="/Hosting/">
     <Project Path="Hosting/NetCord.Hosting.AspNetCore/NetCord.Hosting.AspNetCore.csproj" />