DEV Community: liveavabot

Converting iPhone HEVC Videos to Telegram Video Avatars With ffmpeg

liveavabot — Thu, 13 Aug 2026 09:03:38 +0000

The Silent Failure Nobody Warns You About

You take a nice short clip on your iPhone. You open Telegram, go to Settings, tap your avatar, choose "Set Video". The upload spins. Then... nothing. No error, no toast, just the old picture staring back at you.

I hit this three times before I realized what was happening. iPhone records video in HEVC (H.265) inside a .mov container. Telegram's video avatar accepts H.264 in MP4. So the app quietly drops your upload on the floor.

That was the seed for @liveavabot. Send it any clip, get back a file Telegram will actually accept.

What the Telegram Video Avatar Spec Actually Requires

The official rules are scattered across the Bot API docs and community reverse-engineering. Here is what I settled on after testing:

Container: MP4 with faststart (moov atom at the start).
Video codec: H.264, baseline or main profile, yuv420p pixel format.
Resolution: square, 800x800 is the sweet spot. 640x640 works too.
Duration: up to 10 seconds (Telegram trims silently past that).
File size: under 2 MB. Above ~2.5 MB the client rejects it.
Audio: none. Any audio track and the client treats it as a regular video.
Framerate: 30 fps caps out cleanly. 60 fps sometimes glitches.

Miss any one of these and the upload fails without an error message. Not great.

The ffmpeg Pipeline

The whole conversion is three steps: detect a square crop, scale to 800x800, encode to H.264 with the right flags. All of it fits in one ffmpeg invocation.

First I run cropdetect to find a reasonable square region. Portrait videos need cropping to a square, not just scaling (else your face gets squished):

ffmpeg -hide_banner -i input.mov \
  -vf "cropdetect=24:16:0" -t 3 -f null - 2>&1 \
  | grep -oP 'crop=\S+' | tail -1

That returns something like crop=1080:1080:0:420. Feed that into the real pass, forcing 800x800, no audio, yuv420p, and faststart:

ffmpeg -y -i input.mov \
  -vf "crop=1080:1080:0:420,scale=800:800:flags=lanczos,fps=30" \
  -c:v libx264 -profile:v main -pix_fmt yuv420p \
  -preset veryfast -crf 26 \
  -movflags +faststart \
  -an -t 10 \
  output.mp4

The important flags nobody documents together:

-pix_fmt yuv420p: without this some Telegram clients render green frames.
-movflags +faststart: puts the moov atom first so the client can preview before downloading the full file.
-an: drops audio. Non-negotiable for the avatar spec.
-crf 26: quality/size tradeoff. 26 keeps 10s under 2 MB for most content.

If the output still lands above 2 MB, I re-encode with -crf 30. Above 4 MB source, I do one warm-up pass at -crf 32 before falling back further.

Wiring It Into aiogram 3

The bot handler is small. Accept a video, animation, or document; run it through the pipeline; send back the MP4.

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

router = Router()

@router.message(F.video | F.animation | F.document)
async def handle_media(message: Message):
    file = message.video or message.animation or message.document
    if file.file_size and file.file_size > 20 * 1024 * 1024:
        await message.reply("Too big. 20 MB max input.")
        return

    with tempfile.TemporaryDirectory() as tmp:
        src = pathlib.Path(tmp) / "in.bin"
        dst = pathlib.Path(tmp) / "out.mp4"
        await message.bot.download(file.file_id, destination=src)

        ok = await convert_to_avatar(src, dst)
        if not ok:
            await message.reply("Conversion failed. Send a shorter clip.")
            return

        await message.reply_video(
            FSInputFile(dst),
            caption="Upload as your Telegram avatar.",
        )

The convert_to_avatar function is just an asyncio.create_subprocess_exec wrapper around the ffmpeg command above, with the cropdetect step first. Nothing fancy. ffmpeg is doing the heavy lifting, I just wrote the wrapper.

Packaging It as @liveavabot

Once the conversion worked reliably, I put a Telegram Stars paywall in front of it (25 stars per conversion, roughly 30 cents). The whole thing runs on one small VPS with a systemd unit, ffmpeg from the Debian repo, and aiogram 3 in a venv. No queue, no worker pool, no S3. When a message comes in, it converts on the box and sends the file back.

Traffic is small enough (a few hundred users, single-digit concurrent conversions) that this is fine. If it grows past that, adding a worker queue is a two-file change.

You can try it at https://t.me/LiveAvaBot?start=devto_article_20260813.

Edge Cases and What Is Next

A few things bit me during the build.

Videos rotated by EXIF: iPhone stores rotation as metadata, not in the pixel data. ffmpeg's -vf chain runs before rotation is applied. Fix by prepending transpose= based on ffprobe orientation, or use -noautorotate and handle it yourself.

Animated GIFs with palette artifacts: convert through the paletteuse filter first if colors look wrong, otherwise a straight -i input.gif into the same H.264 pipeline works.

HDR sources from newer iPhones: these have BT.2020 color space and look washed out after conversion. Tone-map with zscale=t=linear:npl=100,tonemap=hable.

Bots sending 4K: I hard-cap input at 20 MB, and if the resolution is over 1920x1920 I downscale before the crop pass to save CPU.

What is next: batch conversion (send 3 clips, get 3 back), custom crop selection (tap the region you want), and maybe a web version for people who do not want to talk to a bot.

Built by me. @liveavabot.

Converting iPhone HEVC Videos to Telegram Video Avatars with ffmpeg

liveavabot — Tue, 11 Aug 2026 08:03:58 +0000

The problem: your iPhone video will not upload as a Telegram avatar

I recorded a 4-second clip on my iPhone last month, tried to set it as my Telegram profile video, and got nothing. No error, no toast, just silence. The upload dialog closed and my avatar stayed the same static image.

Turns out Telegram's video avatar endpoint quietly rejects anything it cannot decode. iPhones record in HEVC (H.265) by default since iOS 11, and Telegram's avatar pipeline only accepts H.264. There is no error message, no fallback, no "please convert this first". It just fails.

I built a small bot to fix this exact problem. Send it any video or GIF, get back a file that Telegram will actually accept as your profile animation. This post is the build log.

What Telegram's video avatar spec actually wants

The requirements are scattered across the Bot API reference and a few forum threads. Here is the full list I had to satisfy, discovered through trial and error:

Codec: H.264 (libx264). HEVC, VP9, AV1 all rejected.
Container: MP4 with the faststart flag.
Pixel format: yuv420p. yuv420p10le or yuv444p will not work.
Resolution: exactly 800x800, square crop.
Duration: 10 seconds or less.
Size: under 2 MB. This is the killer constraint.
Audio: must be stripped. Even a silent audio track can cause issues.
Frame rate: I clamp to 30 fps to save bytes.

The 2 MB cap is the hardest part. A 10-second 800x800 H.264 clip at reasonable quality is closer to 3 or 4 MB with default settings. You need aggressive bitrate control.

The ffmpeg pipeline

Here is the actual command the bot runs. Breakdown below:

ffmpeg -y -i input.mov \
  -vf "scale=800:800:force_original_aspect_ratio=increase,crop=800:800" \
  -c:v libx264 -profile:v baseline -level 3.1 \
  -pix_fmt yuv420p \
  -r 30 \
  -t 10 \
  -b:v 1200k -maxrate 1400k -bufsize 2000k \
  -an \
  -movflags +faststart \
  output.mp4

Walking through it:

scale=800:800:force_original_aspect_ratio=increase,crop=800:800 scales the shorter dimension to 800 then center-crops to a square. This preserves aspect ratio without stretching faces. For sources with black letterbox bars, I run cropdetect=24:16:0 as a separate probe pass first to get the real crop values, then feed those into the encode.

-c:v libx264 -profile:v baseline -level 3.1 picks H.264 with the most compatible profile. Baseline profile means no B-frames, which decodes faster on old Android clients.

-pix_fmt yuv420p is non-negotiable. iPhone HEVC often uses yuv420p10le (10-bit), and Telegram silently rejects the output even after codec conversion if you leave the pixel format alone. Force 8-bit.

-b:v 1200k -maxrate 1400k -bufsize 2000k is the bitrate ceiling that keeps a 10-second clip under 2 MB. I landed on these values after about 40 test uploads.

-an strips audio. -movflags +faststart moves the moov atom to the front so Telegram can start decoding before the file finishes downloading.

The aiogram 3 handler

I use aiogram 3 (async, type-hinted) for the Telegram side. The handler receives a video or animation, downloads it, runs ffmpeg, and sends the result back. Here is the core:

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

router = Router()

@router.message(F.video | F.animation | F.video_note | F.document)
async def convert_to_avatar(message: Message):
    if message.video:
        file_id = message.video.file_id
    elif message.animation:
        file_id = message.animation.file_id
    elif message.video_note:
        file_id = message.video_note.file_id
    else:
        file_id = message.document.file_id

    tmp = Path(tempfile.mkdtemp())
    src = tmp / f"in_{uuid.uuid4().hex}"
    dst = tmp / f"out_{uuid.uuid4().hex}.mp4"

    file = await message.bot.get_file(file_id)
    await message.bot.download_file(file.file_path, destination=str(src))

    proc = await asyncio.create_subprocess_exec(
        "ffmpeg", "-y", "-i", str(src),
        "-vf", "scale=800:800:force_original_aspect_ratio=increase,crop=800:800",
        "-c:v", "libx264", "-profile:v", "baseline", "-level", "3.1",
        "-pix_fmt", "yuv420p", "-r", "30", "-t", "10",
        "-b:v", "1200k", "-maxrate", "1400k", "-bufsize", "2000k",
        "-an", "-movflags", "+faststart",
        str(dst),
        stdout=asyncio.subprocess.DEVNULL,
        stderr=asyncio.subprocess.PIPE,
    )
    await proc.communicate()

    if proc.returncode != 0:
        await message.answer("ffmpeg failed. Try a shorter or lower-res clip.")
        return

    size_mb = dst.stat().st_size / 1024 / 1024
    if size_mb > 2:
        await message.answer(f"Output is {size_mb:.1f} MB, over the 2 MB limit. Trim first.")
        return

    await message.answer_video(
        FSInputFile(dst),
        caption="Set this as your profile video: open Settings, tap the avatar, pick Video.",
    )

Notes on this:

F.video | F.animation | F.video_note | F.document catches every file type users actually send. Documents matter because Telegram Desktop uploads MP4s as documents by default, not videos.

I use asyncio.create_subprocess_exec instead of subprocess.run because the bot handles concurrent requests. Blocking on ffmpeg would freeze every other user's conversion.

The 2 MB post-check is a safety net. My bitrate settings usually keep the file comfortably under, but a very high-motion 10-second clip can spike past. Rather than silently produce a file Telegram will reject, I return an explicit error and let the user trim.

Packaging it as @liveavabot

The bot is live at @LiveAvaBot with 301 users so far. Behind the scenes it runs on a small VPS: one Python process, ffmpeg from apt, a SQLite database for user state and rate limits. Nothing fancy. The whole thing is under 2000 lines of Python.

I added a few conveniences on top of the ffmpeg core:

HEVC pre-detection: ffprobe reads the codec first. If the input is already H.264 under 2 MB and 800x800, I skip re-encoding and just send it back.
Rate limit: 5 conversions per user per hour. Prevents someone from hammering the queue.
GIF support: .gif inputs get treated as animations, output as MP4. Telegram avatars must be MP4, animated GIFs will not work as avatars directly.

Edge cases and what is next

Things that still trip the bot up:

4K vertical iPhone clips: cropping to 800x800 loses too much face. I want to add a face-detection pass to center on the subject instead of the geometric center.
Weird pixel formats: some Android phones export in exotic YUV variants that ffmpeg auto-converts wrong. Forcing -pix_fmt yuv420p early in the filter chain catches most of these.
Silent audio tracks: -an strips them, but I have seen odd cases where the video still fails until I re-mux with an explicit -map 0:v:0. Not fully debugged.

Next up: a /crop_square command that lets the user pick which part of a 16:9 video to keep, since automatic center-crop is not always right for portrait clips.

Built by me, @liveavabot on Telegram.

Converting iPhone HEVC Videos to Telegram Video Avatars with FFmpeg

liveavabot — Sun, 09 Aug 2026 07:04:10 +0000

The problem: iPhone videos silently die as Telegram avatars

Telegram lets you set a short video as your profile picture. It's a nice feature. But if you try to upload a video shot on an iPhone, it often just fails. No error, no explanation, the upload spinner runs and then nothing happens.

I hit this myself last month. Shot a 4-second clip, tried to set it as my avatar, got nothing. Turned out the file was HEVC (H.265), which iPhones use by default since iOS 11. Telegram's video avatar endpoint only accepts H.264. It doesn't tell you that. It just silently rejects.

So I built @LiveAvaBot. Send it any video or GIF, get back a file that Telegram will actually accept as your profile picture. Under the hood it's a thin wrapper around ffmpeg with some aiogram glue. This post is the technical write-up.

What Telegram's video avatar spec actually requires

I dug through the Bot API docs and did a bunch of testing. The undocumented reality:

Codec: H.264 (yuv420p pixel format). HEVC gets rejected.
Container: MP4 with faststart flag (moov atom at the front).
Resolution: exactly 800x800 square. Non-square videos need cropping, not letterboxing.
Duration: max 10 seconds. Anything longer gets truncated or rejected.
File size: under 2MB. Bigger files fail silently.
Audio: must be stripped. Even a silent audio track sometimes causes issues.
Framerate: 30fps works, higher rates occasionally break.

The 2MB cap is the interesting one. It means you can't just crank the bitrate. You have to actually think about the encoding.

FFmpeg: cropdetect, scale, encode

The pipeline has two ffmpeg passes. First pass runs cropdetect to figure out where the actual content sits (some videos have black bars). Second pass does the real conversion.

ffmpeg -i input.mov -vf cropdetect=24:16:0 -f null - 2>&1 | \
  grep -oE 'crop=[0-9:]+' | tail -1

That gives you something like crop=1080:1080:0:420. Feed it back into the encode:

ffmpeg -y -i input.mov \
  -t 10 \
  -vf "crop=1080:1080:0:420,scale=800:800:flags=lanczos,fps=30,format=yuv420p" \
  -c:v libx264 -profile:v high -level 4.0 \
  -pix_fmt yuv420p \
  -b:v 1400k -maxrate 1600k -bufsize 3200k \
  -movflags +faststart \
  -an \
  output.mp4

Breaking down the flags that matter:

-t 10 caps duration at 10 seconds.
crop=... uses the values from the detect pass.
scale=800:800:flags=lanczos gets us to the required square. Lanczos is sharper than default bicubic.
format=yuv420p inside the filter graph, plus -pix_fmt yuv420p on the output. Belt and suspenders. HEVC often uses yuv420p10le which Telegram hates.
-b:v 1400k targets the 2MB budget for 10 seconds. Adjust down for longer clips.
-movflags +faststart puts the moov atom at the start of the file. Telegram needs this for streaming.
-an drops audio.

Bitrate math: 2MB is roughly 16 Mbit. Over 10 seconds that's a 1.6 Mbit/s ceiling. I aim for 1.4 Mbit/s target with a 1.6 Mbit/s cap, and the file lands around 1.7 to 1.8MB in practice. Enough headroom for the container overhead.

The aiogram 3 handler

Nothing fancy on the bot side. Download the incoming file, run the pipeline, send back the result.

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

router = Router()

async def run_ffmpeg(input_path: Path, output_path: Path) -> None:
    detect = await asyncio.create_subprocess_exec(
        "ffmpeg", "-i", str(input_path),
        "-vf", "cropdetect=24:16:0", "-f", "null", "-",
        stdout=asyncio.subprocess.DEVNULL,
        stderr=asyncio.subprocess.PIPE,
    )
    _, stderr = await detect.communicate()
    crop = parse_crop(stderr.decode()) or "in_w:in_h:0:0"

    encode = await asyncio.create_subprocess_exec(
        "ffmpeg", "-y", "-i", str(input_path),
        "-t", "10",
        "-vf", f"crop={crop},scale=800:800:flags=lanczos,fps=30,format=yuv420p",
        "-c:v", "libx264", "-profile:v", "high", "-level", "4.0",
        "-pix_fmt", "yuv420p",
        "-b:v", "1400k", "-maxrate", "1600k", "-bufsize", "3200k",
        "-movflags", "+faststart",
        "-an",
        str(output_path),
    )
    await encode.wait()

@router.message(F.video | F.animation | F.document)
async def handle_video(message: Message) -> None:
    file = message.video or message.animation or message.document
    if not file:
        return

    with tempfile.TemporaryDirectory() as tmp:
        tmp_path = Path(tmp)
        src = tmp_path / "src"
        dst = tmp_path / "avatar.mp4"
        await message.bot.download(file, destination=src)
        await run_ffmpeg(src, dst)
        await message.answer_video(
            FSInputFile(dst),
            caption="Ready. Long-press your profile picture in Telegram to set it."
        )

The parse_crop helper is five lines of regex on the ffmpeg stderr, I won't bore you with it.

Points worth calling out:

F.video | F.animation | F.document catches all three ways Telegram delivers uploaded video content. GIFs come in as animation. Compressed video is video. Uncompressed (send-as-file) is document.
Using asyncio.create_subprocess_exec instead of subprocess.run keeps the bot responsive under concurrent load. On my single-CPU VPS I can process 3 or 4 clips in parallel before ffmpeg starts thrashing.
The temporary directory is nuked on exit. No leftover files.

Packaging it as a bot

The actual bot runs on a small Hetzner box under systemd. aiogram 3 with long polling (no webhook, no reverse proxy, keeps ops simple). SQLite for the tiny amount of state I keep (user id, conversion count for basic analytics).

The whole thing is maybe 300 lines of Python plus the ffmpeg invocation. If you want to try it, send a video to the bot.

Edge cases and things that broke

A few things that cost me hours of debugging:

Portrait videos with bars. The cropdetect pass helps a lot, but sometimes it catches actual content as "black" if the video opens on a dark scene. Adding cropdetect=24:16:0,select='gt(t\,1)' skips the first second before detecting.

Live Photos. These are a HEIC still plus a short MOV. iPhone sends the MOV part when you share. Usually fine, but the MOV is often only 1.5 seconds and shows up jittery. I don't do anything special, just document it.

Slow-mo footage. iPhone slow-mo is 240fps internally but plays back at variable rate via metadata. ffmpeg respects the playback rate, so the output looks smooth. Was a pleasant surprise, not something I had to fix.

Audio track presence. Even with -an, some source files with weird audio containers cause the mux to complain. Adding -map 0:v:0 explicitly before -c:v forces video-only mapping and shuts that up.

What's next

Currently handling around 300 users with a couple of conversions per day. Things on my list:

Batch mode: send multiple videos, get a zip back.
4K source handling. Right now anything over 1080p gets awkward memory usage during the crop pass.
Optional audio on avatars for Telegram Premium users (spec allows it, I just haven't wired it up).

If you want to build something similar, ffmpeg is doing 95% of the work. I just wrote the wrapper and the retry logic for when an encode fails.

Built by me. Live at @LiveAvaBot.

LiveAvaBot Developer API: Embed Telegram Video Avatar Conversion in Your App

liveavabot — Fri, 07 Aug 2026 06:02:08 +0000

I built @liveavabot last year to fix a stupid problem: iPhone videos silently fail as Telegram video avatars. The bot has processed conversions for 290 users so far, and a few of them asked the same question: "can I hit this from my own code?"

So I shipped a REST API. This post walks through the Telegram spec that makes video avatars weird, the ffmpeg pipeline that solves it, and how to call the new endpoint from your own app.

Why video avatars are harder than they look

Telegram's video avatar format is picky. The spec, if you dig into the Bot API docs and the desktop client source, boils down to:

Codec: H.264 (yuv420p pixel format), audio track removed
Resolution: 800x800, square, center-cropped
Duration: 3 to 10 seconds
File size: under 2 MB
Container: MP4 with faststart flag

Miss any of these and Telegram either rejects the upload with a generic error or, worse, accepts it and displays a black square. iPhone videos are HEVC (H.265) by default since iOS 11, and Telegram's avatar upload does not transcode. It just refuses.

Most users never figure out why their video "doesn't work." They try three times, give up, use a still photo.

The ffmpeg pipeline

Here is the actual command the bot runs. It does cropdetect to find the tightest square crop, then re-encodes to spec:

ffmpeg -i input.mov \
  -vf "crop='min(iw,ih)':'min(iw,ih)',scale=800:800,format=yuv420p" \
  -c:v libx264 -profile:v high -level 4.0 \
  -preset medium -crf 23 \
  -movflags +faststart \
  -an \
  -t 10 \
  -y output.mp4

A few things worth noting:

crop='min(iw,ih)':'min(iw,ih)' grabs a centered square from portrait or landscape source. No math, ffmpeg figures it out.
format=yuv420p is the pixel format Telegram actually renders. Skip it and iOS devices show nothing.
-an strips audio. Telegram ignores it anyway, but including it counts toward the 2 MB budget.
-movflags +faststart moves the moov atom to the front. Without it, Telegram sometimes chokes on large files even when they fit the size limit.
-t 10 hard-caps duration at 10 seconds. If the source is shorter, ffmpeg just uses what's there.

CRF 23 usually keeps a 10-second 800x800 clip under 2 MB. If it goes over, the bot re-runs with CRF 28 as a fallback.

The aiogram 3 handler

The Telegram-side code is boring on purpose. Grab the file, hand it to the converter, send the result back:

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

router = Router()

@router.message(F.video | F.animation | F.document)
async def handle_video(msg: Message):
    file = msg.video or msg.animation or msg.document
    src = Path(f"/tmp/{file.file_id}.mov")
    dst = Path(f"/tmp/{file.file_id}_avatar.mp4")

    await msg.bot.download(file, destination=src)
    await msg.answer("converting...")

    proc = await asyncio.create_subprocess_exec(
        "ffmpeg", "-i", str(src),
        "-vf", "crop='min(iw,ih)':'min(iw,ih)',scale=800:800,format=yuv420p",
        "-c:v", "libx264", "-crf", "23",
        "-movflags", "+faststart", "-an", "-t", "10",
        "-y", str(dst),
    )
    await proc.wait()

    await msg.answer_video(FSInputFile(dst))
    src.unlink(missing_ok=True)
    dst.unlink(missing_ok=True)

In production the converter runs in a worker with a queue, size checks, HEVC detection, and a fallback CRF pass. But this snippet is what the core actually does.

The REST API

A few devs asked to embed this in their own apps: profile-picture flows in a client, a wedding-video service, a Discord-to-Telegram bridge. So I exposed the same pipeline over HTTP.

Endpoint

POST /api/v1/convert
Authorization: Bearer <token>
Content-Type: multipart/form-data

file: <video>
preset: lofi|bw|vignette|blur|none  (optional, default: none)
trim_start: 0.0  (optional)

Response

{
  "status": "ok",
  "output_url": "https://...",
  "duration_s": 8.2,
  "size_bytes": 1847291,
  "codec": "h264"
}

The preset parameter applies an ffmpeg filter chain on top of the base conversion. lofi adds grain and a slight desaturation, bw is a straight greyscale, vignette is the ffmpeg vignette filter with defaults, blur is a soft gaussian on the edges. trim_start shifts the source window if the good bit is not at second zero.

Output URLs are signed and expire after 1 hour. Downloading the file is your job; the bot does not keep it.

Getting a token

Send /api to @liveavabot and it DMs you a token. Rate limits are generous during beta (60 requests per hour per token), let me know if you hit them.

Quick curl example

curl -X POST https://api.liveava.bot/api/v1/convert \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@my_video.mov" \
  -F "preset=lofi"

Lessons and edge cases

A few things I learned shipping this:

HEVC detection has to happen before you trust anything. ffprobe -show_streams is your friend. Some "MP4" files from Android are actually HEVC in an MP4 container.
The 2 MB limit is not always exactly 2 MB. Telegram seems to accept up to ~2.1 MB in practice, but I keep the target under 1.9 MB to be safe.
4K source video is still rough. The crop+scale pass on a 4K 60fps clip takes 15-20 seconds on the current worker. I have not optimised this yet.
The API's biggest surprise: about half the traffic is from people testing whether their video will work before they even open Telegram. That was not the use case I designed for.

Built by me, @liveavabot is at https://t.me/LiveAvaBot?start=devto_article_20260807. API docs and token via /api in the bot. Feedback welcome, especially from anyone building on top of it.

Converting iPhone HEVC Videos to Telegram Video Avatars With FFmpeg and Aiogram 3

liveavabot — Wed, 05 Aug 2026 05:02:59 +0000

I built a tiny Telegram bot that does one boring thing: it takes any video or GIF you send it and spits back a file Telegram will actually accept as a video avatar. Sounds trivial. It wasn't.

The reason it wasn't trivial is that Telegram's video-avatar format is a narrow slice of MP4, and iPhone videos land outside that slice by default. If you drag a fresh iPhone clip into the desktop app's avatar picker, Telegram just says the file is not supported. No hint about codec, no hint about duration, no hint about resolution. So I read the spec, wrote an ffmpeg pipeline, wrapped it in aiogram 3, and shipped it as @liveavabot. This post is the build log.

The pain: iPhone HEVC silently fails

Since iOS 11 the default camera codec is HEVC (H.265) in an .mov container, yuv420p10le, variable frame rate. Telegram's clients decode HEVC fine for playback, but the avatar upload path is stricter than the general video path. It wants H.264, baseline or main profile, 8-bit yuv420p, square 800x800, no audio, up to 10 seconds, up to 2 MB, and moov atom at the front so the server can index it without downloading the whole file.

Send it a 4K HEVC portrait clip and it rejects the file with a generic error. Users assume the bot is broken. It isn't, Telegram is just picky and quiet about it.

So the bot's job is to normalize any input into that narrow slice.

What the Telegram spec actually requires

From the API docs and a lot of trial and error, a working video avatar looks like this:

Container: MP4, moov atom at the start (-movflags +faststart).
Video codec: H.264, profile main or baseline, level 3.1 or lower.
Pixel format: yuv420p (8-bit, not 10-bit).
Resolution: 800x800, square, center-cropped from the source.
Frame rate: constant, 30 fps works reliably.
Duration: up to 10 seconds, hard cap.
Audio: none, must be stripped.
File size: under 2 MB. This is the real constraint, everything else you can hit easily.

The 2 MB cap is what makes the encoding interesting. At 800x800 30fps for 10 seconds you have about 1.6 Mbps of budget. That is thin for anything with motion, so the bot has to be honest about bitrate and use a two-pass or CRF-with-cap strategy.

The ffmpeg pipeline

I settled on a two-step approach: first probe the source with cropdetect to find the actual content bounds (iPhone videos are often letterboxed or shot in portrait), then encode with a hard bitrate ceiling.

Here is the cropdetect probe. It samples a few frames and prints suggested crop rectangles:

ffmpeg -ss 0.5 -i input.mov -t 2 \
  -vf cropdetect=24:16:0 \
  -f null - 2>&1 | grep -oP 'crop=\S+' | tail -1

That gives you something like crop=1080:1080:0:420. The bot parses that and feeds it into the real encode:

ffmpeg -y -i input.mov \
  -t 10 \
  -vf "crop=1080:1080:0:420,scale=800:800:flags=lanczos,fps=30,format=yuv420p" \
  -an \
  -c:v libx264 -profile:v main -level 3.1 \
  -preset veryfast -crf 26 \
  -maxrate 1400k -bufsize 2800k \
  -movflags +faststart \
  output.mp4

A few things worth calling out:

-t 10 before -i would seek in the input, which is faster but can miss the intended clip start. Placing it after -i cuts the output cleanly.
format=yuv420p in the filter chain forces 8-bit even if the source is 10-bit HEVC. Without this, x264 will bail on some inputs.
-an strips audio. Telegram rejects avatars with an audio track even if it's silent.
-crf 26 with -maxrate 1400k is a compromise. CRF alone can blow the 2 MB cap on high-motion clips, so the maxrate is a safety net. If the output still lands over 2 MB, the bot re-encodes with -crf 30 and a lower maxrate.
-movflags +faststart moves the moov atom to the front. Telegram's server needs this to accept the upload without a full download.

After this pipeline, a 47 MB 4K HEVC portrait clip from an iPhone 15 becomes a 1.7 MB square MP4 that Telegram accepts on the first try.

The aiogram 3 handler

The bot itself is small. aiogram 3 makes the routing clean. Here is the trimmed video handler:

import asyncio
import tempfile
from pathlib import Path

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

router = Router()


@router.message(F.video | F.animation | F.document)
async def handle_video(message: Message) -> None:
    file = message.video or message.animation or message.document
    if not file:
        await message.reply("send a video or gif")
        return

    with tempfile.TemporaryDirectory() as tmp:
        src = Path(tmp) / "in.bin"
        dst = Path(tmp) / "out.mp4"

        await message.bot.download(file, destination=src)

        crop = await detect_crop(src)
        ok = await encode_avatar(src, dst, crop)

        if not ok or dst.stat().st_size > 2 * 1024 * 1024:
            await message.reply("could not fit under 2mb, try a shorter clip")
            return

        await message.reply_video(FSInputFile(dst), caption="upload this in settings as your video avatar")


async def detect_crop(src: Path) -> str:
    proc = await asyncio.create_subprocess_exec(
        "ffmpeg", "-ss", "0.5", "-i", str(src), "-t", "2",
        "-vf", "cropdetect=24:16:0", "-f", "null", "-",
        stdout=asyncio.subprocess.DEVNULL,
        stderr=asyncio.subprocess.PIPE,
    )
    _, err = await proc.communicate()
    for line in reversed(err.decode(errors="ignore").splitlines()):
        if "crop=" in line:
            return line.split("crop=")[-1].split()[0]
    return "in_w:in_h:0:0"

The encode_avatar function is a thin wrapper around the ffmpeg command above. If the first pass overshoots 2 MB, it retries with tighter parameters. Two retries is enough for 99% of inputs I have seen so far.

One gotcha: F.document catches files Telegram treats as documents rather than videos, which happens when the client uploads a raw .mov. Without that filter, iPhone shares from the Files app get ignored.

Packaging as @liveavabot

The bot lives at https://t.me/LiveAvaBot?start=devto_article_20260805. Send it any video, get back a Telegram-ready 800x800 MP4. It also handles GIFs (animation type) and raw documents. Hosting is a small VPS with ffmpeg installed from the distro repo. No queue, no worker pool, just async subprocesses. At 281 total users and a handful of conversions a day it does not need more.

The stack: aiogram 3 for the Telegram side, ffmpeg for the encoding, sqlite for logs and stats. Deployment is a systemd unit and a git pull. That is the whole thing.

Lessons and edge cases

A few things I learned the hard way:

Portrait videos are the norm on mobile. Assume the input is 9:16 and center-crop to square, do not fit-with-black-bars. Users hate letterboxing on avatars.
10-bit HEVC is more common than you think. Always force format=yuv420p in the filter chain, not just as an output pixel format.
The 2 MB cap is what fails, not codec or resolution. Build the retry loop first, the crop logic second.
Telegram does not tell you why the avatar upload failed. If your file matches the spec and still fails, check ffprobe output.mp4 for extra streams (subtitles, data streams). Strip them with -map 0:v:0 if needed.
4K sources are slow to decode on tiny VPS boxes. A 20-second 4K HEVC clip took 14 seconds to process on a 2-vCPU machine. Users are patient for up to about 10 seconds, so I cap accepted input duration and warn early.

What is next: proper 4K handling with a two-pass encode, and a preview thumbnail so users see the crop before uploading. The crop is right most of the time, but for landscape videos with the subject on one side it picks the middle and cuts them out.

Built by me, @liveavabot: https://t.me/LiveAvaBot?start=devto_article_20260805. Feedback and edge-case clips welcome, that is how the crop heuristic gets better.

Three Aiogram 3 Patterns From Building a Telegram Video Bot

liveavabot — Mon, 03 Aug 2026 04:03:24 +0000

The problem: iPhone videos silently fail as Telegram avatars

Telegram has a feature where your profile picture can be a short looping video instead of a still image. Cool feature. Except when you upload an iPhone video, Telegram either rejects it silently or shows a generic error. Nothing tells you why.

The reason: iPhones since 2016 record video in HEVC (H.265) by default. Telegram's video avatar endpoint accepts H.264 only, and the file has strict constraints most people never see documented in one place.

I got tired of manually converting videos in an ffmpeg terminal every time a friend asked how to set a video avatar. So I built @liveavabot: forward any video or GIF, get back a Telegram-compatible avatar file, tap "set as profile photo", done.

This post covers three aiogram 3 patterns that made the bot maintainable as it grew from a 200-line script to a service handling a few hundred users a day.

What Telegram actually requires

Before any code, the spec you need to hit:

Codec: H.264 (libx264)
Pixel format: yuv420p
Container: mp4 with faststart flag
Resolution: 800x800 (square)
Duration: 10 seconds or less
File size: 2 MB or less
Audio: none (strip the audio track entirely)
Frame rate: 30 fps is safe, 60 works if size allows

Miss any of these and Telegram gives you an unhelpful error or accepts the file but refuses to display it as an avatar. The 2 MB ceiling is the killer. It forces you to think about bitrate carefully on every encode.

Pattern 1: FSMContext plus inline keyboards for multi-step flows

The first version of the bot was one handler: send video, get result. Then I wanted presets ("Lofi", "B&W", "Vignette"). That meant asking the user which filter to apply after they sent the video. FSMContext turned out to be the cleanest way.

from aiogram import F, Router
from aiogram.fsm.state import State, StatesGroup
from aiogram.fsm.context import FSMContext
from aiogram.types import (
    Message, CallbackQuery,
    InlineKeyboardMarkup, InlineKeyboardButton,
)

router = Router()

class ConvertFlow(StatesGroup):
    waiting_preset = State()

def preset_kb() -> InlineKeyboardMarkup:
    return InlineKeyboardMarkup(inline_keyboard=[[
        InlineKeyboardButton(text="Lofi", callback_data="preset:lofi"),
        InlineKeyboardButton(text="B&W", callback_data="preset:bw"),
        InlineKeyboardButton(text="Vignette", callback_data="preset:vignette"),
        InlineKeyboardButton(text="Blur", callback_data="preset:blur"),
    ]])

@router.message(F.video | F.animation)
async def got_video(message: Message, state: FSMContext):
    file_id = (message.video or message.animation).file_id
    await state.update_data(file_id=file_id)
    await state.set_state(ConvertFlow.waiting_preset)
    await message.answer("Pick a preset:", reply_markup=preset_kb())

@router.callback_query(F.data.startswith("preset:"))
async def picked_preset(cq: CallbackQuery, state: FSMContext):
    preset = cq.data.split(":", 1)[1]
    data = await state.update_data(preset=preset)
    await cq.answer()
    await do_conversion(cq.message, data["file_id"], preset)
    await state.clear()

Two things I learned the hard way.

Keep the state small. Store only the file_id (Telegram gives you a persistent handle) plus a couple of user choices. Do not stash raw bytes in state. Redis or MemoryStorage will hate you.

Always set a timeout. Users abandon flows. I added a background task that clears any state older than 15 minutes.

Also worth noting: callback_data is capped at 64 bytes and must be a string. For anything more complex than a fixed enum, use aiogram's CallbackData factory. It gives you typed payloads with validation. Cleaner than parsing colon-separated strings once you have five or more actions.

Pattern 2: A semaphore to keep ffmpeg from eating the VPS

ffmpeg is CPU-bound and hungry. Four concurrent invocations on a 2-core VPS will spike load average past 8 and the bot stops responding to pings. I learned this when a small burst of users made the systemd service look dead to my monitoring.

The fix is one line:

import asyncio

_SEM = asyncio.Semaphore(4)

async def run_ffmpeg(cmd: list[str]) -> tuple[int, bytes, bytes]:
    async with _SEM:
        proc = await asyncio.create_subprocess_exec(
            *cmd,
            stdout=asyncio.subprocess.PIPE,
            stderr=asyncio.subprocess.PIPE,
        )
        stdout, stderr = await proc.communicate()
        return proc.returncode, stdout, stderr

Tune the semaphore value to your host. On a 4-core box I use 4. On a 2-core VPS I use 2. Users see a small queue delay under load but the bot stays responsive on the aiogram event loop, which is what matters. Sending a "typing" chat action covers the wait.

Pattern 3: The actual ffmpeg pipeline

Here is the command the bot runs. It uses cropdetect first to find the largest content region, then re-encodes to Telegram's spec:

# step 1: find the crop box from a 3-second sample
ffmpeg -y -i input.mov \
  -vf "cropdetect=24:16:0,metadata=mode=print" \
  -f null -t 3 - 2>&1 | grep crop=

# step 2: encode using the detected crop
ffmpeg -y -i input.mov \
  -t 10 \
  -vf "crop=1080:1080:420:0,scale=800:800,fps=30,format=yuv420p" \
  -c:v libx264 -preset veryfast -crf 26 \
  -movflags +faststart \
  -an \
  output.mp4

Why each flag matters:

-t 10 hard-caps duration before encoding, avoids extra work
crop=... uses cropdetect output, so a 16:9 iPhone video becomes a centered square instead of a squashed rectangle
scale=800:800 matches Telegram avatar dimensions
fps=30 normalizes frame rate, some sources have variable fps that breaks looping
format=yuv420p is the pixel format Apple hardware decoders expect
-crf 26 is a quality setting that usually lands under 2 MB for 10 seconds
-movflags +faststart moves the moov atom to the front, needed for streaming
-an strips audio, required by the avatar spec

If the output is still over 2 MB, the bot re-runs with -crf 28, then -crf 30. Three attempts, then it gives up and tells the user.

Lessons and edge cases

A few things the tutorials never mention:

Animated GIFs come in as message.animation, not message.video. Handle both, or you drop half the "convert my meme" requests.
Portrait iPhone videos have rotation metadata. ffmpeg respects it if you do nothing, but if you use raw -map, you can end up sideways. Test with a portrait video before shipping.
Some videos have the moov atom at the end. They will not stream. -movflags +faststart fixes it on the encode side.
Users forward videos that Telegram itself recompressed twice already. Quality is already gone by the time you get them. Nothing you can do about it, just document it.
File size targets are cliffs. 2.00 MB works, 2.01 MB does not. Always encode with a safety margin.

The bot runs on a small VPS handling a few hundred users a day. Total ffmpeg time per conversion is 3 to 8 seconds. aiogram 3's async model keeps interaction snappy while workers grind in the background.

If you want to try it: t.me/LiveAvaBot. Send any video or GIF, get a Telegram-ready avatar back.

Built by me, @liveavabot.

Why Your iPhone Video Fails as a Telegram Avatar (and How to Fix It)

liveavabot — Sat, 01 Aug 2026 03:04:46 +0000

The silent failure

I tried to set a video as my Telegram profile picture. Recorded a 6-second clip on my iPhone 15, opened Telegram Desktop, hit "Set as video". Progress bar filled. Nothing happened. No error, no warning, just... nothing. My profile still had the old static photo.

Turned out the iPhone recorded in HEVC (H.265), and Telegram's video avatar endpoint accepts H.264 only. It doesn't tell you that. It just accepts the upload and drops it on the floor.

That's the bug I wanted to fix, and it became @LiveAvaBot.

What Telegram actually wants

The official spec for video profile pictures isn't documented in one place. I pieced it together from the Bot API docs, the Telegram Desktop source, and trial and error:

Codec: H.264, yuv420p pixel format
Container: MP4 with faststart
Resolution: 800x800, square, cropped from center
Duration: up to 10 seconds (longer gets rejected)
File size: under 2 MB (soft cap, sometimes 3 MB works)
Audio: must be stripped (any audio stream causes silent rejection on some clients)
Frame rate: 30 fps max (60 fps works but adds size)

Miss any of these and the client silently fails. No 400 response, no toast, nothing.

The ffmpeg pipeline

The core transform is a two-pass ffmpeg call. First, cropdetect on a sample of the video to find where the actual content is, then a scale+crop+encode pass to produce the square 800x800 output.

# Pass 1: detect crop rectangle
ffmpeg -ss 0 -t 3 -i input.mov \
  -vf "cropdetect=24:16:0" \
  -f null - 2>&1 | grep -o "crop=[0-9:]*" | tail -1

# Pass 2: crop + scale + encode
ffmpeg -y -i input.mov \
  -vf "crop=1080:1080:420:540,scale=800:800,fps=30,format=yuv420p" \
  -c:v libx264 -preset veryfast -crf 26 \
  -movflags +faststart \
  -an -t 10 \
  -pix_fmt yuv420p \
  output.mp4

The -an strips audio. The format=yuv420p in the filter chain and -pix_fmt yuv420p at the codec level both matter. Some clients care about the container-level pixel format flag, others read from the codec stream.

Tuning -crf was the tricky part. At crf=23 (ffmpeg default), a 10-second 800x800 clip often ended up around 3.5 MB, over the Telegram limit. At crf=28, quality got mushy in low-light scenes. crf=26 with -preset veryfast was the sweet spot for a 2 MB budget.

For clips that still bust the size limit, I do a second encode pass with crf=30 and 24 fps as a fallback. That covers about 95% of uploads without going to a full two-pass ABR encode, which would double the CPU cost.

Wiring it into aiogram 3

The bot logic is standard aiogram 3. Receive a video, download it, run the pipeline, send back as an input file. Here's the handler:

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

router = Router()

@router.message(F.video | F.animation | F.document)
async def handle_video(msg: Message):
    file = msg.video or msg.animation or msg.document
    if file.file_size and file.file_size > 20 * 1024 * 1024:
        await msg.reply("File too big. Max 20 MB.")
        return

    with tempfile.TemporaryDirectory() as tmp:
        src = Path(tmp) / "input"
        dst = Path(tmp) / "output.mp4"

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

        status = await msg.reply("Converting...")
        try:
            await asyncio.to_thread(run_pipeline, src, dst)
        except subprocess.CalledProcessError as e:
            await status.edit_text(f"ffmpeg failed: {e.returncode}")
            return

        await msg.reply_video(
            FSInputFile(dst),
            caption="Ready. Long-press your profile photo, tap Edit, choose Set as Avatar.",
        )
        await status.delete()

asyncio.to_thread is important. ffmpeg is CPU-bound and blocks. Running it in a thread keeps the event loop responsive so other users don't stall behind a single long encode.

Packaging it as @liveavabot

Deploy target: a small Hetzner box with systemd. Ffmpeg from apt, Python 3.11 in a venv, aiogram 3.4. No Docker, no k8s, one unit file and a token.

Currently at 265 users, most from a single Reddit thread on r/Telegram. Conversion rate on video uploads sits around 80%. The 20% that fail are usually 4K HDR clips where the encode busts the size limit even at crf=30. Still an open TODO.

Try it here: https://t.me/LiveAvaBot?start=devto_article_20260801. Send a video, get a Telegram-ready MP4 back in about 8 seconds for a typical 6-second iPhone clip.

Edge cases I hit along the way

HDR to SDR: iPhone 15 records in HDR HLG. Telegram doesn't render HDR, colors come out washed. Added zscale=t=linear:npl=100,format=gbrpf32le,zscale=p=bt709,tonemap=hable:desat=0,zscale=t=bt709:m=bt709:r=tv,format=yuv420p to the filter chain. Ugly, but works.
Portrait vs landscape: cropdetect picks up letterboxing on portrait video shot in landscape orientation. I bypass it for aspect ratios more square than 1:1.2.
GIFs from Twitter: they come in as MP4 with no audio stream already. The -an flag is a no-op there but doesn't hurt.
Rotation metadata: MOVs with rotate=90 in metadata need -vf filters applied after auto-rotation. -noautorotate and then a manual transpose filter fixed a batch of clips that were coming out sideways.

What's next

Better fallback for oversized 4K clips, probably a two-pass ABR encode gated on file size. A /gif mode that outputs animated MP4 stickers. And figuring out why some Android clients still reject the output even though it passes every spec check I know about.

Built by me, @LiveAvaBot.

Converting iPhone HEVC Videos to Telegram Video Avatars with FFmpeg

liveavabot — Thu, 30 Jul 2026 03:02:55 +0000

The bug that made me write this

I tried setting a short clip from my iPhone as my Telegram profile video. Telegram accepted the upload, showed a spinner, then quietly reverted to my old static picture. No error message. No hint. Just the old avatar again.

The clip was H.265 (HEVC), which iPhones record by default. Telegram's video avatar endpoint accepts H.264 only. The upload technically worked, the server just refused to use the file, and there was no user-visible reason.

I wrote a bot that takes any video or GIF and produces a file Telegram will actually accept as a video avatar. This post is the ffmpeg pipeline and the aiogram 3 handler that runs it.

What Telegram's video avatar format actually is

Telegram doesn't document this well, but reverse engineering it gives you:

Container: MP4
Video codec: H.264, yuv420p, high profile is fine
Audio: must be removed entirely
Resolution: 800x800 square, exact
Duration: 10 seconds max (I clamp to 9.9 to be safe)
File size: 2 MB max
Frame rate: 30 fps works, higher gets rejected sometimes
moov atom at the front (faststart)

If any of those are wrong, the upload either silently fails or the avatar shows as a still frame from second zero.

The ffmpeg pipeline

The tricky part is turning a rectangular phone video into an 800x800 square without ugly letterboxing. I run cropdetect on a probe pass, then crop and scale in the encode pass.

ffmpeg -ss 00:00:02 -i input.mov -vframes 10 \
  -vf cropdetect=24:16:0 -f null - 2>&1 | \
  grep -o 'crop=[0-9:]*' | tail -1
# example output: crop=1080:1080:0:420

Then the actual encode with the detected crop values:

ffmpeg -y -i input.mov \
  -t 9.9 \
  -an \
  -vf "crop=1080:1080:0:420,scale=800:800:flags=lanczos,format=yuv420p,fps=30" \
  -c:v libx264 -preset veryfast -crf 23 \
  -profile:v high -level 4.0 \
  -movflags +faststart \
  -pix_fmt yuv420p \
  output.mp4

Key flags:

-an drops audio. Telegram rejects avatars with any audio track.
-vf format=yuv420p plus the explicit -pix_fmt yuv420p are belt and suspenders. Some sources are yuv444p and Telegram won't touch that.
-movflags +faststart moves the moov atom to the start of the file so the server can begin streaming without downloading the whole thing.
-t 9.9 clamps duration. I found 10.0 flat sometimes gets rejected by rounding.
-crf 23 keeps files under 2 MB for most 9 second clips. If the output goes over, I re-encode with -crf 28 and warn the user about quality.

For GIFs I skip cropdetect and center-crop to a square, because GIFs are usually already framed for the subject.

Aiogram 3 handler

I run aiogram 3 with the Router pattern. The handler grabs the file, hands it to an async ffmpeg subprocess, then sends back the result.

import asyncio
import subprocess
import tempfile
from pathlib import Path

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

router = Router()

async def convert(src: Path, dst: Path) -> None:
    cmd = [
        "ffmpeg", "-y", "-i", str(src),
        "-t", "9.9",
        "-an",
        "-vf", "cropdetect=24:16:0,scale=800:800:flags=lanczos,format=yuv420p,fps=30",
        "-c:v", "libx264", "-preset", "veryfast", "-crf", "23",
        "-profile:v", "high", "-level", "4.0",
        "-movflags", "+faststart",
        "-pix_fmt", "yuv420p",
        str(dst),
    ]
    proc = await asyncio.create_subprocess_exec(
        *cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE
    )
    _, stderr = await proc.communicate()
    if proc.returncode != 0:
        raise RuntimeError(stderr.decode()[-500:])

@router.message(F.video | F.animation | F.document)
async def handle_video(message: Message) -> None:
    file = message.video or message.animation or message.document
    if not file:
        return

    with tempfile.TemporaryDirectory() as tmp:
        src = Path(tmp) / "in"
        dst = Path(tmp) / "out.mp4"

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

        try:
            await convert(src, dst)
        except RuntimeError as e:
            await message.answer(f"ffmpeg failed: {e}")
            return

        size_mb = dst.stat().st_size / 1024 / 1024
        if size_mb > 2.0:
            await message.answer(
                f"Output is {size_mb:.1f} MB, over the 2 MB Telegram limit. "
                "Try a shorter clip."
            )
            return

        await message.answer_video(FSInputFile(dst))

That's the core. The production version has more error handling, rate limiting, and metrics, but the pipeline is 40 lines.

Packaging this as @liveavabot

I put the pipeline behind a bot. Send it any video or GIF, get back an MP4 you can set as your Telegram video avatar. It handles iPhone HEVC, WhatsApp exports, Instagram reels saves, TikTok downloads, and other common sources.

Stack:

aiogram 3 on Python 3.11
ffmpeg 6.x from apt
systemd unit, no docker
SQLite for user counts and rate limiting
Hetzner CX22, 2 GB RAM is enough for concurrent ffmpeg jobs

Cost so far: 4 EUR per month for the VPS. ffmpeg does the actual work, I just wrote the wrapper and the Telegram plumbing.

Try it: https://t.me/LiveAvaBot?start=devto_article_20260730

Edge cases I hit

iPhone Live Photos: the .mov wrapper contains a still HEIC plus a 3 second video. ffmpeg picks the right stream automatically, but the aspect is often 4:3 not 16:9, so cropdetect matters.
Animated WebPs sent as stickers: Telegram sends these as documents with mime image/webp. ffmpeg handles them, but you need -r 30 on input or the output fps is broken.
Videos with rotation metadata: shoot vertical on iPhone, ffmpeg auto-rotates on read. Works fine.
Very short GIFs (under 1 second): I loop them to 3 seconds so the avatar isn't a blink. Use -stream_loop 3 -t 3 before -i.
Files over 20 MB: Telegram's bot API caps downloads at 20 MB. I catch that and tell the user to trim before sending.

What's next

Small backlog:

Auto face-detect crop instead of center-crop (dlib or mediapipe)
Batch mode for multiple videos in one message
Preset selection (portrait, landscape, action)

The core problem, HEVC to H.264 with the right specs, is solved. The rest is polish.

Built by me, @liveavabot on Telegram.

Converting iPhone HEVC Videos to Telegram Video Avatars With ffmpeg

liveavabot — Tue, 28 Jul 2026 02:03:13 +0000

I hit this bug last month. Uploaded a clip from my iPhone as a video avatar in Telegram. It processed, the UI said done, and then nothing happened. My avatar was still the old one. No error, no message, just silence.

Turns out Telegram silently rejects videos that don't match its exact video-avatar spec. And iPhone videos never match it, because Apple encodes in HEVC by default.

I got annoyed. I wrote a bot. Now it lives at t.me/LiveAvaBot and I want to walk through what the spec actually requires and how ffmpeg handles it.

What Telegram Actually Wants

The video-avatar format is stricter than most people realize. Here's what I reverse-engineered by trial and error:

Codec: H.264 (avc1). HEVC (hvc1) is rejected.
Resolution: exactly 800x800 square. Not 720, not 1080.
Pixel format: yuv420p. yuv420p10le fails silently.
Duration: 10 seconds or less. 10.1 seconds gets truncated with weird artifacts.
File size: 2 MB or less. Over that, Telegram compresses it aggressively and quality drops.
Audio: must be stripped. Audio tracks cause silent rejection on some clients.
Container: mp4 with faststart flag (moov atom at the start).

None of this is documented well. The Bot API accepts sendVideo happily, but for the personal profile video avatar the constraints tighten dramatically and there's no error surface. Your upload just quietly does nothing.

The Encode Pipeline

Most source videos aren't square. A phone clip is 1080x1920 portrait, a screen recording might be 1920x1080 landscape. You need to pick a 1:1 window from the interesting part of the frame.

I use ffmpeg's cropdetect filter to find where the actual content is (skipping black bars) and then center-crop a square from that. Two passes, first detect, then encode:

# Pass 1: detect crop rectangle
CROP=$(ffmpeg -i input.mov -vf cropdetect=24:16:0 -f null - 2>&1 \
  | grep -oE 'crop=[0-9:]+' | tail -1)

# Pass 2: encode with detected crop, scaled to 800x800
ffmpeg -y -loglevel error \
  -i input.mov \
  -t 10 \
  -vf "${CROP},scale=800:800:flags=lanczos,format=yuv420p,fps=30" \
  -an \
  -c:v libx264 -preset veryfast -crf 23 \
  -profile:v high -level 4.0 \
  -movflags +faststart \
  -f mp4 output.mp4

Breaking down the filters in pass 2:

crop=... cuts the detected rectangle from the source.
scale=800:800:flags=lanczos downscales to the target with a decent kernel.
format=yuv420p forces 8-bit 4:2:0 (kills HEVC 10-bit HDR).
fps=30 normalizes the frame rate. iPhone shoots 60, Telegram gets confused.
-an strips audio.
-t 10 clips to 10 seconds.
-movflags +faststart puts the moov atom at the front so Telegram can start playing before download completes.

CRF 23 with the veryfast preset lands most videos under 2 MB. If a clip goes over, I re-encode at CRF 28. Anything still over 2 MB gets rejected with a friendly message to the user.

The aiogram 3 Handler

Here's the minimal handler that ties it together. aiogram 3 with async/await, the whole path from receiving the video to responding with the converted file:

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

router = Router()

async def convert_to_avatar(src: str, dst: str) -> None:
    proc = await asyncio.create_subprocess_exec(
        "ffmpeg", "-y", "-loglevel", "error",
        "-i", src,
        "-t", "10",
        "-vf", "crop=in_h:in_h:(in_w-in_h)/2:0,scale=800:800:flags=lanczos,format=yuv420p,fps=30",
        "-an",
        "-c:v", "libx264",
        "-preset", "veryfast",
        "-crf", "23",
        "-profile:v", "high",
        "-level", "4.0",
        "-movflags", "+faststart",
        "-f", "mp4",
        dst,
        stderr=asyncio.subprocess.PIPE,
    )
    _, err = await proc.communicate()
    if proc.returncode != 0:
        raise RuntimeError(err.decode(errors="ignore"))

@router.message(F.video | F.animation | F.document)
async def handle_video(msg: Message):
    file = msg.video or msg.animation or msg.document
    if file.file_size and file.file_size > 50 * 1024 * 1024:
        await msg.reply("File too big. 50 MB cap.")
        return
    await msg.bot.send_chat_action(msg.chat.id, ChatAction.UPLOAD_VIDEO)
    with tempfile.TemporaryDirectory() as td:
        src = pathlib.Path(td) / "in.bin"
        dst = pathlib.Path(td) / "out.mp4"
        await msg.bot.download(file, destination=str(src))
        try:
            await convert_to_avatar(str(src), str(dst))
        except RuntimeError as e:
            await msg.reply(f"ffmpeg failed: {str(e)[:200]}")
            return
        if dst.stat().st_size > 2 * 1024 * 1024:
            await msg.reply("Output over 2 MB, try a shorter clip.")
            return
        await msg.reply_video(FSInputFile(dst))

That's the whole flow. Download, convert, check size, send back. In production I added a queue, per-user rate limiting, and better error messages, but this is the core.

Packaging It as a Bot

I wrapped this into a live bot: @LiveAvaBot. Users send any video or GIF, and get back a file they can drag into Telegram's video-avatar picker. It handles HEVC, portrait, landscape, GIFs, MOV, MP4, and weirder containers like webm.

The whole thing runs on a small VPS. ffmpeg does the heavy lifting, I just wrote the wrapper.

Edge Cases and What's Next

A few things I learned the hard way:

Rotation metadata: iPhone videos have a rotation flag in the container. Newer ffmpeg respects it by default, but on older builds the output comes out sideways. I added -noautorotate and handle rotation manually via transpose when the metadata says so.
Variable frame rate: Screen recordings often have VFR. Forcing fps=30 fixed frame-drift artifacts even without audio.
HDR to SDR: iPhone Pro shoots Dolby Vision. Just forcing yuv420p tone-maps poorly. I added a zscale plus tonemap chain when the source is HDR. It's ugly but works.
4K sources: Currently I downscale in one pass. Not great quality-wise. Next version will do a two-pass with proper sharpening.

Next on my list is a Telegram Stars payment for a batch mode (convert 10 clips at once). Free tier keeps the single-clip flow.

Built by me, @liveavabot. Feedback welcome, especially edge cases where my ffmpeg pipeline breaks.

Converting iPhone HEVC Videos to Telegram Video Avatars With FFmpeg

liveavabot — Sun, 26 Jul 2026 01:05:00 +0000

The Silent Failure

You record a short clip on your iPhone. You open Telegram Desktop, go to settings, click "Set video". The upload starts, spins for a second, and nothing happens. No error. No toast. The old picture avatar stays exactly where it was.

I hit this maybe twenty times before I sat down with tcpdump and figured out what was happening. Telegram's client silently drops the upload if the file does not match a very specific set of constraints. HEVC (the default codec on modern iPhones) is one of them. No warning, no fallback, just a dead upload.

What Telegram Actually Wants

After digging through the Bot API docs, MTProto source, and a few third-party clients, the requirements for a video avatar are:

Container: MP4 with faststart (moov atom at the front).
Video codec: H.264 baseline or main profile, yuv420p pixel format.
Resolution: exactly 800x800, square.
Duration: up to 10 seconds, ideally under 9.
File size: under 2 MB.
Audio: must be removed entirely. Not muted, removed.
Frame rate: 30 fps caps out cleanly.

Any of those wrong and the client refuses the upload without telling you why. HEVC is by far the most common cause because Apple made it the default in iOS 11 and never looked back.

The FFmpeg Recipe

The tricky part is not the codec conversion, that is one flag. The tricky part is going from a landscape or portrait clip to a centered 800x800 square without ugly black bars. I use cropdetect on the first pass to find the actual content bounds, then crop and scale on the second.

# Pass 1: find the crop box
ffmpeg -ss 1 -t 3 -i input.mov -vf cropdetect=24:16:0 -f null - 2>&1 \
  | grep -oP 'crop=[^ ]+' | tail -1
# outputs something like: crop=1080:1080:420:0

# Pass 2: crop, scale, re-encode, strip audio
ffmpeg -i input.mov \
  -vf "crop=1080:1080:420:0,scale=800:800:flags=lanczos,format=yuv420p" \
  -c:v libx264 -profile:v main -preset veryfast -crf 26 \
  -pix_fmt yuv420p \
  -t 9.5 -r 30 \
  -movflags +faststart \
  -an \
  output.mp4

Key flags worth calling out:

crop uses the values from cropdetect. I default to a centered square crop when detection fails.
format=yuv420p together with -pix_fmt yuv420p kills the "unsupported pixel format" issue you get with HEVC 10-bit source.
-an drops audio. Telegram rejects the upload if any audio track exists.
-movflags +faststart moves the moov atom so the client can start validating before the whole file arrives.
-crf 26 is a good starting quality. If the output pushes over 2 MB, bump to 28 and re-encode.

That single ffmpeg invocation handles about 95 percent of source files I have thrown at it. The remaining 5 percent are edge cases (extreme aspect ratios, corrupt containers, HDR metadata) that need per-case handling.

The Aiogram Handler

I wanted the whole thing behind a Telegram bot so you never have to touch ffmpeg yourself. Aiogram 3 with async subprocess kept this compact:

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

router = Router()

@router.message(F.video | F.animation | F.document)
async def handle_media(msg: Message):
    file = msg.video or msg.animation or msg.document
    if file.file_size > 20 * 1024 * 1024:
        await msg.answer("File is over 20 MB, too big to fetch.")
        return

    with tempfile.TemporaryDirectory() as tmp:
        src = Path(tmp) / "in.bin"
        dst = Path(tmp) / "out.mp4"
        await msg.bot.download(file, destination=src)

        rc = await run_ffmpeg(src, dst)
        if rc != 0 or not dst.exists():
            await msg.answer("Conversion failed. Try a shorter clip.")
            return

        if dst.stat().st_size > 2 * 1024 * 1024:
            await msg.answer("Result is over 2 MB. Try a shorter clip.")
            return

        await msg.answer_video(
            FSInputFile(dst),
            caption="Set this as your video avatar in Telegram settings.",
        )

async def run_ffmpeg(src: Path, dst: Path) -> int:
    cmd = [
        "ffmpeg", "-y", "-i", str(src),
        "-vf", "crop=in_h:in_h,scale=800:800:flags=lanczos,format=yuv420p",
        "-c:v", "libx264", "-profile:v", "main", "-preset", "veryfast",
        "-crf", "26", "-pix_fmt", "yuv420p",
        "-t", "9.5", "-r", "30",
        "-movflags", "+faststart", "-an",
        str(dst),
    ]
    proc = await asyncio.create_subprocess_exec(
        *cmd,
        stdout=asyncio.subprocess.DEVNULL,
        stderr=asyncio.subprocess.DEVNULL,
    )
    return await proc.wait()

Two things I got wrong on my first pass:

I forgot the 20 MB Bot API download cap. If you want bigger files you need a local Bot API server. For a "convert my selfie clip" use case, 20 MB is fine.
I originally sent the result as a document. Telegram treats documents differently in the video avatar picker. Sending as answer_video puts it in the video gallery where the avatar picker actually looks.

Packaged as a Bot

I bundled this into a bot called @liveavabot. Send it any video or GIF, get back a valid Telegram video avatar. It runs the same ffmpeg recipe above, plus a few extras: cropdetect fallback for weird aspect ratios, auto-CRF adjustment if the file lands over 2 MB, and animated GIF support (which needs -fflags +genpts to fix timestamps).

If you want to try it: https://t.me/LiveAvaBot?start=devto_article_20260726

Lessons and Edge Cases

Stuff I learned along the way that is not in any doc:

HEIC still images uploaded as "video" by some Android clients arrive as MP4 with a single frame. Detect and reject early with a duration check.
iPhone slow-motion clips have variable frame rates that some ffmpeg builds mishandle. Force -vsync cfr -r 30 to normalize.
HDR HEVC from newer iPhones has BT.2020 color primaries. Add -vf "zscale=t=linear:npl=100,tonemap=hable,zscale=p=bt709:t=bt709:m=bt709:r=tv,format=yuv420p" before your crop chain, or accept washed-out output.
The 2 MB cap is enforced client-side. A 2.1 MB file uploads successfully via the Bot API and then vanishes when the client tries to set it as an avatar. Always re-encode with a lower CRF if you land close to the limit.
faststart matters more than you think. Without it, the client waits for the whole file before it can validate dimensions, and the upload times out on slower connections.

Next on my list: batch mode (send five clips, get five avatars back), and a browser extension that intercepts drag-drop uploads on Telegram Web and runs the same conversion locally with ffmpeg.wasm. If you have opinions on either, ping the bot.

Built by me, @liveavabot.

Building a Telegram Video Avatar Bot with ffmpeg and Aiogram 3

liveavabot — Fri, 24 Jul 2026 01:02:45 +0000

The problem: iPhone videos silently fail as Telegram avatars

Try setting a video as your Telegram profile picture from an iPhone. It just... doesn't work. No error, no explanation. The upload dialog closes, your avatar stays the same.

I hit this myself last month. Recorded a short clip on my iPhone, tried to set it as my TG avatar, nothing happened. Turns out iOS records in HEVC (H.265) by default, and Telegram's video avatar spec only accepts H.264. There's no warning. The client just refuses silently.

So I built a bot that fixes this. Send it any video or GIF, get back a file that Telegram will actually accept.

What Telegram wants for a video avatar

The spec is undocumented in the public Bot API docs. From reverse-engineering the client behavior:

Codec: H.264 (yuv420p pixel format)
Container: MP4 with faststart flag
Resolution: 800x800, square, center-cropped
Duration: max 10 seconds
File size: max 2 MB
Audio: must be stripped

Miss any of these and the client rejects the upload without telling you why. The 2 MB cap is the annoyingly tight one, especially at 10 seconds and 800x800 resolution.

The ffmpeg pipeline

Two passes. First a cropdetect pass to find the safe square region. Then the actual encode.

ffmpeg -ss 0 -t 10 -i input.mov \
  -vf "cropdetect=24:16:0" -f null - 2>&1 \
  | grep -oE "crop=[0-9:]+" | tail -1

That gives you something like crop=1080:1080:420:0. Feed it into the encode:

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

Notes:

-an strips audio. Telegram wants silent video for avatars.
-movflags +faststart moves the moov atom to the front so TG can start reading before download completes.
-crf 26 is my sweet spot at 800x800 to stay under 2 MB. Adjust down for higher quality if the clip is short enough.
format=yuv420p inside the filter chain is belt-and-braces. Some players still choke on yuv444.

If the encode comes out over 2 MB, I retry with -crf 30. If still too big, I trim duration. That's the whole size-target logic. No fancy VBR two-pass.

Wiring it into aiogram 3

The bot is Python with aiogram 3. Handler for incoming video, document, or animation:

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

router = Router()

@router.message(F.video | F.document | F.animation)
async def handle_video(msg: Message):
    file_obj = msg.video or msg.animation or msg.document
    if not file_obj:
        return

    with tempfile.TemporaryDirectory() as tmp:
        src = Path(tmp) / "in.bin"
        dst = Path(tmp) / "out.mp4"

        await msg.bot.download(file_obj, destination=src)
        await msg.reply("Converting, hang on...")

        rc = await convert(src, dst)
        if rc != 0 or not dst.exists():
            await msg.reply("ffmpeg choked on that file, sorry")
            return

        await msg.reply_video(
            FSInputFile(dst),
            caption="Ready. Long-press your avatar in Settings to set it."
        )

async def convert(src: Path, dst: Path) -> int:
    crop = await detect_crop(src)
    cmd = [
        "ffmpeg", "-y", "-ss", "0", "-t", "10", "-i", str(src),
        "-vf", f"{crop},scale=800:800:flags=lanczos,format=yuv420p",
        "-c:v", "libx264", "-preset", "slow", "-crf", "26",
        "-pix_fmt", "yuv420p", "-movflags", "+faststart", "-an",
        str(dst),
    ]
    proc = await asyncio.create_subprocess_exec(*cmd,
        stdout=asyncio.subprocess.DEVNULL,
        stderr=asyncio.subprocess.DEVNULL)
    return await proc.wait()

detect_crop runs the cropdetect pass and greps the last crop= line. I skipped it above for brevity. It's a 15-line asyncio subprocess plus regex.

Edge cases that bit me

HEVC with rotation metadata

iPhone portrait videos have a 90-degree rotation flag in the container. If you crop before ffmpeg applies the rotation, you crop the wrong region. Fix: don't set -noautorotate. Let ffmpeg apply rotation automatically before the filter chain runs.

Animated GIFs with transparent frames

Converting straight to yuv420p gives random flashes on transparent pixels. Add a palette pass for GIF sources, or pre-composite over black with pad=color=black.

Very short clips

Telegram accepts clips under 1 second but the avatar loop looks janky. I now pad short clips with tpad=stop_mode=clone:stop_duration=1 to hit at least 2 seconds.

Files bigger than 20 MB

Telegram Bot API can't download files bigger than 20 MB directly. For those the bot replies asking to trim the clip client-side. Not solving that one right now.

Packaging as a public bot

It's live at t.me/LiveAvaBot. Send any video or GIF, get back a converted MP4 ready to set as your TG video avatar. Free for the first few conversions per user, then Telegram Stars after that (mostly to cover the VPS ffmpeg CPU).

The whole bot is about 400 lines of Python. ffmpeg does the heavy lifting, I just wrote the pipeline and the aiogram wiring.

What I'd do differently

Two-pass encoding for size targeting would be nicer than my "try crf 26, retry crf 30" heuristic. ffmpeg's -fs flag exists but often truncates output, so I never trusted it. Better path is probably -b:v with a proper two-pass log file. For 10-second clips the current approach is fine.

Also, no 4K HEVC support yet. Decoding 4K HEVC on a shared vCPU is slow enough that users time out before it finishes. If demand grows I'll move ffmpeg to a beefier worker.

Built by me. Bot: @liveavabot.

Converting iPhone HEVC Videos to Telegram Video Avatars with FFmpeg

liveavabot — Wed, 22 Jul 2026 00:04:27 +0000

The problem: iPhone videos that Telegram refuses

I wanted to set a short clip as my Telegram video avatar. Recorded 8 seconds on my iPhone, opened the profile picture menu, hit upload. Telegram accepted the file, showed a spinner, then reverted to my old photo. No error message, just silence.

iPhones record video in HEVC (H.265) by default since iOS 11. Telegram's video avatar endpoint only accepts H.264 in an MP4 container. HEVC gets rejected server-side without a user-facing message. The upload "succeeds" but the profile never updates.

That's the pain that made me build @liveavabot.

What Telegram actually requires

The video avatar spec isn't in the public Bot API docs (video avatars are a client feature, not a bot feature), but the constraints are visible if you inspect the desktop client's upload path:

Container: MP4 with faststart (moov atom at the beginning)
Video codec: H.264, yuv420p pixel format, Baseline or Main profile
Resolution: 800x800 square, exactly
Duration: 10 seconds max
File size: 2 MB max
Audio: must be stripped

Miss any of these and the client either rejects the upload immediately or, worse, accepts it and silently discards it. HEVC lands in the second failure mode. So do yuv444p files from some Android editors, and any resolution that isn't exactly 800x800.

Cropdetect, scale, and format conversion in one pipe

FFmpeg handles all of this if you chain the right filters. Here's the actual command my bot runs:

ffmpeg -i input.mov \
  -t 10 \
  -vf "scale=800:800:force_original_aspect_ratio=increase,crop=800:800,format=yuv420p" \
  -c:v libx264 \
  -profile:v main \
  -preset veryfast \
  -crf 26 \
  -movflags +faststart \
  -an \
  -y output.mp4

Breaking it down:

-t 10 caps duration at 10 seconds. If the source is longer, the tail is dropped.
The scale filter with force_original_aspect_ratio=increase upscales so the smaller side fits 800. Then crop=800:800 slices out a centered square. This handles portrait, landscape, and already-square input uniformly.
format=yuv420p forces the pixel format Telegram wants.
-c:v libx264 -profile:v main picks H.264 with a widely compatible profile.
-crf 26 targets a quality level that usually keeps output under 2 MB for 10 seconds at 800x800. If it doesn't, I re-encode with -crf 30 as a fallback.
-movflags +faststart moves the moov atom to the start of the file so Telegram can begin decoding without downloading the whole thing.
-an strips audio. Video avatars are muted anyway.

For source videos with letterboxing (someone screen-recorded a phone video on a laptop), I run cropdetect first:

ffmpeg -i input.mov -vf cropdetect=24:16:0 -f null - 2>&1 | \
  grep -oP 'crop=\K[0-9:]+' | tail -1

That prints something like 640:640:0:0 which I feed back as a pre-crop before the scale pipeline.

The aiogram 3 handler

The bot side is small. Aiogram 3 handles file downloads, so the whole flow is: receive video, download, shell out to ffmpeg, upload the result. Here's the trimmed handler:

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

router = Router()

@router.message(F.video | F.animation | F.document)
async def convert(msg: Message):
    file = msg.video or msg.animation or msg.document
    if file.file_size and file.file_size > 50 * 1024 * 1024:
        await msg.answer("Source is over 50 MB, please trim it first.")
        return

    with tempfile.TemporaryDirectory() as tmp:
        src = pathlib.Path(tmp) / "in.bin"
        dst = pathlib.Path(tmp) / "out.mp4"

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

        proc = await asyncio.create_subprocess_exec(
            "ffmpeg", "-i", str(src), "-t", "10",
            "-vf", "scale=800:800:force_original_aspect_ratio=increase,"
                   "crop=800:800,format=yuv420p",
            "-c:v", "libx264", "-profile:v", "main",
            "-preset", "veryfast", "-crf", "26",
            "-movflags", "+faststart", "-an", "-y", str(dst),
            stdout=asyncio.subprocess.DEVNULL,
            stderr=asyncio.subprocess.DEVNULL,
        )
        rc = await proc.wait()

        if rc != 0 or not dst.exists():
            await msg.answer("Conversion failed. Try a different source.")
            return

        if dst.stat().st_size > 2 * 1024 * 1024:
            await msg.answer("Output exceeded 2 MB. Retrying at lower quality.")
            return

        await msg.answer_video(
            FSInputFile(dst),
            caption="Ready. Long-press your avatar in Settings, "
                    "pick 'Set as Video', upload this file."
        )

A few things worth noting:

I accept F.video | F.animation | F.document because iPhone shares often arrive as document with mime video/quicktime, not video. Missing that check drops half the real traffic.
The 50 MB source cap matches Bot API's getFile limit for non-premium bots. Bigger sources need the local Bot API server.
The 2 MB output check is a safety net. In practice CRF 26 hits under 2 MB about 95% of the time for typical phone clips.

Packaging it as @liveavabot

I glued the handler above to a Postgres row per user (for stats and rate limits), a Redis queue for concurrent conversions, and a small aiogram middleware for logging. The whole thing runs on a cheap Hetzner VPS with ffmpeg from apt. No GPU, no cloud transcoder. 800x800 for 10 seconds is trivial CPU load, veryfast preset finishes it in under a second.

Try it: https://t.me/LiveAvaBot?start=devto_article_20260722. Send any video or GIF, it sends back a Telegram-compatible avatar file.

Edge cases I learned the hard way

Rotated iPhone videos. iPhones store portrait video as landscape with a rotation flag in metadata. FFmpeg 5+ honors it by default, 4.x needs -noautorotate handling. Check your distro version.
Animated stickers as source. Telegram sends .tgs (Lottie JSON), not video. Ignore those in the handler, they'd just error.
GIFs with palette artifacts. Old GIFs upscale ugly. I added -sws_flags lanczos to the scale filter, which sharpens the result a lot without slowing anything down.
Voice-over videos. People sometimes complain that audio was stripped. I added a note in the reply caption explaining Telegram video avatars are muted by spec.

What's next

Right now the bot is stateless per conversion. Next iteration adds a trim mode where users pick the 10-second window from a longer clip, using inline buttons and ffmpeg's -ss seek. After that, probably batch mode for multi-file uploads.

Built by me. @liveavabot lives at https://t.me/LiveAvaBot?start=devto_article_20260722 if you want to try it or fork the concept.