v2 "processors"

.github/workflows/release.yml

@@ -2,7 +2,7 @@ name: Release
 
 on:
   release:
-    types: [ created ]
+    types: [ published ]
 
 permissions:
   contents: write
@@ -11,53 +11,24 @@ jobs:
 
   release:
     runs-on: ubuntu-latest
-
-    env:
-      ReferenceUrl: https://exmod-team.github.io/SL-References/Dev.zip
-      ReferencePath: ${{ github.workspace }}/References
-
     steps:
 
-      - uses: actions/checkout@v4
-
-      - name: Set Up .NET
-        uses: actions/setup-dotnet@v4.0.1
-        with:
-          dotnet-version: 9.0.x
-
-      - name: Download References
-        run: |
-          wget -O "References.zip" ${{ env.ReferenceUrl }}
-          unzip -d ${{ env.ReferencePath }} "References.zip"
+      - uses: actions/checkout@v6
 
-      - name: Rename Assembly-CSharp
-        working-directory: ${{ env.ReferencePath }}
-        run: mv Assembly-CSharp-Publicized.dll Assembly-CSharp.dll
+      - uses: Axwabo/scpsl-references-downloader@v1
 
       - name: Build
-        run: dotnet build -c:Release -o Output
+        run: dotnet build -c Release -o Out
 
       - name: Create Bundle
-        working-directory: Output
-        run: |
-          mkdir SecretLabNAudio
-          mkdir SecretLabNAudio/bin
-          mkdir SecretLabNAudio/LICENSES
-
-          mv SecretLabNAudio.dll SecretLabNAudio/bin
-          ls | grep -E "^(NAudio|NLayer|NVorbis)" | xargs -I {0} mv {0} SecretLabNAudio/bin
-
-          cp -r ../THIRD_PARTY_LICENSES SecretLabNAudio/LICENSES
-          cp ../LICENSE SecretLabNAudio/LICENSES/SecretLabNAudio.txt
-
-          cd SecretLabNAudio
-          zip -r ../SecretLabNAudio.zip .
+        working-directory: Out
+        run: ${{ github.workspace }}/bundle.sh
 
       - name: Upload Assets
         uses: softprops/action-gh-release@v2
         with:
-          files: Output/SecretLabNAudio*.dll,Output/SecretLabNAudio*.xml,Output/SecretLabNAudio.zip
+          files: Out/SecretLabNAudio*.dll,Out/SecretLabNAudio*.xml,Out/SecretLabNAudio.zip
 
       - name: Push to NuGet
-        working-directory: Output
+        working-directory: Out
         run: dotnet nuget push SecretLabNAudio.*.nupkg -k ${{ secrets.NUGET_API_KEY }} -s https://api.nuget.org/v3/index.json

Directory.Build.props

@@ -2,10 +2,11 @@
     <PropertyGroup>
         <TargetFramework>net48</TargetFramework>
         <Nullable>enable</Nullable>
-        <LangVersion>13</LangVersion>
+        <LangVersion>14</LangVersion>
         <PlatformTarget>x64</PlatformTarget>
         <DisableImplicitFrameworkReferences>true</DisableImplicitFrameworkReferences>
-        <Version>1.0.2</Version>
+        <Version>2.0.0</Version>
+        <PackageVersion>2.0.0-alpha1</PackageVersion>
     </PropertyGroup>
 
     <ItemGroup>
@@ -14,24 +15,26 @@
     </ItemGroup>
 
     <ItemGroup>
-        <Reference Include="mscorlib" Private="false" />
-        <Reference Include="System" Private="false" />
-        <Reference Include="System.Core" Private="false" />
-        <Reference Include="System.Data" Private="false" />
+        <Reference Include="mscorlib" />
+        <Reference Include="System" />
+        <Reference Include="System.Core" />
+        <Reference Include="System.Data" />
     </ItemGroup>
 
     <ItemGroup>
-        <Reference Include="Assembly-CSharp" Private="false" />
-        <Reference Include="Mirror" Private="false" />
-        <Reference Include="UnityEngine.CoreModule" Private="false" />
+        <Reference Include="Assembly-CSharp" />
+        <Reference Include="Mirror" />
+        <Reference Include="UnityEngine.CoreModule" />
     </ItemGroup>
 
     <ItemGroup>
         <Using Include="System" />
+        <Using Include="System.Collections.Generic" />
+        <Using Include="System.Diagnostics.CodeAnalysis" />
+        <Using Include="System.IO" />
         <Using Include="LabApi.Features.Wrappers" />
         <Using Include="Mirror" />
         <Using Include="NAudio.Wave" />
-        <Using Include="SecretLabNAudio.Core.Extensions" />
         <Using Include="UnityEngine" />
         <Using Include="UnityEngine.Object" Alias="Object" />
     </ItemGroup>

Directory.Build.targets

@@ -1,21 +1,22 @@
 <Project>
-    <Import Project="ReferencePath.props.user" Condition="Exists('ReferencePath.props.user')"/>
+    <Import Project="ReferencePath.props.user" Condition="Exists('ReferencePath.props.user')" />
     <PropertyGroup>
         <ReferencePath Condition="$(ReferencePath) == ''">$(SL_REFERENCES)</ReferencePath>
         <AssemblySearchPaths>$(ReferencePath);$(AssemblySearchPaths)</AssemblySearchPaths>
     </PropertyGroup>
-    
+
     <Target Name="NotifyIncompleteSetup" BeforeTargets="PrepareForBuild" Condition="$(ReferencePath) == ''">
         <PropertyGroup>
-            <Template>
-&lt;Project&gt;
-    &lt;PropertyGroup&gt;
-        &lt;ReferencePath&gt;&lt;/ReferencePath&gt;
-    &lt;/PropertyGroup&gt;
-&lt;/Project&gt;
-            </Template>
+            <Props>$(MSBuildThisFileDirectory)ReferencePath.props.user</Props>
+            <Template><![CDATA[
+<Project>
+    <PropertyGroup>
+        <ReferencePath></ReferencePath>
+    </PropertyGroup>
+</Project>
+            ]]></Template>
         </PropertyGroup>
-        <WriteLinesToFile File="$(MSBuildThisFileDirectory)ReferencePath.props.user" Lines="$(Template)" Condition="!Exists('$(MSBuildThisFileDirectory)ReferencePath.props.user')" />
+        <WriteLinesToFile File="$(Props)" Lines="$(Template)" Condition="!Exists($(Props))" />
         <Error Text="The ReferencePath property is not specified! Make sure to set the property in the ReferencePath.props.user file." />
     </Target>
 </Project>

Directory.Packages.props

@@ -5,7 +5,7 @@
 
     <ItemGroup>
         <PackageVersion Include="NAudio.Core" Version="2.2.1" />
-        <PackageVersion Include="Northwood.LabAPI" Version="1.1.3" />
+        <PackageVersion Include="Northwood.LabAPI" Version="1.1.4" />
 
         <PackageVersion Include="NAudio.Wasapi" Version="2.2.1" />
 

README.md

@@ -50,8 +50,8 @@ This library has a number of open-source dependencies. See [Attributions](ATTRIB
 4. Extract the necessary files from the `bin/` directory of the archive as **dependencies**
     - `NAudio.Core.dll` is **always required**
     - `NLayer` and `NLayer.NAudioSpport.dll` for `.mp3` support (optional)
-    - `NAudio.Vorbis.dll` and `NVorbis.dll` for `.ogg` support (optional)
-    - `NAudio.Wasapi.dll` for Media Foundation support (optional, WIndows-only)
+    - `NAudio.Vorbis.dll`, `NVorbis.dll` and `System.ValueTuple.dll` for `.ogg` support (optional)
+    - `NAudio.Wasapi.dll` for Media Foundation support (optional, Windows-only)
 5. Optionally download the necessary **plugin(s)** from the releases page
     - `SecretLabNAudio.NLayer.dll` for `.mp3` support
     - `SecretLabNAudio.NVorbis.dll` for `.ogg` support

SecretLabNAudio.Core/AudioPlayer.Create.cs

@@ -1,4 +1,6 @@
-namespace SecretLabNAudio.Core;
+using SecretLabNAudio.Core.Extensions;
+
+namespace SecretLabNAudio.Core;
 
 public partial class AudioPlayer
 {

SecretLabNAudio.Core/AudioPlayer.cs

@@ -1,8 +1,8 @@
-using SecretLabNAudio.Core.Providers;
+using SecretLabNAudio.Core.Extensions;
+using SecretLabNAudio.Core.Providers;
 using SecretLabNAudio.Core.SendEngines;
 using VoiceChat.Codec;
 using VoiceChat.Codec.Enums;
-using VoiceChat.Networking;
 
 namespace SecretLabNAudio.Core;
 
@@ -14,23 +14,60 @@ public sealed partial class AudioPlayer : MonoBehaviour
 
     private static readonly byte[] EncoderBuffer = new byte[1024];
 
-    private ISampleProvider? _sampleProvider;
-
     /// <summary>The provider this player will read from. Set to null to skip updates.</summary>
-    /// <exception cref="ArgumentException"><inheritdoc cref="ThrowIfIncompatible" path="exception"/></exception>
+    /// <exception cref="ArgumentException">
+    /// Thrown when the given sample provider is not null and does not match the following criteria:
+    /// <para>
+    /// Encoding = <see cref="WaveFormatEncoding.IeeeFloat"/><br/>
+    /// Sample Rate = <see cref="SampleRate"/><br/>
+    /// Channels = <see cref="Channels"/>
+    /// </para>
+    /// </exception>
+    /// <remarks>Setting the provider changes the value of <see cref="OwnsProvider"/> to whether the given provider is an <see cref="IAudioProcessor"/>.</remarks>
+    /// <seealso cref="AudioPlayerExtensions.Use"/>
+    /// <seealso cref="AudioPlayerExtensions.UseFile(AudioPlayer,string,bool,float)"/>
+    /// <seealso cref="AudioPlayerExtensions.UseShortClip(AudioPlayer,string,bool,float)"/>
+    /// <seealso cref="AudioPlayerExtensions.UseMixer(AudioPlayer,bool)"/>
+    /// <seealso cref="AudioPlayerExtensions.UseQueue(AudioPlayer)"/>
+    /// <seealso cref="AudioPlayerExtensions.WithUnmanagedProvider(AudioPlayer,ISampleProvider)"/>
     public ISampleProvider? SampleProvider
     {
-        get => _sampleProvider;
+        get;
         set
         {
+            if (value == field)
+                return;
             ThrowIfIncompatible(value);
-            _sampleProvider = value;
+            try
+            {
+                if (OwnsProvider)
+                    (field as IDisposable)?.Dispose();
+            }
+            catch (Exception e)
+            {
+                Debug.LogError(e);
+            }
+
+            field = value;
+            OwnsProvider = value is IAudioProcessor;
         }
     }
 
+    /// <summary>Whether to dispose of the <see cref="SampleProvider"/> when the provider is changed or this component is pooled/destroyed.</summary>
+    /// <remarks>This property is automatically set when the <see cref="SampleProvider"/> changes.</remarks>
+    public bool OwnsProvider { get; set; }
+
     /// <summary>The <see cref="SpeakerToy"/> this player is attached to.</summary>
     public SpeakerToy Speaker { get; private set; } = null!;
 
+    /// <summary>The controller ID of this player.</summary>
+    /// <seealso cref="SpeakerToy.ControllerId"/>
+    public byte Id
+    {
+        get => Speaker.ControllerId;
+        set => Speaker.ControllerId = value;
+    }
+
     /// <summary>
     /// The <see cref="SendEngine"/> used to broadcast audio messages.
     /// If null, encoding and broadcasting is skipped.
@@ -53,17 +90,15 @@ public ISampleProvider? SampleProvider
     /// <summary>True if playback has finished on the previous frame (fewer samples were read than requested).</summary>
     public bool HasEnded { get; private set; }
 
-    /// <summary>The controller ID of this player.</summary>
-    /// <seealso cref="SpeakerToy.ControllerId"/>
-    public byte Id
-    {
-        get => Speaker.ControllerId;
-        set => Speaker.ControllerId = value;
-    }
+    /// <summary>
+    /// If true, the <see cref="SampleProvider"/> will be read from continuously.
+    /// If false, the <see cref="SampleProvider"/> will be set to null upon reaching its end.
+    /// </summary>
+    public bool AlwaysRead { get; set; } = true;
 
     /// <summary>Invoked every frame when no samples were read from the <see cref="SampleProvider"/>.</summary>
     /// <remarks>The provider is not set to null by default.</remarks>
-    /// <seealso cref="AudioPlayerExtensions.UnsetProviderOnEnd"/>
+    /// <seealso cref="AlwaysRead"/>
     /// <seealso cref="HasEnded"/>
     public event Action? NoSamplesRead;
 
@@ -102,19 +137,11 @@ private void OnDisable()
         SampleProvider = null;
         SendEngine = SendEngine.DefaultEngine;
         OutputMonitor = null;
+        AlwaysRead = true;
         _remainingTime = 0;
     }
 
-    private void OnDestroy()
-    {
-        SampleProvider = null;
-        SendEngine = null;
-        OutputMonitor = null;
-        _encoder.Dispose();
-        Destroyed?.Invoke();
-        NoSamplesRead = null;
-        Destroyed = null;
-    }
+    private void OnDestroy() => _encoder.Dispose();
 
     private void ProcessPacket()
     {
@@ -131,10 +158,7 @@ private void ProcessPacket()
 
         if (read == 0)
         {
-            HasEnded = true;
-            ClearBuffer();
-            OutputMonitor?.OnEmpty();
-            NoSamplesRead?.Invoke();
+            End();
             return;
         }
 
@@ -150,20 +174,28 @@ private void ProcessPacket()
         OutputMonitor?.OnRead(ReadBuffer.AsSpan()[..read]);
         if (SendEngine == null)
             return;
-#pragma warning disable CS0618
         if (MasterAmplification is not 1f)
             for (var i = 0; i < read; i++)
                 ReadBuffer[i] *= MasterAmplification;
-#pragma warning restore CS0618
         var encoded = _encoder.Encode(ReadBuffer, EncoderBuffer);
         SendEngine.Broadcast(new AudioMessage(Id, EncoderBuffer, encoded));
     }
 
-    /// <summary>Resets the amount of samples to send and clears the <see cref="SampleProvider"/>'s buffer if it's a <see cref="BufferedSampleProvider"/>.</summary>
+    private void End()
+    {
+        HasEnded = true;
+        ClearBuffer();
+        OutputMonitor?.OnEmpty();
+        NoSamplesRead?.Invoke();
+        if (!AlwaysRead)
+            SampleProvider = null;
+    }
+
+    /// <summary>Resets the amount of samples to send and clears the buffer of the single <see cref="BufferedSampleProvider"/> input (if present).</summary>
     public void ClearBuffer()
     {
         _remainingTime = 0;
-        (SampleProvider as BufferedSampleProvider)?.Clear();
+        this.SingleInputAs<BufferedSampleProvider>()?.Clear();
     }
 
     /// <summary>Destroys the player and its <see cref="Speaker"/>.</summary>