feat(rich-markdown): fill media attributes from ffprobe/ffmpeg

[popstas]

Fills Telegram media attributes ourselves from ffprobe/ffmpeg instead of relying on Telethon's metadata inference and the server's partial re-parse, so large videos stop rendering as empty rectangles and an animated .gif actually attaches.

Closes the two open rich_markdown items in docs/TODO.md.

Why

Telethon's utils.get_attributes() needs hachoir to read a media file. Without one it returns a stub DocumentAttributeVideo(duration=0, w=1, h=1) for every mp4 and no DocumentAttributeAudio at all. Telegram repairs the metadata by re-parsing the upload, but only below an undocumented size threshold — measured live 2026-07-29 (Saved Messages, msg 407429/407430), seven videos up to 6.30 MB came back with real duration, dimensions, thumbs=2 and supports_streaming=True, while three from 12.72 MB up kept duration=0, w=1, h=1, thumbs=None and rendered as an empty rectangle in the clients.

What changed

• messages/media_probe.py (new, no Telethon imports, plain data out) — probe_media(), extract_thumbnail(), convert_gif_to_mp4(), ffprobe_available()/ffmpeg_available(). ffprobe/ffmpeg are optional external binaries, not pip dependencies: a failed probe is never an error (the pre-probe stub goes out with a WARNING naming the file), because a box without them must still be able to send. Every call is a blocking subprocess and runs through asyncio.to_thread, never on the event loop. A cover-art stream (disposition.attached_pic) is not a video stream — an .mp3 with artwork would otherwise be shaped like a video and take the artwork's dimensions.
• _document_attributes() is now the single place a video/audio/animation attribute is built, replacing Telethon's stub rather than joining it (two DocumentAttributeVideo in one document is a malformed request).
• Videos get an ffmpeg-generated preview frame (10% in — frame 0 of a real recording is often black) as thumb=. The missing preview is what makes the empty rectangle, so it is generated for every video rather than for large ones only.
• An animated .gif is uploaded as a converted silent mp4 (temp file removed in a finally on every exit path), with the author's own <name>.mp4 written back as the filename attribute so the temp name never reaches the article. Since conversion is what makes the file attachable, a .gif with no ffmpeg on PATH is rejected by _validate_rich_files before the operation row is opened, leaving the idempotency key free for the retry after the install.
• Every rich-media upload is now logged at INFO — uploading 34 files previously wrote nothing to the log at all, so a broken article was undiagnosable after the fact.

The markdown body is untouched by all of this: a .gif is still referenced as tg://video?id=… and media_kind() is unchanged. Conversion is purely about the upload's shape.

GIF wire facts, proven live

The plan assumed a .gif simply never attaches. scripts/spike_rich_gif.py (new, added in this branch) settled it against the real account on 2026-07-29 (Saved Messages, msg 407434-407437):

Upload	Server response	Article
98 KB image/gif	transcoded server-side → video/mp4, 98 KB → 21 KB, Telegram's own DocumentAttributeVideo(w=320 h=240 duration=2.0) + Animated + thumbs=2, renamed loop.gif.mp4	attaches, real PageBlockVideo
21.2 MB image/gif	not transcoded — keeps mime=image/gif, thumbs=None, DocumentAttributeAnimated dropped	send fails RICH_MESSAGE_VIDEO_INVALID
21.2 MB → ffmpeg mp4	22.2 MB → 9.6 MB, real Video + Animated, thumbs=2	attaches, real PageBlockVideo

So a raw-gif upload is normalised by the server regardless of what we attach — but only below an undocumented threshold. Conversion is therefore unconditional: the small-gif case the server handles is not worth a second code path.

Testing

.venv/bin/pytest -q → 2201 passed (2168 before this branch), .venv/bin/ruff check src tests clean. All new tests use in-memory fakes and monkeypatched subprocess.run — no Telegram traffic and no real ffmpeg/ffprobe subprocess in the suite. The one live run was the GIF spike above, executed once under explicit authorization.

Docs

CLAUDE.md (the "Local media in an article is CLI-only" architecture bullet, plus a Common-commands entry for the new spike), README.md (including a note that the Docker image ships without ffmpeg), skills/telegram-assistant/SKILL.md (re-synced to ~/.claude/skills/), docs/TODO.md.

🤖 Generated with Claude Code