Skip to content

Commit 462f9db

Browse files
feat(producer): add hls output format (#4014)
* feat(engine): add packageHls for HLS VOD packaging Adds `packageHls` next to `muxVideoWithAudio`: stream-copies an already-encoded H.264 video and optional AAC sidecar into an HLS VOD directory (`master.m3u8` + split video/audio renditions, MPEG-TS segments) with `-c copy`, so no re-encode happens at package time. Depends on the locked GOP from the previous commit. `-hls_time` can only cut at existing keyframes, so `gopSize = segmentSeconds x fps` is what makes every segment exactly `segmentSeconds` long and IDR-aligned. A test packages an unlocked encode to pin that: the same call yields one 4s segment instead of four 1s ones. Deliberately omits the mp4 mux's provenance tags, which MPEG-TS drops and whose `-movflags` is invalid for `-f hls`, and `-avoid_negative_ts`, which would discard the AAC priming and shift audio against video (see issue 3487). A real-ffmpeg test asserts the first presentable audio sample lands on the first video frame. No caller yet; `format: "hls"` in the producer follows. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]> * fix(engine): zero HLS mux base and reject % in packageHls outputDir - Pass -muxdelay 0 -muxpreload 0 so the first segment starts at PTS 0 instead of the mpegts muxer's 1.4 s base; A/V alignment through the AAC priming packet is unchanged - Throw on an outputDir containing %, which ffmpeg expands as a printf conversion in -hls_segment_filename and fails with a misleading "No such file or directory" - Assert alignment on relative spacing rather than on how one ffmpeg build clamps the priming packet's negative PTS - Encode the test fixture with the full software GOP lock (lockedGopCodecParams), not just appendLockedGopArgs - Trim comments to the non-obvious rationale Co-Authored-By: Claude Fable 5.1 <[email protected]> * test(engine): satisfy the ffprobe argv contract in packageHls test `producer/src/utils/ffprobeArgvContract.test.ts` sweeps every package at the source level and requires `--` to be the argv entry immediately before an ffprobe input path. The `probe()` helper here passed `join(outputDir, HLS_VIDEO_PLAYLIST)` in that slot, which the contract's comma-splitting parser reads as two entries, so the producer suite was red on this branch while the engine suite stayed green. `probe()` now takes the input path as a parameter and appends the terminator itself. The sibling ffmpeg `run()` helper switches from a spread-in-array-literal to `.concat`, because a verbosity-flag-then-spread literal is indistinguishable from the ffprobe wrapper shape the contract demands a terminator on. The matcher reads raw source including comments. Co-Authored-By: Claude Fable 5.1 <[email protected]> * fix(engine): drop the audio-only variant from the HLS master playlist With `a:0,agroup:aud` in `-var_stream_map`, ffmpeg lists the audio rendition twice in `master.m3u8`: as the `#EXT-X-MEDIA:TYPE=AUDIO` group the video variant references, and again as a standalone `#EXT-X-STREAM-INF` variant with no `RESOLUTION`. That is valid HLS, but a player choosing by bandwidth can select it and play sound with no picture, and the VOD consumer asked for a single rendition. `stripAudioOnlyVariants` removes any variant tag without a `RESOLUTION` attribute together with its URI line; `packageHls` applies it to the master after a successful audio+video run. The rendition group and the audio playlist are untouched, so `audio.m3u8` is still referenced from the master. Pinned by a unit test on the playlist text and by the real-ffmpeg test, which now asserts exactly one `#EXT-X-STREAM-INF`. Co-Authored-By: Claude Fable 5.1 <[email protected]> * refactor(producer): extract hdrMode warning and decision-log helpers `resolveEffectiveHdrMode` was already over the fallow complexity gate on `main` (21 cyclomatic / 25 cognitive / CRAP 462) and only surfaces now because the HLS format work needs to touch its downgrade warning. Pull the downgrade message into `formatDowngradeWarning` and the "which mode and why" info line into `logHdrDecision`, which puts the function under the threshold. No behavior change: every log string is byte-identical and `hdrMode.test.ts` asserts them unchanged. Co-Authored-By: Claude Fable 5.1 <[email protected]> * feat(producer): add hls output format Adds `format: "hls"` to `@hyperframes/producer`. An HLS render is the same opaque H.264 + AAC encode as `mp4`, stream-copied at assemble time (no re-encode) into a directory: `master.m3u8`, `video.m3u8` + `video_%05d.ts`, and `audio.m3u8` + `audio_%05d.ts` when the composition has audio. The load-bearing part is that `-c copy -f hls` can only cut a segment at an existing keyframe, so the encoder's GOP is locked to `hlsSegmentSeconds x fps` frames. `resolveHlsEncoderGopLock` returns that pair as one value spread into both encoder inputs, so the streaming and disk/chunked paths cannot disagree — a render reaching only one of them still succeeds, it just emits variable-length segments silently. - `renderFormat.ts`: `hls` is opaque (`outputNeedsAlpha` is now `!== "mp4" && !== "hls"` — missing this flips HLS to RGBA screenshot capture with nothing failing), supports page-side compositing, and `outputUsesH264Pipeline` replaces the three `outputFormat === "mp4"` router gates. - `hlsConfig.ts`: `hlsSegmentSeconds` (default 4, positive integer), the GOP derivation, and the fail-fast gates. `force-hdr` is rejected (v1 is SDR-only; HDR10 needs HEVC in fMP4), and so is `useGpu` — the GOP lock is software-only, so a GPU HLS render segments correctly by accident on videotoolbox and wrong on nvenc. - `assembleStage.ts`: `hls` branches to `packageHls` instead of mux/faststart, after the same `padOrTrimAudioToVideoFrameCount` the mp4 mux uses. - `artifactTransaction.ts`: a directory artifact can now carry a `probeTarget` + `requiredFiles`, so the #3395 truncation gate still runs for HLS against `video.m3u8`. `expectedFrames` is inert there (ffprobe reports no frame count through the hls demuxer); duration carries it. - `renderRequest.ts`: accepts `hls` + `hlsSegmentSeconds`; distributed conversion rejects it alongside `gif`. `DistributedFormat` is unchanged. `RENDER_REQUEST_VERSION` stays at 1: the new field is optional, the parser ignores unknown option keys, and an older worker already rejects `format: "hls"` with "Render request format is invalid". - `hdrMode.ts`: the non-mp4 SDR downgrade warning no longer claims "HDR + alpha" for `hls`; the helper extraction landed in the preceding refactor commit. Verified: `hlsRender.integration.test.ts` renders a real 10 s composition and asserts 3 segments, the first two exactly 4.000 s, every segment starting on an IDR frame, and PTS 0. Removing the GOP wiring collapses it to 2 segments, so the test is load-bearing. Both producer lanes (unit and integration) run on every PR in `ci.yml`, so that wiring check is on the PR gate. CLI flags and docs are deliberately left to the next PR in the series. Co-Authored-By: Claude Fable 5.1 <[email protected]> * fix(engine): close the HLS master playlist rewrite race CodeQL flagged two high-severity alerts on the `stripAudioOnlyVariants` rewrite: a check-then-use race (`existsSync` then a separate path-based read and write) and insecure creation of a file at a predictable path in the OS temp dir. Both came from resolving `master.m3u8` three times. Open it once with `r+` and owner-only mode — which neither creates the playlist nor widens its permissions, ffmpeg owns that — then read, truncate and write through that one descriptor. Absence is still tolerated for the argument-level tests that stub ffmpeg, now via ENOENT rather than a prior existence check. No behavior change: `hlsRender.integration.test.ts` still renders a real composition with audio and asserts the stripped master playlist. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]> --------- Co-authored-by: Claude Opus 5 (1M context) <[email protected]>
1 parent 0a1c6f5 commit 462f9db

19 files changed

Lines changed: 1847 additions & 82 deletions

‎packages/engine/src/index.ts‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -161,10 +161,15 @@ export {
161161
encodeFramesChunkedConcat,
162162
muxVideoWithAudio,
163163
applyFaststart,
164+
packageHls,
164165
detectGpuEncoder,
165166
ENCODER_PRESETS,
166167
getEncoderPreset,
168+
HLS_MASTER_PLAYLIST,
169+
HLS_VIDEO_PLAYLIST,
170+
HLS_AUDIO_PLAYLIST,
167171
type GpuEncoder,
172+
type PackageHlsOptions,
168173
} from "./services/chunkEncoder.js";
169174
export type { EncoderOptions, EncodeResult, MuxResult } from "./services/chunkEncoder.types.js";
170175

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

Lines changed: 153 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,13 +7,18 @@
77
*/
88

99
import {
10+
closeSync,
1011
copyFileSync,
1112
existsSync,
13+
ftruncateSync,
1214
mkdirSync,
1315
mkdtempSync,
16+
openSync,
17+
readFileSync,
1418
readdirSync,
1519
statSync,
1620
writeFileSync,
21+
writeSync,
1722
} from "fs";
1823
import { join, dirname, extname } from "path";
1924
import { DEFAULT_CONFIG, type EngineConfig } from "../config.js";
@@ -781,6 +786,154 @@ export async function muxVideoWithAudio(
781786
};
782787
}
783788

789+
export const HLS_MASTER_PLAYLIST = "master.m3u8";
790+
export const HLS_VIDEO_PLAYLIST = "video.m3u8";
791+
export const HLS_AUDIO_PLAYLIST = "audio.m3u8";
792+
793+
/**
794+
* Drop the standalone audio-only variant ffmpeg's `-var_stream_map` adds to
795+
* the master playlist.
796+
*
797+
* With `a:0,agroup:aud` the hls muxer lists the audio rendition twice: as the
798+
* `#EXT-X-MEDIA:TYPE=AUDIO` entry the video variant references (wanted), and
799+
* again as its own `#EXT-X-STREAM-INF` variant with no `RESOLUTION` (not
800+
* wanted). That is valid HLS, but a player choosing variants by bandwidth can
801+
* pick it and play sound with no picture, and the VOD consumer asked for a
802+
* single rendition. A variant tag without a `RESOLUTION` attribute is
803+
* audio-only; its URI is always the following line, so both go.
804+
*/
805+
export function stripAudioOnlyVariants(masterPlaylist: string): string {
806+
const lines = masterPlaylist.split("\n");
807+
const kept: string[] = [];
808+
for (let i = 0; i < lines.length; i++) {
809+
const line = lines[i]!;
810+
if (line.startsWith("#EXT-X-STREAM-INF:") && !line.includes("RESOLUTION=")) {
811+
// ffmpeg separates variants with a blank line; drop the one before this
812+
// variant so the master does not end up with two in a row.
813+
if (kept.at(-1) === "") kept.pop();
814+
i += 1;
815+
continue;
816+
}
817+
kept.push(line);
818+
}
819+
return kept.join("\n");
820+
}
821+
822+
export interface PackageHlsOptions extends Partial<Pick<EngineConfig, "ffmpegProcessTimeout">> {
823+
/** Whole seconds, so it matches the integer `EXT-X-TARGETDURATION` ffmpeg writes. */
824+
segmentSeconds: number;
825+
signal?: AbortSignal;
826+
}
827+
828+
/**
829+
* Stream-copy an H.264 video (and optional AAC sidecar) into an HLS VOD
830+
* directory: `master.m3u8`, `video.m3u8` + `video_%05d.ts`, and `audio.m3u8` +
831+
* `audio_%05d.ts` when audio is given. `outputPath` in the result is the directory.
832+
* The master carries exactly one `#EXT-X-STREAM-INF` variant (the video, with
833+
* the audio attached as a rendition group); see `stripAudioOnlyVariants`.
834+
*
835+
* `-hls_time` cuts at the first keyframe at or after each target, so the input
836+
* must be encoded with the GOP lock (`gopSize = segmentSeconds × fps`). The lock
837+
* is software-encoder only; a GPU encode will not segment on time.
838+
*/
839+
export async function packageHls(
840+
videoPath: string,
841+
audioPath: string | null,
842+
outputDir: string,
843+
options: PackageHlsOptions,
844+
): Promise<MuxResult> {
845+
const { segmentSeconds, signal } = options;
846+
if (!Number.isInteger(segmentSeconds) || segmentSeconds <= 0) {
847+
throw new Error(
848+
`[chunkEncoder] packageHls requires a positive integer segmentSeconds (received ${String(segmentSeconds)})`,
849+
);
850+
}
851+
// `-hls_segment_filename` is a printf template and the hls muxer does not honor `%%`.
852+
if (outputDir.includes("%")) {
853+
throw new Error(`[chunkEncoder] packageHls outputDir must not contain "%": ${outputDir}`);
854+
}
855+
856+
// ffmpeg does not create the directory for the segment pattern.
857+
if (!existsSync(outputDir)) mkdirSync(outputDir, { recursive: true });
858+
859+
const hasAudio = audioPath !== null;
860+
const args = hasAudio
861+
? ["-i", videoPath, "-i", audioPath, "-map", "0:v:0", "-map", "1:a:0"]
862+
: ["-i", videoPath, "-map", "0:v:0"];
863+
864+
args.push(
865+
"-c",
866+
"copy",
867+
"-f",
868+
"hls",
869+
"-hls_time",
870+
String(segmentSeconds),
871+
"-hls_playlist_type",
872+
"vod",
873+
"-hls_flags",
874+
"independent_segments",
875+
"-hls_segment_type",
876+
"mpegts",
877+
"-var_stream_map",
878+
hasAudio ? "v:0,agroup:aud,name:video a:0,agroup:aud,name:audio" : "v:0,name:video",
879+
"-master_pl_name",
880+
HLS_MASTER_PLAYLIST,
881+
"-hls_segment_filename",
882+
join(outputDir, "%v_%05d.ts"),
883+
// Without these the mpegts muxer starts the stream at PTS 1.4 s.
884+
"-muxdelay",
885+
"0",
886+
"-muxpreload",
887+
"0",
888+
);
889+
890+
// No provenance tags (MPEG-TS drops them; `-movflags` is invalid for `-f hls`)
891+
// and no `-avoid_negative_ts`, which would drop the AAC priming (#3487).
892+
args.push("-y", join(outputDir, "%v.m3u8"));
893+
894+
const processTimeout = options.ffmpegProcessTimeout ?? DEFAULT_CONFIG.ffmpegProcessTimeout;
895+
const result = await runFfmpeg(args, { signal, timeout: processTimeout });
896+
897+
if (signal?.aborted) {
898+
return {
899+
success: false,
900+
outputPath: outputDir,
901+
durationMs: result.durationMs,
902+
error: "FFmpeg HLS packaging cancelled",
903+
};
904+
}
905+
if (result.success && hasAudio) {
906+
const masterPath = join(outputDir, HLS_MASTER_PLAYLIST);
907+
// One descriptor for the read-modify-write: re-resolving the path to write
908+
// it back races anything else in this predictable temp dir, and `r+` with
909+
// owner-only mode neither creates nor widens the playlist ffmpeg wrote.
910+
// A missing one is fine — the argument-level tests stub ffmpeg.
911+
let master: number | undefined;
912+
try {
913+
master = openSync(masterPath, "r+", 0o600);
914+
} catch (error) {
915+
if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
916+
}
917+
if (master !== undefined) {
918+
try {
919+
const stripped = stripAudioOnlyVariants(readFileSync(master, "utf-8"));
920+
// Stripping only shortens the playlist; truncate or the tail survives.
921+
ftruncateSync(master, 0);
922+
writeSync(master, stripped, 0, "utf-8");
923+
} finally {
924+
closeSync(master);
925+
}
926+
}
927+
}
928+
return {
929+
success: result.success,
930+
outputPath: outputDir,
931+
durationMs: result.durationMs,
932+
error: !result.success ? formatFfmpegError(result.exitCode, result.stderr) : undefined,
933+
failureReason: result.failureReason,
934+
};
935+
}
936+
784937
export async function applyFaststart(
785938
inputPath: string,
786939
outputPath: string,

0 commit comments

Comments
 (0)