Why iPhone Videos Silently Fail as Telegram Video Avatars

Telegram's video avatar feature, live since 2020, quietly fails for clips recorded on iPhones. Since iOS 11, iPhones default to HEVC (H.265) encoding, but Telegram's avatar pipeline only accepts H.264 — when it receives HEVC, the client neither transcodes nor warns the user, the upload just completes with no visible change. This is especially confusing because regular video messages in chats do get transcoded fine, making the avatar path's strictness feel like a bug.

The author reverse-engineered Telegram's undocumented requirements: MP4 container, H.264 video, yuv420p pixel format, square dimensions up to 800x800, a 10-second cap, absolutely no audio track (even if muted), and a file size under roughly 2MB. Missing any of these triggers the same silent failure. The fix is a single FFmpeg command that center-crops to square, scales to 800x800, converts to yuv420p, strips audio, and moves the moov atom forward for fast preview loading. For letterboxed sources, a cropdetect pass identifies black bars before cropping, and a CRF retry loop handles the 2MB size constraint.

This logic was packaged into an aiogram 3-based Telegram bot (@LiveAvaBot) that downloads the file, runs FFmpeg as a non-blocking subprocess, and returns the converted clip. Practical lessons include iPhones storing rotation as metadata rather than rotated pixels, muted audio tracks still counting as audio and causing rejection, and centered crops chopping off foreheads in portrait video, requiring an upward-shifted crop window. For engineers, it's a concrete case study in how undocumented platform media requirements cause silent failures — and how reverse engineering plus a small utility can solve them.