@hyperframes/engine 0.6.94 → 0.6.96

package/dist/services/systemMemory.js

@@ -7,10 +7,112 @@
  * They all need the same "how much memory does this box have" reading, so
  * it lives here once instead of being re-derived inline.
  */
+import { readFileSync } from "fs";
 import { totalmem } from "os";
+const BYTES_PER_MIB = 1024 * 1024;
+const BYTES_PER_MIB_BIGINT = BigInt(BYTES_PER_MIB);
+// These are the paths as seen from INSIDE a container, where the runtime
+// mounts the container's own cgroup at the namespace root — the case this
+// probe exists for. They are deliberately not resolved via /proc/self/cgroup:
+// on a bare host under systemd the process's real limit may live in a nested
+// slice (e.g. /sys/fs/cgroup/user.slice/.../memory.max) that these root paths
+// don't see, and that's acceptable — bare hosts are covered by total-RAM
+// detection, and chasing nested slices adds fragility for no container gain.
+const CGROUP_V2_MEMORY_MAX_PATH = "/sys/fs/cgroup/memory.max";
+const CGROUP_V1_MEMORY_LIMIT_PATH = "/sys/fs/cgroup/memory/memory.limit_in_bytes";
+// Kernel no-limit sentinel is page-rounded 2^63-1 (~9223372036854771712); >= 2^60 is implausible as a real limit.
+const CGROUP_V1_NO_LIMIT_CUTOFF_BYTES = 2n ** 60n;
+let _cachedCgroupLimitMb;
+let _warnedCgroupReadFailure = false;
+/** Parse cgroup v2/v1 memory limits from sysfs file contents into MiB. */
+export function parseCgroupLimitMb(v2Content, v1Content) {
+    if (v2Content !== null) {
+        return parseCgroupV2LimitMb(v2Content);
+    }
+    return parseCgroupV1LimitMb(v1Content);
+}
+function parseCgroupV2LimitMb(content) {
+    const trimmed = content.trim();
+    if (trimmed === "max") {
+        return null;
+    }
+    return parsePositiveByteLimitMb(trimmed);
+}
+function parseCgroupV1LimitMb(content) {
+    if (content === null) {
+        return null;
+    }
+    return parsePositiveByteLimitMb(content.trim(), CGROUP_V1_NO_LIMIT_CUTOFF_BYTES);
+}
+function parsePositiveByteLimitMb(content, noLimitCutoffBytes) {
+    if (!/^\d+$/.test(content)) {
+        return null;
+    }
+    const bytes = BigInt(content);
+    if (bytes <= 0n) {
+        return null;
+    }
+    if (noLimitCutoffBytes !== undefined && bytes >= noLimitCutoffBytes) {
+        return null;
+    }
+    return Number(bytes / BYTES_PER_MIB_BIGINT);
+}
+/** Test-only: reset the cached cgroup memory probe. */
+export function _resetCgroupLimitCacheForTests() {
+    _cachedCgroupLimitMb = undefined;
+    _warnedCgroupReadFailure = false;
+}
+function getCgroupLimitMb() {
+    if (_cachedCgroupLimitMb !== undefined)
+        return _cachedCgroupLimitMb;
+    if (process.platform !== "linux") {
+        _cachedCgroupLimitMb = null;
+        return null;
+    }
+    const v2Content = readCgroupFile(CGROUP_V2_MEMORY_MAX_PATH);
+    const v1Content = v2Content === null ? readCgroupFile(CGROUP_V1_MEMORY_LIMIT_PATH) : null;
+    _cachedCgroupLimitMb = parseCgroupLimitMb(v2Content, v1Content);
+    if (_cachedCgroupLimitMb !== null) {
+        console.info(`[SystemMemory] cgroup memory limit detected: ${_cachedCgroupLimitMb} MiB — ` +
+            `it governs memory-adaptive render behaviour instead of host RAM.`);
+    }
+    return _cachedCgroupLimitMb;
+}
+function readCgroupFile(path) {
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch (error) {
+        const code = getErrorCode(error);
+        if (code !== "ENOENT" && code !== "ENOTDIR") {
+            warnCgroupReadFailure(path, error);
+        }
+        return null;
+    }
+}
+function getErrorCode(error) {
+    if (typeof error !== "object" || error === null || !("code" in error)) {
+        return undefined;
+    }
+    return typeof error.code === "string" ? error.code : undefined;
+}
+function formatCgroupReadError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const code = getErrorCode(error);
+    return code ? `${code}: ${message}` : message;
+}
+function warnCgroupReadFailure(path, error) {
+    if (_warnedCgroupReadFailure)
+        return;
+    _warnedCgroupReadFailure = true;
+    console.warn(`[SystemMemory] Unable to read cgroup memory limit at ${path} ` +
+        `(${formatCgroupReadError(error)}); falling back to host RAM.`);
+}
 /** Total physical RAM in MiB. */
 export function getSystemTotalMb() {
-    return Math.floor(totalmem() / (1024 * 1024));
+    const hostTotalMb = Math.floor(totalmem() / BYTES_PER_MIB);
+    const cgroupLimitMb = getCgroupLimitMb();
+    return cgroupLimitMb === null ? hostTotalMb : Math.min(hostTotalMb, cgroupLimitMb);
 }
 /**
  * Total-RAM ceiling (MiB) at or below which the host is treated as
@@ -34,14 +136,13 @@ export const LOW_MEMORY_TOTAL_MB_THRESHOLD = 8192;
  * survive". Accepts an explicit `totalMb` so callers (and tests) can pass
  * a known value instead of re-probing.
  *
- * Caveat: `os.totalmem()` reports the *host's* physical RAM, not a
- * cgroup/container memory limit. A 4 GB container on a 32 GB host will not
- * auto-flag as low-memory, and an 8 GB container on a 64 GB host won't
- * either. Containerised and serverless callers (Docker `--docker` renders,
- * Lambda) that want a specific profile should set `PRODUCER_LOW_MEMORY_MODE`
- * explicitly rather than relying on auto-detection. Hosts whose *total* RAM
- * is genuinely <= the threshold (laptops, small VMs, small Lambda tiers) are
- * detected correctly regardless of container nesting.
+ * Caveat: Linux cgroup v1/v2 memory limits are consulted when readable, so
+ * Docker and serverless runtimes, including Lambda tiers with readable cgroup
+ * ceilings, inherit the tighter container limit instead of the host's physical
+ * RAM. Environments that hide cgroup files should set
+ * `PRODUCER_LOW_MEMORY_MODE` explicitly rather than relying on auto-detection.
+ * Hosts whose *effective* total RAM is genuinely <= the threshold (laptops,
+ * small VMs, small Lambda tiers, small containers) are detected correctly.
  */
 export function isLowMemorySystem(totalMb = getSystemTotalMb()) {
     return totalMb <= LOW_MEMORY_TOTAL_MB_THRESHOLD;

package/dist/services/systemMemory.js.map

@@ -1 +1 @@
-{"version":3,"file":"systemMemory.js","sourceRoot":"","sources":["../../src/services/systemMemory.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,IAAI,CAAC;AAE9B,iCAAiC;AACjC,MAAM,UAAU,gBAAgB;IAC9B,OAAO,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC;AAChD,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAG,IAAI,CAAC;AAElD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,iBAAiB,CAAC,UAAkB,gBAAgB,EAAE;IACpE,OAAO,OAAO,IAAI,6BAA6B,CAAC;AAClD,CAAC"}
+{"version":3,"file":"systemMemory.js","sourceRoot":"","sources":["../../src/services/systemMemory.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/engine",
-  "version": "0.6.94",
+  "version": "0.6.96",
   "description": "Seekable web page to video rendering engine (Puppeteer + FFmpeg)",
   "repository": {
     "type": "git",
@@ -21,7 +21,7 @@
     "linkedom": "^0.18.12",
     "puppeteer": "^24.0.0",
     "puppeteer-core": "^24.39.1",
-    "@hyperframes/core": "^0.6.94"
+    "@hyperframes/core": "^0.6.96"
   },
   "devDependencies": {
     "@types/node": "^25.0.10",

package/src/services/chunkEncoder.test.ts

@@ -1,6 +1,93 @@
-import { describe, it, expect, vi } from "vitest";
+import { EventEmitter } from "node:events";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, it, expect, vi } from "vitest";
 import { ENCODER_PRESETS, getEncoderPreset, buildEncoderArgs } from "./chunkEncoder.js";
 
+const TINY_PNG = Buffer.from(
+  "iVBORw0KGgoAAAANSUhEUgAAAAIAAAACCAIAAAD91JpzAAAACXBIWXMAAAABAAAAAQBPJcTWAAAAEElEQVR4nGP8wwACLGCSAQANBAECv1AVswAAAABJRU5ErkJggg==",
+  "base64",
+);
+
+const tempDirs: string[] = [];
+
+afterEach(() => {
+  for (const dir of tempDirs.splice(0)) {
+    rmSync(dir, { recursive: true, force: true });
+  }
+  vi.resetModules();
+  vi.doUnmock("child_process");
+  vi.useRealTimers();
+});
+
+function createFrameFixture(): { root: string; framesDir: string } {
+  const root = mkdtempSync(join(tmpdir(), "hf-chunk-encoder-"));
+  tempDirs.push(root);
+  const framesDir = join(root, "frames");
+  mkdirSync(framesDir);
+  for (let i = 1; i <= 2; i++) {
+    writeFileSync(join(framesDir, `frame_${String(i).padStart(6, "0")}.png`), TINY_PNG);
+  }
+  return { root, framesDir };
+}
+
+const tinyEncodeOptions = {
+  fps: { num: 30, den: 1 },
+  width: 2,
+  height: 2,
+  codec: "h264" as const,
+  preset: "ultrafast",
+  quality: 28,
+  pixelFormat: "yuv420p",
+  useGpu: false,
+};
+
+function encodeTimeoutMessage(timeoutMs: number): string {
+  return `FFmpeg killed after exceeding ffmpegEncodeTimeout (${timeoutMs} ms)`;
+}
+
+type FakeProc = EventEmitter & {
+  stderr: EventEmitter;
+  kill: ReturnType<typeof vi.fn>;
+  killed: boolean;
+};
+
+type SpawnCall = {
+  command: string;
+  args: readonly string[];
+  proc: FakeProc;
+};
+
+function createFakeProc(): FakeProc {
+  const proc = new EventEmitter() as FakeProc;
+  proc.stderr = new EventEmitter();
+  proc.kill = vi.fn(() => {
+    proc.killed = true;
+    return true;
+  });
+  proc.killed = false;
+  return proc;
+}
+
+function createSpawnSpy(): {
+  spawn: (command: string, args: readonly string[]) => FakeProc;
+  calls: SpawnCall[];
+} {
+  const calls: SpawnCall[] = [];
+  const spawn = (command: string, args: readonly string[]): FakeProc => {
+    const proc = createFakeProc();
+    calls.push({ command, args, proc });
+    return proc;
+  };
+  return { spawn, calls };
+}
+
+function emitClose(proc: FakeProc, code: number): void {
+  proc.emit("exit", code);
+  proc.emit("close", code);
+}
+
 describe("ENCODER_PRESETS", () => {
   it("has draft, standard, and high presets", () => {
     expect(ENCODER_PRESETS).toHaveProperty("draft");
@@ -26,6 +113,248 @@ describe("ENCODER_PRESETS", () => {
   });
 });
 
+describe("encodeFramesFromDir ffmpegEncodeTimeout", () => {
+  it("kills ffmpeg when config timeout elapses", async () => {
+    vi.useFakeTimers();
+    const { spawn, calls } = createSpawnSpy();
+    vi.resetModules();
+    vi.doMock("child_process", () => ({ spawn }));
+
+    const { encodeFramesFromDir } = await import("./chunkEncoder.js");
+    const { root, framesDir } = createFrameFixture();
+
+    const encodePromise = encodeFramesFromDir(
+      framesDir,
+      "frame_%06d.png",
+      join(root, "timeout.mp4"),
+      tinyEncodeOptions,
+      undefined,
+      { ffmpegEncodeTimeout: 1000 },
+    );
+
+    expect(calls).toHaveLength(1);
+    const proc = calls[0]!.proc;
+    vi.advanceTimersByTime(999);
+    expect(proc.kill).not.toHaveBeenCalled();
+
+    vi.advanceTimersByTime(1);
+    expect(proc.kill).toHaveBeenCalledWith("SIGTERM");
+
+    proc.stderr.emit("data", Buffer.from("terminated by timeout\n"));
+    emitClose(proc, 143);
+
+    const result = await encodePromise;
+    expect(result.success).toBe(false);
+    expect(result.error).toContain("FFmpeg exited with code 143");
+    expect(result.error).toContain("terminated by timeout");
+    expect(result.error).toContain(encodeTimeoutMessage(1000));
+  });
+
+  it("keeps non-timeout ffmpeg failures unchanged", async () => {
+    vi.useFakeTimers();
+    const { spawn, calls } = createSpawnSpy();
+    vi.resetModules();
+    vi.doMock("child_process", () => ({ spawn }));
+
+    const { encodeFramesFromDir } = await import("./chunkEncoder.js");
+    const { root, framesDir } = createFrameFixture();
+
+    const encodePromise = encodeFramesFromDir(
+      framesDir,
+      "frame_%06d.png",
+      join(root, "failure.mp4"),
+      tinyEncodeOptions,
+      undefined,
+      { ffmpegEncodeTimeout: 1000 },
+    );
+
+    expect(calls).toHaveLength(1);
+    const proc = calls[0]!.proc;
+    proc.stderr.emit("data", Buffer.from("encoder failed\n"));
+    emitClose(proc, 1);
+
+    const result = await encodePromise;
+    expect(result.success).toBe(false);
+    expect(result.error).toContain("FFmpeg exited with code 1");
+    expect(result.error).toContain("encoder failed");
+    expect(result.error).not.toContain("ffmpegEncodeTimeout");
+  });
+
+  it("uses the default timeout when config is omitted", async () => {
+    vi.useFakeTimers();
+    const { spawn, calls } = createSpawnSpy();
+    vi.resetModules();
+    vi.doMock("child_process", () => ({ spawn }));
+
+    const { encodeFramesFromDir } = await import("./chunkEncoder.js");
+    const { root, framesDir } = createFrameFixture();
+
+    const encodePromise = encodeFramesFromDir(
+      framesDir,
+      "frame_%06d.png",
+      join(root, "default.mp4"),
+      tinyEncodeOptions,
+    );
+
+    expect(calls).toHaveLength(1);
+    const proc = calls[0]!.proc;
+    vi.advanceTimersByTime(599_999);
+    expect(proc.kill).not.toHaveBeenCalled();
+
+    emitClose(proc, 0);
+
+    const result = await encodePromise;
+    expect(result.success).toBe(true);
+    expect(result.framesEncoded).toBe(2);
+    expect(result.fileSize).toBe(0);
+  });
+});
+
+describe("encodeFramesChunkedConcat ffmpegEncodeTimeout", () => {
+  it("passes config timeout to per-chunk encodes", async () => {
+    vi.useFakeTimers();
+    const { spawn, calls } = createSpawnSpy();
+    vi.resetModules();
+    vi.doMock("child_process", () => ({ spawn }));
+
+    const { encodeFramesChunkedConcat } = await import("./chunkEncoder.js");
+    const { root, framesDir } = createFrameFixture();
+
+    const encodePromise = encodeFramesChunkedConcat(
+      framesDir,
+      "frame_%06d.png",
+      join(root, "chunked.mp4"),
+      tinyEncodeOptions,
+      30,
+      undefined,
+      { ffmpegEncodeTimeout: 1000 },
+    );
+
+    expect(calls).toHaveLength(1);
+    const proc = calls[0]!.proc;
+    vi.advanceTimersByTime(999);
+    expect(proc.kill).not.toHaveBeenCalled();
+
+    vi.advanceTimersByTime(1);
+    expect(proc.kill).toHaveBeenCalledWith("SIGTERM");
+
+    proc.stderr.emit("data", Buffer.from("chunk timeout\n"));
+    emitClose(proc, 143);
+
+    const result = await encodePromise;
+    expect(result.success).toBe(false);
+    expect(result.error).toContain("Chunk 0 encode failed");
+    expect(result.error).toContain("chunk timeout");
+    expect(result.error).toContain(encodeTimeoutMessage(1000));
+  });
+
+  it("keeps non-timeout chunk failures unchanged", async () => {
+    vi.useFakeTimers();
+    const { spawn, calls } = createSpawnSpy();
+    vi.resetModules();
+    vi.doMock("child_process", () => ({ spawn }));
+
+    const { encodeFramesChunkedConcat } = await import("./chunkEncoder.js");
+    const { root, framesDir } = createFrameFixture();
+
+    const encodePromise = encodeFramesChunkedConcat(
+      framesDir,
+      "frame_%06d.png",
+      join(root, "chunked-failure.mp4"),
+      tinyEncodeOptions,
+      30,
+      undefined,
+      { ffmpegEncodeTimeout: 1000 },
+    );
+
+    expect(calls).toHaveLength(1);
+    const proc = calls[0]!.proc;
+    proc.stderr.emit("data", Buffer.from("chunk failed\n"));
+    emitClose(proc, 1);
+
+    const result = await encodePromise;
+    expect(result.success).toBe(false);
+    expect(result.error).toBe("Chunk 0 encode failed: chunk failed\n");
+    expect(result.error).not.toContain("ffmpegEncodeTimeout");
+  });
+
+  it("kills concat ffmpeg when config timeout elapses", async () => {
+    vi.useFakeTimers();
+    const { spawn, calls } = createSpawnSpy();
+    vi.resetModules();
+    vi.doMock("child_process", () => ({ spawn }));
+
+    const { encodeFramesChunkedConcat } = await import("./chunkEncoder.js");
+    const { root, framesDir } = createFrameFixture();
+
+    const encodePromise = encodeFramesChunkedConcat(
+      framesDir,
+      "frame_%06d.png",
+      join(root, "concat-timeout.mp4"),
+      tinyEncodeOptions,
+      30,
+      undefined,
+      { ffmpegEncodeTimeout: 1000 },
+    );
+
+    expect(calls).toHaveLength(1);
+    emitClose(calls[0]!.proc, 0);
+    await Promise.resolve();
+
+    expect(calls).toHaveLength(2);
+    const concatProc = calls[1]!.proc;
+    vi.advanceTimersByTime(999);
+    expect(concatProc.kill).not.toHaveBeenCalled();
+
+    vi.advanceTimersByTime(1);
+    expect(concatProc.kill).toHaveBeenCalledWith("SIGTERM");
+
+    concatProc.stderr.emit("data", Buffer.from("concat timeout\n"));
+    emitClose(concatProc, 143);
+
+    const result = await encodePromise;
+    expect(result.success).toBe(false);
+    expect(result.error).toContain("Chunk concat failed");
+    expect(result.error).toContain("concat timeout");
+    expect(result.error).toContain(encodeTimeoutMessage(1000));
+  });
+
+  it("uses the default timeout for per-chunk encodes when config is omitted", async () => {
+    vi.useFakeTimers();
+    const { spawn, calls } = createSpawnSpy();
+    vi.resetModules();
+    vi.doMock("child_process", () => ({ spawn }));
+
+    const { encodeFramesChunkedConcat } = await import("./chunkEncoder.js");
+    const { root, framesDir } = createFrameFixture();
+
+    const encodePromise = encodeFramesChunkedConcat(
+      framesDir,
+      "frame_%06d.png",
+      join(root, "chunked-default.mp4"),
+      tinyEncodeOptions,
+      30,
+    );
+
+    expect(calls).toHaveLength(1);
+    const chunkProc = calls[0]!.proc;
+    vi.advanceTimersByTime(599_999);
+    expect(chunkProc.kill).not.toHaveBeenCalled();
+
+    emitClose(chunkProc, 0);
+    await Promise.resolve();
+
+    expect(calls).toHaveLength(2);
+    const concatProc = calls[1]!.proc;
+    emitClose(concatProc, 0);
+
+    const result = await encodePromise;
+    expect(result.success).toBe(true);
+    expect(result.framesEncoded).toBe(2);
+    expect(result.fileSize).toBe(0);
+  });
+});
+
 describe("getEncoderPreset", () => {
   it("returns h264 with yuv420p for mp4 format", () => {
     const preset = getEncoderPreset("standard", "mp4");

package/src/services/chunkEncoder.ts

@@ -39,6 +39,11 @@ export interface EncoderPreset {
   hdr?: { transfer: HdrTransfer };
 }
 
+function appendEncodeTimeoutMessage(error: string, timedOut: boolean, timeoutMs: number): string {
+  if (!timedOut) return error;
+  return `${error}\nFFmpeg killed after exceeding ffmpegEncodeTimeout (${timeoutMs} ms)`;
+}
+
 /**
  * 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);
@@ -428,7 +433,9 @@ export async function encodeFramesFromDir(
     }
 
     const encodeTimeout = config?.ffmpegEncodeTimeout ?? DEFAULT_CONFIG.ffmpegEncodeTimeout;
+    let timedOut = false;
     const timer = setTimeout(() => {
+      timedOut = true;
       ffmpeg.kill("SIGTERM");
     }, encodeTimeout);
 
@@ -440,7 +447,7 @@ export async function encodeFramesFromDir(
       clearTimeout(timer);
       if (signal) signal.removeEventListener("abort", onAbort);
       const durationMs = Date.now() - startTime;
-      if (signal?.aborted) {
+      if (signal?.aborted && !timedOut) {
         resolve({
           success: false,
           outputPath,
@@ -452,14 +459,18 @@ export async function encodeFramesFromDir(
         return;
       }
 
-      if (code !== 0) {
+      if (code !== 0 || timedOut) {
         resolve({
           success: false,
           outputPath,
           durationMs,
           framesEncoded: 0,
           fileSize: 0,
-          error: formatFfmpegError(code, stderr),
+          error: appendEncodeTimeoutMessage(
+            formatFfmpegError(code, stderr),
+            timedOut,
+            encodeTimeout,
+          ),
         });
         return;
       }
@@ -477,7 +488,7 @@ export async function encodeFramesFromDir(
         durationMs: Date.now() - startTime,
         framesEncoded: 0,
         fileSize: 0,
-        error: `[FFmpeg] ${err.message}`,
+        error: appendEncodeTimeoutMessage(`[FFmpeg] ${err.message}`, timedOut, encodeTimeout),
       });
     });
   });
@@ -490,6 +501,7 @@ export async function encodeFramesChunkedConcat(
   options: EncoderOptions,
   chunkSizeFrames: number,
   signal?: AbortSignal,
+  config?: Partial<Pick<EngineConfig, "ffmpegEncodeTimeout">>,
 ): Promise<EncodeResult> {
   const start = Date.now();
   const files = readdirSync(framesDir)
@@ -548,15 +560,39 @@ export async function encodeFramesChunkedConcat(
       const ffmpeg = spawn(getFfmpegBinary(), args);
       trackChildProcess(ffmpeg);
       let stderr = "";
+      const encodeTimeout = config?.ffmpegEncodeTimeout ?? DEFAULT_CONFIG.ffmpegEncodeTimeout;
+      let timedOut = false;
+      const timer = setTimeout(() => {
+        timedOut = true;
+        ffmpeg.kill("SIGTERM");
+      }, encodeTimeout);
       ffmpeg.stderr.on("data", (d) => {
         stderr += d.toString();
       });
       ffmpeg.on("close", (code) => {
-        if (code === 0) resolve({ success: true });
-        else resolve({ success: false, error: `Chunk ${i} encode failed: ${stderr.slice(-400)}` });
+        clearTimeout(timer);
+        if (code === 0 && !timedOut) resolve({ success: true });
+        else {
+          resolve({
+            success: false,
+            error: appendEncodeTimeoutMessage(
+              `Chunk ${i} encode failed: ${stderr.slice(-400)}`,
+              timedOut,
+              encodeTimeout,
+            ),
+          });
+        }
       });
       ffmpeg.on("error", (err) => {
-        resolve({ success: false, error: `Chunk ${i} encode error: ${err.message}` });
+        clearTimeout(timer);
+        resolve({
+          success: false,
+          error: appendEncodeTimeoutMessage(
+            `Chunk ${i} encode error: ${err.message}`,
+            timedOut,
+            encodeTimeout,
+          ),
+        });
       });
     });
     if (!chunkResult.success) {
@@ -592,15 +628,39 @@ export async function encodeFramesChunkedConcat(
     const ffmpeg = spawn(getFfmpegBinary(), concatArgs);
     trackChildProcess(ffmpeg);
     let stderr = "";
+    const encodeTimeout = config?.ffmpegEncodeTimeout ?? DEFAULT_CONFIG.ffmpegEncodeTimeout;
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      ffmpeg.kill("SIGTERM");
+    }, encodeTimeout);
     ffmpeg.stderr.on("data", (d) => {
       stderr += d.toString();
     });
     ffmpeg.on("close", (code) => {
-      if (code === 0) resolve({ success: true });
-      else resolve({ success: false, error: `Chunk concat failed: ${stderr.slice(-400)}` });
+      clearTimeout(timer);
+      if (code === 0 && !timedOut) resolve({ success: true });
+      else {
+        resolve({
+          success: false,
+          error: appendEncodeTimeoutMessage(
+            `Chunk concat failed: ${stderr.slice(-400)}`,
+            timedOut,
+            encodeTimeout,
+          ),
+        });
+      }
     });
     ffmpeg.on("error", (err) => {
-      resolve({ success: false, error: `Chunk concat error: ${err.message}` });
+      clearTimeout(timer);
+      resolve({
+        success: false,
+        error: appendEncodeTimeoutMessage(
+          `Chunk concat error: ${err.message}`,
+          timedOut,
+          encodeTimeout,
+        ),
+      });
     });
   });