The upload that fails without a message
I wanted an animated avatar for my bot. I recorded a 6 second clip on my iPhone, sent it to BotFather, and nothing happened. No error, the video just never showed up as an avatar. It took me a while to figure out that the file was HEVC (H.265), and Telegram won't accept that for video avatars.
The annoying part is that the failure is silent. Telegram doesn't say "wrong codec". It just doesn't apply the file. So I wrote a small converter, and this post walks through how it works.
What the Telegram spec requires
The video avatar format has a few hard requirements:
- MP4 container with H.264 video. iPhone clips are HEVC by default, and those get rejected.
- 800x800 pixels, square.
- 10 seconds maximum.
- No audio track.
- Around 2 MB maximum file size.
You can confirm the codec of an iPhone clip with ffprobe -v error -show_streams input.mov | grep codec_name. If it prints hevc, that's your problem. Most iPhone videos are 1920x1080 or 1080x1920 landscape or portrait, so they also need a crop to square.
Crop, scale, and convert in one ffmpeg pass
ffmpeg does all of the heavy lifting here. I just wrote the wrapper around it. The flow has two steps. First, cropdetect finds the real picture area so black bars from screen recordings don't end up in the avatar. Second, I encode with a square center crop, scale to 800x800, and drop the audio.
# step 1: find the content box, ignore the black bars
CROP=$(ffmpeg -i input.mov -t 10 -vf cropdetect=limit=24:round=2 -an -f null - 2>&1 \
| grep -o 'crop=[0-9:]*' | tail -n 1 | cut -d= -f2)
# step 2: square crop, scale, convert to H.264, strip audio
ffmpeg -y -i input.mov -t 10 \
-vf "crop=${CROP},crop='min(iw,ih)':'min(iw,ih)',scale=800:800,format=yuv420p" \
-an -c:v libx264 -preset slow -crf 30 \
-movflags +faststart avatar.mp4
A few things in there matter. format=yuv420p forces 8-bit 4:2:0, which is what Telegram's player expects. Some iPhone sources are 10-bit, and without this the output plays badly or gets rejected. -movflags +faststart moves the metadata to the front of the file, which helps when the client streams it. -an removes audio entirely instead of trying to keep it.
For the size limit, -crf 30 works for most 10 second clips at 800x800. In my tests, typical clips landed somewhere around 500 KB to 1.2 MB. Noisy footage, like grass or crowds, can go over 2 MB. More on that in the lessons section.
A minimal aiogram 3 handler
The bot side is just a handler that downloads the file, runs ffmpeg as a subprocess, and sends the result back. I use asyncio.create_subprocess_exec so ffmpeg doesn't block the event loop.
import asyncio
import tempfile
from pathlib import Path
from aiogram import Bot, F, Router
from aiogram.types import FSInputFile, Message
router = Router()
async def run_ffmpeg(*args: str) -> None:
proc = await asyncio.create_subprocess_exec("ffmpeg", "-y", *args)
if await proc.wait() != 0:
raise RuntimeError("ffmpeg failed")
@router.message(F.video | F.animation)
async def make_avatar(message: Message, bot: Bot) -> None:
media = message.video or message.animation
workdir = Path(tempfile.mkdtemp())
src = workdir / "input"
out = workdir / "avatar.mp4"
info = await bot.get_file(media.file_id)
await bot.download_file(info.file_path, destination=src)
await run_ffmpeg(
"-i", str(src), "-t", "10",
"-vf", "crop='min(iw,ih)':'min(iw,ih)',scale=800:800,format=yuv420p",
"-an", "-c:v", "libx264", "-preset", "slow", "-crf", "30",
"-movflags", "+faststart", str(out),
)
await message.answer_video(FSInputFile(out))
This version has no queue, no concurrency limit, and no cleanup of the temp directory. For a bot with a few users that's fine. Under real load you'd want all three.
Packaging it as @liveavabot
I wrapped this into a bot. You send it any video or GIF, and it sends back a file that fits the avatar spec. It's at https://t.me/LiveAvaBot?start=devto_article_20261117. So far it has 529 users total, and 4 conversions in the last 24 hours. That's a small number, but it does tell me people run into the HEVC wall.
Lessons and what's next
-
-fstruncates the output silently when it hits the size limit, so the clip just gets cut off. Don't use it for this. Check the file size after encoding and retry with a higher CRF if it's too big. - Long GIFs with huge frame counts are slow. I cap input at 10 seconds with
-t, but I haven't done anything smarter yet. - Next on the list: the CRF retry loop above, and a preview before sending the final file.
Built by me, @liveavabot.
Top comments (0)