A full-featured download manager.
// ffmpeg capability — spawn + AsyncIterable progress + abort.
//
// Operation handle pattern (I38):
// run() returns an FfmpegOpHandle<T> immediately. The caller can await
// handle.result or iterate handle.progress independently. The handle's
// abort() method sends SIGTERM to the spawned process; if the process
// has not exited within 5 seconds, SIGKILL is sent.
//
// Progress events:
// Parsed from stderr via /time=(\d+):(\d+):([\d.]+).*?speed=([\d.]+)x/.
// Debounced: at most one event per 1 000 ms wall-clock time. If no new
// progress arrives within 1 s after the most recent event, the prior
// progress is re-emitted as a keep-alive sentinel so consumers do not
// starve. Iterator ends when the process closes.
//
// Abort / timeout:
// abort() -> SIGTERM -> 5 s grace -> SIGKILL.
// An external AbortSignal chains into the same abort() path.
// timeoutMs defaults to 60 min; hard cap is 60 min.
//
// Staging redirect hook:
// FfmpegCapabilityHostOptions.stagingPathFor(outputPath) -> stagedPath.
// When provided, the resolved staged path is substituted for the caller's
// outputPath in argv *and* returned in the result payload. The
// CapabilityBridge.gateFfmpegOutput path is the primary caller and
// redirects upstream before invoking run/transcode/etc., so this hook is
// typically a no-op in production wiring; it remains as an explicit
// injection point for unit tests of the capability host in isolation.
//
// Boundary: MUST NOT import electron, @main/, or @server/.
import { spawn } from 'node:child_process'
import { randomUUID } from 'node:crypto'
import {
type FfmpegDetection,
type FfmpegDetectionResult,
projectActiveToLegacy,
} from './ffmpeg-detect'
// Manual merges accept standalone media, never playlists or demuxers that
// discover other files. A file-only protocol allowlist alone still lets HLS,
// DASH, concat and image sequences read paths the user never selected.
// MOV external data references keep FFmpeg's disabled default; this API does
// not accept demuxer options that could enable them. Apply this policy
// before opening *each* input, for both probing and merging.
const LOCAL_MEDIA_INPUT_OPTIONS = [
'-protocol_whitelist',
'file',
'-format_whitelist',
'mov,matroska,webm,avi,mpegts,mpegvideo,mpeg,aac,mp3,flac,ogg,wav,flv',
]
// ---------------------------------------------------------------------------
// Error class
// ---------------------------------------------------------------------------
export class FfmpegError extends Error {
constructor(
public readonly code: string,
message: string
) {
super(message)
this.name = 'FfmpegError'
}
}
// ---------------------------------------------------------------------------
// Types
// ---------------------------------------------------------------------------
export interface FfmpegProgress {
/** 0..100, best-effort; requires expectedDurationMs to be non-zero */
percent: number
/** e.g. "1.2x" */
speed: string
/** current time position in ms */
timeMs: number
}
export interface FfmpegOpHandle<T> {
id: string
result: Promise<T>
progress: AsyncIterable<FfmpegProgress>
abort(): void
}
export interface FfmpegRunOptions {
/** Raw ffmpeg args (excluding the binary path). */
argv: string[]
/** Output path; CapabilityBridge.gateFfmpegOutput pre-redirects it for beforeFinalize. */
outputPath: string
/** Default 60 * 60_000; hard cap 60 min. */
timeoutMs?: number
signal?: AbortSignal
/** When provided, drives percent calculation. */
expectedDurationMs?: number
}
export interface MediaInfo {
durationMs: number
format?: string
streams: ReadonlyArray<{ type: string; codec?: string; bitrate?: number }>
}
export interface FfmpegCapabilityHostOptions {
detect: FfmpegDetection
/** Revalidate managed binaries immediately before every spawn, including cached paths. */
validateBinaryPath?: (binaryPath: string) => void
/**
* Optional staging redirect. Primary callers (CapabilityBridge.gateFfmpegOutput)
* pre-redirect the output before invoking run/transcode/etc., so this hook is
* usually undefined in production. Tests and direct callers of FfmpegCapabilityHost
* can set it to observe path rewrites.
*/
stagingPathFor?: (outputPath: string) => string
/**
* Override the spawn function. Defaults to node:child_process.spawn.
* Provided for testing without requiring a real ffmpeg binary.
*/
spawnFn?: typeof spawn
}
// ---------------------------------------------------------------------------
// Constants
// ---------------------------------------------------------------------------
const SIGKILL_GRACE_MS = 5_000
const MAX_TIMEOUT_MS = 60 * 60_000
const PROGRESS_DEBOUNCE_MS = 1_000
const KEEP_ALIVE_IDLE_MS = 1_000
// ---------------------------------------------------------------------------
// Progress parsing helpers
// ---------------------------------------------------------------------------
// Matches stderr lines like:
// frame=42 fps=30.0 q=-0.0 size=N/A time=00:00:05.000 bitrate=N/A speed=1.5x
const PROGRESS_RE = /time=(\d+):(\d+):([\d.]+).*?speed=([\d.]+)x/
// Matches Duration in probe output:
// Duration: 00:01:23.45, ...
const DURATION_RE = /Duration:\s+(\d+):(\d+):([\d.]+)/
function parseHmsToMs(h: string, m: string, s: string): number {
return (
Number.parseInt(h, 10) * 3_600_000 +
Number.parseInt(m, 10) * 60_000 +
Math.round(Number.parseFloat(s) * 1_000)
)
}
function parseProgress(
line: string,
expectedDurationMs: number
): FfmpegProgress | null {
const match = PROGRESS_RE.exec(line)
if (!match) return null
const timeMs = parseHmsToMs(match[1], match[2], match[3])
const speed = `${match[4]}x`
const percent =
expectedDurationMs > 0
? Math.min(100, (timeMs / expectedDurationMs) * 100)
: 0
return { percent, speed, timeMs }
}
// ---------------------------------------------------------------------------
// Internal AsyncIterable queue
// ---------------------------------------------------------------------------
interface Queue<T> {
push(v: T): void
close(): void
iter: AsyncIterable<T>
}
function makeQueue<T>(): Queue<T> {
const buf: T[] = []
const waiters: Array<(v: IteratorResult<T, undefined>) => void> = []
let closed = false
function push(v: T): void {
if (closed) return
if (waiters.length > 0) {
// biome-ignore lint/style/noNonNullAssertion: guarded by length check above
waiters.shift()!({ value: v, done: false })
} else {
buf.push(v)
}
}
function close(): void {
if (closed) return
closed = true
for (const w of waiters) {
w({ value: undefined, done: true })
}
waiters.length = 0
}
const iter: AsyncIterable<T> = {
[Symbol.asyncIterator]() {
return {
next(): Promise<IteratorResult<T, undefined>> {
return new Promise((resolve) => {
if (buf.length > 0) {
// biome-ignore lint/style/noNonNullAssertion: guarded by length check above
resolve({ value: buf.shift()!, done: false })
} else if (closed) {
resolve({ value: undefined, done: true })
} else {
waiters.push(resolve)
}
})
},
}
},
}
return { push, close, iter }
}
// ---------------------------------------------------------------------------
// FfmpegCapabilityHost
// ---------------------------------------------------------------------------
/** Unavailable no-op handle — returned immediately when ffmpeg is not available. */
function unavailableHandle(id: string): FfmpegOpHandle<{ outputPath: string }> {
const err = new FfmpegError(
'plugin.capability.unavailable',
'ffmpeg not available'
)
const promise: Promise<{ outputPath: string }> = Promise.reject(err)
// Suppress unhandled rejection warnings when caller only uses .progress.
promise.catch(() => undefined)
const emptyIter: AsyncIterable<FfmpegProgress> = {
[Symbol.asyncIterator]() {
return {
next(): Promise<IteratorResult<FfmpegProgress, undefined>> {
return Promise.resolve({ value: undefined, done: true })
},
}
},
}
return { id, result: promise, progress: emptyIter, abort: () => undefined }
}
export class FfmpegCapabilityHost {
private detect: FfmpegDetection
private detectionGeneration = 0
private readonly stagingPathFor: ((p: string) => string) | undefined
private readonly spawnFn: typeof spawn
private readonly validateBinaryPath:
| ((binaryPath: string) => void)
| undefined
constructor(opts: FfmpegCapabilityHostOptions) {
this.detect = opts.detect
this.stagingPathFor = opts.stagingPathFor
this.spawnFn = opts.spawnFn ?? spawn
this.validateBinaryPath = opts.validateBinaryPath
}
get available(): boolean {
return this.detect.available
}
get version(): string | undefined {
return this.detect.version
}
/** Refresh future calls after an explicit host probe; running children keep their binary. */
updateDetection(detection: FfmpegDetection): void {
this.detectionGeneration++
this.detect = { ...detection }
}
/** Older probes may finish last, but cannot overwrite the newest requested snapshot. */
async refreshDetection(
probe: () => Promise<FfmpegDetectionResult>
): Promise<FfmpegDetectionResult> {
const generation = ++this.detectionGeneration
try {
const result = await probe()
if (generation === this.detectionGeneration)
this.detect = projectActiveToLegacy(result)
return result
} catch (error) {
if (generation === this.detectionGeneration)
this.detect = { available: false }
throw error
}
}
// -------------------------------------------------------------------------
// run
// -------------------------------------------------------------------------
run(opts: FfmpegRunOptions): FfmpegOpHandle<{ outputPath: string }> {
if (!this.detect.available || !this.detect.binaryPath) {
return unavailableHandle(randomUUID())
}
try {
this.validateBinaryPath?.(this.detect.binaryPath)
} catch {
return unavailableHandle(randomUUID())
}
const id = randomUUID()
const clampedTimeoutMs = Math.min(
opts.timeoutMs !== undefined && opts.timeoutMs >= 0
? opts.timeoutMs
: MAX_TIMEOUT_MS,
MAX_TIMEOUT_MS
)
const expectedDurationMs = opts.expectedDurationMs ?? 0
// Substitute staged path when the test-isolation hook is set.
const resolvedOutputPath = this.stagingPathFor
? this.stagingPathFor(opts.outputPath)
: opts.outputPath
// biome-ignore lint/style/noNonNullAssertion: binaryPath guarded above
const binaryPath = this.detect.binaryPath!
const queue = makeQueue<FfmpegProgress>()
// -----------------------------------------------------------------------
// Spawn process
// -----------------------------------------------------------------------
const proc = this.spawnFn(binaryPath, opts.argv, {
stdio: ['ignore', 'pipe', 'pipe'],
})
// -----------------------------------------------------------------------
// Abort machinery
// -----------------------------------------------------------------------
let aborted = false
let settled = false
let killTimer: ReturnType<typeof setTimeout> | undefined
let timeoutTimer: ReturnType<typeof setTimeout>
const abort = (): void => {
if (aborted || settled) return
aborted = true
clearTimeout(timeoutTimer)
try {
proc.kill('SIGTERM')
} catch {
// ignore errors from kill (process may already be gone)
}
killTimer = setTimeout(() => {
try {
proc.kill('SIGKILL')
} catch {
// ignore
}
}, SIGKILL_GRACE_MS)
}
// Chain external AbortSignal
if (opts.signal) {
if (opts.signal.aborted) {
abort()
} else {
opts.signal.addEventListener('abort', abort, { once: true })
}
}
// Internal operation timeout
timeoutTimer = setTimeout(abort, clampedTimeoutMs)
// -----------------------------------------------------------------------
// Progress debounce + keep-alive
// -----------------------------------------------------------------------
let lastEmitTs = 0
let lastProgress: FfmpegProgress | null = null
let keepAliveTimer: ReturnType<typeof setTimeout> | undefined
const scheduleKeepAlive = (): void => {
clearTimeout(keepAliveTimer)
if (lastProgress === null) return
const captured = lastProgress
keepAliveTimer = setTimeout(() => {
queue.push(captured)
// Reschedule for continuous keep-alive while process is running.
scheduleKeepAlive()
}, KEEP_ALIVE_IDLE_MS)
}
const emitProgress = (p: FfmpegProgress): void => {
const now = Date.now()
const elapsed = now - lastEmitTs
lastProgress = p
if (elapsed >= PROGRESS_DEBOUNCE_MS) {
lastEmitTs = now
queue.push(p)
scheduleKeepAlive()
}
// else: debounce — lastProgress updated but no emit this tick
}
// -----------------------------------------------------------------------
// stderr -> progress
// -----------------------------------------------------------------------
let stderrBuf = ''
proc.stderr?.on('data', (chunk: Buffer) => {
stderrBuf += chunk.toString()
const lines = stderrBuf.split(/[\r\n]/)
stderrBuf = (lines.pop() ?? '').slice(-8192)
for (const line of lines) {
const p = parseProgress(line, expectedDurationMs)
if (p !== null) emitProgress(p)
}
})
// -----------------------------------------------------------------------
// Result promise
// -----------------------------------------------------------------------
const result = new Promise<{ outputPath: string }>((resolve, reject) => {
proc.on('error', (err: Error) => {
settled = true
opts.signal?.removeEventListener('abort', abort)
clearTimeout(timeoutTimer)
clearTimeout(killTimer)
clearTimeout(keepAliveTimer)
queue.close()
reject(
new FfmpegError(
'plugin.ffmpeg.spawn_error',
`ffmpeg spawn error: ${err.message}`
)
)
})
proc.on('close', (code: number | null) => {
settled = true
opts.signal?.removeEventListener('abort', abort)
clearTimeout(timeoutTimer)
clearTimeout(killTimer)
clearTimeout(keepAliveTimer)
queue.close()
if (aborted) {
reject(
new FfmpegError(
'plugin.ffmpeg.aborted',
'FFmpeg operation cancelled'
)
)
} else if (code === 0) {
resolve({ outputPath: resolvedOutputPath })
} else {
reject(
new FfmpegError(
'plugin.ffmpeg.exit_nonzero',
`ffmpeg exited with code ${code}`
)
)
}
})
})
return { id, result, progress: queue.iter, abort }
}
// -------------------------------------------------------------------------
// probe
// -------------------------------------------------------------------------
probe(input: {
path: string
signal?: AbortSignal
localOnly?: boolean
}): Promise<MediaInfo> {
if (!this.detect.available || !this.detect.binaryPath) {
return Promise.reject(
new FfmpegError('plugin.capability.unavailable', 'ffmpeg not available')
)
}
// biome-ignore lint/style/noNonNullAssertion: binaryPath guarded above
const binaryPath = this.detect.binaryPath!
return new Promise<MediaInfo>((resolve, reject) => {
try {
this.validateBinaryPath?.(binaryPath)
} catch {
reject(
new FfmpegError(
'plugin.ffmpeg.untrusted',
'FFmpeg integrity check failed'
)
)
return
}
// `ffmpeg -i <input>` prints the container/stream metadata to stderr
// during input analysis, then exits non-zero ("output file must be
// specified") — we ignore the exit code. We deliberately do NOT append
// `-f null -`: that forces a full decode of the entire file (minutes for
// a multi-GB video, tripping the 30s timeout) yet produces nothing this
// parser reads — duration/format/streams all come from the header block.
input.signal?.throwIfAborted()
const proc = this.spawnFn(
binaryPath,
[
...(input.localOnly
? ['-nostdin', ...LOCAL_MEDIA_INPUT_OPTIONS]
: []),
'-i',
input.path,
],
{
stdio: ['ignore', 'pipe', 'pipe'],
}
)
let closed = false
let failure: FfmpegError | undefined
let killTimer: ReturnType<typeof setTimeout> | undefined
const stop = (error: FfmpegError) => {
if (closed || failure) return
failure = error
clearTimeout(timer)
try {
proc.kill('SIGTERM')
} catch {
// The child may already have exited; still wait for close.
}
killTimer = setTimeout(() => {
try {
proc.kill('SIGKILL')
} catch {
// The child may already have exited.
}
}, SIGKILL_GRACE_MS)
}
const abort = () =>
stop(
new FfmpegError('plugin.ffmpeg.aborted', 'FFmpeg operation cancelled')
)
const timer = setTimeout(() => {
stop(
new FfmpegError(
'plugin.ffmpeg.probe_timeout',
'ffmpeg probe timed out'
)
)
}, 30_000)
// Cap the captured stderr: probe only needs the small header block
// (Input/Duration/Stream lines). Without a cap, an input pointed at a
// pipe/large stream (or a misbehaving ffmpeg) could flood stderr and
// exhaust heap inside the 30s window.
const STDERR_CAP_BYTES = 1 << 20 // 1 MB
let stderrCapture = ''
proc.stderr?.on('data', (chunk: Buffer) => {
if (stderrCapture.length < STDERR_CAP_BYTES) {
stderrCapture += chunk.toString()
}
})
proc.on('error', (err: Error) => {
// ChildProcess emits close after error, including spawn failure.
// Settling here would release the manual job while the child is alive.
failure ??= new FfmpegError(
'plugin.ffmpeg.spawn_error',
`ffmpeg spawn error: ${err.message}`
)
})
proc.on('close', () => {
closed = true
clearTimeout(timer)
clearTimeout(killTimer)
input.signal?.removeEventListener('abort', abort)
if (failure) {
reject(failure)
return
}
// ffmpeg -i ... -f null - exits 1 for probe; we ignore the code.
const durationMatch = DURATION_RE.exec(stderrCapture)
const durationMs = durationMatch
? parseHmsToMs(durationMatch[1], durationMatch[2], durationMatch[3])
: 0
const formatMatch = /Input #0,\s+([^,]+),/.exec(stderrCapture)
const format = formatMatch ? formatMatch[1].trim() : undefined
// Parse stream lines: e.g. "Stream #0:0: Video: h264 ..."
const streams: Array<{
type: string
codec?: string
bitrate?: number
}> = []
const streamRe =
/Stream #\d+:\d+.*?:\s+(Video|Audio|Subtitle|Data):\s+(\S+)/g
let sm: RegExpExecArray | null
// biome-ignore lint/suspicious/noAssignInExpressions: idiomatic regex while-loop
while ((sm = streamRe.exec(stderrCapture)) !== null) {
streams.push({
type: sm[1].toLowerCase(),
codec: sm[2].replace(',', ''),
})
}
resolve({ durationMs, format, streams })
})
input.signal?.addEventListener('abort', abort, { once: true })
if (input.signal?.aborted) abort()
})
}
// -------------------------------------------------------------------------
// transcode
// -------------------------------------------------------------------------
transcode(opts: {
input: string
output: string
videoCodec?: string
audioCodec?: string
timeoutMs?: number
signal?: AbortSignal
expectedDurationMs?: number
}): FfmpegOpHandle<{ outputPath: string }> {
const argv = [
'-i',
opts.input,
'-c:v',
opts.videoCodec ?? 'libx264',
'-c:a',
opts.audioCodec ?? 'aac',
'-y',
opts.output,
]
return this.run({
argv,
outputPath: opts.output,
timeoutMs: opts.timeoutMs,
signal: opts.signal,
expectedDurationMs: opts.expectedDurationMs,
})
}
// -------------------------------------------------------------------------
// extractAudio
// -------------------------------------------------------------------------
extractAudio(opts: {
input: string
output: string
codec?: 'mp3' | 'aac' | 'flac' | 'wav'
timeoutMs?: number
signal?: AbortSignal
expectedDurationMs?: number
}): FfmpegOpHandle<{ outputPath: string }> {
const codecMap: Record<string, string> = {
mp3: 'libmp3lame',
aac: 'aac',
flac: 'flac',
wav: 'pcm_s16le',
}
const ffmpegCodec = codecMap[opts.codec ?? 'mp3'] ?? 'libmp3lame'
const argv = [
'-i',
opts.input,
'-vn',
'-c:a',
ffmpegCodec,
'-y',
opts.output,
]
return this.run({
argv,
outputPath: opts.output,
timeoutMs: opts.timeoutMs,
signal: opts.signal,
expectedDurationMs: opts.expectedDurationMs,
})
}
// -------------------------------------------------------------------------
// mergeStreams
// -------------------------------------------------------------------------
mergeStreams(opts: {
videoInput: string
audioInput: string
output: string
expectedDurationMs?: number
localOnly?: boolean
timeoutMs?: number
signal?: AbortSignal
}): FfmpegOpHandle<{ outputPath: string }> {
const inputOptions = opts.localOnly ? LOCAL_MEDIA_INPUT_OPTIONS : []
const argv = [
'-nostdin',
...inputOptions,
'-i',
opts.videoInput,
...inputOptions,
'-i',
opts.audioInput,
'-map',
'0:v:0',
'-map',
'1:a:0',
'-c:v',
'copy',
'-c:a',
'copy',
'-y',
opts.output,
]
return this.run({
argv,
outputPath: opts.output,
timeoutMs: opts.timeoutMs,
signal: opts.signal,
expectedDurationMs: opts.expectedDurationMs,
})
}
// -------------------------------------------------------------------------
// generateThumbnail
// -------------------------------------------------------------------------
generateThumbnail(opts: {
input: string
output: string
timestampSec?: number
width?: number
height?: number
timeoutMs?: number
signal?: AbortSignal
}): FfmpegOpHandle<{ outputPath: string }> {
const sizeArgs: string[] =
opts.width !== undefined || opts.height !== undefined
? ['-vf', `scale=${opts.width ?? -1}:${opts.height ?? -1}`]
: []
const argv = [
'-ss',
String(opts.timestampSec ?? 1),
'-i',
opts.input,
'-frames:v',
'1',
...sizeArgs,
'-y',
opts.output,
]
return this.run({
argv,
outputPath: opts.output,
timeoutMs: opts.timeoutMs,
signal: opts.signal,
})
}
}