Wire Opus end-to-end playback + Backfill-Opus action (Phase 18.5)

Player picks Opus when the browser can decode it and a sidecar exists (else lossless), injecting the sidecar before stream init; seek reuses the same format. Adds the Backfill-Opus bulk API endpoint + CMS action.

DeepDrftManager/Components/Pages/Tracks/Releases.razor

@@ -51,6 +51,26 @@
                     <span>Backfill High-res (@MissingHighResCount)</span>
                 }
             </MudButton>
+            @* Backfill-Opus (Phase 18.5). Unlike the two waveform buttons, the Opus derive runs on a
+               server-side background worker: the API decides which tracks lack Opus and enqueues them, so
+               there is no client-side "missing N" count to gate on and no per-track progress to render — the
+               action schedules the work and reports the (enqueued / skipped) outcome. Re-runnable: a second
+               press only enqueues tracks still missing Opus. Disabled while a press is in flight. *@
+            <MudButton Variant="Variant.Outlined"
+                       Color="Color.Primary"
+                       StartIcon="@Icons.Material.Filled.GraphicEq"
+                       Disabled="@(_bulkRunning || _highResBulkRunning || _opusBackfillRunning)"
+                       OnClick="BackfillOpusAsync">
+                @if (_opusBackfillRunning)
+                {
+                    <MudProgressCircular Class="mr-2" Size="Size.Small" Indeterminate="true" />
+                    <span>Scheduling…</span>
+                }
+                else
+                {
+                    <span>Backfill Opus</span>
+                }
+            </MudButton>
         </MudStack>
     </MudStack>
 
@@ -150,6 +170,11 @@
     private int _highResBulkTotal;
     private int _highResBulkDone;
 
+    // Local state for the "Backfill Opus" action. The Opus derive is server-side and background-queued, so
+    // there is no client-side per-track loop or progress total — this flag only guards the button while the
+    // single scheduling call is in flight.
+    private bool _opusBackfillRunning;
+
     protected override async Task OnInitializedAsync()
     {
         // Seed the active tab from ?medium= so a catalogue card deep-links straight to its medium. Panel 0
@@ -291,4 +316,50 @@
             Snackbar.Add($"Backfilled {succeeded} high-res datum(s); {failures} failed.", Severity.Warning);
         }
     }
+
+    /// <summary>
+    /// Kick off the catalogue-wide Backfill-Opus pass. The API enumerates the tracks lacking a complete Opus
+    /// artifact, enqueues a background derive for each, and returns the (enqueued, skipped) counts. This is a
+    /// single scheduling call — the transcodes run server-side afterward — so there is no per-track progress
+    /// to render here, just a busy flag and a result snackbar. Re-runnable: a second press only schedules
+    /// tracks still missing Opus.
+    /// </summary>
+    private async Task BackfillOpusAsync()
+    {
+        _opusBackfillRunning = true;
+        StateHasChanged();
+        try
+        {
+            var result = await CmsTrackService.BackfillOpusAsync();
+            if (!result.Success)
+            {
+                var error = result.Messages.FirstOrDefault()?.Message ?? "Failed to start the Opus backfill.";
+                Snackbar.Add(error, Severity.Error);
+                return;
+            }
+
+            var (enqueued, skipped) = (result.Value.Enqueued, result.Value.Skipped);
+            if (enqueued == 0)
+            {
+                Snackbar.Add($"All {skipped} track(s) already have Opus — nothing to backfill.", Severity.Info);
+            }
+            else
+            {
+                Snackbar.Add(
+                    $"Scheduled {enqueued} Opus transcode(s) in the background ({skipped} already had Opus). " +
+                    "They will appear as each finishes.",
+                    Severity.Success);
+            }
+        }
+        catch (Exception ex)
+        {
+            Logger.LogError(ex, "Opus backfill failed to start");
+            Snackbar.Add("Failed to start the Opus backfill.", Severity.Error);
+        }
+        finally
+        {
+            _opusBackfillRunning = false;
+            StateHasChanged();
+        }
+    }
 }

DeepDrftManager/Services/CmsTrackService.cs

@@ -765,6 +765,45 @@ public class CmsTrackService : ICmsTrackService
         }
     }
 
+    public async Task<ResultContainer<OpusBackfillResult>> BackfillOpusAsync(CancellationToken ct = default)
+    {
+        var client = _httpClientFactory.CreateClient(ContentCmsClientName);
+
+        HttpResponseMessage response;
+        try
+        {
+            response = await client.PostAsync("api/track/opus/backfill", null, ct);
+        }
+        catch (Exception ex)
+        {
+            _logger.LogError(ex, "Content API call failed for Opus backfill");
+            return ResultContainer<OpusBackfillResult>.CreateFailResult("Content API is unreachable.");
+        }
+
+        using (response)
+        {
+            if (!response.IsSuccessStatusCode)
+            {
+                var body = await response.Content.ReadAsStringAsync(ct);
+                _logger.LogError("Content API Opus backfill failed: {Status} {Body}", (int)response.StatusCode, body);
+                return ResultContainer<OpusBackfillResult>.CreateFailResult("Failed to start the Opus backfill.");
+            }
+
+            OpusBackfillResult payload;
+            try
+            {
+                payload = await response.Content.ReadFromJsonAsync<OpusBackfillResult>(ct);
+            }
+            catch (Exception ex)
+            {
+                _logger.LogError(ex, "Failed to deserialize Opus backfill response from Content API");
+                return ResultContainer<OpusBackfillResult>.CreateFailResult("Content API returned an unexpected response.");
+            }
+
+            return ResultContainer<OpusBackfillResult>.CreatePassResult(payload);
+        }
+    }
+
     public async Task<ResultContainer<List<ReleaseDto>>> GetReleasesAsync(CancellationToken ct = default)
     {
         var client = _httpClientFactory.CreateClient(ContentCmsClientName);

DeepDrftManager/Services/ICmsTrackService.cs

@@ -152,6 +152,15 @@ public interface ICmsTrackService
     /// </summary>
     Task<Result> GenerateHighResWaveformAsync(string entryKey, CancellationToken ct = default);
 
+    /// <summary>
+    /// Trigger the catalogue-wide Backfill-Opus pass via <c>POST api/track/opus/backfill</c> (Phase 18.5).
+    /// The API enqueues a background Opus derive for every track lacking a complete Opus artifact and returns
+    /// the (enqueued, skipped) counts. Enqueue-only — the transcodes run server-side on a serial background
+    /// worker, so this call returns as soon as the work is scheduled, not when transcoding finishes. The
+    /// <c>Enqueued</c> count is how many derives were scheduled; <c>Skipped</c> is how many already had Opus.
+    /// </summary>
+    Task<ResultContainer<OpusBackfillResult>> BackfillOpusAsync(CancellationToken ct = default);
+
     /// <summary>Returns all releases with track counts from GET api/track/albums.</summary>
     Task<ResultContainer<List<ReleaseDto>>> GetReleasesAsync(CancellationToken ct = default);
 
@@ -160,3 +169,11 @@ public interface ICmsTrackService
     /// </summary>
     Task<ResultContainer<int>> GetTrackCountAsync(CancellationToken ct = default);
 }
+
+/// <summary>
+/// Outcome of a Backfill-Opus pass (Phase 18.5): how many tracks had a background derive scheduled
+/// (<paramref name="Enqueued"/>) and how many were skipped because they already carry a complete Opus
+/// artifact (<paramref name="Skipped"/>). Both are counts of tracks, not finished transcodes — the work
+/// runs asynchronously on the API's background worker after this returns.
+/// </summary>
+public readonly record struct OpusBackfillResult(int Enqueued, int Skipped);