diffusers-workflow 0.4.0__py3-none-any.whl

dw/loudness.py

@@ -0,0 +1,82 @@
+"""BS.1770 loudness measurement, shared by the media probe and the audio
+tasks so both read a level the same way.
+
+Peak and loudness are different quantities - a sparse voice-over and a dense
+score can share a peak and still sit tens of dB apart in how loud they sound,
+because a peak is one sample and loudness is measured over the whole track
+(#361). `integrated_lufs` is the BS.1770 integrated measure pyloudnorm
+implements; `true_peak_dbfs` is the inter-sample peak BS.1770 defines
+alongside it - a sample-peak reading can miss a peak that only appears
+between samples, which is what an encoder's reconstruction filter can ring
+up past 0 dBFS even when every decoded sample was under it.
+"""
+
+import logging
+import math
+
+import numpy
+import pyloudnorm
+import scipy.signal
+
+logger = logging.getLogger("dw")
+
+# The floor a level is reported at rather than -inf, which JSON cannot carry
+SILENCE_DBFS = -120.0
+
+# BS.1770's gating block is 400 ms; pyloudnorm refuses anything shorter
+MIN_LUFS_SECONDS = 0.4
+
+# Minimum oversampling BS.1770 defines for a true-peak measurement
+TRUE_PEAK_OVERSAMPLE = 4
+
+
+def _dbfs(value):
+    if value <= 0:
+        return SILENCE_DBFS
+    return max(SILENCE_DBFS, 20.0 * math.log10(float(value)))
+
+
+def integrated_lufs(samples, rate):
+    """Integrated loudness in LUFS, or None when it cannot be measured.
+
+    `samples` is (frames, channels) or (frames,). None for a clip shorter
+    than the 400 ms gating block, an all-silent clip (pyloudnorm's own
+    -inf, which JSON cannot carry either), or anything pyloudnorm refuses -
+    a measurement that failed reads as "unknown" rather than as a crashed
+    task or probe.
+    """
+    if samples is None or samples.size == 0:
+        return None
+    frames = samples.shape[0]
+    if frames < int(round(MIN_LUFS_SECONDS * rate)):
+        return None
+    try:
+        meter = pyloudnorm.Meter(rate)
+        value = float(meter.integrated_loudness(samples))
+    except Exception as e:
+        logger.debug(f"integrated_lufs: could not measure: {e}")
+        return None
+    if not math.isfinite(value):
+        return None
+    return value
+
+
+def true_peak_dbfs(samples, oversample=TRUE_PEAK_OVERSAMPLE):
+    """The inter-sample (true) peak of a track, in dBFS.
+
+    `samples` is (frames, channels) or (frames,). Oversamples with a
+    polyphase FIR (BS.1770's own reconstruction) and reads the peak of the
+    interpolated signal, which is what a lossy encoder's own reconstruction
+    filter can ring up past a sample-peak reading that stayed under 0 dBFS.
+    SILENCE_DBFS for an empty track, never None - unlike integrated
+    loudness, a true peak is defined for any track, including a silent one.
+    """
+    if samples is None or samples.size == 0:
+        return SILENCE_DBFS
+    try:
+        oversampled = scipy.signal.resample_poly(samples, oversample, 1, axis=0)
+    except Exception as e:
+        logger.debug(f"true_peak_dbfs: could not oversample: {e}")
+        oversampled = samples
+    peak = float(numpy.abs(oversampled).max(initial=0.0))
+    return _dbfs(peak)

dw/media_audio.py

@@ -0,0 +1,217 @@
+"""A soundtrack, or a named slice of one, as WAV bytes - the form
+get_output_audio hands an agent for a muxed video (whose container it
+cannot play) or for a track too long to send whole (#193).
+
+PyAV only, like media_info: this runs in the server process, where a
+request must not pull in torch or materialise frames.
+"""
+
+import io
+import logging
+import math
+import wave
+
+import av
+import numpy
+from av.audio.resampler import AudioResampler
+
+logger = logging.getLogger("dw")
+
+# The most a soundtrack may be as base64 before the gallery route refuses to
+# extract it whole - the twin of dw_mcp/media.py's MAX_RETURNED_BYTES (the
+# MCP package's cap on any inline payload). Two constants because the two
+# packages do not import each other; a whole track over this is cut off at
+# the header, before a frame is decoded, rather than decoded, shipped and
+# then refused by the client.
+MAX_INLINE_AUDIO_BYTES = 4 * 1024 * 1024
+
+
+class NoSoundtrack(ValueError):
+    """The file has no audio stream to extract."""
+
+
+def _container_duration(container):
+    """The container's own duration (seconds) from its header alone - no
+    stream is decoded to produce this number."""
+    return (
+        float(container.duration / av.time_base)
+        if container.duration is not None
+        else None
+    )
+
+
+def media_duration(path):
+    """The container's duration (seconds), read from its header alone - no
+    stream is decoded. `extract_audio` needs the same figure as `total`;
+    this is that computation, exposed for a caller that wants only the
+    length, since decoding to get one number defeats the "nothing to
+    extract" case (serving an audio file whole - #193)."""
+    with av.open(path) as container:
+        return _container_duration(container)
+
+
+def audio_shape(path):
+    """The soundtrack's duration (seconds), sample rate and channel count
+    from the container's headers alone - what projecting the size of a
+    whole-track WAV needs, and nothing decoded to get it. `None` when the
+    file has no audio stream."""
+    with av.open(path) as container:
+        if not container.streams.audio:
+            return None
+        stream = container.streams.audio[0]
+        return {
+            "duration_seconds": _container_duration(container),
+            "sample_rate": int(stream.rate),
+            "channels": int(stream.channels),
+        }
+
+
+def projected_wav_base64_size(shape):
+    """How many bytes the whole track would be as base64 16-bit PCM WAV -
+    `extract_audio`'s output for the same file, sized from `audio_shape`
+    without producing it. `None` when the container states no duration."""
+    if shape is None or shape["duration_seconds"] is None:
+        return None
+    pcm = int(shape["duration_seconds"] * shape["sample_rate"] * shape["channels"] * 2)
+    return 4 * math.ceil(pcm / 3)
+
+
+def extract_audio(path, start=None, duration=None):
+    """The soundtrack of `path` as 16-bit PCM WAV bytes, plus what was cut.
+
+    With `start` and `duration` (seconds) only that slice is decoded and
+    returned; the info dict says so (`excerpt: True`) and carries the whole
+    track's length as `of_seconds`, so a slice always names itself. A
+    slice that runs past the end is clipped to it; a `start` past the end
+    is refused, since an empty answer would read as a silent track.
+
+    Returns:
+        (wav_bytes, info) with info = {sample_rate, channels,
+        duration_seconds, of_seconds, start, excerpt}
+    """
+    excerpt = start is not None or duration is not None
+    start = float(start or 0.0)
+    if excerpt and (duration is None or float(duration) <= 0):
+        raise ValueError("An excerpt needs a duration above zero")
+    if start < 0:
+        raise ValueError("An excerpt cannot start before zero")
+
+    with av.open(path) as container:
+        if not container.streams.audio:
+            raise NoSoundtrack(f"{path} has no soundtrack")
+        stream = container.streams.audio[0]
+        total = _container_duration(container)
+        if total is not None and start >= total:
+            raise ValueError(
+                f"start {start:.2f}s is past the end of a {total:.2f}s track"
+            )
+        stop = start + float(duration) if excerpt else None
+        if stop is not None and total is not None:
+            stop = min(stop, total)
+
+        rate = int(stream.rate)
+        channels = int(stream.channels)
+        layout = (
+            "stereo"
+            if channels == 2
+            else ("mono" if channels == 1 else stream.layout.name)
+        )
+        resampler = AudioResampler(format="s16", layout=layout, rate=rate)
+
+        # pts is a timestamp on the container's clock, not an offset from
+        # this stream's first sample: a stream with an edit list or a
+        # non-zero start (which real muxers write) carries a `start_time`,
+        # and both the seek target and each frame's clock have to be
+        # zeroed against it before they mean seconds into the track -
+        # the same anchor `_read_frames` in media_frames uses. Unanchored,
+        # `start=2.5` on a track shifted by one second came back from
+        # about 1.5 s: the wrong audio, silently.
+        anchor = stream.start_time if stream.start_time is not None else 0
+        if start > 0:
+            # Seek to the keyframe at or before `start`, less one packet of
+            # pre-roll: the first packet a decoder sees after a seek is its
+            # warm-up, and for AAC and mp3 the samples it yields come out
+            # attenuated or silent - so an excerpt at 2.5 s opened with a
+            # gap that is not in the file. Landing a packet early hands that
+            # warm-up to samples the pts-based trim below drops anyway.
+            frame_size = int(stream.codec_context.frame_size or 0)
+            preroll = frame_size / rate if frame_size else 0.1
+            container.seek(
+                int(max(0.0, start - preroll) / stream.time_base) + anchor,
+                stream=stream,
+                backward=True,
+            )
+
+        pieces = []
+        seen = 0  # samples decoded so far - the clock for a frame with no pts
+        started = False
+        done = False  # Break outer loop when stop time is reached
+        sought = start > 0
+        restarted = False
+        for frame in container.decode(stream):
+            if done:
+                break
+            if frame.pts is None and sought and not restarted:
+                # No pts means the seek's landing cannot be known, so the
+                # sample count is the only clock there is - and it has to
+                # count from the top. Start over once and read to `start`.
+                container.seek(0, stream=stream, backward=True)
+                resampler = AudioResampler(format="s16", layout=layout, rate=rate)
+                restarted = True
+                seen = 0
+                continue
+            frame_start = (
+                float((frame.pts - anchor) * stream.time_base)
+                if frame.pts is not None
+                else seen / rate
+            )
+            for chunk in resampler.resample(frame):
+                samples = chunk.to_ndarray()  # (1, samples * channels) packed s16
+                samples = samples.reshape(-1, channels)
+                chunk_start = frame_start
+                chunk_end = chunk_start + samples.shape[0] / rate
+                seen += samples.shape[0]
+                frame_start = chunk_end  # a frame yielding two chunks: the second follows the first
+                if chunk_end <= start:
+                    continue
+                if not started and chunk_start < start:
+                    # round, not floor: float pts arithmetic lands a hair
+                    # under the exact sample and floor then keeps one too many
+                    samples = samples[int(round((start - chunk_start) * rate)) :]
+                    chunk_start = start
+                started = True
+                if stop is not None and chunk_end > stop:
+                    samples = samples[: max(0, int(round((stop - chunk_start) * rate)))]
+                pieces.append(samples)
+                if stop is not None and chunk_end >= stop:
+                    done = True
+                    break
+        # Flush the resampler whatever ended the loop: it may still hold
+        # samples that belong before `stop`. Anything past `stop` is cut.
+        held = sum(p.shape[0] for p in pieces)
+        for chunk in resampler.resample(None):
+            samples = chunk.to_ndarray().reshape(-1, channels)
+            if stop is not None:
+                room = max(0, int(round((stop - start) * rate)) - held)
+                samples = samples[:room]
+            if samples.shape[0]:
+                pieces.append(samples)
+                held += samples.shape[0]
+
+    pcm = numpy.concatenate(pieces) if pieces else numpy.zeros((0, channels), "<i2")
+    buffer = io.BytesIO()
+    with wave.open(buffer, "w") as handle:
+        handle.setnchannels(channels)
+        handle.setsampwidth(2)
+        handle.setframerate(rate)
+        handle.writeframes(pcm.astype("<i2").tobytes())
+
+    returned = pcm.shape[0] / rate
+    return buffer.getvalue(), {
+        "sample_rate": rate,
+        "channels": channels,
+        "duration_seconds": returned,
+        "of_seconds": total if total is not None else returned,
+        "start": start,
+        "excerpt": excerpt,
+    }

dw/media_frames.py

@@ -0,0 +1,367 @@
+"""Frames out of a video file by seeking to them - a moment, an evenly
+spaced contact sheet, or the frame pair either side of a seam - without
+decoding the clip whole. The server process runs this per request; a
+four-minute 1080p clip materialised as PIL frames is tens of gigabytes,
+so nothing here ever holds more than the frames it returns, each already
+fitted to its tile where a caller asked for many (#193).
+"""
+
+import logging
+import math
+
+import av
+import numpy
+from PIL import Image
+
+from .tasks.video_utils import (
+    _compose_grid,
+    _default_columns,
+    _evenly_spaced_indices,
+    _format_timestamp,
+    _grid_tile,
+)
+
+logger = logging.getLogger("dw")
+
+# Each cell of a contact sheet and each side of a seam pair is a seek, a
+# decode and a resize in the server process; a sheet past 64 cells is
+# unreadable anyway, and `at` has its own cap in the route
+# (MAX_FRAME_MOMENTS). Both are ValueErrors, so the route answers 400.
+MAX_CONTACT_SHEET_FRAMES = 64
+MAX_SEAMS = 32
+
+
+def video_shape(path):
+    """Frame count, fps and size, from the container's own headers where
+    they are written and by counting otherwise."""
+    with av.open(path) as container:
+        if not container.streams.video:
+            raise ValueError(f"{path} has no video stream")
+        stream = container.streams.video[0]
+        fps = float(stream.average_rate) if stream.average_rate else None
+        count = int(stream.frames) if stream.frames else None
+        if count is None:
+            count = sum(1 for _ in container.decode(stream))
+        return {
+            "frame_count": count,
+            "fps": fps,
+            "width": int(stream.width),
+            "height": int(stream.height),
+        }
+
+
+def resolve_crop_box(crop, width, height):
+    """`[x, y, w, h]` as Pillow's `(left, upper, right, lower)`, clamped to
+    a frame. Every frame of one video shares the same dimensions, so a
+    caller resolves this once against `video_shape(path)` and reuses it
+    across every tile - the same `[x, y, width, height]` convention
+    `get_output_image`'s crop uses. Refused when it is not four
+    non-negative integers, starts outside the frame, or has nothing in it."""
+    try:
+        x, y, w, h = (int(v) for v in crop)
+    except (TypeError, ValueError):
+        raise ValueError(f"crop must be [x, y, width, height] in pixels, got {crop!r}.")
+    if x < 0 or y < 0 or w <= 0 or h <= 0:
+        raise ValueError(
+            f"crop must have a non-negative origin and a positive size, got {crop!r}."
+        )
+    if x >= width or y >= height:
+        raise ValueError(
+            f"crop origin ({x}, {y}) lies outside the {width}x{height} frame."
+        )
+    return (x, y, min(x + w, width), min(y + h, height))
+
+
+def frames_at(path, moments, shape=None, crop_box=None):
+    """One tile per moment - a float in seconds or "frame:N" - in the order
+    asked for. Each tile is {label, frame, seconds, image}.
+
+    `shape` reuses an already-computed `video_shape(path)` - a caller such
+    as the gallery route that also reports the clip's own frame_count/fps
+    would otherwise pay for `video_shape`'s container open (and, lacking a
+    header frame count, a full decode) a second time for the same answer.
+
+    `crop_box` (`resolve_crop_box`'s Pillow box) is cut from each frame
+    right after decode, before it is returned - full source resolution,
+    not whatever a caller's `max_dimension` later downscales it to."""
+    shape = shape if shape is not None else video_shape(path)
+    indexes = [_moment_to_index(moment, shape) for moment in moments]
+    fit = (lambda image, index: image.crop(crop_box)) if crop_box else None
+    images = _read_frames(path, indexes, fit=fit)
+    return [_tile(index, images[index], shape) for index in indexes]
+
+
+def contact_sheet(path, count, tile_width=320, shape=None, crop_box=None):
+    """N evenly spaced frames (first and last included) tiled into one
+    image - frame_grid without a workflow. `shape` reuses an
+    already-computed `video_shape(path)`; see `frames_at`.
+
+    `crop_box`, as in `frames_at`, is cut from each frame before it is
+    stamped and tiled into the sheet - the sheet is built from cropped
+    frames rather than cropped after assembly, so the box means the same
+    source-pixel region whatever the sheet's own `tile_width` ends up."""
+    if int(count) < 1:
+        raise ValueError("count must be at least 1")
+    shape = shape if shape is not None else video_shape(path)
+    # Clamp to the clip's own length before checking the cap: a count that
+    # would only ever produce a handful of cells (a short clip) should not
+    # be refused for the raw number the caller asked for.
+    count = min(int(count), shape["frame_count"])
+    if count > MAX_CONTACT_SHEET_FRAMES:
+        raise ValueError(
+            f"count {count} is more than a contact sheet holds "
+            f"({MAX_CONTACT_SHEET_FRAMES}); ask for a smaller one, or `at` for moments"
+        )
+    indexes = _evenly_spaced_indices(shape["frame_count"], count)
+
+    def fit(image, index):
+        if crop_box:
+            image = image.crop(crop_box)
+        return _stamped_tile(image, index, shape["fps"], tile_width)
+
+    images = _read_frames(path, indexes, fit=fit)
+    tiles = [images[index] for index in indexes]
+    grid = _compose_grid(tiles, _default_columns(len(tiles)))
+    return {
+        "label": f"contact sheet, {len(tiles)} frames",
+        "frame": indexes[0],
+        "seconds": _seconds(indexes[0], shape),
+        "image": grid,
+        "frames": list(indexes),
+    }
+
+
+def seam_tiles(
+    path, boundaries, names=None, tile_width=320, shape=None, wanted=None, crop_box=None
+):
+    """For each boundary (the frame index a shot *starts* at), the last
+    frame before it and the first frame at it, side by side - the seam and
+    continuity evidence in one image. Seam i sits between shot i and shot
+    i+1; `names` names the shots, "shot 1".. by default.
+
+    `boundaries` and `names` are validated in full regardless of `wanted` -
+    they describe the whole cut, and a seam's label names the shots either
+    side of it by position in that full list. `wanted` (a set of 1-based
+    seam numbers, or None for all) then limits which seams are actually
+    decoded and composed: a caller after seam 2 of twelve should not pay to
+    decode and tile the other eleven. `shape` reuses an already-computed
+    `video_shape(path)`; see `frames_at`.
+
+    `crop_box`, as in `frames_at`, is cut from each source frame before it
+    is fit to `tile_width` and paired into a seam - the pair is built from
+    cropped frames rather than cropped after pairing."""
+    shape = shape if shape is not None else video_shape(path)
+    total = shape["frame_count"]
+    for boundary in boundaries:
+        if not 1 <= int(boundary) <= total - 1:
+            raise ValueError(
+                f"boundary {boundary} is not inside the clip (1..{total - 1})"
+            )
+    boundaries = [int(b) for b in boundaries]
+    names = list(names or [f"shot {n + 1}" for n in range(len(boundaries) + 1)])
+    if len(names) != len(boundaries) + 1:
+        raise ValueError(
+            f"{len(boundaries)} boundaries make {len(boundaries) + 1} shots, "
+            f"but {len(names)} names were given"
+        )
+    if wanted is not None:
+        off = sorted(int(s) for s in wanted if not 1 <= int(s) <= len(boundaries))
+        if off:
+            raise ValueError(
+                f"seam {', '.join(str(s) for s in off)} is not in this cut - "
+                f"{len(boundaries)} boundaries make seams 1..{len(boundaries)}"
+            )
+    chosen = [
+        (seam, boundary)
+        for seam, boundary in enumerate(boundaries, start=1)
+        if wanted is None or seam in wanted
+    ]
+    if len(chosen) > MAX_SEAMS:
+        raise ValueError(
+            f"{len(chosen)} seams is more than one call serves ({MAX_SEAMS}); "
+            "name the seams wanted (`seams=1,2,...`)"
+        )
+    frame_indexes = sorted({b - 1 for _, b in chosen} | {b for _, b in chosen})
+
+    def fit(image, _index):
+        if crop_box:
+            image = image.crop(crop_box)
+        return _fit_width(image, tile_width)
+
+    images = _read_frames(path, frame_indexes, fit=fit)
+    tiles = []
+    for seam, boundary in chosen:
+        before = images[boundary - 1]
+        after = images[boundary]
+        pair = _compose_grid([before, after], 2)
+        difference = float(
+            numpy.abs(
+                numpy.asarray(before, dtype=numpy.int16)
+                - numpy.asarray(after, dtype=numpy.int16)
+            ).mean()
+        )
+        tiles.append(
+            {
+                "label": f"seam {seam}: {names[seam - 1]} | {names[seam]}",
+                "frame": boundary,
+                "seconds": _seconds(boundary, shape),
+                "difference": round(difference, 2),
+                "image": pair,
+            }
+        )
+    return tiles
+
+
+def _moment_to_index(moment, shape):
+    total = shape["frame_count"]
+    if isinstance(moment, str) and moment.startswith("frame:"):
+        raw = moment[len("frame:") :]
+        try:
+            index = int(raw)
+        except ValueError:
+            raise ValueError(f'"{moment}" - frame index must be a whole number')
+        if index < 0:
+            index += total
+        if not 0 <= index < total:
+            raise ValueError(
+                f"frame {index} is past the end of a {total}-frame clip "
+                f"(frames 0-{total - 1})"
+            )
+        return index
+    fps = shape["fps"]
+    if fps is None:
+        raise ValueError("this clip has no frame rate, so name a frame: 'frame:N'")
+    seconds = float(moment)
+    if not math.isfinite(seconds):
+        raise ValueError(f"{moment!r} is not a moment in seconds")
+    index = int(round(seconds * fps))
+    if index < 0:
+        index += total
+    if not 0 <= index < total:
+        duration = total / fps
+        message = (
+            f"{moment!r} s is past the end of a {duration:.2f} s "
+            f"({total}-frame) clip - bare numbers in 'at' are seconds"
+        )
+        # A fractional value is a seconds overshoot, not a frame index in
+        # disguise - the frame: hint only makes sense for a whole number
+        # that would itself be a valid frame index.
+        if seconds.is_integer() and 0 <= int(seconds) < total:
+            message += f'; use "frame:{_format_moment(moment)}" for a frame index'
+        raise ValueError(message)
+    return index
+
+
+def _format_moment(moment):
+    if isinstance(moment, float) and moment.is_integer():
+        return str(int(moment))
+    return str(moment)
+
+
+def _seconds(index, shape):
+    return index / shape["fps"] if shape["fps"] else float(index)
+
+
+def _tile(index, image, shape):
+    fps = shape["fps"]
+    stamp = _format_timestamp(index, fps) if fps else f"#{index}"
+    return {
+        "label": f"{stamp} (frame {index})",
+        "frame": index,
+        "seconds": _seconds(index, shape),
+        "image": image,
+    }
+
+
+def _stamped_tile(image, index, fps, tile_width):
+    """A contact-sheet cell: fitted like `_fit_width` (never upscaled) and
+    stamped with its timestamp by `frame_grid`'s own tile maker, so the
+    sheet says which cell is which without the text part."""
+    return _grid_tile(image, index, fps, min(int(tile_width), image.width), label=True)
+
+
+def _fit_width(image, tile_width):
+    # never upscaled: a tile wider than its source is a blurred enlargement
+    # that costs bytes and shows nothing the source holds
+    tile_width = min(int(tile_width), image.width)
+    height = max(1, round(image.height * tile_width / image.width))
+    return image.resize((tile_width, height), Image.LANCZOS).convert("RGB")
+
+
+def _read_frames(path, indexes, fit=None):
+    """The frames at these indexes, as {index: PIL image}, in one forward
+    pass that seeks to the keyframe before each wanted frame rather than
+    decoding from the top. Decodes are dropped as soon as they are past.
+
+    `fit(image, index)`, when given, is applied to each frame as it is
+    decoded, so a caller tiling many frames never holds one at source size.
+
+    This assumes a constant frame rate, which every file this engine writes
+    has (`encode_video` / `export_to_video` write a fixed `fps`): a
+    `backward=True` seek lands on the keyframe at or before the target
+    timestamp, and `frame.pts * stream.time_base` converts that keyframe's
+    own presentation time back to an exact frame index (`round(seconds *
+    fps)`) - verified against PyAV 18.1's actual seek landings (a
+    single-keyframe short clip, where every seek lands on frame 0; a `g=10`
+    multi-keyframe clip, where a seek to frame 95 lands exactly on frame 90;
+    and a clip whose packets carry a 5-frame pts offset - an edit list or a
+    non-zero start, which real muxers write - where the raw pts arithmetic
+    landed 5 frames off until it was anchored on `stream.start_time`).
+    `start_pts` is that anchor: pts is a timestamp against the *container's*
+    clock, not a frame count from this stream's first frame, so it has to be
+    zeroed against wherever this stream actually starts before it means a
+    frame index. `position` is then a plain frame counter from that
+    landing, decoding forward to the target and dropping what is skipped
+    past.
+    """
+    wanted = sorted(set(int(i) for i in indexes))
+    found = {}
+    with av.open(path) as container:
+        stream = container.streams.video[0]
+        fps = float(stream.average_rate) if stream.average_rate else None
+        start_pts = stream.start_time if stream.start_time is not None else 0
+        position = 0  # index of the next frame decode() will yield
+        for target in wanted:
+            if target < position or target - position > 2 * (int(fps) if fps else 24):
+                # seek back or a long way forward: land on the keyframe at
+                # or before the target, then read up to it. The seek target
+                # is a container timestamp too, so it needs the same anchor.
+                seconds = target / fps if fps else 0.0
+                container.seek(
+                    int(seconds / stream.time_base) + start_pts,
+                    stream=stream,
+                    backward=True,
+                )
+                position = None
+            recovered = False
+            for frame in container.decode(stream):
+                if position is None:
+                    # first frame after a seek says where we landed
+                    position = (
+                        int(
+                            round(
+                                float((frame.pts - start_pts) * stream.time_base) * fps
+                            )
+                        )
+                        if fps and frame.pts is not None
+                        else 0
+                    )
+                    if position > target and not recovered:
+                        # Landed past the target: the keyframe estimate was
+                        # wrong for this file (off-rate or VFR). Reading on
+                        # would scan to EOF and blame the caller; read from
+                        # the top once instead, which is always correct.
+                        container.seek(start_pts, stream=stream, backward=True)
+                        position = None
+                        recovered = True
+                        continue
+                if position == target:
+                    image = frame.to_image()
+                    found[target] = fit(image, target) if fit is not None else image
+                    position += 1
+                    break
+                position += 1
+        missing = [i for i in wanted if i not in found]
+        if missing:
+            raise ValueError(f"could not decode frame(s) {missing} of {path}")
+    return found