Files
hyperframes/packages/engine/src/services/chunkEncoder.ts
T
PaprikaChenandClaude Opus 5.5 1a9fb8acb6 feat: opt-in 4:4:4 chroma for SDR MP4 masters (#5820)
* feat(engine): decouple transparent background from png capture format

PNG capture used to imply a cleared page background. A new
CaptureOptions.transparentBackground lets lossless opaque PNG capture
(4:4:4 MP4 output) keep the page background. Absent, it still follows
format === "png", so alpha output and motion blur are unchanged.

Opaque PNG skips drawElement, whose verification and worker-encode
paths are JPEG-only.

Refs #5555

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

* feat(engine): add 4:4:4 chroma option to getEncoderPreset

getEncoderPreset takes an optional chromaSubsampling ("420" by
default). "444" returns yuv444p for SDR MP4, so libx264 encodes the
High 4:4:4 Predictive profile and odd sizes need no even padding.
WebM, MOV and HDR presets ignore it. The ChromaSubsampling type is
exported for the producer.

Refs #5555

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

* feat(producer): chromaSubsampling render option with lossless png capture

RenderConfig.chromaSubsampling ("420" by default) opts an SDR MP4
render into 4:4:4. "444" encodes libx264 yuv444p and captures every
frame as opaque PNG: Chrome's quality-100 JPEG is already 4:2:0 on
beginFrame and screenshot capture, and drawElement can fall back to
screenshot mid-render, so PNG is the only capture that keeps the
colour. drawElement is turned off for these renders.

The probe and main capture options share resolveCaptureSurface, so
they cannot disagree on format, quality or background.

Formats other than mp4, GPU encoding and HDR output are rejected
before any work starts, auto-detected HDR sources fail before capture,
and distributed requests refuse 444. The default render is unchanged.

Refs #5555

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

* feat(producer,studio-server): accept chromaSubsampling on render routes

The shared parseEncoderOptions validates chromaSubsampling and answers
400 for "444" with a non-mp4 format, gpu, or force-hdr, so a request
that would come back 4:2:0 never starts a render. The Studio render
route, both Studio adapters and the producer HTTP server forward it.
The producer server also refuses "444" with outputDynamicRange "hdr",
which parseEncoderOptions cannot see.

No Studio UI control; the option is route-level like crf and hdrMode.

Refs #5555

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

* feat(cli): add --chroma-subsampling flag

`hyperframes render --chroma-subsampling 444` opts an SDR MP4 render
into full-resolution chroma (yuv444p with lossless PNG capture). The
default stays 420. The plan rejects 444 with a non-mp4 format, --gpu
or --hdr before anything renders, with a usage error that names the
conflicting flag.

The value reaches the local render request and, only when it is 444,
the Docker argv, so default Docker invocations are unchanged.

Refs #5555

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

* docs: document 4:4:4 chroma subsampling

Add a "4:4:4 masters" section to the rendering guide: when to use
--chroma-subsampling 444, why it captures PNG, the measured chroma gain
(large for text and UI, none for footage and gradients), its limits,
and a player compatibility table to be filled in from testing.

Document the flag in the CLI reference, the built-in rendering docs and
the hyperframes-cli skill reference (with the regenerated skills
manifest), and the chromaSubsampling option in the producer docs.

Refs #5555

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

* docs: add 4:4:4 player compatibility results

Fill the 4:4:4 compatibility table from testing H.264 High 4:4:4
Predictive output. Chrome 155, Edge 155, VLC 3.0, Safari on iOS 26.6
and Safari 26.6 on macOS play it, and so does AVFoundation on macOS
26.6, the framework QuickTime Player plays through. Firefox 157 on
Windows and both Windows media players do not.

Refs #5555

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

* docs: note the measured render cost of 4:4:4 output

Replace the vague "slower capture" note with measured numbers: a text
and UI composition rendered in about twice the default time, full-frame
footage in about three and a half times, because PNG encoding cost grows
with image detail.

Refs #5555

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

* fix(producer): reject chromaSubsampling 444 in distributed render config

Distributed configs have no chroma field and validateDistributedRenderConfig
ignored unknown keys, so a JS caller passing chromaSubsampling: "444" to the
Lambda or Cloud Run SDK got a 4:2:0 file with no error. Reject it, and make
the rendering guide say so precisely.

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

* test(producer): check a 444 render reaches the encoder as yuv444p

Every helper had tests, but nothing checked the orchestrator passes
chromaSubsampling through, so dropping it from the encoder preset or capture
surface would turn 444 renders back into 4:2:0 with all tests green. Render a
small fixture with "444" and with the default and check pix_fmt with ffprobe.

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

* refactor(producer): move the 444 drawElement gate into a helper

Keeps runCompileStage under the fallow complexity threshold.

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

* chore: keep comment share at or below the merge-base

comment-ratchet failed on 11 files this PR touched. Keep the 4:4:4
rationale once in chromaSubsampling.ts, move the distributed-render
reason into its error message, and cut the rest.

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

* test(producer): check a 444 render captures full-resolution chroma

The encoder check alone passes when chromaSubsampling is dropped from the
capture surface: frames are captured as JPEG and encoded yuv444p with
4:2:0 colour. Put a red/blue edge at an odd x, inside a 4:2:0 chroma
pair, and require the two pixels to differ in Cb.

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

* chore(producer): trim the chromaSubsampling.ts header to the package comment share

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

* fix: finish switching to capturesAlpha from #6262

The merge that adopted main's transparent / capturesAlpha left these files
uncommitted, so resolveCaptureSurface still returned transparentBackground.

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

* refactor(engine): use transparent / capturesAlpha from #6262

main added CaptureOptions.transparent and capturesAlpha (#6262), which do
what this PR's transparentBackground did. Use them, keep the PNG check in
drawElementWorkerEncodeEligible, and re-pin test-classification.mjs and
the skills manifest against current main.

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

* chore(producer): cut the 4:4:4 comment blocks to one to three lines

The reasoning lives in the PR description with the measurements.

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

* refactor: reconcile 4:4:4 chroma with latest main

Keep main's video-layer capture overrides, template entry resolution,
ProRes profile parsing and blur-differential tests alongside the chroma
option, and fold the encoder sub-parsers into one loop.

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

* chore: keep main's compile-stage tests and regenerate the skills manifest

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

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 00:20:55 +00:00

1153 lines
42 KiB
TypeScript
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
// fallow-ignore-file code-duplication complexity
/**
* Chunk Encoder Service
*
* Encodes captured frames into video using FFmpeg.
* Supports CPU (libx264) and GPU encoding.
*/
import { frameSequencePath } from "./extractedFrameIndex.js";
import {
closeSync,
copyFileSync,
existsSync,
ftruncateSync,
mkdirSync,
openSync,
readFileSync,
readdirSync,
statSync,
writeFileSync,
writeSync,
} from "fs";
import { join, dirname, extname, resolve } from "path";
import { DEFAULT_CONFIG, type EngineConfig } from "../config.js";
import {
type GpuEncoder,
getCachedGpuEncoder,
getCachedNvencPresets,
getGpuEncoderName,
buildVideoToolboxRateControlArgs,
mapPresetForGpuEncoder,
} from "../utils/gpuEncoder.js";
import { type HdrTransfer, getHdrEncoderColorParams, hdrFrameTagsFilter } from "../utils/hdr.js";
import { withEvenDimensionPad } from "../utils/evenDimensions.js";
import {
SDR_CAPTURE_TO_BT709_FILTER,
SDR_RGB_TO_TAGGED_BT709_FILTER,
} from "../utils/sdrCaptureColor.js";
import {
describeFfmpegFailure,
ffmpegStatsReader,
formatFfmpegError,
isExternalFfmpegInterruption,
runFfmpeg,
} from "../utils/runFfmpeg.js";
import { extractAudioMetadata } from "../utils/ffprobe.js";
import { type Fps, fpsToFfmpegArg, fpsToNumber } from "@hyperframes/core";
import type { EncoderOptions, EncodeResult, MuxResult } from "./chunkEncoder.types.js";
import { appendVp9CpuUsedArg } from "./vp9Options.js";
import { appendSoftwareEncoderThreadsArg } from "./softwareEncoderThreads.js";
import { appendRenderProvenanceArgs } from "../utils/renderProvenance.js";
import { createStagingDir } from "@hyperframes/core/atomic-file";
export type { EncoderOptions, EncodeResult, MuxResult } from "./chunkEncoder.types.js";
export const ENCODER_PRESETS = {
draft: { preset: "ultrafast", quality: 28, codec: "h264" as const },
standard: { preset: "medium", quality: 18, codec: "h264" as const },
high: { preset: "fast", quality: 15, codec: "h264" as const },
};
export type ChromaSubsampling = "420" | "444";
export interface EncoderPreset {
preset: string;
quality: number;
codec: "h264" | "h265" | "vp9" | "prores";
pixelFormat: string;
hdr?: { transfer: HdrTransfer };
}
function appendEncodeTimeoutMessage(error: string, timedOut: boolean, timeoutMs: number): string {
if (!timedOut) return error;
return (
`${error}\nFFmpeg killed after writing no new frame for ffmpegEncodeTimeout (${timeoutMs} ms). ` +
"An encode that is still writing frames is never stopped; if this encoder legitimately " +
"pauses longer between frames, raise FFMPEG_ENCODE_TIMEOUT_MS (ms)."
);
}
function isAacSidecar(audioPath: string): boolean {
return extname(audioPath).toLowerCase() === ".aac";
}
const KNOWN_NON_AAC_AUDIO_EXTENSIONS = new Set([
".flac",
".mp3",
".oga",
".ogg",
".opus",
".wav",
".webm",
]);
export interface MuxVideoWithAudioOptions extends Partial<
Pick<EngineConfig, "ffmpegProcessTimeout">
> {
/**
* Codec of the sidecar audio when the caller already knows it. HyperFrames
* render paths pass the mixed AAC sidecar by contract, so muxing should not
* depend on the file extension alone.
*/
audioCodec?: "aac";
/** Replaces `-i <videoPath>` (which is then unused), e.g. with a concat-demuxer input. */
videoInputArgs?: readonly string[];
/**
* @deprecated No longer used. `-avoid_negative_ts` is never passed for
* mp4/mov muxing (ffmpeg's `auto` default already resolves to `disabled`
* for those containers), so the AAC priming edit list is preserved
* unconditionally and this flag has no effect. See issue #3487. Kept for
* source compatibility; it will be removed in a future major.
*/
preserveAudioPrimingEditList?: boolean;
}
async function shouldCopyAacSidecar(
audioPath: string,
options: MuxVideoWithAudioOptions | undefined,
) {
if (options?.audioCodec === "aac" || isAacSidecar(audioPath)) return true;
const audioExtension = extname(audioPath).toLowerCase();
if (KNOWN_NON_AAC_AUDIO_EXTENSIONS.has(audioExtension)) return false;
try {
const metadata = await extractAudioMetadata(audioPath);
return metadata.audioCodec === "aac";
} catch {
// Preserve the pre-existing fallback for invalid or unprobeable sidecars:
// let the final ffmpeg transcode path surface the actionable mux error.
return false;
}
}
/** ProRes profile names in the order users are told about them. */
export const PRORES_PROFILE_NAMES = ["4444", "hq", "422", "lt", "proxy"] as const;
export type ProresProfile = (typeof PRORES_PROFILE_NAMES)[number];
/** The one table for `-profile:v` and pixel format; all but 4444 are 4:2:2 without alpha. */
export const PRORES_PROFILES: Record<
ProresProfile,
{ profile: string; pixelFormat: string; alpha: boolean }
> = {
"4444": { profile: "4444", pixelFormat: "yuva444p10le", alpha: true },
hq: { profile: "3", pixelFormat: "yuv422p10le", alpha: false },
"422": { profile: "2", pixelFormat: "yuv422p10le", alpha: false },
lt: { profile: "1", pixelFormat: "yuv422p10le", alpha: false },
proxy: { profile: "0", pixelFormat: "yuv422p10le", alpha: false },
};
export function isProresProfile(value: unknown): value is ProresProfile {
return typeof value === "string" && (PRORES_PROFILE_NAMES as readonly string[]).includes(value);
}
/**
* Get encoder preset for a given quality and output format.
* WebM uses VP9 with alpha-capable pixel format; MP4 uses h264 (or h265 for HDR);
* MOV uses ProRes 4444 with alpha for editor-compatible transparency, or a 422 profile without alpha.
*/
export function getEncoderPreset(
quality: "draft" | "standard" | "high",
format: "mp4" | "webm" | "mov" = "mp4",
hdr?: { transfer: HdrTransfer },
proresProfile: ProresProfile = "4444",
chromaSubsampling: ChromaSubsampling = "420",
): EncoderPreset {
const base = ENCODER_PRESETS[quality];
if (format === "webm") {
return {
preset: base.preset === "ultrafast" ? "realtime" : "good",
quality: base.quality,
codec: "vp9",
pixelFormat: "yuva420p",
};
}
if (format === "mov") {
const { profile, pixelFormat } = PRORES_PROFILES[proresProfile];
return { preset: profile, quality: base.quality, codec: "prores", pixelFormat };
}
if (hdr) {
return {
preset: base.preset === "ultrafast" ? "fast" : base.preset,
quality: base.quality,
codec: "h265",
pixelFormat: "yuv420p10le",
hdr,
};
}
return { ...base, pixelFormat: chromaSubsampling === "444" ? "yuv444p" : "yuv420p" };
}
// Re-export GPU utilities so existing consumers that import from chunkEncoder still work.
export { detectGpuEncoder, getCachedGpuEncoder, type GpuEncoder } from "../utils/gpuEncoder.js";
/** The `lockGopForChunkConcat` / `gopSize` pair, shared by every encoder entry point. */
export interface LockedGopOptions {
lockGopForChunkConcat?: boolean;
gopSize?: number;
}
/**
* Integer GOP length, or `null` when no lock was requested. Throws on a lock
* with an invalid size — a silent fallback ships open-GOP output that only
* surfaces later as a broken playback seam.
*/
export function resolveLockedGopSize(options: LockedGopOptions): number | null {
if (options.lockGopForChunkConcat !== true) return null;
if (
typeof options.gopSize !== "number" ||
!Number.isFinite(options.gopSize) ||
options.gopSize <= 0
) {
throw new Error(
`[chunkEncoder] lockGopForChunkConcat=true requires a positive integer gopSize (received ${String(options.gopSize)})`,
);
}
return Math.floor(options.gopSize);
}
/**
* Closed-GOP / forced-keyframe args for libx264 / libx265, so an orchestrator
* can concat chunks with `-c copy` or cut the stream into segments with
* `-f hls -c copy`. Without them the encoder picks its own keyframes and a
* boundary may not land on an independently decodable IDR.
*/
export function appendLockedGopArgs(args: string[], gopSize: number): void {
args.push(
"-g",
String(gopSize),
"-keyint_min",
String(gopSize),
"-sc_threshold",
"0",
"-force_key_frames",
`expr:eq(mod(n,${gopSize}),0)`,
);
}
/**
* The `-x264-params` / `-x265-params` fragment that bakes the IDR cadence into
* the encoder itself — `-force_key_frames` alone still permits mini-GOPs with
* open-GOP references. `repeat-headers=1` keeps each boundary self-contained.
*/
export function lockedGopCodecParams(codec: "h264" | "h265", gopSize: number): string {
const shared = "scenecut=0:open-gop=0:repeat-headers=1";
return codec === "h264" ? shared : `keyint=${gopSize}:min-keyint=${gopSize}:${shared}`;
}
/** Frames per keyframe interval: the nearest whole frame, never below one. */
export function keyframeIntervalToGopSize(fps: Fps, seconds: number): number {
return Math.max(1, Math.round(fpsToNumber(fps) * seconds));
}
const BITRATE_PATTERN = /^(\d+(?:\.\d+)?)([kKmMgG]?)$/;
function bitrateToBitsPerSecond(value: string): number {
const match = BITRATE_PATTERN.exec(value);
if (!match) throw new Error(`[chunkEncoder] invalid bitrate ${JSON.stringify(value)}`);
const unit = match[2]!.toLowerCase();
const scale = { g: 1_000_000_000, m: 1_000_000, k: 1_000 }[unit] ?? 1;
return Number(match[1]) * scale;
}
/** `-maxrate` / `-bufsize` for the VBV cap, written once for both arg builders. Buffer defaults to 2x. */
export function appendRateCapArgs(
args: string[],
options: { codec?: string; maxBitrate?: string; bufferSize?: string },
): void {
const { maxBitrate, bufferSize } = options;
if (maxBitrate === undefined) {
if (bufferSize !== undefined) throw new Error("[chunkEncoder] bufferSize requires maxBitrate");
return;
}
const codec = options.codec ?? "h264";
if (codec !== "h264" && codec !== "h265") {
throw new Error(`[chunkEncoder] maxBitrate is not supported for codec ${codec}`);
}
const cap = bitrateToBitsPerSecond(maxBitrate);
const buffer = bufferSize !== undefined ? bitrateToBitsPerSecond(bufferSize) : cap * 2;
if (cap <= 0 || buffer <= 0) {
throw new Error("[chunkEncoder] maxBitrate and bufferSize must be positive");
}
args.push("-maxrate", String(Math.round(cap)), "-bufsize", String(Math.round(buffer)));
}
export function buildEncoderArgs(
options: EncoderOptions,
inputArgs: string[],
outputPath: string,
gpuEncoder: GpuEncoder = null,
nvencPresets?: ReadonlySet<string>,
): string[] {
const {
fps,
codec = "h264",
preset = "medium",
quality = 23,
bitrate,
pixelFormat = "yuv420p",
vp9CpuUsed,
useGpu = false,
} = options;
// libx264 cannot encode HDR. If a caller passes hdr with codec=h264 we'd
// produce a "half-HDR" file (BT.2020 container tags but a BT.709 VUI block
// inside the bitstream) which confuses HDR-aware players. Strip hdr and
// log a warning so the caller picks h265 (the SDR-tagged output is honest).
if (options.hdr && codec === "h264") {
console.warn(
"[chunkEncoder] HDR is not supported with codec=h264 (libx264 has no HDR support). " +
"Stripping HDR metadata and tagging output as SDR/BT.709. Use codec=h265 for HDR output.",
);
options = { ...options, hdr: undefined };
}
// Without -xerror, ffmpeg ends the video at the first frame file it cannot read and still exits 0.
const args: string[] = ["-xerror", ...inputArgs, "-r", fpsToFfmpegArg(fps)];
const shouldUseGpu = useGpu && gpuEncoder !== null;
appendRateCapArgs(args, options);
if (codec === "h264" || codec === "h265") {
if (shouldUseGpu) {
const encoderName = getGpuEncoderName(gpuEncoder, codec);
args.push("-c:v", encoderName);
switch (gpuEncoder) {
case "nvenc":
args.push("-preset", mapPresetForGpuEncoder("nvenc", preset, nvencPresets));
if (bitrate) args.push("-b:v", bitrate);
else args.push("-cq", String(quality));
break;
case "videotoolbox":
args.push(
...buildVideoToolboxRateControlArgs({
bitrate,
width: options.width,
height: options.height,
fps: fpsToNumber(fps),
quality,
}),
);
break;
case "vaapi":
args.unshift("-vaapi_device", "/dev/dri/renderD128");
args.push("-vf", "format=nv12,hwupload");
if (bitrate) args.push("-b:v", bitrate);
else args.push("-qp", String(quality));
break;
case "qsv":
args.push("-preset", mapPresetForGpuEncoder("qsv", preset));
if (bitrate) args.push("-b:v", bitrate);
else args.push("-global_quality", String(quality));
break;
case "amf":
if (bitrate) args.push("-b:v", bitrate);
else args.push("-rc", "cqp", "-qp_i", String(quality), "-qp_p", String(quality));
break;
}
// Same B-frame story as the SW branch below — nvenc/amf emit B-frames
// by default (qsv via b_strategy, vaapi too), and the negative-DTS
// freeze hits the same downstream players. The unconditional
// `-avoid_negative_ts make_zero` near the bottom of this function
// covers the mux level, but we belt-and-suspenders the encoder too
// so even tools that consume the chunk file directly (without going
// through our mux step) play correctly. videotoolbox doesn't accept
// `-bf` so it's skipped — videotoolbox h264 also doesn't emit
// negative DTS in practice on macOS Sonoma+.
if (
codec === "h264" &&
(gpuEncoder === "nvenc" ||
gpuEncoder === "qsv" ||
gpuEncoder === "vaapi" ||
gpuEncoder === "amf")
) {
args.push("-bf", "0");
if (gpuEncoder === "qsv") {
args.push("-b_strategy", "0");
}
}
} else {
const encoderName = codec === "h264" ? "libx264" : "libx265";
args.push("-c:v", encoderName, "-preset", preset);
appendSoftwareEncoderThreadsArg(args, encoderName);
if (bitrate) args.push("-b:v", bitrate);
else args.push("-crf", String(quality));
// Closed-GOP / forced-keyframe args so an external orchestrator can
// ffmpeg-concat chunk files with `-c copy`. See `appendLockedGopArgs`.
const gop = resolveLockedGopSize(options);
const lockGop = gop !== null;
if (gop !== null) appendLockedGopArgs(args, gop);
// Disable B-frames. Standard h264 with B-frames produces negative DTS
// at the start of the stream (the first B-frame's decode order is
// "before" the first I-frame's presentation time). VS Code's video
// preview, several browser <video> pipelines, and some HW decoders
// freeze on the first frame when DTS is negative, so audio plays alone.
// -bf 0 makes PTS == DTS at every frame, eliminating the issue at the
// source. Quality cost is ~5–10% larger files at the same CRF — a
// worthwhile trade for "the file plays everywhere".
//
// Also emit `-bf 0` for h265 when closed-GOP is locked: chunked
// concat-copy of h265 with B-frames hits the same negative-DTS hazard
// at every chunk boundary, even though single-stream h265 normally
// tolerates B-frames fine.
if (codec === "h264" || (codec === "h265" && lockGop)) {
args.push("-bf", "0");
}
// Encoder-specific params: anti-banding + color space tagging.
// aq-mode=3 redistributes bits to dark flat areas (gradients).
// For HDR x265 paths we additionally embed BT.2020 + transfer + HDR static
// mastering metadata via x265-params; libx264 only carries BT.709 tags
// since HDR through H.264 is not supported by this encoder path.
//
// When closed-GOP is locked we additionally bake the keyint/scenecut
// controls into the codec param string so libx264's slice-type decisions
// and libx265's rate-control respect the IDR cadence end-to-end (without
// these, ffmpeg's `-force_key_frames` is honored but the underlying
// encoder may still insert mini-GOPs with open-GOP references that
// break concat-copy on some decoders). `repeat-headers=1` writes SPS/PPS
// at every keyframe so each chunk file is self-contained.
const xParamsFlag = codec === "h264" ? "-x264-params" : "-x265-params";
const colorParams =
codec === "h265" && options.hdr
? getHdrEncoderColorParams(options.hdr.transfer).x265ColorParams
: "colorprim=bt709:transfer=bt709:colormatrix=bt709";
const gopParams = gop !== null ? lockedGopCodecParams(codec, gop) : "";
const joinParams = (...parts: string[]): string =>
parts.filter((p) => p.length > 0).join(":");
if (preset === "ultrafast") {
args.push(xParamsFlag, joinParams("aq-mode=3", colorParams, gopParams));
} else {
args.push(
xParamsFlag,
joinParams("aq-mode=3", "aq-strength=0.8", "deblock=1,1", colorParams, gopParams),
);
}
}
// Apple devices require hvc1 tag for HEVC playback (default hev1 won't open in QuickTime)
if (codec === "h265") {
args.push("-tag:v", "hvc1");
}
} else if (codec === "vp9") {
args.push("-c:v", "libvpx-vp9", "-b:v", bitrate || "0", "-crf", String(quality));
args.push("-deadline", preset === "ultrafast" ? "realtime" : "good");
args.push("-row-mt", "1");
appendVp9CpuUsedArg(args, vp9CpuUsed);
// `-auto-alt-ref 0` is mandatory for chunk concat-copy: libvpx-vp9's
// alt-ref frames can reference frames in either direction inside a
// GOP, so a chunk-boundary frame is not guaranteed to be the first
// displayable reference when alt-ref is on. The shared `vp9CpuUsed`
// option pins speed/quality against libvpx-vp9 default drift across
// versions for both chunked and streaming WebM encodes.
const vp9Gop = resolveLockedGopSize(options);
const lockGopVp9 = vp9Gop !== null;
if (vp9Gop !== null) {
args.push("-g", String(vp9Gop), "-keyint_min", String(vp9Gop), "-auto-alt-ref", "0");
}
if (pixelFormat === "yuva420p") {
// Alpha + alt-ref is unsupported by libvpx-vp9. The closed-GOP
// branch above already emits `-auto-alt-ref 0`, so skip the
// duplicate push.
if (!lockGopVp9) {
args.push("-auto-alt-ref", "0");
}
args.push("-metadata:s:v:0", "alpha_mode=1");
}
} else if (codec === "prores") {
args.push("-c:v", "prores_ks", "-profile:v", preset, "-vendor", "apl0");
args.push("-vf", SDR_RGB_TO_TAGGED_BT709_FILTER);
args.push("-pix_fmt", pixelFormat);
appendRenderProvenanceArgs(args, outputPath);
return [...args, "-y", outputPath];
}
// Color space metadata — tags the output so players interpret colors correctly.
//
// Default (no options.hdr): Chrome screenshots are sRGB/bt709 pixels and
// we tag them truthfully as bt709. Tagging as bt2020 when pixels are bt709
// causes browsers to apply the wrong color transform, producing visible
// orange/warm shifts.
//
// HDR (options.hdr provided): the caller asserts the input pixels are
// already in the BT.2020 color space (e.g. extracted HDR video frames or a
// pre-tagged source). We tag the output as BT.2020 + the corresponding
// transfer (smpte2084 for PQ, arib-std-b67 for HLG). HDR static mastering
// metadata (master-display, max-cll) is embedded only in the SW libx265
// path above; GPU H.265 + HDR carries the color tags but not the static
// metadata, which is acceptable for previews but not for HDR-aware delivery.
if (codec === "h264" || codec === "h265") {
if (options.hdr) {
const transferTag = options.hdr.transfer === "pq" ? "smpte2084" : "arib-std-b67";
args.push(
"-colorspace:v",
"bt2020nc",
"-color_primaries:v",
"bt2020",
"-color_trc:v",
transferTag,
"-color_range",
"tv",
);
} else {
args.push(
"-colorspace:v",
"bt709",
"-color_primaries:v",
"bt709",
"-color_trc:v",
"bt709",
"-color_range",
"tv",
);
}
// Range conversion: Chrome's full-range capture → limited/TV range; SDR also
// converts to the BT.709 matrix it is tagged with.
const hdrTags = options.hdr ? hdrFrameTagsFilter(options.hdr.transfer) : undefined;
const sdrFilter = options.hdr ? undefined : SDR_CAPTURE_TO_BT709_FILTER;
const captureFilter = sdrFilter ?? `scale=in_range=pc:out_range=tv,${hdrTags}`;
if (gpuEncoder === "vaapi") {
// vaapi already runs `format=nv12,hwupload`; the nv12 conversion aligns
// odd dimensions before upload, so only prepend the colour conversion.
const vfIdx = args.indexOf("-vf");
if (vfIdx !== -1) {
args[vfIdx + 1] = `${captureFilter},${args[vfIdx + 1]}`;
}
} else if (shouldUseGpu) {
// nvenc/videotoolbox/qsv/amf feed software frames straight to the HW
// encoder. They hit the same "height not divisible by 2" abort as
// libx264 on an odd-sized 4:2:0 canvas, so pad odd dimensions up to even
// on the software side before the encode.
const vf = withEvenDimensionPad(
sdrFilter ?? hdrTags ?? "",
pixelFormat,
options.width,
options.height,
);
if (vf) args.push("-vf", vf);
} else {
// The scale filter handles both 8-bit and 10-bit correctly. Pad odd
// dimensions up to even so libx264/libx265 (4:2:0) don't abort with
// "height not divisible by 2" on an odd-sized composition canvas.
args.push(
"-vf",
withEvenDimensionPad(captureFilter, pixelFormat, options.width, options.height),
);
}
// Fixed timescale for consistent A/V timing across platforms.
args.push("-video_track_timescale", "90000");
}
if (gpuEncoder !== "vaapi") {
args.push("-pix_fmt", pixelFormat);
}
args.push("-avoid_negative_ts", "make_zero");
appendRenderProvenanceArgs(args, outputPath);
args.push("-y", outputPath);
return args;
}
const framesReader = (onFrames?: (frames: number) => void) =>
onFrames && ffmpegStatsReader(({ frames }) => frames !== undefined && onFrames(frames));
/** ffmpeg's frame read error, which the encoder summary pushes out of the stderr tail, and where it stopped. */
function frameReadFailure(
stderr: string,
framePattern: string,
startNumber: number,
framesRead: number,
frameCount: number,
): string {
const lines = stderr.match(/^.*(?:Error during demuxing|Could not open file).*$/gm) ?? [];
const readError = [...new Set(lines.map((line) => line.trim()))].join("; ");
if (!readError) return "";
const name = framePattern.replace(/%0(\d+)d/, (_, width: string) =>
String(startNumber + framesRead).padStart(Number(width), "0"),
);
const at = framesRead < frameCount ? ` at ${name} (${framesRead} of ${frameCount} read)` : "";
return `[FFmpeg] could not read a frame${at}: ${readError}\n`;
}
const secondsReader = (onSeconds?: (seconds: number) => void) =>
onSeconds && ffmpegStatsReader(({ seconds }) => seconds !== undefined && onSeconds(seconds));
export async function encodeFramesFromDir(
framesDir: string,
framePattern: string,
outputPath: string,
options: EncoderOptions,
signal?: AbortSignal,
config?: Partial<Pick<EngineConfig, "ffmpegEncodeTimeout">>,
onFramesEncoded?: (frames: number) => void,
): Promise<EncodeResult> {
const startTime = Date.now();
const outputDir = dirname(outputPath);
if (!existsSync(outputDir)) mkdirSync(outputDir, { recursive: true });
const files = readdirSync(framesDir).filter((f) => f.match(/\.(jpg|jpeg|png)$/i));
const frameCount = files.length;
if (frameCount === 0) {
return {
success: false,
outputPath,
durationMs: Date.now() - startTime,
framesEncoded: 0,
fileSize: 0,
error: "[FFmpeg] No frame files found in directory",
};
}
let gpuEncoder: GpuEncoder = null;
if (options.useGpu) {
gpuEncoder = await getCachedGpuEncoder();
}
const inputPath = frameSequencePath(framesDir, framePattern);
const inputArgs = ["-framerate", fpsToFfmpegArg(options.fps), "-i", inputPath];
const nvencPresets = gpuEncoder === "nvenc" ? await getCachedNvencPresets() : undefined;
const args = buildEncoderArgs(options, inputArgs, outputPath, gpuEncoder, nvencPresets);
const encodeTimeout = config?.ffmpegEncodeTimeout ?? DEFAULT_CONFIG.ffmpegEncodeTimeout;
let framesRead = 0;
const result = await runFfmpeg(args, {
signal,
timeout: encodeTimeout,
onStderr: framesReader((frames) => {
framesRead = frames;
onFramesEncoded?.(frames);
}),
});
if (result.terminationReason === "abort") {
return {
success: false,
outputPath,
durationMs: result.durationMs,
framesEncoded: 0,
fileSize: 0,
error: "FFmpeg encode cancelled",
};
}
if (!result.success) {
return {
success: false,
outputPath,
durationMs: result.durationMs,
framesEncoded: 0,
fileSize: 0,
error: appendEncodeTimeoutMessage(
frameReadFailure(result.stderr, framePattern, 0, framesRead, frameCount) +
formatFfmpegError(result.exitCode, result.stderr),
result.terminationReason === "inactivity",
encodeTimeout,
),
failureReason: isExternalFfmpegInterruption(result) ? "external_interruption" : undefined,
};
}
const fileSize = existsSync(outputPath) ? statSync(outputPath).size : 0;
return {
success: true,
outputPath,
durationMs: Date.now() - startTime,
framesEncoded: frameCount,
fileSize,
};
}
export function buildConcatArgs(concatListPath: string, outputPath: string): string[] {
const args = ["-f", "concat", "-safe", "0", "-i", concatListPath, "-c", "copy"];
// The concat demuxer does not carry per-input container metadata into the
// output, so provenance is re-asserted on the concatenated file.
appendRenderProvenanceArgs(args, outputPath);
args.push("-y", outputPath);
return args;
}
/**
* Sequence rather than a timestamp: two lists written in the same millisecond
* into one directory would otherwise collide, and a concat that reads another
* render's list produces a silently wrong video rather than an error.
*/
let concatListSeq = 0;
function writeConcatList(dir: string, inputPaths: readonly string[]): string {
concatListSeq += 1;
const listPath = join(dir, `concat-list-${process.pid}-${concatListSeq}.txt`);
const body = inputPaths.map((p) => `file '${resolve(p).replace(/'/g, "'\\''")}'`).join("\n");
writeFileSync(listPath, body, "utf-8");
return listPath;
}
/**
* Stream-copy `inputPaths` (closed-GOP, same codec/params) into one file.
* Used by the in-process chunked encode and by segmented capture.
*
* `externalInterruption` distinguishes an ffmpeg killed from outside (SIGTERM
* / SIGKILL from a supervisor or OOM killer) from a genuine encode error;
* callers map it to a retryable failure reason.
*/
export async function concatVideoFiles(
inputPaths: readonly string[],
outputPath: string,
signal?: AbortSignal,
config?: Partial<Pick<EngineConfig, "ffmpegEncodeTimeout">>,
): Promise<{ success: true } | { success: false; error: string; externalInterruption: boolean }> {
const [firstInput] = inputPaths;
if (firstInput === undefined) {
return { success: false, error: "concatVideoFiles: no inputs", externalInterruption: false };
}
mkdirSync(dirname(outputPath), { recursive: true });
// The list lives with the inputs, not with the output: concurrent encodes
// get their own chunk directory but can share an output directory.
// The list is left on disk deliberately: it is removed with the work dir,
// and `--debug` keeps both so a bad concat can be reproduced from its list.
const listPath = writeConcatList(dirname(firstInput), inputPaths);
const encodeTimeout = config?.ffmpegEncodeTimeout ?? DEFAULT_CONFIG.ffmpegEncodeTimeout;
const result = await runFfmpeg(buildConcatArgs(listPath, outputPath), {
signal,
timeout: encodeTimeout,
});
if (result.success) return { success: true };
return {
success: false,
error: appendEncodeTimeoutMessage(
`Chunk concat failed: ${result.stderr.slice(-400)}`,
result.terminationReason === "inactivity",
encodeTimeout,
),
externalInterruption: isExternalFfmpegInterruption(result),
};
}
export async function encodeFramesChunkedConcat(
framesDir: string,
framePattern: string,
outputPath: string,
options: EncoderOptions,
chunkSizeFrames: number,
signal?: AbortSignal,
config?: Partial<Pick<EngineConfig, "ffmpegEncodeTimeout">>,
onFramesEncoded?: (frames: number) => void,
): Promise<EncodeResult> {
const start = Date.now();
const files = readdirSync(framesDir)
.filter((f) => f.match(/\.(jpg|jpeg|png)$/i))
.sort();
if (files.length === 0) {
return {
success: false,
outputPath,
durationMs: Date.now() - start,
framesEncoded: 0,
fileSize: 0,
error: "[FFmpeg] No frame files found in directory",
};
}
const chunkSize = Math.max(30, Math.floor(chunkSizeFrames));
const chunkCount = Math.ceil(files.length / chunkSize);
mkdirSync(dirname(outputPath), { recursive: true });
// Keep intermediates under the caller-owned output directory for its existing
// cleanup/debug policy, but never reuse another invocation's chunk files.
const chunkDir = createStagingDir(dirname(outputPath), "chunk-encode-");
const chunkPaths: string[] = [];
for (let i = 0; i < chunkCount; i++) {
if (signal?.aborted) {
return {
success: false,
outputPath,
durationMs: Date.now() - start,
framesEncoded: 0,
fileSize: 0,
error: "Chunked encode cancelled",
};
}
const startNumber = i * chunkSize;
const framesInChunk = Math.min(chunkSize, files.length - startNumber);
const ext = outputPath.endsWith(".webm")
? ".webm"
: outputPath.endsWith(".mov")
? ".mov"
: ".mp4";
const chunkPath = join(chunkDir, `chunk_${String(i).padStart(4, "0")}${ext}`);
const inputPath = frameSequencePath(framesDir, framePattern);
const inputArgs = [
"-framerate",
fpsToFfmpegArg(options.fps),
"-start_number",
String(startNumber),
"-i",
inputPath,
"-frames:v",
String(framesInChunk),
];
let gpuEncoder: GpuEncoder = null;
if (options.useGpu) gpuEncoder = await getCachedGpuEncoder();
const nvencPresets = gpuEncoder === "nvenc" ? await getCachedNvencPresets() : undefined;
const args = buildEncoderArgs(options, inputArgs, chunkPath, gpuEncoder, nvencPresets);
const encodeTimeout = config?.ffmpegEncodeTimeout ?? DEFAULT_CONFIG.ffmpegEncodeTimeout;
let framesRead = 0;
const processResult = await runFfmpeg(args, {
signal,
timeout: encodeTimeout,
onStderr: framesReader((frames) => {
framesRead = frames;
onFramesEncoded?.(startNumber + frames);
}),
});
const chunkResult = {
success: processResult.success,
error: processResult.success
? undefined
: appendEncodeTimeoutMessage(
frameReadFailure(
processResult.stderr,
framePattern,
startNumber,
framesRead,
framesInChunk,
) + `Chunk ${i} encode failed: ${processResult.stderr.slice(-400)}`,
processResult.terminationReason === "inactivity",
encodeTimeout,
),
};
if (!chunkResult.success) {
return {
success: false,
outputPath,
durationMs: Date.now() - start,
framesEncoded: 0,
fileSize: 0,
error: chunkResult.error,
failureReason: isExternalFfmpegInterruption(processResult)
? "external_interruption"
: undefined,
};
}
chunkPaths.push(chunkPath);
}
const concatResult = await concatVideoFiles(chunkPaths, outputPath, signal, config);
if (!concatResult.success) {
return {
success: false,
outputPath,
durationMs: Date.now() - start,
framesEncoded: 0,
fileSize: 0,
error: concatResult.error,
failureReason: concatResult.externalInterruption ? "external_interruption" : undefined,
};
}
const fileSize = existsSync(outputPath) ? statSync(outputPath).size : 0;
return {
success: true,
outputPath,
durationMs: Date.now() - start,
framesEncoded: files.length,
fileSize,
};
}
export async function muxVideoWithAudio(
videoPath: string,
audioPath: string,
outputPath: string,
signal?: AbortSignal,
config?: MuxVideoWithAudioOptions,
fps?: Fps,
onSecondsWritten?: (seconds: number) => void,
): Promise<MuxResult> {
const outputDir = dirname(outputPath);
if (!existsSync(outputDir)) mkdirSync(outputDir, { recursive: true });
const outputExtension = extname(outputPath).toLowerCase();
const isWebm = outputExtension === ".webm";
const isMov = outputExtension === ".mov";
const shouldCopyAudio = isWebm ? false : await shouldCopyAacSidecar(audioPath, config);
const args = [...(config?.videoInputArgs ?? ["-i", videoPath]), "-i", audioPath, "-c:v", "copy"];
if (isWebm) {
args.push("-c:a", "libopus", "-b:a", "128k");
} else if (isMov) {
if (shouldCopyAudio) {
args.push("-c:a", "copy");
} else {
args.push("-c:a", "aac", "-b:a", "192k");
}
} else {
// processCompositionAudio (audioMixer.ts) performs the AAC encode and
// owns the single encoder-priming interval. Copying that sidecar into
// MP4 preserves the correct priming metadata; re-encoding it during mux
// creates another priming interval that ffmpeg writes as an empty leading
// video edit list, which QuickTime/Safari render as a black first frame.
if (shouldCopyAudio) {
args.push("-c:a", "copy", "-movflags", "+faststart");
} else {
args.push("-c:a", "aac", "-b:a", "192k", "-movflags", "+faststart");
}
}
// No `-avoid_negative_ts` here, in any mode. ffmpeg's default is `auto`,
// which the mp4/mov muxers (AVFMT_TS_NEGATIVE) already resolve to
// `disabled` — the correct behavior for the containers this function
// writes. Passing `make_zero` explicitly overrides that default and, on the
// dominant audio-copy path, discards the AAC priming edit list the sidecar
// encode created: the video start_time shifts forward one AAC frame
// (~21ms) and the muxer writes an empty video edit at t=0, which
// edit-list-honoring players (QuickTime/Safari) show as a black first
// frame. See issue #3487. The video-only encoder args (buildEncoderArgs)
// still pass the flag deliberately — those chunks are consumed as raw
// elementary output, not as a delivered mp4/mov.
//
// Re-assert provenance here: this stage re-muxes into the delivered
// container, and the mp4 muxer drops the encode stage's tags without the
// use_metadata_tags flag that appendRenderProvenanceArgs adds.
appendRenderProvenanceArgs(args, outputPath);
if (fps !== undefined) {
// Set the exact output framerate so the muxer doesn't PTS-average a
// fractional rational like `360000/12001` instead of `30/1` into the
// output container metadata. `-c:v copy` is retained; no re-encode.
args.push("-r", fpsToFfmpegArg(fps));
}
args.push("-y", outputPath);
const processTimeout = config?.ffmpegProcessTimeout ?? DEFAULT_CONFIG.ffmpegProcessTimeout;
const result = await runFfmpeg(args, {
signal,
timeout: processTimeout,
onStderr: secondsReader(onSecondsWritten),
});
if (signal?.aborted) {
return {
success: false,
outputPath,
durationMs: result.durationMs,
error: "FFmpeg mux cancelled",
};
}
return {
success: result.success,
outputPath,
durationMs: result.durationMs,
error: !result.success ? describeFfmpegFailure(result, processTimeout) : undefined,
failureReason: result.failureReason,
};
}
export const HLS_MASTER_PLAYLIST = "master.m3u8";
export const HLS_VIDEO_PLAYLIST = "video.m3u8";
export const HLS_AUDIO_PLAYLIST = "audio.m3u8";
/**
* Drop the standalone audio-only variant ffmpeg's `-var_stream_map` adds to
* the master playlist.
*
* With `a:0,agroup:aud` the hls muxer lists the audio rendition twice: as the
* `#EXT-X-MEDIA:TYPE=AUDIO` entry the video variant references (wanted), and
* again as its own `#EXT-X-STREAM-INF` variant with no `RESOLUTION` (not
* wanted). That is valid HLS, but a player choosing variants by bandwidth can
* pick it and play sound with no picture, and the VOD consumer asked for a
* single rendition. A variant tag without a `RESOLUTION` attribute is
* audio-only; its URI is always the following line, so both go.
*/
export function stripAudioOnlyVariants(masterPlaylist: string): string {
const lines = masterPlaylist.split("\n");
const kept: string[] = [];
for (let i = 0; i < lines.length; i++) {
const line = lines[i]!;
if (line.startsWith("#EXT-X-STREAM-INF:") && !line.includes("RESOLUTION=")) {
// ffmpeg separates variants with a blank line; drop the one before this
// variant so the master does not end up with two in a row.
if (kept.at(-1) === "") kept.pop();
i += 1;
continue;
}
kept.push(line);
}
return kept.join("\n");
}
export interface PackageHlsOptions extends Partial<Pick<EngineConfig, "ffmpegProcessTimeout">> {
/** Whole seconds, so it matches the integer `EXT-X-TARGETDURATION` ffmpeg writes. */
segmentSeconds: number;
signal?: AbortSignal;
}
/**
* Stream-copy an H.264 video (and optional AAC sidecar) into an HLS VOD
* directory: `master.m3u8`, `video.m3u8` + `video_%05d.ts`, and `audio.m3u8` +
* `audio_%05d.ts` when audio is given. `outputPath` in the result is the directory.
* The master carries exactly one `#EXT-X-STREAM-INF` variant (the video, with
* the audio attached as a rendition group); see `stripAudioOnlyVariants`.
*
* `-hls_time` cuts at the first keyframe at or after each target, so the input
* must be encoded with the GOP lock (`gopSize = segmentSeconds × fps`). The lock
* is software-encoder only; a GPU encode will not segment on time.
*/
export async function packageHls(
videoPath: string,
audioPath: string | null,
outputDir: string,
options: PackageHlsOptions,
): Promise<MuxResult> {
const { segmentSeconds, signal } = options;
if (!Number.isInteger(segmentSeconds) || segmentSeconds <= 0) {
throw new Error(
`[chunkEncoder] packageHls requires a positive integer segmentSeconds (received ${String(segmentSeconds)})`,
);
}
// `-hls_segment_filename` is a printf template and the hls muxer does not honor `%%`.
if (outputDir.includes("%")) {
throw new Error(`[chunkEncoder] packageHls outputDir must not contain "%": ${outputDir}`);
}
// ffmpeg does not create the directory for the segment pattern.
if (!existsSync(outputDir)) mkdirSync(outputDir, { recursive: true });
const hasAudio = audioPath !== null;
const args = hasAudio
? ["-i", videoPath, "-i", audioPath, "-map", "0:v:0", "-map", "1:a:0"]
: ["-i", videoPath, "-map", "0:v:0"];
args.push(
"-c",
"copy",
"-f",
"hls",
"-hls_time",
String(segmentSeconds),
"-hls_playlist_type",
"vod",
"-hls_flags",
"independent_segments",
"-hls_segment_type",
"mpegts",
"-var_stream_map",
hasAudio ? "v:0,agroup:aud,name:video a:0,agroup:aud,name:audio" : "v:0,name:video",
"-master_pl_name",
HLS_MASTER_PLAYLIST,
"-hls_segment_filename",
join(outputDir, "%v_%05d.ts"),
// Without these the mpegts muxer starts the stream at PTS 1.4 s.
"-muxdelay",
"0",
"-muxpreload",
"0",
);
// No provenance tags (MPEG-TS drops them; `-movflags` is invalid for `-f hls`)
// and no `-avoid_negative_ts`, which would drop the AAC priming (#3487).
args.push("-y", join(outputDir, "%v.m3u8"));
const processTimeout = options.ffmpegProcessTimeout ?? DEFAULT_CONFIG.ffmpegProcessTimeout;
const result = await runFfmpeg(args, { signal, timeout: processTimeout });
if (signal?.aborted) {
return {
success: false,
outputPath: outputDir,
durationMs: result.durationMs,
error: "FFmpeg HLS packaging cancelled",
};
}
if (result.success && hasAudio) {
const masterPath = join(outputDir, HLS_MASTER_PLAYLIST);
// One descriptor for the read-modify-write: re-resolving the path to write
// it back races anything else in this predictable temp dir, and `r+` with
// owner-only mode neither creates nor widens the playlist ffmpeg wrote.
// A missing one is fine — the argument-level tests stub ffmpeg.
let master: number | undefined;
try {
master = openSync(masterPath, "r+", 0o600);
} catch (error) {
if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
}
if (master !== undefined) {
try {
const stripped = stripAudioOnlyVariants(readFileSync(master, "utf-8"));
// Stripping only shortens the playlist; truncate or the tail survives.
ftruncateSync(master, 0);
writeSync(master, stripped, 0, "utf-8");
} finally {
closeSync(master);
}
}
}
return {
success: result.success,
outputPath: outputDir,
durationMs: result.durationMs,
error: !result.success ? describeFfmpegFailure(result, processTimeout) : undefined,
failureReason: result.failureReason,
};
}
export async function applyFaststart(
inputPath: string,
outputPath: string,
signal?: AbortSignal,
config?: Partial<Pick<EngineConfig, "ffmpegProcessTimeout">>,
fps?: Fps,
onSecondsWritten?: (seconds: number) => void,
): Promise<MuxResult> {
// faststart is MP4-only (moves moov atom to file start for streaming).
// WebM and MOV don't need it — skip the re-mux.
if (outputPath.endsWith(".webm") || outputPath.endsWith(".mov")) {
if (inputPath !== outputPath) copyFileSync(inputPath, outputPath);
return { success: true, outputPath, durationMs: 0 };
}
const args = ["-i", inputPath, "-c", "copy", "-movflags", "+faststart"];
appendRenderProvenanceArgs(args, outputPath);
if (fps !== undefined) {
// Set the exact output framerate so the final remux doesn't PTS-average
// a fractional rational like `360000/12001` instead of `30/1` into the
// output container metadata. `-c copy` is retained; no re-encode.
args.push("-r", fpsToFfmpegArg(fps));
}
args.push("-y", outputPath);
const processTimeout = config?.ffmpegProcessTimeout ?? DEFAULT_CONFIG.ffmpegProcessTimeout;
const result = await runFfmpeg(args, {
signal,
timeout: processTimeout,
onStderr: secondsReader(onSecondsWritten),
});
if (signal?.aborted) {
return {
success: false,
outputPath,
durationMs: result.durationMs,
error: "FFmpeg faststart cancelled",
};
}
return {
success: result.success,
outputPath,
durationMs: result.durationMs,
error: !result.success ? describeFfmpegFailure(result, processTimeout) : undefined,
failureReason: result.failureReason,
};
}