FFmpeg

ATTRIBUTIONS.md

@@ -37,3 +37,16 @@ MPEG 1 & 2 Decoder for Layers 1, 2, & 3
 https://github.com/naudio/NLayer
 
 License: MIT
+
+# FFmpeg
+
+> [!NOTE]
+> While SecretLabNAudio does not ship, nor does it link its libraries with FFmpeg,
+> it starts FFmpeg processes to provide utilities.
+> SecretLabNAudio contains an installer to download FFmpeg.
+
+A complete, cross-platform solution to record, convert and stream audio and video.
+
+https://ffmpeg.org/
+
+License: LGPL-2.1

Directory.Build.props

@@ -1,12 +1,24 @@
 <Project>
+
     <PropertyGroup>
         <TargetFramework>net48</TargetFramework>
         <Nullable>enable</Nullable>
         <LangVersion>14</LangVersion>
         <PlatformTarget>x64</PlatformTarget>
         <DisableImplicitFrameworkReferences>true</DisableImplicitFrameworkReferences>
         <Version>2.0.0</Version>
-        <PackageVersion>2.0.0-alpha5</PackageVersion>
+    </PropertyGroup>
+
+    <PropertyGroup>
+        <Authors>Axwabo</Authors>
+        <Company>Axwabo</Company>
+
+        <PackageVersion>2.0.0-beta2</PackageVersion>
+        <PackageReadmeFile>README.md</PackageReadmeFile>
+        <PackageLicenseExpression>LGPL-3.0-only</PackageLicenseExpression>
+
+        <RepositoryType>git</RepositoryType>
+        <RepositoryUrl>https://github.com/Axwabo/SecretLabNAudio</RepositoryUrl>
     </PropertyGroup>
 
     <ItemGroup>
@@ -42,4 +54,5 @@
     <ItemGroup Condition="$(ProjectName) != 'SecretLabNAudio.Core'">
         <ProjectReference Include="../SecretLabNAudio.Core/SecretLabNAudio.Core.csproj" />
     </ItemGroup>
+
 </Project>

Directory.Packages.props

@@ -14,5 +14,6 @@
 
         <PackageVersion Include="NVorbis" Version="0.10.5" />
         <PackageVersion Include="NAudio.Vorbis" Version="1.5.0" />
+        <PackageVersion Include="System.ValueTuple" Version="4.5.0" />
     </ItemGroup>
 </Project>

README.md

@@ -24,6 +24,7 @@ This library has a number of open-source dependencies. See [Attributions](ATTRIB
 - SpeakerToy pooling
 - Automatic reader resolution by file type
 - Cache for short audio clips
+- FFmpeg-based audio processing for (almost) all formats, even over the network
 - Windows-only Media Foundation support for a wider range of formats, and decoding over the network
 
 > [!TIP]
@@ -51,30 +52,38 @@ This library has a number of open-source dependencies. See [Attributions](ATTRIB
 3. Extract the necessary DLLs from the `bin/` directory
    - See the [table below](#modules) for what you need
    - Place dependencies into the **dependencies** directory
-     - Linux: `~/.config/SCP Secret Laboratory/LabAPI/dependencies/<port>/`
-     - Windows: `%appdata%/SCP Secret Laboratory/LabAPI/dependencies/<port>/`
+       - Linux: `~/.config/SCP Secret Laboratory/LabAPI/dependencies/<port>/`
+       - Windows: `%appdata%/SCP Secret Laboratory/LabAPI/dependencies/<port>/`
    - Place plugins into the **plugins** directory
-     - Linux: `~/.config/SCP Secret Laboratory/LabAPI/plugins/<port>/`
-     - Windows: `%appdata%/SCP Secret Laboratory/LabAPI/plugins/<port>/`
+       - Linux: `~/.config/SCP Secret Laboratory/LabAPI/plugins/<port>/`
+       - Windows: `%appdata%/SCP Secret Laboratory/LabAPI/plugins/<port>/`
 4. Restart the server
 
 ### Modules
 
 To support reading from some file formats, install the modules you need.
 
+FFmpeg supports effectively all formats at the cost of running as a separate process.
+The FFmpeg module's APIs must be invoked separately.
+
 | Usage        | Plugin                             | Dependencies                                  |
 |--------------|------------------------------------|-----------------------------------------------|
 | **required** | (none)                             | `SecretLabNAudio.Core` `NAudio.Core`          |
 | mp3          | `SecretLabNAudio.NLayer`           | `NLayer` `NLayer.NAudioSupport`               |
 | ogg          | `SecretLabNAudio.NVorbis`          | `NVorbis` `NAudio.Vorbis` `System.ValueTuple` |
 | most formats | `SecretLabNAudio.MediaFoundation`* | `NAudio.Wasapi`*                              |
+| FFmpeg       | `SecretLabNAudio.FFmpeg`**         | (none)                                        |
 
 > [!NOTE]
 > *MediaFoundation is only available on Windows.
+>
+> **FFmpeg itself is not shipped with SecretLabNAudio.
+> See the [wiki](https://github.com/Axwabo/SecretLabNAudio/wiki/FFmpeg-Installation) on how to install it.
 
 ## Development
 
 Simply install the `SecretLabNAudio.Core` package from NuGet.
+You can also add the `SecretLabNAudio.FFmpeg` package, which references the former one.
 
 Manual installation:
 

SecretLabNAudio.Core/AudioPlayer.cs

@@ -179,7 +179,7 @@ private void ProcessPacket()
             _remainingTime -= PacketDuration;
         }
 
-        OutputMonitor?.OnRead(ReadBuffer.AsSpan()[..read]);
+        OutputMonitor?.OnRead(ReadBuffer.AsSpan(0, read));
         if (SendEngine == null)
             return;
         if (MasterAmplification is not 1f)

SecretLabNAudio.Core/FileReading/ClipName.cs

@@ -15,6 +15,14 @@ public readonly record struct ClipName(string Original, bool TrimExtension = tru
     /// <returns>A new <see cref="ClipName"/>.</returns>
     public static implicit operator ClipName(string original) => new(original);
 
+    /// <summary>
+    /// Converts this name to its final form.
+    /// </summary>
+    /// <returns>The extension removed if <see cref="TrimExtension"/> is true, <see cref="Original"/> otherwise.</returns>
+    public override string ToString() => TrimExtension
+        ? Path.ChangeExtension(Original, null)
+        : Original;
+
     /// <summary>
     /// Converts a name and trim flag tuple to a <see cref="ClipName"/>.
     /// </summary>
@@ -24,11 +32,11 @@ public static implicit operator ClipName((string Original, bool TrimExtension) t
         => new(tuple.Original, tuple.TrimExtension);
 
     /// <summary>
-    /// Converts this name to its final form.
+    /// Converts the path to a <see cref="ClipName"/> based on the file's name.
     /// </summary>
-    /// <returns>The extension removed if <see cref="TrimExtension"/> is true, <see cref="Original"/> otherwise.</returns>
-    public override string ToString() => TrimExtension
-        ? Path.ChangeExtension(Original, null)
-        : Original;
+    /// <param name="path">The path (absolute or relative) to convert.</param>
+    /// <param name="trimExtension">The value of <see cref="TrimExtension"/> in the result.</param>
+    /// <returns>A new <see cref="ClipName"/> corresponding to the file name.</returns>
+    public static ClipName FromPath(string path, bool trimExtension = true) => new(Path.GetFileName(path), trimExtension);
 
 }

SecretLabNAudio.Core/Processors/Mixer.cs

@@ -170,8 +170,8 @@ private void ThrowIfIncompatible(ISampleProvider input, bool isOwned)
     public int Read(float[] buffer, int offset, int count)
     {
         _readBuffer = BufferHelpers.Ensure(_readBuffer, count);
-        var readSpan = _readBuffer.AsSpan()[..count];
-        var targetSpan = buffer.AsSpan()[offset..(offset + count)];
+        var readSpan = _readBuffer.AsSpan(0, count);
+        var targetSpan = buffer.AsSpan(offset, count);
         targetSpan.Clear();
         var total = 0;
         for (var i = _inputs.Count - 1; i >= 0; i--)

SecretLabNAudio.Core/SecretLabNAudio.Core.csproj

@@ -1,26 +1,20 @@
 <Project Sdk="Microsoft.NET.Sdk">
+
     <PropertyGroup>
         <GenerateDocumentationFile>true</GenerateDocumentationFile>
         <GeneratePackageOnBuild>true</GeneratePackageOnBuild>
     </PropertyGroup>
 
     <PropertyGroup>
-        <Authors>Axwabo</Authors>
-        <Company>Axwabo</Company>
         <Product>SecretLabNAudio.Core</Product>
-
         <PackageId>SecretLabNAudio.Core</PackageId>
         <PackageDescription>Advanced audio player API for SCP: Secret Laboratory using NAudio</PackageDescription>
-        <PackageReadmeFile>README.md</PackageReadmeFile>
-        <PackageLicenseExpression>LGPL-3.0-only</PackageLicenseExpression>
         <PackageTags>SCP:SL LabAPI NAudio</PackageTags>
         <PackageProjectUrl>https://nuget.org/packages/SecretLabNAudio.Core</PackageProjectUrl>
-
-        <RepositoryType>git</RepositoryType>
-        <RepositoryUrl>https://github.com/Axwabo/SecretLabNAudio</RepositoryUrl>
     </PropertyGroup>
 
     <ItemGroup>
         <None Include="../README.md" Pack="true" PackagePath="/" />
     </ItemGroup>
+
 </Project>

SecretLabNAudio.Core/XmlDocs/Clips.xml

@@ -10,7 +10,7 @@
                 A
                 <see cref="T:SecretLabNAudio.Core.Providers.RawSourceSampleProvider" />
                 if the clip was added to the cache.
-                If the file doesn't exist, no <see cref="T:SecretLabNAudio.Core.FileReading.IAudioReaderFactory">factory</see> was registered for the type, or no
+                Null if the file doesn't exist, no <see cref="T:SecretLabNAudio.Core.FileReading.IAudioReaderFactory">factory</see> was registered for the type, or no
                 <see cref="T:NAudio.Wave.WaveStream" />
                 was returned.
             </returns>

SecretLabNAudio.FFmpeg/Caches/AudioCacheBase.cs

@@ -0,0 +1,88 @@
+using SecretLabNAudio.FFmpeg.Extensions;
+
+namespace SecretLabNAudio.FFmpeg.Caches;
+
+/// <summary>
+/// A base class for caching optimized audio files.
+/// </summary>
+/// <typeparam name="TSource">The type of input to accept from callers.</typeparam>
+/// <typeparam name="TKey">The type of key to generate the file path with.</typeparam>
+public abstract class AudioCacheBase<TSource, TKey>
+{
+
+    /// <summary>
+    /// Initializes a new cache, and creates the directory if necessary.
+    /// </summary>
+    /// <param name="folder">The directory to save files to.</param>
+    protected AudioCacheBase(string folder)
+    {
+        Folder = folder;
+        Directory.CreateDirectory(folder);
+    }
+
+    /// <summary>
+    /// Initializes a new cache, and creates the directory if necessary.
+    /// </summary>
+    /// <param name="directoryInfo">The directory to save files to.</param>
+    protected AudioCacheBase(DirectoryInfo directoryInfo) : this(directoryInfo.FullName)
+    {
+    }
+
+    /// <summary>
+    /// The directory to save files to.
+    /// </summary>
+    public string Folder { get; }
+
+    /// <summary>
+    /// Gets the key corresponding to the source.
+    /// </summary>
+    /// <param name="source">The source to convert.</param>
+    /// <returns>The key associated with the source.</returns>
+    public abstract TKey GetKey(TSource source);
+
+    /// <summary>
+    /// Gets fully qualified output path given a key and an optimization target.
+    /// </summary>
+    /// <param name="key">The key to save by.</param>
+    /// <param name="optimizeFor">What to optimize for.</param>
+    /// <returns>A fully qualified path to the cached file.</returns>
+    public string GetOutput(TKey key, OptimizeFor optimizeFor) => Path.Combine(Folder, $"{key}.{optimizeFor.Extension}");
+
+    /// <summary>
+    /// Asynchronously starts and waits for FFmpeg to perform caching.
+    /// </summary>
+    /// <param name="source">The object to save by.</param>
+    /// <param name="optimizeFor">What to optimize for.</param>
+    /// <param name="cancellationToken">The token to monitor for cancellation requests.</param>
+    /// <returns>An <see cref="Awaitable"/> representing the asynchronous operation.</returns>
+    public abstract Awaitable<SaveCacheResult> CacheAsync(TSource source, OptimizeFor optimizeFor, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Attempts to get the cached path of a source.
+    /// </summary>
+    /// <param name="source">The object to find the value by.</param>
+    /// <param name="cachedPath">The fully qualified path if a cached file was found, null otherwise.</param>
+    /// <returns>Whether a cached file was found.</returns>
+    /// <remarks><see cref="OptimizeFor.ReadingSpeed"/> is checked first, then <see cref="OptimizeFor.FileSize"/>.</remarks>
+    public virtual bool TryGetPath(TSource source, [NotNullWhen(true)] out string? cachedPath)
+    {
+        var key = GetKey(source);
+        var speed = GetOutput(key, OptimizeFor.ReadingSpeed);
+        if (File.Exists(speed))
+        {
+            cachedPath = speed;
+            return true;
+        }
+
+        var size = GetOutput(key, OptimizeFor.FileSize);
+        if (File.Exists(size))
+        {
+            cachedPath = size;
+            return true;
+        }
+
+        cachedPath = null;
+        return false;
+    }
+
+}

SecretLabNAudio.FFmpeg/Caches/OptimizeFor.cs

@@ -0,0 +1,19 @@
+namespace SecretLabNAudio.FFmpeg.Caches;
+
+/// <summary>
+/// Represents values indicating a cached audio file's type.
+/// </summary>
+public enum OptimizeFor
+{
+
+    /// <summary>
+    /// Optimize for reading performance (WAV).
+    /// </summary>
+    ReadingSpeed,
+
+    /// <summary>
+    /// Optimize for a smaller file size (Ogg Vorbis).
+    /// </summary>
+    FileSize
+
+}

SecretLabNAudio.FFmpeg/Caches/SaveCacheError.cs

@@ -0,0 +1,63 @@
+namespace SecretLabNAudio.FFmpeg.Caches;
+
+/// <summary>
+/// Represents error states that can occur while saving an audio file to a cache.
+/// </summary>
+public abstract record SaveCacheError
+{
+
+    /// <summary>
+    /// The error returned when the <see cref="CancellationToken"/> signals cancellation.
+    /// </summary>
+    public static SaveCacheError Canceled { get; } = new CanceledError();
+
+    /// <summary>
+    /// Creates a <see cref="FFmpegStartupError"/> based on the error code.
+    /// </summary>
+    /// <param name="errorCode">The error code to convert.</param>
+    /// <returns>A new <see cref="FFmpegStartupError"/> as a <see cref="SaveCacheError"/>.</returns>
+    public static implicit operator SaveCacheError(NativeErrorCode errorCode) => new FFmpegStartupError(errorCode);
+
+    /// <summary>
+    /// Creates an <see cref="ExceptionError"/> from the exception.
+    /// </summary>
+    /// <param name="exception">The exception to encapsulate.</param>
+    /// <returns>A new <see cref="ExceptionError"/> as a <see cref="SaveCacheError"/>.</returns>
+    public static implicit operator SaveCacheError(Exception exception) => new ExceptionError(exception);
+
+}
+
+/// <summary>
+/// The error representing an invalid input argument.
+/// </summary>
+/// <param name="Source">The source that was provided.</param>
+public sealed record InvalidInputError(string? Source) : SaveCacheError;
+
+/// <summary>
+/// The error representing a file that was not found.
+/// </summary>
+/// <param name="Path">The provided file path.</param>
+public sealed record FileNotFoundError(string Path) : SaveCacheError;
+
+/// <summary>
+/// The error representing an FFmpeg startup failure.
+/// </summary>
+/// <param name="ErrorCode">The <see cref="System.ComponentModel.Win32Exception.NativeErrorCode"/> that was caught while starting FFmpeg.</param>
+public sealed record FFmpegStartupError(NativeErrorCode ErrorCode) : SaveCacheError;
+
+/// <summary>
+/// The error representing an error outputted by FFmpeg during its runtime.
+/// </summary>
+/// <param name="ErrorMessage">The full output of the standard error.</param>
+public sealed record FFmpegRuntimeError(string ErrorMessage) : SaveCacheError;
+
+/// <summary>
+/// The error representing the cancellation signaled by a <see cref="CancellationToken"/>.
+/// </summary>
+public sealed record CanceledError : SaveCacheError;
+
+/// <summary>
+/// The error encapsulating an <see cref="System.Exception"/>.
+/// </summary>
+/// <param name="Exception">The exception that was caught.</param>
+public sealed record ExceptionError(Exception Exception) : SaveCacheError;