feat: read approximate frames

[alesanfra]

Reading a frame in the middle of a group of pictures costs every frame from the key frame on. When a frame nearby will do, approximate reads the key frame nearest to each number in frames instead, which costs one decoded frame.

# The nearest key frame within 5 frames, else the frame itself.
frames = list(iterframes.read("video.mp4", frames=[100, 200, 300], approximate=5))

The tolerance is the point. approximate=True accepts any distance, which in a video with a key frame every ten seconds answers three requests a second apart with the same frame; a number bounds the error instead, and a frame with no key frame that close is still read exactly. False, 0 and None read every frame exactly, and approximate with a slice raises ValueError.

What changed

• Selection::Frames carries the tolerance, so the type says the option goes with frames rather than a slice. selected maps each index through the new Seeker::nearest_key before decoding, and Seeker::frame is untouched.
• The index pass still reads every packet: the saving is in decoding alone. Two numbers that snap to the same key frame each get that frame, so the caller receives one frame per number asked for, in the order asked for.
• read, read_batches and FrameReader take approximate; the docs, the README and the reference describe it.

Tests

Nine cases in tests/test_select.py cover snapping to the nearest key frame, a tolerance that leaves distant frames exact, key frames that stand for themselves, repeats, the off switch, batches and both errors. test_approximate_frames_decode_less in tests/test_benchmark.py measures the saving: 0.018s exact against 0.010s approximate on the test video.

The landing page

The random access demo gained an Exact / approximate=45 switch that redraws the whole figure, so the difference is visible rather than described, and the heading now names what the figure shows.

The page is also restyled: warm paper, cards with a dashed inner edge, buttons that press, code in recessed slabs, sprocket holes on the strip of frames, and two self-hosted typefaces (Plus Jakarta Sans and JetBrains Mono, ~30 KB each, SIL OFL). No build step and no third-party request, as before. The social card is now rendered from web/og-card.html against the same stylesheet, so it cannot drift from the site.

🤖 Generated with Claude Code