annie.media.clipping

Cut a browser-playable sub-clip of a video for one segment band (service).

The Segment-review task lets a reviewer watch a band’s exact [start, end) span before accepting or dropping it. cut_clip() re-encodes that span to a small MP4 the browser can play inline. The cut is frame-accurate — the input seek is placed after -i and the stream is re-encoded (libx264) rather than stream-copied — so the embedded clip lines up with the preview strip’s boundaries instead of snapping to the nearest keyframe.

Cuts land in a clips/ subdirectory of temp_dir and are cached by (video, start, end) so re-opening a band does not re-cut. The command mirrors annie.media.rendering.burn_clip()’s web-friendly encode (preview-grade CRF + faststart muxing).

The subdirectory is what keeps a cut alive: the render sweeper deletes any .mp4 sitting directly in temp_dir once it is older than the TTL (three minutes by default), and it protects only in-flight render jobs — a band clip is neither a job nor refreshed while it plays, so a reviewer studying one card for a few minutes would have had the file unlinked out from under the embedded player. The sweeper’s iterdir() scan does not recurse, so clips in clips/ are simply out of its reach.

Functions

clips_dir(→ pathlib.Path)	The directory band cuts are written to (<temp_dir>/clips).
cut_clip(→ pathlib.Path)	Cut [start, end) of video_path to a browser-playable MP4 (frame-accurate).

Module Contents

annie.media.clipping.clips_dir() → pathlib.Path

The directory band cuts are written to (<temp_dir>/clips).

Resolved at call time rather than import time so a test or a runtime settings change that repoints temp_dir is honoured.

Returns:

The clips directory path (not created — cut_clip() makes it on demand).

annie.media.clipping.cut_clip(video_path: str | pathlib.Path, start: float, end: float) → pathlib.Path

Cut [start, end) of video_path to a browser-playable MP4 (frame-accurate).

The result is cached by (video, start, end): a cached file that still exists is returned as-is, so re-opening the same band never re-encodes.

Parameters:

• video_path – The long source video the band belongs to.

• start – Span start, in seconds.

• end – Span end, in seconds (must be greater than start).

Returns:

The path to the cut clip, under clips_dir().

Raises:

• ValueError – If end is not strictly after start.

• RuntimeError – If the ffmpeg subprocess fails.