DEV Community

liveavabot
liveavabot

Posted on

Converting iPhone HEVC Videos for Telegram Video Avatars with ffmpeg

I built a small Telegram bot for video avatars, and the first bug I hit was a silent failure. Some iPhone videos upload fine, Telegram accepts the file, and then nothing happens. No error message.

Why iPhone videos fail silently

Most iPhones record in HEVC (H.265) inside a .MOV container by default. Telegram's video avatar pipeline expects H.264 in an MP4. The upload succeeds, so there's no error to catch, and the avatar just never updates.

I spent an evening assuming my code was wrong before I ran ffprobe on the file:

ffprobe -v error -select_streams v:0 -show_entries stream=codec_name,width,height -of csv=p=0 input.MOV
# hevc,1920,1080
Enter fullscreen mode Exit fullscreen mode

That hevc line was the whole story. The file was 1920x1080 landscape too, which is a second problem, since the avatar needs a square.

What the spec requires

These are the constraints I target, based on what I've seen work:

  • Codec: H.264 (AVC), MP4 container
  • Resolution: 800x800, square
  • Duration: 10 seconds max
  • File size: 2 MB max
  • Audio: removed

Telegram doesn't document all of this in one place, so treat the numbers as what I've confirmed in testing, not a spec I'm quoting. If Telegram changes the limits, the bot will need an update.

Converting with ffmpeg: cropdetect, then scale and encode

The conversion runs in two passes. The first pass finds the crop rectangle from the first 10 seconds. The second pass crops, scales, strips audio, and encodes.

# pass 1: detect the crop rectangle
ffmpeg -hide_banner -i input.MOV -t 10 -vf cropdetect=24:16:0 -f null - 2>&1 \
  | grep -o 'crop=[0-9:]*' | tail -1
# prints something like crop=1080:1080:420:0

# pass 2: crop, scale, drop audio, encode
ffmpeg -y -i input.MOV -t 10 -an \
  -vf 'crop=1080:1080:420:0,scale=800:800:flags=lanczos,fps=30,format=yuv420p' \
  -c:v libx264 -preset medium -crf 26 -movflags +faststart \
  output.mp4
Enter fullscreen mode Exit fullscreen mode

A few notes on those flags:

  • cropdetect on a landscape clip gives a rectangle that's rarely square. I take min(w, h) as the side and center the crop, so the subject stays in frame.
  • format=yuv420p matters. Without it, some HEVC sources produce 4:2:2 or 4:4:4 output that the Telegram client won't play.
  • -movflags +faststart moves the moov atom to the front, so playback starts before the whole file downloads.
  • -an removes audio. Telegram ignores it for avatars anyway, and it eats into the 2 MB budget.

If the output comes out over 2 MB, I bump -crf by 2 and encode again. In my tests a 10-second clip at crf 26 usually lands between 600 KB and 1.2 MB, so the retry rarely fires. It exists for high-motion footage.

The aiogram 3 handler

Here's the bot side, trimmed to the parts that matter. It downloads the upload, converts it with the same two ffmpeg passes, and sends the result back.

import asyncio
import re
import tempfile
from pathlib import Path

from aiogram import Bot, F, Router
from aiogram.types import FSInputFile, Message

router = Router()
MAX_BYTES = 2 * 1024 * 1024
CROP_RE = re.compile(r'crop=(\d+):(\d+):(\d+):(\d+)')


async def run(*args: str) -> str:
    proc = await asyncio.create_subprocess_exec(
        *args,
        stdout=asyncio.subprocess.PIPE,
        stderr=asyncio.subprocess.STDOUT,
    )
    out, _ = await proc.communicate()
    return out.decode(errors='replace')


async def detect_square_crop(src: Path) -> str:
    log = await run(
        'ffmpeg', '-hide_banner', '-i', str(src), '-t', '10',
        '-vf', 'cropdetect=24:16:0', '-f', 'null', '-',
    )
    matches = CROP_RE.findall(log)
    if not matches:
        raise ValueError('cropdetect found nothing')
    w, h, x, y = map(int, matches[-1])
    side = min(w, h)
    x += (w - side) // 2
    y += (h - side) // 2
    return f'crop={side}:{side}:{x}:{y}'


@router.message(F.video | F.animation)
async def to_avatar(message: Message, bot: Bot) -> None:
    media = message.video or message.animation
    workdir = Path(tempfile.mkdtemp())
    src = workdir / 'in.bin'
    dst = workdir / 'avatar.mp4'

    tg_file = await bot.get_file(media.file_id)
    await bot.download_file(tg_file.file_path, destination=src)

    crop = await detect_square_crop(src)
    crf = 26
    while True:
        vf = f'{crop},scale=800:800:flags=lanczos,fps=30,format=yuv420p'
        await run(
            'ffmpeg', '-y', '-i', str(src), '-t', '10', '-an',
            '-vf', vf, '-c:v', 'libx264', '-preset', 'medium',
            '-crf', str(crf), '-movflags', '+faststart', str(dst),
        )
        if dst.stat().st_size <= MAX_BYTES or crf >= 36:
            break
        crf += 2

    if dst.stat().st_size > MAX_BYTES:
        await message.answer('Could not fit this clip under 2 MB, try a shorter one.')
        return

    await message.answer_video(FSInputFile(dst))
Enter fullscreen mode Exit fullscreen mode

Things I got wrong the first time:

  • ffmpeg writes its log to stderr, so I merge stderr into stdout. Reading only stdout returned nothing and the crop regex never matched.
  • bot.download_file takes the path from get_file, not the file_id. Passing the file_id directly fails with a confusing error.
  • Running ffmpeg with create_subprocess_shell plus string formatting broke on filenames with spaces. Passing an argument list avoids that.

The handler runs ffmpeg inline, so one slow conversion blocks nothing else, but a burst of uploads does pile up CPU. I haven't added a queue yet.

How this became @liveavabot

The handler above is most of the bot. The rest is a database for usage counts, a size check before download, and a message when the clip is too long. I put it up as @LiveAvaBot so people could try it without installing ffmpeg.

The numbers after roughly three weeks: 534 users total, 5 new users in the last 24 hours, 3 conversions in the same window, and zero Stars revenue in 24 hours. The conversion rate is low, and I don't yet know whether that's the onboarding message, the 10-second limit, or simply that most people who find the bot don't have a broken HEVC clip to fix.

Lessons and what's next

The biggest lesson is to check the codec before you debug your code. Half my time went into reading my own handler when one ffprobe line would have pointed at the problem.

Edge cases I still see:

  • Variable frame rate sources from screen recordings need the fps=30 filter, or the output drifts.
  • Some GIFs with a transparent background come out with a black box after format=yuv420p. I'm looking at compositing onto white first.
  • Very high-motion clips hit the 2 MB cap at crf 36 and still fail. Those get the error message, which is better than a silent failure.

Next I want to test the output on older Telegram clients and add a queue so bursts don't stall the worker.

Built by me: @liveavabot

Top comments (0)