Converting iPhone HEVC Videos to Telegram Video Avatars with ffmpeg

The Pain: iPhone Videos Silently Fail

iPhone records video as HEVC (H.265) inside a .mov container by default. Telegram's video avatar feature has a very narrow spec, and HEVC isn't part of it. Desktop clients sometimes surface a generic error, but mobile clients usually accept the upload and then refuse to render it. You see the spinner, then nothing.

The first time this happened to me I thought my account was broken. Turns out the file just didn't match the spec.

What Telegram Actually Requires

After reading the docs and testing a couple dozen clips, the constraints for a profile video on Telegram are:

• Codec: H.264 (libx264), profile baseline or main
• Container: MP4 with +faststart so the moov atom sits at the front
• Resolution: 800x800 square, exact
• Pixel format: yuv420p (8-bit, no 10-bit)
• Duration: up to 10 seconds
• Audio: none, the track must be stripped
• File size: under 2 MB to be safe

Miss any one of these and the upload fails quietly. The 800x800 constraint is the trickiest, because most phone footage is 16:9 or 9:16, so you need to crop, not just scale.

The ffmpeg Pipeline

ffmpeg can handle every part of this in one pass. The interesting bit is cropdetect, which finds the safe square crop region without losing the subject. I run it as a two-pass: first detect, then encode.

Pass One: Detect Crop

Look at the middle of the clip and propose a crop:

ffmpeg -ss 1 -i input.mov -vframes 50 \
  -vf "cropdetect=24:16:0" \
  -f null - 2>&1 | grep -o "crop=[^ ]*" | tail -1

That returns something like crop=1080:1080:420:0. ffmpeg picks the largest non-letterboxed rectangle it can find. You can also just hard-crop to a centered square if you trust the input.

Pass Two: Encode

The actual encode:

ffmpeg -y -i input.mov \
  -t 10 \
  -vf "crop=1080:1080:420:0,scale=800:800:flags=lanczos,format=yuv420p" \
  -c:v libx264 -profile:v main -level 4.0 \
  -preset slow -crf 28 \
  -movflags +faststart \
  -an \
  output.mp4

A few notes on the flags:

• -t 10 clips at the Telegram max of 10 seconds
• -an drops audio, which is mandatory
• -movflags +faststart rewrites the moov atom to the start so Telegram can stream-read the header
• crf 28 keeps quality reasonable while staying small. For most 10-second clips this lands under 1.5 MB, leaving headroom under the 2 MB cap

If the output is still too big, drop -crf to 30 or 32. Below 32 quality gets noticeably blocky.

Wiring It Into an aiogram 3 Handler

I use aiogram 3 because the async API plays nicely with running ffmpeg as a subprocess. Here is the minimal handler that takes any video or animation, runs the pipeline, and sends back the result:

import asyncio
import tempfile
from pathlib import Path
from aiogram import Router, F
from aiogram.types import Message, FSInputFile

router = Router()

FFMPEG_CMD = [
    "ffmpeg",
    "-y",
    "-i",
    "{input}",
    "-t",
    "10",
    "-vf",
    "crop=in_h:in_h:(in_w-in_h)/2:0,scale=800:800:flags=lanczos,format=yuv420p",
    "-c:v",
    "libx264",
    "-profile:v",
    "main",
    "-level",
    "4.0",
    "-preset",
    "slow",
    "-crf",
    "28",
    "-movflags",
    "+faststart",
    "-an",
    "{output}",
]

@router.message(F.video | F.animation | F.video_note)
async def convert(message: Message):
    with tempfile.TemporaryDirectory() as tmp:
        src = Path(tmp) / "src"
        dst = Path(tmp) / "avatar.mp4"
        file = message.video or message.animation or message.video_note
        await message.bot.download(file, destination=src)
        cmd = [a.format(input=str(src), output=str(dst)) for a in FFMPEG_CMD]
        proc = await asyncio.create_subprocess_exec(
            *cmd,
            stdout=asyncio.subprocess.DEVNULL,
            stderr=asyncio.subprocess.PIPE,
        )
        _, err = await proc.communicate()
        if proc.returncode != 0:
            await message.answer(f"ffmpeg failed: {err.decode()[-200:]}")
            return
        await message.answer_video(
            FSInputFile(dst),
            caption="Set this in Settings > Edit Profile > Set Profile Video.",
        )

The crop expression in_h:in_h:(in_w-in_h)/2:0 is a centered square crop based on input dimensions, which works for both landscape and portrait sources without a detect pass. I use the two-pass cropdetect version only when the user opts in for smart crop.

Packaging It as @liveavabot

After running this for myself for a couple of weeks, I packaged it as a Telegram bot. Send any video, GIF, or .mov from your phone, get back an 800x800 H.264 clip ready to drop into the profile video slot. Free for the first few conversions, then a small Telegram Stars payment.

You can try it here: t.me/LiveAvaBot

Most of the work in the bot is glue: rate limiting, file size guards, dedup of identical uploads, and a small queue so a long encode doesn't block other users. The actual conversion is still those two ffmpeg passes.

Edge Cases and Lessons

A few things I learned the hard way:

• HEVC with HDR metadata. iPhone 12 and newer can record in Dolby Vision. Stripping the metadata with -bsf:v hevc_metadata=colour_primaries=1:transfer_characteristics=1:matrix_coefficients=1 before the main pipeline avoids weird washed-out colors after transcode.

• 10-bit input. Some Android phones record yuv420p10le. Always force format=yuv420p in the filter chain or Telegram silently rejects the output.

• GIFs without a fixed framerate. Animated GIFs from the web sometimes have variable frame delays. Add -r 30 before -i to clamp the input rate, otherwise duration math gets weird and -t 10 cuts off too early.

• Vertical TikTok exports. The centered crop loses heads when the subject sits in the top third. I added a face-detection fallback later, but the simple centered crop is good enough for around 90% of inputs.

Next on my list is supporting AV1, which Telegram now accepts on some clients. The H.264 fallback stays for compatibility, but AV1 at lower bitrate could push the file size cap further.

Built by me, @liveavabot. If you hit a video format that doesn't convert cleanly, send it to the bot and reply with /feedback, I read every message.