feat: Smarter ffmpeg/ffprobe resolution, until we bundle it

.gitignore

@@ -42,3 +42,7 @@ crates/client-web/dist/
 
 # dev temp files
 .dev/
+
+# git worktrees
+.worktrees/
+artifacts

crates/client-web/src/api.ts

@@ -53,6 +53,41 @@ export interface ServerCapabilities {
   };
 }
 
+/** Validation result for a single transcoding binary (configured path or candidate). */
+export interface BinaryProbe {
+  resolved_path?: string;
+  version?: string;
+  error?: string;
+  /** Transcoding-relevant encoders this ffmpeg supports (ffmpeg only). */
+  encoders?: string[];
+}
+
+/** One directory discovered to contain ffmpeg and/or ffprobe. */
+export interface ToolCandidate {
+  directory: string;
+  ffmpeg?: BinaryProbe;
+  ffprobe?: BinaryProbe;
+}
+
+/** Result of the on-demand transcoding-tools discovery call. */
+export interface ToolDiscoveryResponse {
+  configured_ffmpeg: BinaryProbe;
+  configured_ffprobe: BinaryProbe;
+  candidates: ToolCandidate[];
+}
+
+/** A structured transcode error recoverable via the session-status endpoint. */
+export interface TranscodeErrorBody {
+  code: string;
+  message: string;
+  action?: string;
+}
+
+/** Status of a playback session's transcode. */
+export interface SessionStatusResponse {
+  error?: TranscodeErrorBody;
+}
+
 export interface BootstrapUser {
   id: number;
   username: string;
@@ -415,8 +450,13 @@ export interface MediaHome {
   collections: MediaCollectionSummary[];
 }
 
+/** Whether the source media has been analyzed by ffprobe. */
+export type PlaybackAnalysisState = 'analyzed' | 'awaiting_analysis';
+
 export interface PlaybackDecision {
   item_id: number;
+  /** Whether the source media was probed; if 'awaiting_analysis', playback is blocked. */
+  analysis_state: PlaybackAnalysisState;
   can_direct_play: boolean;
   transcode_required: boolean;
   reason: string;
@@ -1275,6 +1315,32 @@ export function deletePlaybackSession(sessionId: string): Promise<void> {
   return requestJson<void>('DELETE', `/api/v1/sessions/${sessionId}`);
 }
 
+/** Discover ffmpeg/ffprobe candidates and validate the configured paths (admin). */
+export function discoverTranscodingTools(): Promise<ToolDiscoveryResponse> {
+  return requestJson<ToolDiscoveryResponse>('POST', '/api/v1/system/tools/discover');
+}
+
+/** Read a playback session's transcode status (cheap map lookup, not a spawn). */
+export function getSessionStatus(sessionId: string): Promise<SessionStatusResponse> {
+  return requestJson<SessionStatusResponse>('GET', `/api/v1/sessions/${encodeURIComponent(sessionId)}/status`);
+}
+
+/** Re-probe status: whether a job is running and how many files await analysis. */
+export interface ReprobeStatusResponse {
+  in_progress: boolean;
+  pending_count: number;
+}
+
+/** Get re-probe status (running? how many files pending ffprobe analysis). */
+export function getReprobeStatus(): Promise<ReprobeStatusResponse> {
+  return requestJson<ReprobeStatusResponse>('GET', '/api/v1/system/tools/reprobe');
+}
+
+/** Manually trigger a ffprobe re-probe of all unanalyzed media files (admin). */
+export function triggerReprobe(): Promise<ReprobeStatusResponse> {
+  return requestJson<ReprobeStatusResponse>('POST', '/api/v1/system/tools/reprobe');
+}
+
 export function getArtworkUrl(itemId: number, kind: 'poster' | 'backdrop' | 'logo' = 'poster', revision?: number): string {
   const params = new URLSearchParams({ kind });
   if (typeof revision === 'number') {

crates/client-web/src/app.ts

@@ -425,7 +425,7 @@
   `;
 }
 
 function render(preserveScroll = true): void {
   if (!state.isPlayerOpen && !state.activeTrailer) {
     document.body.style.cursor = '';
   }
@@ -468,7 +468,7 @@
       ${renderRail()}
       <div class="main-shell">
         <div class="main-shell-inner">
-          ${state.error ? `<section class="panel error-panel page-panel">${escapeHtml(state.error)}</section>` : ''}
+          ${state.error ? `<section class="panel error-panel page-panel">${escapeHtml(state.error)}${state.playbackError?.action === 'open_settings' ? `<button class="secondary-button" type="button" data-action="open-settings">Open settings</button>` : ''}</section>` : ''}
           ${renderCurrentPage()}
         </div>
       </div>

crates/client-web/src/app/eventBindings.ts

@@ -43,7 +43,7 @@ import {
   selectedItemDefaultMetadataYear,
   selectedItemExtras,
 } from './itemPersonView';
-import { buildSettingsFromForm } from './settingsView';
+import { buildSettingsFromForm, renderDiscoverResults, renderPathValidation } from './settingsView';
 import { setButtonBusy } from './ui';
 import {
   addLibrary,
@@ -52,6 +52,8 @@ import {
   createUser,
   deleteLibrary,
   deleteMissingItems,
+  discoverTranscodingTools,
+  getReprobeStatus,
   getItemMetadata,
   getLogs,
   getUsers,
@@ -71,6 +73,7 @@ import {
   type MediaShelf,
   type ScheduledTaskId,
   type UpdateUserRequest,
+  triggerReprobe,
 } from '../api';
 
 /** Replaces a DOM subtree while preserving any coordinator-level patch behavior. */
@@ -527,6 +530,93 @@ function bindRenderEvents(context: AppEventBindingContext): void {
     });
   });
 
+  document.querySelectorAll<HTMLElement>('[data-action="open-settings"]').forEach((button) => {
+    button.addEventListener('click', () => {
+      navigateTo('/settings');
+    });
+  });
+
+  document.querySelector<HTMLButtonElement>('#detect-ffmpeg')?.addEventListener('click', async (event) => {
+    const button = event.currentTarget as HTMLButtonElement;
+    const resultsContainer = document.querySelector<HTMLElement>('#ffmpeg-discover-results');
+    const ffmpegInput = document.querySelector<HTMLInputElement>('input[name="ffmpeg_path"]');
+    const ffprobeInput = document.querySelector<HTMLInputElement>('input[name="ffprobe_path"]');
+    const ffmpegValidation = document.querySelector<HTMLElement>('#ffmpeg-path-validation');
+    const ffprobeValidation = document.querySelector<HTMLElement>('#ffprobe-path-validation');
+    if (!resultsContainer || !ffmpegInput || !ffprobeInput) {
+      return;
+    }
+    setButtonBusy(button, true);
+    try {
+      const discovery = await discoverTranscodingTools();
+      resultsContainer.innerHTML = renderDiscoverResults(discovery);
+      resultsContainer.hidden = false;
+
+      // Per-field validation detail, driven by the configured-path probes.
+      if (ffmpegValidation) {
+        ffmpegValidation.innerHTML = renderPathValidation(discovery.configured_ffmpeg, 'ffmpeg');
+        ffmpegValidation.hidden = !ffmpegValidation.innerHTML;
+      }
+      if (ffprobeValidation) {
+        ffprobeValidation.innerHTML = renderPathValidation(discovery.configured_ffprobe, 'ffprobe');
+        ffprobeValidation.hidden = !ffprobeValidation.innerHTML;
+      }
+
+      // [Use] buttons write <dir>/ffmpeg + <dir>/ffprobe into the path fields.
+      resultsContainer.querySelectorAll<HTMLButtonElement>('[data-use-directory]').forEach((useButton) => {
+        useButton.addEventListener('click', () => {
+          const dir = useButton.dataset.useDirectory;
+          if (!dir) {
+            return;
+          }
+          ffmpegInput.value = `${dir}/ffmpeg`;
+          ffprobeInput.value = `${dir}/ffprobe`;
+        });
+      });
+    } catch (error) {
+      resultsContainer.hidden = false;
+      resultsContainer.innerHTML = `<p class="muted">Detection failed: ${escapeHtml(error instanceof Error ? error.message : 'unknown error')}</p>`;
+    } finally {
+      setButtonBusy(button, false);
+    }
+  });
+
+  // Re-probe media info: show the button when there are unanalyzed files
+  // (ffprobe was missing during scan), and trigger the job on click.
+  const reprobeButton = document.querySelector<HTMLButtonElement>('#reprobe-media');
+  const reprobeStatus = document.querySelector<HTMLElement>('#reprobe-status');
+  if (reprobeButton && reprobeStatus) {
+    getReprobeStatus()
+      .then((status) => {
+        if (status.in_progress) {
+          reprobeStatus.hidden = false;
+          reprobeStatus.textContent = 'Re-probing media info is in progress… (see Dashboard → Activities).';
+        } else if (status.pending_count > 0) {
+          reprobeButton.hidden = false;
+          reprobeStatus.hidden = false;
+          reprobeStatus.textContent = `${status.pending_count} media file(s) were scanned without ffprobe and need re-analysis. Click to re-probe.`;
+        }
+      })
+      .catch((error) => {
+        console.warn('Failed to fetch reprobe status', error);
+      });
+
+    reprobeButton.addEventListener('click', async () => {
+      setButtonBusy(reprobeButton, true);
+      try {
+        await triggerReprobe();
+        reprobeStatus.hidden = false;
+        reprobeStatus.textContent = 'Re-probe started. Watch Dashboard → Activities for progress; playback unlocks as files are analyzed.';
+        reprobeButton.hidden = true;
+      } catch (error) {
+        reprobeStatus.hidden = false;
+        reprobeStatus.textContent = `Re-probe failed to start: ${escapeHtml(error instanceof Error ? error.message : 'unknown error')}`;
+      } finally {
+        setButtonBusy(reprobeButton, false);
+      }
+    });
+  }
+
   document.querySelectorAll<HTMLButtonElement>('[data-provider-settings]').forEach((button) => {
     button.addEventListener('click', () => {
       const providerId = button.dataset.providerSettings;

crates/client-web/src/app/playbackController.ts

@@ -7,6 +7,7 @@ import {
   deletePlaybackSession,
   getArtworkUrl,
   getItem,
+  getSessionStatus,
   getSessionStreamUrl,
   getWebClientProfile,
   resolveApiUrl,
@@ -322,8 +323,8 @@ function renderMediaPlayerOverlay(): string {
           <span class="loading-spinner player-loading-spinner" aria-hidden="true"></span>
         </div>
         <div class="player-error-indicator" aria-live="polite">
-          <strong>Playback could not start</strong>
-          <span>Try another audio track or start playback again.</span>
+          <strong>${escapeHtml(state.playbackError ? 'Playback failed' : 'Playback could not start')}</strong>
+          <span>${escapeHtml(state.playbackError?.message ?? 'Try another audio track or start playback again.')}</span>
         </div>
         <div class="player-idle-hit-area" aria-hidden="true"></div>
         <div class="player-top-controls player-controls">
@@ -615,6 +616,8 @@ export async function startPlayback(item: MediaItemDetail, startMs: number): Pro
   state.isPlayerOpen = true;
   state.activeAudioStreamIndex = undefined;
   state.isAudioTrackMenuOpen = false;
+  // Clear any stale playback error from a previous attempt.
+  state.playbackError = undefined;
   render();
 
   if (previousSession) {
@@ -627,6 +630,28 @@ export async function startPlayback(item: MediaItemDetail, startMs: number): Pro
     item_id: item.id,
     client_profile: getWebClientProfile(),
   });
+
+  // Server-truth gate: if the source media was never analyzed by ffprobe
+  // (ffprobe was missing during scan), the decision is untrustworthy and the
+  // server returns analysis_state = 'awaiting_analysis'. Refuse to open a
+  // doomed player and surface the error instead. This replaces the old,
+  // buggy client-side capabilities-cache preflight.
+  const decision = state.activePlaybackSession.decision;
+  if (decision.analysis_state === 'awaiting_analysis') {
+    state.playbackError = {
+      code: 'media_not_analyzed',
+      message: decision.reason || 'This media has not been analyzed yet. Set the ffprobe path in Settings and re-probe media info.',
+      action: 'open_settings',
+    };
+    state.error = state.playbackError.message;
+    render();
+    // The player overlay covers the page banner, so toggle the in-player error
+    // class directly (the shell is mounted by the render() above).
+    document.querySelector<HTMLElement>('.media-player-shell')?.classList.remove('is-media-loading');
+    document.querySelector<HTMLElement>('.media-player-shell')?.classList.add('has-media-error');
+    return;
+  }
+
   render();
 }
 
@@ -1330,6 +1355,23 @@ export function bindPlayerProgress(): void {
   player.addEventListener('error', () => {
     setPlayerError();
     console.error('Media playback failed', player.error);
+    const sessionId = state.activePlaybackSession?.session_id;
+    if (!sessionId) {
+      return;
+    }
+    // Best-effort: recover a structured error from the per-session store. This
+    // is a cheap map lookup on the server, not a transcode spawn. It only helps
+    // when the browser actually fires `error` (HTTP failures are unreliable).
+    void getSessionStatus(sessionId)
+      .then((status) => {
+        if (status.error) {
+          state.playbackError = status.error;
+          render();
+        }
+      })
+      .catch((error) => {
+        console.warn('Failed to fetch session status after playback error', error);
+      });
   });
   player.addEventListener('loadedmetadata', () => {
     applyInitialDirectSeek();