Song server: central song library with on-demand downloads

- VocaluxeSongServer: ASP.NET Core server that scans an UltraStar library and
  serves the song list (ETag), single files (Range) and zip bundles; optional
  API key; Dockerfile and Gitea workflow for git.disi.dev/projects/vocaluxe-song-server
- Game: config section SongServer (Url, ApiKey). At song loading, the song text
  files are mirrored into a local cache that is loaded like a song folder;
  without connection the last library is used
- VocaluxeLib: CSongFiles hook for all song file access; media are downloaded on
  demand (covers in the background, preview audio, everything before singing
  with progress in the sing screen)
- Tests for scanner, API and downloads (incl. resume); AGENTS.md for the fork

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

VocaluxeSongServer/Library/CLibraryIndex.cs

@@ -0,0 +1,106 @@
+using Microsoft.Extensions.Options;
+
+namespace VocaluxeSongServer.Library
+{
+    public sealed class CLibraryOptions
+    {
+        /// <summary>Root folder of the song library (in Docker: the mounted share, default /songs).</summary>
+        public string Path { get; set; } = "/songs";
+        /// <summary>Minutes between automatic rescans. 0 = only at startup and via POST /api/v1/library/rescan.</summary>
+        public int ScanIntervalMinutes { get; set; } = 10;
+        /// <summary>If set, every /api request needs the header X-Api-Key with this value.</summary>
+        public string ApiKey { get; set; } = "";
+    }
+
+    /// <summary>Holds the current library snapshot and rescans it in the background.</summary>
+    public sealed class CLibraryIndex : BackgroundService
+    {
+        private readonly CLibraryScanner _Scanner;
+        private readonly CLibraryOptions _Options;
+        private readonly ILogger<CLibraryIndex> _Logger;
+        private readonly SemaphoreSlim _ScanLock = new(1, 1);
+        private readonly SemaphoreSlim _RescanRequested = new(0, 1);
+        private volatile CLibrarySnapshot? _Current;
+
+        public CLibraryIndex(CLibraryScanner scanner, IOptions<CLibraryOptions> options, ILogger<CLibraryIndex> logger)
+        {
+            _Scanner = scanner;
+            _Options = options.Value;
+            _Logger = logger;
+        }
+
+        /// <summary>The last completed scan, or null while the first scan is running.</summary>
+        public CLibrarySnapshot? Current => _Current;
+
+        public string Root => System.IO.Path.GetFullPath(_Options.Path);
+
+        /// <summary>Asks for a rescan as soon as possible (returns immediately).</summary>
+        public void RequestRescan()
+        {
+            if (_RescanRequested.CurrentCount == 0)
+            {
+                try
+                {
+                    _RescanRequested.Release();
+                }
+                catch (SemaphoreFullException)
+                {
+                    // Already requested.
+                }
+            }
+        }
+
+        public async Task ScanNowAsync(CancellationToken ct = default)
+        {
+            await _ScanLock.WaitAsync(ct);
+            try
+            {
+                if (!Directory.Exists(Root))
+                {
+                    _Logger.LogError("Library folder {Root} does not exist", Root);
+                    return;
+                }
+
+                var started = DateTime.UtcNow;
+                var snapshot = await Task.Run(() => _Scanner.Scan(Root), ct);
+                var changed = _Current?.Dto.Version != snapshot.Dto.Version;
+                _Current = snapshot;
+                _Logger.LogInformation("Scanned {Root}: {Songs} songs, {Files} files in {Seconds:0.0} s{Changed}", Root,
+                    snapshot.Dto.Songs.Count, snapshot.Dto.Files.Count, (DateTime.UtcNow - started).TotalSeconds, changed ? "" : " (unchanged)");
+            }
+            finally
+            {
+                _ScanLock.Release();
+            }
+        }
+
+        protected override async Task ExecuteAsync(CancellationToken stoppingToken)
+        {
+            while (!stoppingToken.IsCancellationRequested)
+            {
+                try
+                {
+                    await ScanNowAsync(stoppingToken);
+                }
+                catch (OperationCanceledException) when (stoppingToken.IsCancellationRequested)
+                {
+                    return;
+                }
+                catch (Exception e)
+                {
+                    _Logger.LogError(e, "Library scan failed");
+                }
+
+                var interval = _Options.ScanIntervalMinutes > 0 ? TimeSpan.FromMinutes(_Options.ScanIntervalMinutes) : Timeout.InfiniteTimeSpan;
+                try
+                {
+                    await _RescanRequested.WaitAsync(interval, stoppingToken);
+                }
+                catch (OperationCanceledException)
+                {
+                    return;
+                }
+            }
+        }
+    }
+}