diff --git a/src/Discord.Net/Audio/AudioMode.cs b/src/Discord.Net/Audio/AudioMode.cs index 7cc5a08c1..bc883d6c9 100644 --- a/src/Discord.Net/Audio/AudioMode.cs +++ b/src/Discord.Net/Audio/AudioMode.cs @@ -2,12 +2,17 @@ namespace Discord.Audio { + /// Specifies an audio mode for Discord. [Flags] public enum AudioMode : byte { + /// Audio send/receive is disabled. Disabled = 0, + /// Audio can only be broadcasted by the client. Outgoing = 1, + /// Audio can only be received by the client. Incoming = 2, + /// Audio can be sent and received by the client. Both = Outgoing | Incoming } } diff --git a/src/Discord.Net/Audio/IAudioClient.cs b/src/Discord.Net/Audio/IAudioClient.cs index 312152142..546b9e3f7 100644 --- a/src/Discord.Net/Audio/IAudioClient.cs +++ b/src/Discord.Net/Audio/IAudioClient.cs @@ -5,19 +5,26 @@ namespace Discord.Audio { public interface IAudioClient { + /// Fired when the client connects to Discord. event Func Connected; + /// Fired when the client disconnects from Discord. event Func Disconnected; + /// Fired in response to a heartbeat, providing the old and new latency. event Func LatencyUpdated; + /// Gets the API client used for communicating with Discord. DiscordVoiceAPIClient ApiClient { get; } /// Gets the current connection state of this client. ConnectionState ConnectionState { get; } /// Gets the estimated round-trip latency, in milliseconds, to the gateway server. int Latency { get; } + /// Disconnects the current client from Discord. Task DisconnectAsync(); + /// Creates an Opus stream for sending raw Opus-encoded data. RTPWriteStream CreateOpusStream(int samplesPerFrame, int bufferSize = 4000); + /// Creates a PCM stream for sending unencoded PCM data. OpusEncodeStream CreatePCMStream(int samplesPerFrame, int? bitrate = null, OpusApplication application = OpusApplication.MusicOrMixed, int bufferSize = 4000); } } diff --git a/src/Discord.Net/Audio/Opus/OpusApplication.cs b/src/Discord.Net/Audio/Opus/OpusApplication.cs index d6a3ce0cf..12a6ff822 100644 --- a/src/Discord.Net/Audio/Opus/OpusApplication.cs +++ b/src/Discord.Net/Audio/Opus/OpusApplication.cs @@ -1,9 +1,16 @@ namespace Discord.Audio { + /// The types of encoding which Opus supports during encoding. public enum OpusApplication : int { + /// Specifies that the uses + /// encoding to improve the quality of voice communication. Voice = 2048, + /// Specifies that the uses + /// encoding to improve the overall quality of mixed-media audio transmission. MusicOrMixed = 2049, + /// Specifies that the uses + /// encoding to reduce overall latency. LowLatency = 2051 } } diff --git a/src/Discord.Net/Audio/Opus/OpusDecoder.cs b/src/Discord.Net/Audio/Opus/OpusDecoder.cs index ea9376f82..99e0152bc 100644 --- a/src/Discord.Net/Audio/Opus/OpusDecoder.cs +++ b/src/Discord.Net/Audio/Opus/OpusDecoder.cs @@ -24,7 +24,9 @@ namespace Discord.Audio /// Produces PCM samples from Opus-encoded audio. /// PCM samples to decode. /// Offset of the frame in input. + /// Number of bytes of the frame in input. /// Buffer to store the decoded frame. + /// Zero-based offset for the output. public unsafe int DecodeFrame(byte[] input, int inputOffset, int inputCount, byte[] output, int outputOffset) { int result = 0; diff --git a/src/Discord.Net/Audio/Opus/OpusEncoder.cs b/src/Discord.Net/Audio/Opus/OpusEncoder.cs index c1eb3843d..5ed34ac3d 100644 --- a/src/Discord.Net/Audio/Opus/OpusEncoder.cs +++ b/src/Discord.Net/Audio/Opus/OpusEncoder.cs @@ -31,6 +31,9 @@ namespace Discord.Audio /// Produces Opus encoded audio from PCM samples. /// PCM samples to encode. /// Buffer to store the encoded frame. + /// Offset of the frame in input. + /// Number of bytes of the frame in input. + /// Zero-based offset for the output. /// Length of the frame contained in outputBuffer. public unsafe int EncodeFrame(byte[] input, int inputOffset, int inputCount, byte[] output, int outputOffset) { diff --git a/src/Discord.Net/Audio/Sodium/SecretBox.cs b/src/Discord.Net/Audio/Sodium/SecretBox.cs index 4187c9f08..4e601fb25 100644 --- a/src/Discord.Net/Audio/Sodium/SecretBox.cs +++ b/src/Discord.Net/Audio/Sodium/SecretBox.cs @@ -3,13 +3,14 @@ using System.Runtime.InteropServices; namespace Discord.Audio { - public unsafe static class SecretBox + public unsafe static class SecretBox // TODO: should this be public? { [DllImport("libsodium", EntryPoint = "crypto_secretbox_easy", CallingConvention = CallingConvention.Cdecl)] private static extern int SecretBoxEasy(byte* output, byte* input, long inputLength, byte[] nonce, byte[] secret); [DllImport("libsodium", EntryPoint = "crypto_secretbox_open_easy", CallingConvention = CallingConvention.Cdecl)] private static extern int SecretBoxOpenEasy(byte* output, byte* input, long inputLength, byte[] nonce, byte[] secret); + /// Encrypts a payload with the given nonce and secret. public static int Encrypt(byte[] input, int inputOffset, int inputLength, byte[] output, int outputOffset, byte[] nonce, byte[] secret) { fixed (byte* inPtr = input) @@ -21,6 +22,7 @@ namespace Discord.Audio return inputLength + 16; } } + /// Decrypts a payload with the given nonce and secret. public static int Decrypt(byte[] input, int inputOffset, int inputLength, byte[] output, int outputOffset, byte[] nonce, byte[] secret) { fixed (byte* inPtr = input) diff --git a/src/Discord.Net/Audio/Streams/OpusDecodeStream.cs b/src/Discord.Net/Audio/Streams/OpusDecodeStream.cs index c059955a8..1c7cfe765 100644 --- a/src/Discord.Net/Audio/Streams/OpusDecodeStream.cs +++ b/src/Discord.Net/Audio/Streams/OpusDecodeStream.cs @@ -1,5 +1,6 @@ namespace Discord.Audio { + /// A stream which decodes Opus frames as they are read. public class OpusDecodeStream : RTPReadStream { private readonly byte[] _buffer; @@ -13,12 +14,14 @@ _decoder = new OpusDecoder(samplingRate, channels); } + /// Reads Opus-encoded frame from the stream, filling the buffer with PCM data public override int Read(byte[] buffer, int offset, int count) { count = _decoder.DecodeFrame(buffer, offset, count, _buffer, 0); return base.Read(_buffer, 0, count); } + /// protected override void Dispose(bool disposing) { base.Dispose(disposing); diff --git a/src/Discord.Net/Audio/Streams/OpusEncodeStream.cs b/src/Discord.Net/Audio/Streams/OpusEncodeStream.cs index ef773ca56..55d1566d2 100644 --- a/src/Discord.Net/Audio/Streams/OpusEncodeStream.cs +++ b/src/Discord.Net/Audio/Streams/OpusEncodeStream.cs @@ -1,8 +1,11 @@ namespace Discord.Audio { + /// A stream which encodes Opus frames as raw PCM data is written. public class OpusEncodeStream : RTPWriteStream { - public int SampleRate = 48000; + /// The sample rate of the Opus stream. + public int SampleRate = 48000; // TODO: shouldn't these be readonly? + /// The number of channels of the Opus stream. public int Channels = 2; private readonly OpusEncoder _encoder; @@ -18,12 +21,14 @@ _encoder.SetBitrate(bitrate.Value); } + /// Writes Opus-encoded PCM data to the stream. public override void Write(byte[] buffer, int offset, int count) { count = _encoder.EncodeFrame(buffer, offset, count, _buffer, 0); base.Write(_buffer, 0, count); } + /// protected override void Dispose(bool disposing) { base.Dispose(disposing); diff --git a/src/Discord.Net/Audio/Streams/RTPReadStream.cs b/src/Discord.Net/Audio/Streams/RTPReadStream.cs index 4bf7f5e1b..75dd26e7e 100644 --- a/src/Discord.Net/Audio/Streams/RTPReadStream.cs +++ b/src/Discord.Net/Audio/Streams/RTPReadStream.cs @@ -4,14 +4,18 @@ using System.IO; namespace Discord.Audio { + /// A stream used for reading raw audio data from Discord. public class RTPReadStream : Stream { private readonly BlockingCollection _queuedData; //TODO: Replace with max-length ring buffer private readonly AudioClient _audioClient; private readonly byte[] _buffer, _nonce, _secretKey; + /// public override bool CanRead => true; + /// public override bool CanSeek => false; + /// public override bool CanWrite => true; internal RTPReadStream(AudioClient audioClient, byte[] secretKey, int bufferSize = 4000) @@ -23,12 +27,14 @@ namespace Discord.Audio _nonce = new byte[24]; } + /// public override int Read(byte[] buffer, int offset, int count) { var queuedData = _queuedData.Take(); Buffer.BlockCopy(queuedData, 0, buffer, offset, Math.Min(queuedData.Length, count)); return queuedData.Length; } + /// public override void Write(byte[] buffer, int offset, int count) { Buffer.BlockCopy(buffer, 0, _nonce, 0, 12); @@ -38,16 +44,21 @@ namespace Discord.Audio _queuedData.Add(newBuffer); } + /// public override void Flush() { throw new NotSupportedException(); } + /// public override long Length { get { throw new NotSupportedException(); } } + /// public override long Position { get { throw new NotSupportedException(); } set { throw new NotSupportedException(); } } + /// public override void SetLength(long value) { throw new NotSupportedException(); } + /// public override long Seek(long offset, SeekOrigin origin) { throw new NotSupportedException(); } } } diff --git a/src/Discord.Net/Audio/Streams/RTPWriteStream.cs b/src/Discord.Net/Audio/Streams/RTPWriteStream.cs index d547f021a..427b65299 100644 --- a/src/Discord.Net/Audio/Streams/RTPWriteStream.cs +++ b/src/Discord.Net/Audio/Streams/RTPWriteStream.cs @@ -3,6 +3,7 @@ using System.IO; namespace Discord.Audio { + /// A stream used for writing raw audio data to Discord. public class RTPWriteStream : Stream { private readonly AudioClient _audioClient; @@ -10,10 +11,14 @@ namespace Discord.Audio private int _samplesPerFrame; private uint _ssrc, _timestamp = 0; + /// The current output buffer. protected readonly byte[] _buffer; + /// public override bool CanRead => false; + /// public override bool CanSeek => false; + /// public override bool CanWrite => true; internal RTPWriteStream(AudioClient audioClient, byte[] secretKey, int samplesPerFrame, uint ssrc, int bufferSize = 4000) @@ -32,6 +37,7 @@ namespace Discord.Audio _nonce[11] = (byte)(_ssrc >> 0); } + /// public override void Write(byte[] buffer, int offset, int count) { unchecked @@ -51,17 +57,23 @@ namespace Discord.Audio _audioClient.Send(_buffer, count + 12); } + /// public override void Flush() { } + /// public override long Length { get { throw new NotSupportedException(); } } + /// public override long Position { get { throw new NotSupportedException(); } set { throw new NotSupportedException(); } } + /// public override int Read(byte[] buffer, int offset, int count) { throw new NotSupportedException(); } + /// public override void SetLength(long value) { throw new NotSupportedException(); } + /// public override long Seek(long offset, SeekOrigin origin) { throw new NotSupportedException(); } } } diff --git a/src/Discord.Net/Entities/Channels/ChannelType.cs b/src/Discord.Net/Entities/Channels/ChannelType.cs index f05f1598e..1a9771582 100644 --- a/src/Discord.Net/Entities/Channels/ChannelType.cs +++ b/src/Discord.Net/Entities/Channels/ChannelType.cs @@ -1,10 +1,15 @@ namespace Discord { + /// Specifies the type of channel a message was sent to or eceived from. public enum ChannelType { + /// A text channel Text = 0, + /// A direct-message text channel DM = 1, + /// A voice channel channel Voice = 2, + /// A group channel Group = 3 } }