Skip to content

Commit c3ee742

Browse files
committed
fix(video): bound raw frame reads by the shared pixel budget (#807)
1 parent b9f3e35 commit c3ee742

7 files changed

Lines changed: 136 additions & 16 deletions

File tree

‎docs/how-to/stream-camera-motion.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -73,7 +73,9 @@ An input with N frames yields max(0, N−1) observations. Empty or single-frame
7373
inputs have no adjacent pairs. A pair's interval runs from its earlier frame to
7474
its later frame; the final frame's display duration is not an extra measured
7575
interval. Invalid frame shapes and decoding errors raise rather than being
76-
reported as camera stability evidence.
76+
reported as camera stability evidence. A video whose frames exceed 33,554,432
77+
pixels, the default `VideoLimits.maximum_frame_pixels` that `probe_video` and
78+
video import enforce, raises before any frame is decoded.
7779

7880
## Interpret motion and fit evidence
7981

‎src/hflow/_frame_budget.py‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
"""The default decoded-frame size budget shared by video probing and raw-frame readers.
2+
3+
This module has no dependencies so the extractable ``hflow._video_measurements``
4+
package can share the default with ``hflow.media.VideoLimits``.
5+
"""
6+
7+
DEFAULT_MAXIMUM_FRAME_PIXELS = 33554432
8+
_FFMPEG_MAXIMUM_PIXELS_OPTION_LIMIT = 2**31 - 1
9+
10+
11+
def ffmpeg_decoder_maximum_pixels(maximum_frame_pixels: int) -> int:
12+
"""Return FFmpeg's ``-max_pixels`` decoder option for a frame budget.
13+
14+
FFmpeg checks the stride-aligned width (up to 64 padding columns) against
15+
``-max_pixels``, so the decoder needs headroom to accept every frame that fits
16+
the budget. Twice the budget still bounds what a stream that changes after it
17+
was probed can make the decoder allocate.
18+
"""
19+
return min(2 * maximum_frame_pixels, _FFMPEG_MAXIMUM_PIXELS_OPTION_LIMIT)

‎src/hflow/_video_measurements/_raw_frames.py‎

Lines changed: 56 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -7,11 +7,14 @@
77
from contextlib import contextmanager
88
from dataclasses import dataclass
99
from fractions import Fraction
10-
from math import ceil
10+
from math import ceil, prod
1111
from pathlib import Path
1212

1313
import numpy as np
1414

15+
from hflow._field_guards import require_positive_int
16+
from hflow._frame_budget import DEFAULT_MAXIMUM_FRAME_PIXELS, ffmpeg_decoder_maximum_pixels
17+
1518
from ._bounded_process import BoundedProcessError, run_bounded_process
1619
from ._frame_integrity import cleanly_decoded_frame_indices
1720
from ._toolchain import VideoMeasurementToolchain
@@ -26,6 +29,8 @@ class RawFrameError(RuntimeError):
2629
MAXIMUM_DECODED_FRAME_HASH_OUTPUT_BYTES = 256 * 1024 * 1024
2730
FFPROBE_TIMEOUT_SECONDS = 600.0
2831
MAXIMUM_FFPROBE_OUTPUT_BYTES = 256 * 1024 * 1024
32+
# rgb24 is the widest pixel format these readers request.
33+
_MAXIMUM_BYTES_PER_PIXEL = 3
2934

3035

3136
@dataclass(frozen=True)
@@ -54,7 +59,9 @@ def _run_ffprobe(video: Path, toolchain: VideoMeasurementToolchain, arguments: l
5459
return completed_process.stdout
5560

5661

57-
def _probe_frame_shape(video: Path, toolchain: VideoMeasurementToolchain) -> tuple[int, int]:
62+
def _probe_frame_shape(
63+
video: Path, toolchain: VideoMeasurementToolchain, *, maximum_frame_pixels: int
64+
) -> tuple[int, int]:
5865
"""Return the coded ``(height, width)`` of the first video stream."""
5966
output = _run_ffprobe(
6067
video,
@@ -85,9 +92,27 @@ def _probe_frame_shape(video: Path, toolchain: VideoMeasurementToolchain) -> tup
8592
or frame_height <= 0
8693
):
8794
raise RawFrameError(f"ffprobe reported invalid video dimensions for {video}")
95+
_require_frame_within_pixel_budget(video, (frame_height, frame_width), maximum_frame_pixels)
8896
return frame_height, frame_width
8997

9098

99+
def _require_frame_within_pixel_budget(
100+
video: Path, frame_shape: tuple[int, ...], maximum_frame_pixels: int
101+
) -> None:
102+
"""Refuse a ``(height, width[, channels])`` frame larger than the pixel budget."""
103+
require_positive_int(maximum_frame_pixels, "maximum_frame_pixels")
104+
frame_height, frame_width, *channel_dimensions = frame_shape
105+
if frame_height * frame_width > maximum_frame_pixels:
106+
raise RawFrameError(
107+
f"{video} has {frame_width}x{frame_height} frames, which exceed the "
108+
f"{maximum_frame_pixels}-pixel frame budget"
109+
)
110+
if prod(channel_dimensions) > _MAXIMUM_BYTES_PER_PIXEL:
111+
raise RawFrameError(
112+
f"raw frames for {video} cannot exceed {_MAXIMUM_BYTES_PER_PIXEL} bytes per pixel"
113+
)
114+
115+
91116
def _probe_frame_rate(video: Path, toolchain: VideoMeasurementToolchain) -> float:
92117
"""Return the stream's declared constant frame rate."""
93118
output = _run_ffprobe(
@@ -170,6 +195,7 @@ def _decoded_frame_hashes(
170195
filter_graph: str,
171196
source_fps: float,
172197
sample_fps: float | None,
198+
maximum_frame_pixels: int = DEFAULT_MAXIMUM_FRAME_PIXELS,
173199
) -> tuple[list[int], dict[int, set[str]]]:
174200
"""Trace decoded RGB digests without writing frame data or a sidecar file."""
175201
command = [
@@ -179,6 +205,8 @@ def _decoded_frame_hashes(
179205
"-loglevel",
180206
"error",
181207
"-noautorotate",
208+
"-max_pixels",
209+
str(ffmpeg_decoder_maximum_pixels(maximum_frame_pixels)),
182210
"-i",
183211
str(video),
184212
"-map",
@@ -269,16 +297,20 @@ def _raw_frame_stream(
269297
toolchain: VideoMeasurementToolchain,
270298
filter_graph: str,
271299
frame_shape: tuple[int, ...],
300+
maximum_frame_pixels: int = DEFAULT_MAXIMUM_FRAME_PIXELS,
272301
) -> Generator[Iterator[np.ndarray], None, None]:
273302
"""Yield complete ``uint8`` frames from one owned FFmpeg process."""
274-
frame_byte_count = int(np.prod(frame_shape))
303+
_require_frame_within_pixel_budget(video, frame_shape, maximum_frame_pixels)
304+
frame_byte_count = prod(frame_shape)
275305
command = [
276306
str(toolchain.ffmpeg_executable),
277307
"-nostdin",
278308
"-hide_banner",
279309
"-loglevel",
280310
"error",
281311
"-noautorotate",
312+
"-max_pixels",
313+
str(ffmpeg_decoder_maximum_pixels(maximum_frame_pixels)),
282314
"-i",
283315
str(video),
284316
"-map",
@@ -330,15 +362,22 @@ def read_frames() -> Iterator[np.ndarray]:
330362

331363
@contextmanager
332364
def luma_frames(
333-
video: Path, *, toolchain: VideoMeasurementToolchain
365+
video: Path,
366+
*,
367+
toolchain: VideoMeasurementToolchain,
368+
maximum_frame_pixels: int = DEFAULT_MAXIMUM_FRAME_PIXELS,
334369
) -> Generator[Iterator[np.ndarray], None, None]:
335-
"""Yield coded-size ``(height, width)`` 8-bit luma frames in order."""
336-
frame_shape = _probe_frame_shape(video, toolchain)
370+
"""Yield coded-size ``(height, width)`` 8-bit luma frames in order.
371+
372+
A video whose frames exceed ``maximum_frame_pixels`` raises before decoding.
373+
"""
374+
frame_shape = _probe_frame_shape(video, toolchain, maximum_frame_pixels=maximum_frame_pixels)
337375
with _raw_frame_stream(
338376
video,
339377
toolchain=toolchain,
340378
filter_graph=LUMA_FRAME_FILTER_GRAPH,
341379
frame_shape=frame_shape,
380+
maximum_frame_pixels=maximum_frame_pixels,
342381
) as frames:
343382
yield frames
344383

@@ -351,6 +390,7 @@ def rgb_frames(
351390
frames_per_second: float | None = None,
352391
long_edge_pixels: int | None = None,
353392
source_fps: float | None = None,
393+
maximum_frame_pixels: int = DEFAULT_MAXIMUM_FRAME_PIXELS,
354394
) -> Generator[Iterator[SampledRGBFrame], None, None]:
355395
"""Yield sampled RGB frames with their original sample and source positions.
356396
@@ -359,11 +399,14 @@ def rgb_frames(
359399
comparing their digests filters out frames the ``fps`` filter repeated to
360400
fill decoder gaps. No full-video pixel buffer or temporary file is needed.
361401
``sample_index`` preserves the original tick so callers can keep labels
362-
aligned when a tick is omitted.
402+
aligned when a tick is omitted. A source or sample frame that exceeds
403+
``maximum_frame_pixels`` raises before decoding.
363404
"""
364405
if frames_per_second is not None and frames_per_second <= 0:
365406
raise ValueError(f"frames_per_second must be positive, got {frames_per_second}")
366-
source_height, source_width = _probe_frame_shape(video, toolchain)
407+
source_height, source_width = _probe_frame_shape(
408+
video, toolchain, maximum_frame_pixels=maximum_frame_pixels
409+
)
367410
frame_height, frame_width = _scaled_frame_shape((source_height, source_width), long_edge_pixels)
368411
if source_fps is None:
369412
source_fps = _probe_frame_rate(video, toolchain)
@@ -385,12 +428,16 @@ def rgb_frames(
385428
decoded_filter_graph = ",".join(decoded_filters)
386429
sampled_filter_graph = ",".join(sampled_filters)
387430
frame_shape = (frame_height, frame_width, 3)
431+
# An upscaling ``long_edge_pixels`` would otherwise make FFmpeg build
432+
# oversized frames for the digest trace before the raw reader refuses them.
433+
_require_frame_within_pixel_budget(video, frame_shape, maximum_frame_pixels)
388434
decoded_indices, decoded_hashes = _decoded_frame_hashes(
389435
video,
390436
toolchain=toolchain,
391437
filter_graph=decoded_filter_graph,
392438
source_fps=source_fps,
393439
sample_fps=effective_sample_fps,
440+
maximum_frame_pixels=maximum_frame_pixels,
394441
)
395442
clean_decoded_indices = cleanly_decoded_frame_indices(
396443
set(decoded_indices),
@@ -403,6 +450,7 @@ def rgb_frames(
403450
toolchain=toolchain,
404451
filter_graph=sampled_filter_graph,
405452
frame_shape=frame_shape,
453+
maximum_frame_pixels=maximum_frame_pixels,
406454
) as candidate_frames:
407455

408456
def read_frames() -> Iterator[SampledRGBFrame]:

‎src/hflow/media.py‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,14 +16,15 @@
1616
from decimal import ROUND_CEILING, Decimal, InvalidOperation
1717
from pathlib import Path
1818

19+
from hflow._frame_budget import DEFAULT_MAXIMUM_FRAME_PIXELS
1920
from hflow.byte_range_source import LoopbackVideoSource, media_input
2021
from hflow.ffmpeg import ffmpeg_path, ffprobe_path
2122
from hflow.ffmpeg._process import MediaToolError, media_input_was_rejected, run_media_command
2223

2324

2425
@dataclass(frozen=True)
2526
class VideoLimits:
26-
maximum_frame_pixels: int = 33554432
27+
maximum_frame_pixels: int = DEFAULT_MAXIMUM_FRAME_PIXELS
2728
maximum_frames_per_second: float = 240.0
2829
minimum_duration_seconds: float = 0.001
2930
maximum_duration_seconds: float = 86400.0

‎src/hflow/window_measurements.py‎

Lines changed: 17 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@
2626

2727
import numpy as np
2828

29+
from hflow._frame_budget import ffmpeg_decoder_maximum_pixels
2930
from hflow._video_measurement_toolchain import resolved_video_measurement_toolchain
3031
from hflow._video_measurements._frame_statistics import (
3132
FRAME_STATISTICS_DEFINITION_VERSION,
@@ -244,6 +245,9 @@ def _measure_video_window(
244245
f"{measured_window.start_seconds:.3f}",
245246
"-t",
246247
f"{measured_window.duration_seconds:.3f}",
248+
# The probe and this decode open the source separately.
249+
"-max_pixels",
250+
str(ffmpeg_decoder_maximum_pixels(limits.maximum_frame_pixels)),
247251
"-i",
248252
str(source.resolve()),
249253
"-filter_complex",
@@ -272,7 +276,10 @@ def stop_after_timeout() -> None:
272276
try:
273277
if selection.camera_shake is not None:
274278
assert decoding_process.stdout is not None
275-
luma_frames = _Y4mLumaFrames(decoding_process.stdout)
279+
luma_frames = _Y4mLumaFrames(
280+
decoding_process.stdout,
281+
maximum_frame_pixels=limits.maximum_frame_pixels,
282+
)
276283
try:
277284
camera_shake = summarize_camera_shake(
278285
filter_camera_shake(
@@ -439,8 +446,9 @@ def _shared_decode_graph(
439446
class _Y4mLumaFrames(Iterator[np.ndarray]):
440447
"""Read grey YUV4MPEG2 frames; the header carries the rotated output size."""
441448

442-
def __init__(self, stream: IO[bytes]) -> None:
449+
def __init__(self, stream: IO[bytes], *, maximum_frame_pixels: int) -> None:
443450
self._stream = stream
451+
self._maximum_frame_pixels = maximum_frame_pixels
444452
self._frame_shape: tuple[int, int] | None = None
445453
self.frame_count = 0
446454

@@ -452,7 +460,13 @@ def __next__(self) -> np.ndarray:
452460
dimensions = _Y4M_DIMENSIONS.search(header)
453461
if not header.startswith(b"YUV4MPEG2 ") or dimensions is None:
454462
raise MediaToolError("window decode produced an invalid luma stream header")
455-
self._frame_shape = (int(dimensions["height"]), int(dimensions["width"]))
463+
frame_height, frame_width = int(dimensions["height"]), int(dimensions["width"])
464+
if frame_height * frame_width > self._maximum_frame_pixels:
465+
raise MediaToolError(
466+
f"window decode produced {frame_width}x{frame_height} luma frames, which "
467+
f"exceed the {self._maximum_frame_pixels}-pixel frame budget"
468+
)
469+
self._frame_shape = (frame_height, frame_width)
456470
frame_header = self._stream.readline()
457471
if not frame_header:
458472
raise StopIteration

‎tests/test_ffmpeg.py‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@
1515
import sys
1616
import tarfile
1717
from collections.abc import Callable, Iterator
18+
from dataclasses import replace
1819
from pathlib import Path
1920
from types import SimpleNamespace
2021
from typing import Any, cast
@@ -832,6 +833,30 @@ def test_raw_frames_stream_every_frame_at_the_coded_size(
832833
assert set(shapes) == {expected_shape}
833834

834835

836+
@pytest.mark.parametrize(
837+
"frame_reader",
838+
[pytest.param(luma_frames, id="luma"), pytest.param(rgb_frames, id="rgb")],
839+
)
840+
def test_raw_frames_refuse_frames_over_the_pixel_limit_before_decoding(
841+
black_tail_video: Path, tmp_path: Path, frame_reader: Callable[..., Any]
842+
) -> None:
843+
"""The real FFprobe reports 160x120; a stand-in FFmpeg records any decode attempt."""
844+
decode_attempt_marker = tmp_path / "ffmpeg-was-started"
845+
recording_ffmpeg = tmp_path / "ffmpeg"
846+
recording_ffmpeg.write_text(f'#!/bin/sh\ntouch "{decode_attempt_marker}"\nexit 1\n')
847+
recording_ffmpeg.chmod(0o755)
848+
toolchain = replace(resolved_video_measurement_toolchain(), ffmpeg_executable=recording_ffmpeg)
849+
850+
with (
851+
pytest.raises(RawFrameError, match="160x120 frames, which exceed the 19199-pixel"),
852+
frame_reader(
853+
black_tail_video, toolchain=toolchain, maximum_frame_pixels=160 * 120 - 1
854+
) as frames,
855+
):
856+
list(frames)
857+
assert not decode_attempt_marker.exists()
858+
859+
835860
def test_luma_frames_reaps_ffmpeg_when_the_caller_stops_early(
836861
black_tail_video: Path,
837862
) -> None:

‎tests/test_module_boundaries.py‎

Lines changed: 14 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -29,12 +29,23 @@ class _ImportBoundary:
2929
_ImportBoundary(
3030
source_paths=tuple(sorted(Path(video_measurements.__file__).parent.rglob("*.py"))),
3131
restricted_module_prefix="hflow",
32-
allowed_modules=frozenset({"hflow._field_guards"}),
32+
allowed_modules=frozenset({"hflow._field_guards", "hflow._frame_budget"}),
3333
scope=_ImportScope.ALL,
3434
rule=(
3535
"the video-measurements package must not import hflow or any hflow.* module "
36-
"other than the dependency-free hflow._field_guards type guards, because it is "
37-
"designed to be extracted into a standalone package"
36+
"other than the dependency-free hflow._field_guards type guards and "
37+
"hflow._frame_budget default, because it is designed to be extracted into a "
38+
"standalone package"
39+
),
40+
),
41+
_ImportBoundary(
42+
source_paths=(_HFLOW_PACKAGE_DIRECTORY / "_frame_budget.py",),
43+
restricted_module_prefix="hflow",
44+
allowed_modules=frozenset(),
45+
scope=_ImportScope.ALL,
46+
rule=(
47+
"hflow._frame_budget must stay dependency-free so the video-measurements "
48+
"package can share it with hflow.media"
3849
),
3950
),
4051
_ImportBoundary(

0 commit comments

Comments
 (0)