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
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
A few notes on those flags:
-
cropdetecton a landscape clip gives a rectangle that's rarely square. I takemin(w, h)as the side and center the crop, so the subject stays in frame. -
format=yuv420pmatters. Without it, some HEVC sources produce 4:2:2 or 4:4:4 output that the Telegram client won't play. -
-movflags +faststartmoves the moov atom to the front, so playback starts before the whole file downloads. -
-anremoves 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))
Things I got wrong the first time:
-
ffmpegwrites its log to stderr, so I merge stderr into stdout. Reading only stdout returned nothing and the crop regex never matched. -
bot.download_filetakes the path fromget_file, not thefile_id. Passing thefile_iddirectly fails with a confusing error. - Running ffmpeg with
create_subprocess_shellplus 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=30filter, 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 36and 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)