Skip to content

A full-featured download manager.

8.9 KB
Raw Blame
// ffmpeg-detect — runtime-agnostic ffmpeg binary probe.
//
// Provides three exports:
//   - probeBinary(path): spawns `<path> -version`, parses version from stdout.
//   - detectFromCandidates(paths[]): walks candidates sequentially, returns
//     first successful probe.
//   - detectInOrder(input, probe?): richer result for UI consumers. Returns
//     the active winner plus per-candidate state across the 4 detection
//     layers (manual / userData / env / PATH) in a fixed order, regardless
//     of which ones are configured. States: 'active' | 'available' |
//     'missing' | 'untrusted' | 'unconfigured' | 'version_mismatch'. The last
//     is reserved for a future semver gate and never emitted here. The `probe`
//     argument is for test injection; production callers omit it.
//
// Used by shell wrappers (Electron + Server) that supply the candidate list.
// This module MUST NOT import electron, @main/, or @server/.

import { spawn } from 'node:child_process'
import { existsSync } from 'node:fs'
import path from 'node:path'

// ---------------------------------------------------------------------------
// Types
// ---------------------------------------------------------------------------

export type FfmpegDetectionFailureReason =
  | 'missing'
  | 'untrusted'
  | 'verification_unavailable'

export interface FfmpegDetection {
  available: boolean
  binaryPath?: string
  version?: string
  /** Why a host-specific preflight declined to execute this candidate. */
  failureReason?: FfmpegDetectionFailureReason
}

// ---------------------------------------------------------------------------
// probeBinary
// ---------------------------------------------------------------------------

const VERSION_RE = /ffmpeg version (\S+)/

/**
 * Probe a single binary path by spawning `<binaryPath> -version`.
 *
 * - If the path contains a separator (i.e. it is an absolute/relative path,
 *   not a bare command name) and does not exist on disk, we skip the spawn
 *   and return immediately.
 * - Otherwise we spawn the process, collect stdout, and parse the version.
 * - Hard timeout: 5 seconds. Process is killed on timeout.
 */
export function probeBinary(binaryPath: string): Promise<FfmpegDetection> {
  const isPathLike = binaryPath.includes('/') || binaryPath.includes('\\')
  if (isPathLike && !existsSync(binaryPath)) {
    return Promise.resolve({ available: false })
  }

  return new Promise<FfmpegDetection>((resolve) => {
    let settled = false
    const settle = (result: FfmpegDetection) => {
      if (settled) return
      settled = true
      resolve(result)
    }

    let ch: ReturnType<typeof spawn>
    try {
      ch = spawn(binaryPath, ['-version'], {
        stdio: ['ignore', 'pipe', 'pipe'],
      })
    } catch {
      settle({ available: false })
      return
    }

    const timer = setTimeout(() => {
      try {
        ch.kill('SIGTERM')
      } catch {
        // ignore kill errors
      }
      settle({ available: false })
    }, 5_000)

    let stdout = ''
    ch.stdout?.on('data', (chunk: Buffer) => {
      stdout += chunk.toString()
    })

    ch.on('error', () => {
      clearTimeout(timer)
      settle({ available: false })
    })

    ch.on('close', (code: number | null) => {
      clearTimeout(timer)
      if (code !== 0 && code !== null) {
        settle({ available: false })
        return
      }
      const match = VERSION_RE.exec(stdout)
      if (match) {
        settle({ available: true, binaryPath, version: match[1] })
      } else {
        settle({ available: false })
      }
    })
  })
}

// ---------------------------------------------------------------------------
// detectFromCandidates
// ---------------------------------------------------------------------------

/**
 * Walk the candidate list sequentially, returning the first successful probe.
 * Returns `{available: false}` if all candidates fail.
 */
export async function detectFromCandidates(
  candidates: ReadonlyArray<string>
): Promise<FfmpegDetection> {
  for (const candidate of candidates) {
    // eslint-disable-next-line no-await-in-loop
    const result = await probeBinary(candidate)
    if (result.available) return result
  }
  return { available: false }
}

// ---------------------------------------------------------------------------
// detectInOrder — enriched per-candidate detection result
// ---------------------------------------------------------------------------

export interface FfmpegDetectionInput {
  /** From MediaSettings.ffmpegBinaryPath; `''` means unconfigured. */
  manualPath: string
  /** userData binaries directory (required; the candidate path is derived). */
  userDataBinariesDir: string
  /** Host platform snapshot used to derive the userData binary name. */
  platform: string
  /** Host-provided environment candidate; `null` means unconfigured. */
  envPath: string | null
}

export type CandidateKind = 'manual' | 'userData' | 'env' | 'path'

export interface FfmpegCandidate {
  kind: CandidateKind
  path: string | null
}

export type CandidateState =
  | 'active'
  | 'available'
  | 'missing'
  | 'untrusted'
  | 'unconfigured'
  | 'verification_unavailable'
  | 'version_mismatch'

export interface FfmpegDetectionResult {
  active: { path: string; version: string } | null
  candidates: Array<{
    kind: CandidateKind
    path: string | null
    state: CandidateState
    version?: string
  }>
}

function ffmpegBinName(platform: string): string {
  return platform === 'win32' ? 'ffmpeg.exe' : 'ffmpeg'
}

/**
 * Build the fixed-priority candidate list without touching the filesystem or
 * executing any candidate. Startup discovery and explicit version probing use
 * this same list so their precedence cannot drift.
 */
export function ffmpegCandidatesInOrder(
  input: FfmpegDetectionInput
): FfmpegCandidate[] {
  return [
    { kind: 'manual', path: input.manualPath || null },
    {
      kind: 'userData',
      path: path.join(input.userDataBinariesDir, ffmpegBinName(input.platform)),
    },
    { kind: 'env', path: input.envPath },
    { kind: 'path', path: 'ffmpeg' },
  ]
}

/**
 * Probe all 4 detection layers in fixed order and return a per-candidate
 * report plus the active winner.
 *
 * Order is always: manual → userData → env → path. Every entry is reported,
 * even when unconfigured or missing.
 *
 * State emission:
 *  - `null` path → `'unconfigured'` (no version).
 *  - Probe succeeds and no active winner yet → `'active'`. The result's
 *    `active.path` is `probe.binaryPath ?? candidatePath` (PATH lookup may
 *    rewrite to an absolute path).
 *    Candidate rows also report this resolved path, rather than the lookup alias.
 *  - Probe succeeds but a higher-priority candidate already won →
 *    `'available'` (still includes version).
 *  - Probe reports `failureReason: 'untrusted'` → `'untrusted'`.
 *  - Temporarily unavailable verification → `'verification_unavailable'`;
 *    keep looking for another usable candidate.
 *  - Any other probe failure → `'missing'`.
 *  - `'version_mismatch'` is reserved for a future semver gate; this
 *    function never emits it.
 *
 * The optional `probe` parameter is for test injection only.
 */
export async function detectInOrder(
  input: FfmpegDetectionInput,
  probe: (binaryPath: string) => Promise<FfmpegDetection> = probeBinary
): Promise<FfmpegDetectionResult> {
  const candidates: FfmpegDetectionResult['candidates'] = []
  let active: FfmpegDetectionResult['active'] = null

  for (const entry of ffmpegCandidatesInOrder(input)) {
    const p = entry.path
    if (!p) {
      candidates.push({ kind: entry.kind, path: null, state: 'unconfigured' })
      continue
    }
    // eslint-disable-next-line no-await-in-loop
    const result = await probe(p)
    const checkedPath = result.binaryPath ?? p
    if (result.available) {
      if (active === null) {
        active = {
          path: checkedPath,
          version: result.version ?? '',
        }
        candidates.push({
          kind: entry.kind,
          path: checkedPath,
          state: 'active',
          version: result.version,
        })
      } else {
        candidates.push({
          kind: entry.kind,
          path: checkedPath,
          state: 'available',
          version: result.version,
        })
      }
    } else {
      candidates.push({
        kind: entry.kind,
        path: checkedPath,
        state: result.failureReason ?? 'missing',
      })
    }
  }

  return { active, candidates }
}

/**
 * Projects a `FfmpegDetectionResult` (enriched per-candidate state) to the
 * legacy `FfmpegDetection` shape consumed by FfmpegCapabilityHost.
 *
 * Treats `active.version === ''` as "no version" (matches the sentinel
 * detectInOrder emits when probeBinary can't parse a version string).
 */
export function projectActiveToLegacy(
  result: FfmpegDetectionResult
): FfmpegDetection {
  return result.active
    ? {
        available: true,
        version: result.active.version || undefined,
        binaryPath: result.active.path,
      }
    : { available: false }
}