Skip to content

Commit e1fda78

Browse files
fix(engine): use supported VideoToolbox quality options (#3687)
1 parent 0ce0bb1 commit e1fda78

6 files changed

Lines changed: 101 additions & 14 deletions

File tree

‎packages/engine/src/services/chunkEncoder.test.ts‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -935,6 +935,27 @@ describe("buildEncoderArgs GPU preset mapping", () => {
935935
expect(presetArg(args)).toBe("p5");
936936
});
937937

938+
it("uses a supported derived bitrate for high-quality VideoToolbox", () => {
939+
const args = buildEncoderArgs(
940+
{
941+
fps: { num: 24, den: 1 },
942+
width: 1920,
943+
height: 1080,
944+
codec: "h264",
945+
preset: "slow",
946+
quality: 15,
947+
useGpu: true,
948+
},
949+
inputArgs,
950+
"out.mp4",
951+
"videotoolbox",
952+
);
953+
954+
expect(args).not.toContain("-q:v");
955+
expect(args[args.indexOf("-b:v") + 1]).toBe("12M");
956+
expect(args[args.indexOf("-allow_sw") + 1]).toBe("1");
957+
});
958+
938959
// hevc_nvenc uses the same p1..p7 preset vocabulary as h264_nvenc, so the
939960
// mapping must apply to both codecs. Locks in "H.264 and H.265 NVENC share
940961
// the preset mapping" against a future refactor that might split the path.

‎packages/engine/src/services/chunkEncoder.ts‎

Lines changed: 11 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -21,13 +21,14 @@ import {
2121
type GpuEncoder,
2222
getCachedGpuEncoder,
2323
getGpuEncoderName,
24+
buildVideoToolboxRateControlArgs,
2425
mapPresetForGpuEncoder,
2526
} from "../utils/gpuEncoder.js";
2627
import { type HdrTransfer, getHdrEncoderColorParams } from "../utils/hdr.js";
2728
import { withEvenDimensionPad } from "../utils/evenDimensions.js";
2829
import { formatFfmpegError, isExternalFfmpegInterruption, runFfmpeg } from "../utils/runFfmpeg.js";
2930
import { extractAudioMetadata } from "../utils/ffprobe.js";
30-
import { type Fps, fpsToFfmpegArg } from "@hyperframes/core";
31+
import { type Fps, fpsToFfmpegArg, fpsToNumber } from "@hyperframes/core";
3132
import type { EncoderOptions, EncodeResult, MuxResult } from "./chunkEncoder.types.js";
3233
import { appendVp9CpuUsedArg } from "./vp9Options.js";
3334
import { appendRenderProvenanceArgs } from "../utils/renderProvenance.js";
@@ -202,12 +203,15 @@ export function buildEncoderArgs(
202203
else args.push("-cq", String(quality));
203204
break;
204205
case "videotoolbox":
205-
if (bitrate) args.push("-b:v", bitrate);
206-
else {
207-
const vtQuality = Math.max(0, Math.min(100, 100 - quality * 2));
208-
args.push("-q:v", String(vtQuality));
209-
}
210-
args.push("-allow_sw", "1");
206+
args.push(
207+
...buildVideoToolboxRateControlArgs({
208+
bitrate,
209+
width: options.width,
210+
height: options.height,
211+
fps: fpsToNumber(fps),
212+
quality,
213+
}),
214+
);
211215
break;
212216
case "vaapi":
213217
args.unshift("-vaapi_device", "/dev/dri/renderD128");

‎packages/engine/src/services/streamingEncoder.test.ts‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -271,6 +271,25 @@ describe("buildStreamingArgs", () => {
271271
expect(presetArg(args)).toBe("p4");
272272
});
273273

274+
it("uses a supported derived bitrate for high-quality VideoToolbox", () => {
275+
const args = buildStreamingArgs(
276+
{
277+
...baseGpu,
278+
fps: { num: 24, den: 1 },
279+
width: 1920,
280+
height: 1080,
281+
preset: "slow",
282+
quality: 15,
283+
},
284+
"/tmp/out.mp4",
285+
"videotoolbox",
286+
);
287+
288+
expect(args).not.toContain("-q:v");
289+
expect(args[args.indexOf("-b:v") + 1]).toBe("12M");
290+
expect(args[args.indexOf("-allow_sw") + 1]).toBe("1");
291+
});
292+
274293
// Same mapping applies to hevc_nvenc: NVENC's preset vocabulary is
275294
// codec-agnostic, so the helper must translate for H.265 too.
276295
it("translates libx264 preset names to NVENC pN for h265 as well", () => {

‎packages/engine/src/services/streamingEncoder.ts‎

Lines changed: 11 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -27,14 +27,15 @@ import {
2727
type GpuEncoder,
2828
getCachedGpuEncoder,
2929
getGpuEncoderName,
30+
buildVideoToolboxRateControlArgs,
3031
mapPresetForGpuEncoder,
3132
} from "../utils/gpuEncoder.js";
3233
import { formatFfmpegError, isExternalFfmpegInterruption } from "../utils/runFfmpeg.js";
3334
import { getFfmpegBinary } from "../utils/ffmpegBinaries.js";
3435
import { getHdrEncoderColorParams } from "../utils/hdr.js";
3536
import { withEvenDimensionPad } from "../utils/evenDimensions.js";
3637
import { DEFAULT_CONFIG, type EngineConfig } from "../config.js";
37-
import { fpsToFfmpegArg, type Fps } from "@hyperframes/core";
38+
import { fpsToFfmpegArg, fpsToNumber, type Fps } from "@hyperframes/core";
3839
import { appendVp9CpuUsedArg } from "./vp9Options.js";
3940
import { appendRenderProvenanceArgs } from "../utils/renderProvenance.js";
4041

@@ -270,12 +271,15 @@ export function buildStreamingArgs(
270271
else args.push("-cq", String(quality));
271272
break;
272273
case "videotoolbox":
273-
if (bitrate) args.push("-b:v", bitrate);
274-
else {
275-
const vtQuality = Math.max(0, Math.min(100, 100 - quality * 2));
276-
args.push("-q:v", String(vtQuality));
277-
}
278-
args.push("-allow_sw", "1");
274+
args.push(
275+
...buildVideoToolboxRateControlArgs({
276+
bitrate,
277+
width: options.width,
278+
height: options.height,
279+
fps: fpsToNumber(fps),
280+
quality,
281+
}),
282+
);
279283
break;
280284
case "vaapi":
281285
args.unshift("-vaapi_device", "/dev/dri/renderD128");

‎packages/engine/src/utils/gpuEncoder.test.ts‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -137,4 +137,12 @@ describe("getProbeArgs", () => {
137137
expect(args).toContain("color=size=320x240:rate=1:duration=1");
138138
}
139139
});
140+
141+
it("probes VideoToolbox with the same supported bitrate option as production", () => {
142+
const args = getProbeArgs("videotoolbox");
143+
144+
expect(args).not.toContain("-q:v");
145+
expect(args[args.indexOf("-b:v") + 1]).toBe("1M");
146+
expect(args[args.indexOf("-allow_sw") + 1]).toBe("1");
147+
});
140148
});

‎packages/engine/src/utils/gpuEncoder.ts‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -107,6 +107,26 @@ export function getGpuEncoderName(encoder: GpuEncoder, codec: "h264" | "h265"):
107107
}
108108
}
109109

110+
export function buildVideoToolboxRateControlArgs(input: {
111+
bitrate?: string;
112+
width: number;
113+
height: number;
114+
fps: number;
115+
quality: number;
116+
}): string[] {
117+
if (input.bitrate) return ["-b:v", input.bitrate, "-allow_sw", "1"];
118+
119+
// VideoToolbox rejects FFmpeg's generic qscale path on supported macOS
120+
// builds. Derive a bitrate from pixel rate instead: the three CRF-shaped
121+
// quality tiers map to roughly 5M / 10M / 12M at 1080p24.
122+
const bitsPerPixel = input.quality <= 15 ? 0.24 : input.quality <= 18 ? 0.16 : 0.08;
123+
const megabitsPerSecond = Math.max(
124+
1,
125+
Math.round((input.width * input.height * input.fps * bitsPerPixel) / 1_000_000),
126+
);
127+
return ["-b:v", `${megabitsPerSecond}M`, "-allow_sw", "1"];
128+
}
129+
110130
// Minimum probe dimensions must clear every GPU encoder's hardware minimum.
111131
// NVIDIA data-center SKUs (L4/T4/A10/A100) reject frames below ~257px on
112132
// either dimension with "Frame Dimension less than the minimum supported
@@ -137,6 +157,17 @@ export function getProbeArgs(encoder: ConcreteGpuEncoder): string[] {
137157

138158
args.push("-c:v", getGpuEncoderName(encoder, "h264"));
139159

160+
if (encoder === "videotoolbox") {
161+
args.push(
162+
...buildVideoToolboxRateControlArgs({
163+
width: GPU_PROBE_WIDTH,
164+
height: GPU_PROBE_HEIGHT,
165+
fps: 1,
166+
quality: 23,
167+
}),
168+
);
169+
}
170+
140171
if (encoder === "amf") {
141172
args.push("-rc", "cqp", "-qp_i", "28", "-qp_p", "28");
142173
}

0 commit comments

Comments
 (0)