feat: Speaker Toy

EXILED/Exiled.API/Exiled.API.csproj

@@ -17,6 +17,7 @@
     </ItemGroup>
 
     <ItemGroup>
+        <PackageReference Include="NVorbis" Version="0.10.5" />
         <PackageReference Include="StyleCop.Analyzers" Version="$(StyleCopVersion)" IncludeAssets="All" PrivateAssets="All" />
         <PackageReference Include="System.Memory" Version="4.5.5" />
         <PackageReference Include="Lib.Harmony" Version="$(HarmonyVersion)" />

EXILED/Exiled.API/Features/Toys/Speaker.cs

@@ -7,16 +7,30 @@
 
 namespace Exiled.API.Features.Toys
 {
-    using AdminToys;
+    using System.Collections.Generic;
+    using System.IO;
+    using System.Linq;
 
+    using AdminToys;
     using Enums;
-    using Exiled.API.Interfaces;
+    using Features;
+    using Interfaces;
+    using MEC;
+    using NVorbis;
+    using UnityEngine;
+    using Utils.Networking;
+    using VoiceChat.Codec;
+    using VoiceChat.Networking;
+
+    using Object = UnityEngine.Object;
 
     /// <summary>
     /// A wrapper class for <see cref="SpeakerToy"/>.
     /// </summary>
     public class Speaker : AdminToy, IWrapper<SpeakerToy>
     {
+        private bool stopPlayback;
+
         /// <summary>
         /// Initializes a new instance of the <see cref="Speaker"/> class.
         /// </summary>
@@ -29,6 +43,15 @@ internal Speaker(SpeakerToy speakerToy)
         /// </summary>
         public SpeakerToy Base { get; }
 
+        /// <summary>
+        /// Gets or sets the controller ID of the SpeakerToy.
+        /// </summary>
+        public byte ControllerID
+        {
+            get => Base.NetworkControllerId;
+            set => Base.NetworkControllerId = value;
+        }
+
         /// <summary>
         /// Gets or sets the volume of the audio source.
         /// </summary>
@@ -80,5 +103,178 @@ public float MinDistance
             get => Base.NetworkMinDistance;
             set => Base.NetworkMinDistance = value;
         }
+
+        /// <summary>
+        /// Gets a value indicating whether the <see cref="Speaker"/> is playing an audio or not. (Use method Stop() to stop the playback).
+        /// </summary>
+        public bool IsPlaying { get; internal set; }
+
+        /// <summary>
+        /// Gets or Sets a list of players that can hear this speaker.
+        /// </summary>
+        public List<Player> BroadcastTo { get; set; }
+
+        /// <summary>
+        /// Creates a new Speaker instance.
+        /// </summary>
+        /// <param name="controllerId">The ControllerId of the SpeakerToy. The ControllerId is used to find out which SpeakerToy is which while playing. If you have the same ID in two SpeakerToys, it will play the same audio file through both SpeakerToys.</param>
+        /// <param name="position">The position to place the SpeakerToy.</param>
+        /// <param name="isSpatial">Indicates whether the audio is spatialized.</param>
+        /// <param name="spawn">Determines if the speaker should be spawned immediately.</param>
+        /// <returns>A new <see cref="Speaker"/> instance.</returns>
+        public static Speaker Create(byte controllerId, Vector3 position, bool isSpatial = false, bool spawn = true)
+        {
+            Speaker speaker = new(Object.Instantiate(ToysHelper.SpeakerBaseObject))
+            {
+                Position = position,
+                IsSpatial = isSpatial,
+                Base = { ControllerId = controllerId },
+                BroadcastTo = new List<Player>(),
+            };
+
+            if (spawn)
+                speaker.Spawn();
+
+            return speaker;
+        }
+
+        /// <summary>
+        /// Gets the <see cref="Speaker"/> associated with a given <see cref="SpeakerToy"/>.
+        /// </summary>
+        /// <param name="speakerToy">The SpeakerToy instance.</param>
+        /// <returns>The corresponding Speaker instance.</returns>
+        public static Speaker Get(SpeakerToy speakerToy)
+        {
+            AdminToy adminToy = Map.Toys.FirstOrDefault(x => x.AdminToyBase == speakerToy);
+            return adminToy is not null ? adminToy as Speaker : new Speaker(speakerToy);
+        }
+
+        /// <summary>
+        /// Plays a single audio file through the speaker system. (No Arguments given (assuming you already preset those)).
+        /// </summary>
+        /// <param name="path">Path to the audio file to play.</param>
+        /// <param name="destroyAfter">Whether the Speaker gets destroyed after it's done playing.</param>
+        public void Play(string path, bool destroyAfter = false) => Play(path, Volume, MinDistance, MaxDistance, destroyAfter);
+
+        /// <summary>
+        /// Plays a single audio file through the speaker system.
+        /// </summary>
+        /// <param name="path">The file path of the audio file.</param>
+        /// <param name="volume">The desired playback volume. (0 to <see cref="float"/>) max limit.</param>
+        /// <param name="minDistance">The minimum distance at which the audio is audible.</param>
+        /// <param name="maxDistance">The maximum distance at which the audio is audible.</param>
+        /// <param name="destroyAfter">Whether the Speaker gets destroyed after it's done playing.</param>
+        public void Play(string path, float volume, float minDistance, float maxDistance, bool destroyAfter)
+        {
+            if (IsPlaying)
+                Stop();
+
+            if (!File.Exists(path))
+            {
+                Log.Warn($"Tried playing audio at {path} but no file was found.");
+                return;
+            }
+
+            Volume = volume;
+            MinDistance = minDistance;
+            MaxDistance = maxDistance;
+
+            IsPlaying = true;
+            Timing.RunCoroutine(PlaybackRoutine(path, destroyAfter));
+        }
+
+        /// <summary>
+        /// Stops the current playback.
+        /// </summary>
+        public void Stop()
+        {
+            stopPlayback = true;
+            IsPlaying = false;
+        }
+
+        private IEnumerator<float> PlaybackRoutine(string filePath, bool destroyAfter)
+        {
+            stopPlayback = false;
+
+            string fileExtension = Path.GetExtension(filePath).ToLower();
+            Log.Debug($"Detected file: {filePath}, Extension: {fileExtension}");
+
+            const int sampleRate = 48000; // Enforce 48kHz
+            const int channels = 1; // Enforce mono audio
+            const int frameSize = 480; // Frame size for 10ms of audio at 48kHz
+
+            Queue<float> streamBuffer = new();
+            float[] readBuffer = new float[frameSize * 4];
+            float[] sendBuffer = new float[frameSize];
+            byte[] encodedBuffer = new byte[512];
+            OpusEncoder encoder = new(VoiceChat.Codec.Enums.OpusApplicationType.Voip);
+
+            float playbackInterval = frameSize / (float)sampleRate;
+            float nextPlaybackTime = Timing.LocalTime;
+
+            if (fileExtension != ".ogg")
+            {
+                Log.Error($"Unsupported file format: {fileExtension}");
+                yield break;
+            }
+
+            using VorbisReader vorbisReader = new(filePath);
+
+            if (vorbisReader.SampleRate != sampleRate || vorbisReader.Channels != channels)
+            {
+                Log.Error($"Invalid OGG file. Expected {sampleRate / 1000}kHz mono, got {vorbisReader.SampleRate / 1000}kHz {vorbisReader.Channels} channel(s).");
+                yield break;
+            }
+
+            Log.Debug($"Playing OGG file with Sample Rate: {sampleRate}, Channels: {channels}");
+
+            while ((streamBuffer.Count < frameSize * 2 && !stopPlayback) || Round.IsEnded)
+            {
+                int samplesRead = vorbisReader.ReadSamples(readBuffer, 0, readBuffer.Length);
+                if (samplesRead <= 0)
+                    break;
+
+                foreach (float sample in readBuffer.Take(samplesRead))
+                    streamBuffer.Enqueue(sample);
+
+                while (!stopPlayback && streamBuffer.Count > 0)
+                {
+                    if (Timing.LocalTime < nextPlaybackTime)
+                    {
+                        yield return Timing.WaitForOneFrame;
+                        continue;
+                    }
+
+                    for (int i = 0; i < frameSize && streamBuffer.Count > 0; i++)
+                        sendBuffer[i] = streamBuffer.Dequeue();
+
+                    int dataLen = encoder.Encode(sendBuffer, encodedBuffer);
+                    AudioMessage audioMessage = new(ControllerID, encodedBuffer, dataLen);
+
+                    if (BroadcastTo.Count <= 0)
+                    {
+                        audioMessage.SendToAuthenticated();
+                    }
+                    else
+                    {
+                        foreach (Player p in BroadcastTo)
+                            p.ReferenceHub.connectionToClient.Send(audioMessage);
+                    }
+
+                    nextPlaybackTime += playbackInterval;
+
+                    if (streamBuffer.Count >= frameSize || vorbisReader.IsEndOfStream)
+                        continue;
+                    samplesRead = vorbisReader.ReadSamples(readBuffer, 0, readBuffer.Length);
+                    foreach (float sample in readBuffer.Take(samplesRead))
+                        streamBuffer.Enqueue(sample);
+                }
+            }
+
+            Log.Debug("Playback completed.");
+            IsPlaying = false;
+            if (destroyAfter)
+                Destroy();
+        }
     }
-}
+}

EXILED/Exiled.API/Features/Toys/ToysHelper.cs

@@ -20,6 +20,8 @@ public static class ToysHelper
     {
         private static PrimitiveObjectToy primitiveBaseObject;
         private static LightSourceToy lightBaseObject;
+        private static SpeakerToy speakerObject;
+
         private static ShootingTarget sportShootingTargetObject;
         private static ShootingTarget dboyShootingTargetObject;
         private static ShootingTarget binaryShootingTargetObject;
@@ -70,6 +72,29 @@ public static LightSourceToy LightBaseObject
             }
         }
 
+        /// <summary>
+        /// Gets the base <see cref="Speaker"/> to instantiate when creating a new speaker.
+        /// </summary>
+        public static SpeakerToy SpeakerBaseObject
+        {
+            get
+            {
+                if (speakerObject is null)
+                {
+                    foreach (GameObject gameObject in NetworkClient.prefabs.Values)
+                    {
+                        if (gameObject.TryGetComponent(out SpeakerToy component))
+                        {
+                            speakerObject = component;
+                            break;
+                        }
+                    }
+                }
+
+                return speakerObject;
+            }
+        }
+
         /// <summary>
         /// Gets the base <see cref="ShootingTarget"/> to instantiate when creating a new sport shooting target.
         /// </summary>