Why iPhone Videos Fail as Telegram Avatars and How I Fixed It

Short summary

iPhone videos fail as Telegram avatars because iOS records HEVC (H.265) in 10-bit by default, while Telegram only accepts H.264 in yuv420p with no audio track. The author reverse-engineered Telegram's exact requirements (MP4, square 800x800, under 2MB, 10s max) and built an ffmpeg-based Telegram bot using aiogram 3 that auto-converts any uploaded video. The two-pass pipeline detects black bars, center-crops to square, downgrades to 8-bit, and strips audio.

• •iPhone HEVC 10-bit video silently fails as Telegram avatars; Telegram only accepts H.264 yuv420p with no audio
• •Exact Telegram avatar specs: MP4, 800x800 square, under 2MB, 10s max, no audio track
• •Author shipped a Telegram bot using aiogram 3 that auto-converts videos with a two-pass ffmpeg pipeline

Generated with AI, which can make mistakes.