Why iPhone Videos Silently Fail as Telegram Video Avatars

Telegram added video avatars back in 2020. You upload a short clip and it loops on your profile instead of a static photo. Fun feature. Except if you recorded that clip on an iPhone, there's a good chance Telegram does nothing with it. No error message. No rejection. The upload finishes and your profile still shows the old photo.

I hit this myself, then watched two friends hit the same wall. So I dug into why, and ended up shipping a bot around the fix. This is the write-up.

Why iPhone Videos Fail

Since iOS 11, iPhones record video in HEVC (H.265) by default. Better codec, roughly half the bitrate of H.264 at the same quality. The problem: Telegram's video avatar pipeline only accepts H.264. When it gets HEVC, the client doesn't transcode and doesn't warn you. It silently drops the upload.

The failure is invisible because regular video messages do get transcoded. Send the same .mov in a chat and it plays fine. Only the avatar path is strict, and that mismatch is exactly what makes people think their app is broken.

What the Spec Actually Requires

Telegram never published a formal document for video avatars, so this is reverse-engineered from what the official clients produce and what the API accepts:

• MP4 container, H.264 video


• yuv420p pixel format (10-bit HDR sources fail without conversion)


• square, up to 800x800


• 10 seconds maximum


• no audio track at all, not just muted


• under roughly 2MB to be reliable

Miss any of these and you get the same silent nothing. The audio rule is the sneaky one: a video with a muted audio track still counts as having audio.

The FFmpeg Pipeline

ffmpeg does all the real work. For a center crop to square, the whole conversion is one command:

ffmpeg -y -i input.mov -t 10 \

  -vf "crop='min(iw,ih)':'min(iw,ih)',scale=800:800,format=yuv420p" \

  -c:v libx264 -preset slow -crf 26 \

  -movflags +faststart \

  -an output.mp4

What each piece does:

• 
  crop='min(iw,ih)':'min(iw,ih)' takes the largest centered square, works for portrait and landscape


• 
  scale=800:800 downsizes to the avatar resolution


• 
  format=yuv420p converts 10-bit HDR footage to 8-bit; without it libx264 produces output Telegram rejects


• 
  -an strips the audio track completely


• 
  -movflags +faststart moves the moov atom to the front so the preview loads instantly


• 
  -t 10 hard-caps duration

For letterboxed input (screen recordings, clips with black bars) a center crop keeps the bars. cropdetect fixes that. Run a short analysis pass first:

ffmpeg -i input.mov -t 3 -vf cropdetect=24:16:0 -f null - 2>&1 \

  | grep -o 'crop=[0-9:]*' | tail -1

It prints something like crop=1080:1080:0:420, which you drop into the filter chain of the encode pass in place of the min() expression.

The 2MB cap needs one more trick. CRF encoding doesn't target a file size, so I encode at crf 26 first, and if the output lands over 2MB I bump CRF by 3 and retry. Two retries cover every 10 second clip I've seen.

The aiogram 3 Handler

The bot side is small. Download the file, shell out to ffmpeg, send the result back:

import asyncio

import tempfile

from pathlib import Path



from aiogram import Bot, F, Router

from aiogram.types import FSInputFile, Message



router = Router()



SQUARE = "crop='min(iw,ih)':'min(iw,ih)',scale=800:800,format=yuv420p"



@router.message(F.video | F.animation)

async def convert(message: Message, bot: Bot):

    src_file = message.video or message.animation



    with tempfile.TemporaryDirectory() as tmp:

        src = Path(tmp) / "in.mp4"

        dst = Path(tmp) / "out.mp4"

        await bot.download(src_file, destination=src)



        proc = await asyncio.create_subprocess_exec(

            "ffmpeg", "-y", "-i", str(src), "-t", "10",

            "-vf", SQUARE,

            "-c:v", "libx264", "-preset", "slow", "-crf", "26",

            "-movflags", "+faststart", "-an", str(dst),

        )

        await proc.wait()



        await message.answer_video(

            FSInputFile(dst),

            caption="Done. Settings > Edit profile > set as video avatar",

        )

Details that matter:

• 
  create_subprocess_exec instead of subprocess.run, so one heavy encode doesn't block the event loop for every other user


• 
  F.animation catches GIFs, which Telegram already stores as silent MP4s, so the same pipeline handles them for free


• Bot API caps downloads at 20MB, so check file_size before downloading and tell the user instead of failing mid-encode

Packaging It as a Bot

I wrapped this into , and the code above is a trimmed version of what runs in production.

If you've hit other undocumented corners of Telegram's media pipeline, tell me in the comments. I collect these.