feat(downloads): a clip or an edit can be a GIF, shared as a picture

A clip and an editor range can come out as a silent GIF (long side
320/480/640, 12 fps, at most 30 s, one palette per GIF); one over 30 MB
is not kept. A shared picture is served inline under the preview's
sandbox, and a GIF's link card is the GIF itself up to 15 MB, the still
for Facebook's crawler.
This commit is contained in:
2026-11-11 01:50:55 +01:00
parent fe38c07e7e
commit c221452a00
24 changed files with 885 additions and 58 deletions
+27 -1
View File
@@ -12,6 +12,9 @@ given in fractions of the box it was drawn in, with that box's aspect: the YouTu
tells its picture's size, so the frame there is drawn over the player's 16:9 box (a short's 9:16),
and the cut maps it onto the real picture (`crop_filter`) — what lies over a letterbox bar is dropped.
A clip may be a GIF instead (`spec["gif"]`, downloads/gif): the same range, crop and tonemap, then a
silent animated picture of at most 30 s rather than a video.
The spec is stored on the job (`DownloadJob.edit_spec`) and is the clip's whole identity: its
signature is the asset's cache key, so marking the same range again is an instant cache hit, and a
different range or audio track is a different clip.
@@ -24,6 +27,7 @@ import re
from pathlib import Path
from typing import Literal
from app.downloads import gif as gifmod
from app.downloads.edit import AAC_ARGS, EVEN_FRAME, INPUT_GUARD, X264_ARGS
from app.plex.sync import HDR_TRANSFERS
@@ -70,6 +74,8 @@ ClipReason = Literal[
"not_found",
"media_missing",
"past_end",
"bad_gif",
"gif_too_long",
]
@@ -90,9 +96,12 @@ def normalize(
end_s: float,
audio_track: int | None = None,
crop: dict | None = None,
gif_side: object = None,
) -> dict:
"""The validated, canonical clip spec. Times are rounded to the millisecond and a crop to four
decimals, so the same marks always give the same cache key. Raises ClipError."""
decimals, so the same marks always give the same cache key. A `gif_side` makes it a GIF of that
size (`downloads/gif`), held to the GIF's own length cap; without one it is the video clip it
always was, spec and cache key alike. Raises ClipError."""
if source not in SOURCES:
raise ClipError("bad_source")
pattern = _YOUTUBE_ID if source == "youtube" else _RATING_KEY
@@ -103,9 +112,20 @@ def normalize(
start, end = round(start_s, 3), round(end_s, 3)
if end - start < MIN_CLIP_S:
raise ClipError("too_short")
side = None
if gif_side is not None:
try:
side = gifmod.normalize_side(gif_side)
except ValueError as e:
raise ClipError("bad_gif") from e
if side is not None and end - start > gifmod.MAX_S:
# Its own reason: a GIF's cap is said in seconds, a clip's in minutes.
raise ClipError("gif_too_long", limit_s=gifmod.MAX_S)
if end - start > MAX_CLIP_S:
raise ClipError("too_long", limit_s=MAX_CLIP_S)
spec: dict = {"source": source, "ref": ref, "start_s": start, "end_s": end}
if side is not None:
spec["gif"] = {"side": side}
if source == "plex" and audio_track is not None:
if not 0 <= audio_track <= _MAX_AUDIO_TRACK:
raise ClipError("bad_audio")
@@ -257,6 +277,12 @@ def audio_track_count(probe: dict) -> int:
return sum(1 for s in probe.get("streams") or [] if s.get("codec_type") == "audio")
def gif_pre(crop: str, hdr: bool) -> str:
"""What a GIF clip's frames go through before the GIF's own size and palette: the crop, then an HDR
source's tonemap (a palette made from PQ frames is as washed out as the frames are)."""
return ",".join([*([crop] if crop else []), *([_TONEMAP] if hdr else [])])
def build_cmd(
src: Path,
dest: Path,