[REA-6855] Write one step's output as a single MP4 file

[Dere-Wah]

Why

A saved step has to be one file a caller can download and play, holding every track the step produced. The recorder's encoder writes segmented fMP4 for HLS, with a timeline that spans the session; a step is written once, whole, so it needs none of that and a small writer of its own. recording/ does not change.

What Changed

write_mp4(path, bundle, fps, config) encodes a MediaBundle into one MP4 with PyAV. Video tracks come first, as H.264 or H.265 streams played at fps, then audio tracks, encoded with the configured codec and bitrate at the track's own rate (48 kHz when it declares none). Each keeps the order the output declares. The file is laid out with +faststart, so it plays while it downloads. Codecs, preset, quality, and audio bitrate come from StepResultsConfig, and the pixel format and profile are the recorder's.

A frame with an odd width or height is padded by one row or column, repeating the edge, because the encoder's pixel format needs even dimensions. Every stream is added before the first packet is written: the muxer writes the file header with that packet, and a stream added after it crashes libav, which is how a step with two video tracks first failed. Each stream is encoded into its own list of packets, and the lists are merged by decode time before they reach the muxer: the muxer buffers only a bounded span of one stream while it waits for the others, so encoding video to the end before any audio fails for a longer step (600 frames at 30 fps with 20 s of audio raised Invalid argument).

A payload the writer cannot encode (no tracks, fps <= 0, a frame of the wrong shape) is refused before the file opens, and a file that fails part-way is removed, so the path holds a whole file or nothing.

The tests decode every file they write back: stream count, frame count, size, rate, codec (h264, hevc, aac), audio length, the progressive layout, the errors, the cleanup after a failure mid-write, and a twenty-second video and audio round trip.

[github-actions]

[codex-review] - [P1] src/reactor_runtime/step_results/mp4.py: Sequential stream encoding causes longer video/audio outputs to exceed FFmpeg’s interleave limit and fail.

Scope: full (498bd52..1c8fe61).

View workflow run.

[Dere-Wah]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• [REA-6855] Serve saved step folders over HTTP #239
• [REA-6855] Save each reported step as a folder of files #238
• [REA-6855] Write one step's output as a single MP4 file #237 👈 (View in Graphite)
• [REA-6855] Read the runtime.step_results block from the manifest #236
• [REA-6854] Close a session when it reaches its steps #235
• [REA-6854] Report each finished step to the runtime with complete_step() #234
• [REA-6854] Apply a session's starting input, sent by a system client #233
• [REA-6854] Read starting_input and steps from the start body #232
• [REA-6854] Deliver commands and reactor events to the model in posted order #231
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[tempusfrangit]

I reproduced the failure described in the existing inline comment: 600 video frames at 30 fps with 20 seconds of 48 kHz audio make write_mp4 raise ArgumentError while encoding the video. Please interleave stream encoding or muxing and add a longer video/audio round-trip regression test before merging.

[Dere-Wah]

@tempusfrangit reproduced the 600-frame + 20 s audio failure and fixed it in e6ae667: every stream's packets are merged by decode time before muxing. test_a_long_video_and_audio_output_is_interleaved round-trips that exact input.