DEV Community: liveavabot

Convert iPhone HEVC Videos to Telegram Video Avatars with ffmpeg

liveavabot — Mon, 01 Jun 2026 06:07:23 +0000

Why Your iPhone Video Won't Work as a Telegram Avatar

Telegram video avatars have strict requirements. The file must be H.264, 800×800, under 10 seconds, under 2MB, with no audio track. Most people don't know this until they try uploading a video and get a vague error, or worse, silence.

iPhone records in HEVC (H.265) by default since iOS 11. Telegram accepts HEVC for regular video messages but silently rejects it for video avatars. You upload, nothing changes, no useful error message.

I ran into this while setting up a profile avatar and spent 20 minutes debugging before I realized the codec was the problem.

What Telegram Requires

The video avatar spec, confirmed through testing:

Container: MP4
Codec: H.264 (libx264), yuv420p pixel format
Resolution: 800×800 (square, not 16:9)
Duration: 10 seconds maximum
File size: 2MB maximum
Audio: must be absent

The yuv420p requirement is the sneaky one. Encode with yuv444p or leave the pixel format at the camera default, and Telegram will reject the file without telling you why.

The ffmpeg Pipeline

The tricky part is the square crop. Most videos are 16:9 or 9:16. You need to find the largest centered square, crop to it, scale to 800×800, then re-encode.

The command I use:

# Inspect source (optional)
ffprobe -v error -select_streams v:0 \
  -show_entries stream=width,height,codec_name \
  -of default=noprint_wrappers=1 input.mp4

# Convert to Telegram video avatar format
ffmpeg -i input.mp4 \
  -vf "crop=ih:ih,scale=800:800,fps=30,format=yuv420p" \
  -c:v libx264 \
  -preset slow \
  -crf 28 \
  -movflags +faststart \
  -an \
  -t 10 \
  output.mp4

Filter chain breakdown:

crop=ih:ih takes a centered square using the video height as both dimensions. Works for landscape source. For portrait or mixed input, use crop=min(iw\,ih):min(iw\,ih).

scale=800:800 resizes to exactly 800×800.

fps=30 normalizes frame rate. Telegram is picky about variable frame rates, and iPhones record VFR in some modes.

format=yuv420p forces the required pixel format.

-an removes audio entirely.

-t 10 hard-caps at 10 seconds.

-movflags +faststart moves the moov atom to the start of the file, required for streaming playback.

CRF 28 with slow preset gives a reasonable size-to-quality tradeoff for the 2MB limit. High-motion clips may need CRF 30-32 to stay under that ceiling.

ffmpeg handles HEVC decoding automatically. No extra flags needed for iPhone input.

The aiogram 3 Handler

A simplified version of the bot handler:

import asyncio
import tempfile
from pathlib import Path

from aiogram import Bot, Dispatcher, F
from aiogram.types import Message, BufferedInputFile

bot = Bot(token="YOUR_TOKEN")
dp = Dispatcher()

async def convert_to_avatar(input_path: Path, output_path: Path) -> bool:
    cmd = [
        "ffmpeg", "-y", "-i", str(input_path),
        "-vf", "crop=ih:ih,scale=800:800,fps=30,format=yuv420p",
        "-c:v", "libx264", "-preset", "slow", "-crf", "28",
        "-movflags", "+faststart", "-an", "-t", "10",
        str(output_path),
    ]
    proc = await asyncio.create_subprocess_exec(
        *cmd,
        stdout=asyncio.subprocess.DEVNULL,
        stderr=asyncio.subprocess.DEVNULL,
    )
    await proc.wait()
    return proc.returncode == 0 and output_path.stat().st_size <= 2 * 1024 * 1024

@dp.message(F.video | F.animation | F.document)
async def handle_video(message: Message):
    await message.answer("Converting, hang on...")

    file_obj = message.video or message.animation or message.document
    file = await bot.get_file(file_obj.file_id)

    with tempfile.TemporaryDirectory() as tmp:
        input_path = Path(tmp) / "input.mp4"
        output_path = Path(tmp) / "output.mp4"
        await bot.download_file(file.file_path, destination=str(input_path))
        ok = await convert_to_avatar(input_path, output_path)
        if not ok:
            await message.answer("Conversion failed or output exceeded 2MB. Try a shorter clip.")
            return
        data = output_path.read_bytes()
        await message.answer_video(
            BufferedInputFile(data, filename="avatar.mp4"),
            caption="Done. Set this as your Telegram video avatar in profile settings.",
        )

F.document catches videos sent as files rather than Telegram video messages. iPhone users sometimes share via "Send as File" to preserve quality, which changes the message type.

The size check after encoding matters. A 60-second 4K source at CRF 28 can still exceed 2MB. The handler returns a useful error instead of uploading an oversized file that Telegram would silently reject.

Packaging It as @liveavabot

I wrapped this pipeline into a production bot with a few additions: deduplication by content hash to avoid processing the same file twice, per-user rate limiting, and retry logic for ffmpeg edge cases.

The bot also handles Telegram's animation type, which is how Telegram stores GIFs internally as MP4 files. The same ffmpeg pipeline works without changes.

Currently at 99 users. Running on a small VPS with system ffmpeg.

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

Built by me. Architecture: aiogram 3, asyncio subprocesses for ffmpeg, PostgreSQL for deduplication state.

Edge Cases Worth Knowing

Variable frame rate: iPhone records VFR in some modes. The fps=30 filter normalizes this. Without it, some encoders produce stuttering on certain devices.

Square GIFs with letterboxing: Some animated GIFs are already square but have letterboxing baked into the frame. The crop=ih:ih logic doesn't handle this well. I switched to min(iw,ih) as the crop dimension to handle both landscape and portrait sources correctly.

The 2MB ceiling: At 10 seconds and 800×800, you have roughly 200KB/s budget. Fast-motion clips hit this reliably. I haven't added two-pass encoding yet, so the current bot just asks users to try a shorter clip.

Corrupted audio streams: Some MP4 files labeled as GIFs carry corrupted audio tracks. Adding -ignore_unknown to the ffmpeg flags handles these without aborting the whole encode.

"Sent as File" videos: When a user sends a video as a document, Telegram skips its own transcoding. The file arrives as-is, usually raw HEVC from the camera. The F.document handler catches this case.

What's Next

Two-pass encoding for the oversized case is on the list. After that, possibly a web frontend that doesn't require Telegram at all.

ffmpeg handles the hard parts. I wrote the wrapper and the bot scaffolding.

Telegram Video Avatars: Fixing iPhone HEVC Files With ffmpeg

liveavabot — Sat, 30 May 2026 04:04:54 +0000

The Problem Nobody Warns You About

You record a short clip on your iPhone, try to set it as your Telegram video avatar, and Telegram just... silently fails. No error message. The avatar doesn't update. You try again. Same result.

The reason is HEVC (H.265). iPhones have been shooting HEVC by default since iOS 11. Telegram's video avatar uploader accepts HEVC files without complaint, processes them, and then quietly discards them. You get no feedback.

I ran into this building @liveavabot. Users kept sending me iPhone videos asking why they didn't work. Once I understood the spec, I wrote the conversion pipeline. Here's what I learned.

What Telegram Actually Requires

Telegram's video avatar format has five hard constraints:

Codec: H.264 (libx264), yuv420p pixel format
Resolution: exactly 800x800 pixels, square
Duration: 10 seconds maximum
File size: 2 MB maximum
Audio: not allowed (stream must be stripped)

HEVC fails the first constraint. Telegram accepts the upload, but the resulting avatar is blank or rejected at the API level. The client shows nothing.

Beyond codec, the square crop is the other common failure point. Most videos are 16:9 or 9:16. If you naively scale to 800x800, you get distortion. You need to detect the actual content area, crop it square, then scale.

The ffmpeg Pipeline

I use two ffmpeg passes. The first detects the crop rectangle, the second does the actual encode.

Pass 1: Crop Detection

ffmpeg -i input.mov \
  -vf cropdetect=24:16:0 \
  -f null -t 10 - 2>&1 | grep cropdetect | tail -1

This samples the first 10 seconds and outputs a crop=W:H:X:Y value. cropdetect=24:16:0 means: black threshold 24, round to 16px increments, skip 0 frames. For most iPhone videos the crop is the full frame, but for letterboxed content it cuts the black bars.

Pass 2: Encode to Telegram Spec

ffmpeg -i input.mov \
  -vf "crop=W:H:X:Y,scale=800:800:force_original_aspect_ratio=disable" \
  -c:v libx264 -pix_fmt yuv420p \
  -crf 28 -preset fast \
  -t 10 \
  -an \
  -movflags +faststart \
  -y output.mp4

Key flags:

scale=800:800:force_original_aspect_ratio=disable forces the square without padding or black bars
-an strips the audio stream entirely
-t 10 hard-caps at 10 seconds
-movflags +faststart moves the moov atom to the front, required for streaming
-crf 28 -preset fast is a starting point; I retry at -crf 32 if the output exceeds 2 MB

For GIFs I skip the cropdetect pass and use scale=800:800:flags=lanczos directly.

The aiogram 3 Handler

The bot accepts video, document, and animation messages, runs the conversion in a subprocess, and sends back the result.

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

router = Router()

async def convert_to_avatar(src: Path, dst: Path) -> bool:
    crop_cmd = [
        "ffmpeg", "-i", str(src),
        "-vf", "cropdetect=24:16:0",
        "-f", "null", "-t", "10", "-",
    ]
    proc = await asyncio.create_subprocess_exec(
        *crop_cmd, stderr=asyncio.subprocess.PIPE,
    )
    _, stderr = await proc.communicate()
    crop = parse_cropdetect(stderr.decode())  # extract last crop= line

    encode_cmd = [
        "ffmpeg", "-i", str(src),
        "-vf", f"{crop},scale=800:800:force_original_aspect_ratio=disable",
        "-c:v", "libx264", "-pix_fmt", "yuv420p",
        "-crf", "28", "-preset", "fast",
        "-t", "10", "-an", "-movflags", "+faststart",
        "-y", str(dst),
    ]
    proc = await asyncio.create_subprocess_exec(*encode_cmd)
    await proc.communicate()
    return dst.exists() and dst.stat().st_size <= 2 * 1024 * 1024

@router.message(F.video | F.document | F.animation)
async def handle_video(message: Message):
    status = await message.answer("Converting...")
    file = await message.bot.get_file(...)
    src = Path(f"/tmp/{file.file_id}.mov")
    dst = src.with_suffix(".mp4")
    await message.bot.download_file(file.file_path, src)
    ok = await convert_to_avatar(src, dst)
    if ok:
        await message.reply_video(FSInputFile(dst))
    else:
        await message.reply("Couldn't fit under 2 MB. Try a shorter clip.")
    await status.delete()

parse_cropdetect is a small helper that greps the stderr output for the last crop= line and returns it formatted for the -vf chain. About 10 lines.

I run the conversion via asyncio.create_subprocess_exec rather than run_in_executor, since the subprocess approach doesn't block the event loop. For a busy bot you'd want a semaphore to cap concurrent ffmpeg processes. For the current load of 91 users, a single async subprocess per request is fine.

Packaging It as @liveavabot

I wrapped the pipeline in a Telegram bot so people don't need ffmpeg installed locally. You send a video or GIF, the bot converts it and sends back an MP4 ready to set as your avatar.

The bot is at https://t.me/LiveAvaBot?start=devto_article_20260530, it's free to use.

Hosting is a single Hetzner VPS. ffmpeg does the heavy lifting. The bot code is around 400 lines of Python including the aiogram handlers, file cleanup, and basic rate limiting.

One thing I added early on: HEVC detection at intake. If the incoming file is H.265, the bot logs it separately so I can track how many iPhone users hit this path. About 30% of video submissions are HEVC.

Edge Cases and What's Next

Portrait 9:16 videos. Most common case. The cropdetect pass handles them. If a screen recording added letterbox bars, cropdetect catches those too and the result is a tighter square.

GIFs over 50 MB. Telegram sends large GIFs as Animation type with an MP4 preview already attached. I decode the original GIF with ffmpeg -ignore_loop 0 and encode it through the same pipeline as a regular video.

2 MB overflow. -crf 28 doesn't always land under 2 MB. I retry at -crf 32. Still over? The bot asks the user to trim to under 8 seconds. Automatic trimming isn't implemented yet, mostly because it changes the content in a way users don't always expect.

Audio removal. Some users are surprised that audio gets stripped. Telegram's spec doesn't allow audio in video avatars, so there's no way around it. Worth stating upfront in the bot's reply message.

Next on the list: a small web UI for people who don't want to use Telegram for the conversion. The ffmpeg command is simple enough to run server-side behind a file upload form.

Built by me, @LiveAvaBot.

Converting iPhone HEVC Videos to Telegram Video Avatars With FFmpeg

liveavabot — Thu, 28 May 2026 03:04:04 +0000

The Problem: iPhone Videos Silently Fail

I tried to set my Telegram video avatar from an iPhone clip and it just didn't work. No error message. The upload completed and my avatar stayed the same.

After digging into the Telegram Bot API spec and a few hours of trial and error with ffprobe, I figured out why. iPhones record video as HEVC (H.265) by default since iOS 11, and Telegram's video avatar endpoint only accepts H.264 in an MP4 container. When you upload HEVC, Telegram drops it on the floor without telling you.

I built @liveavabot to fix this for myself, then opened it up. This post walks through the spec, the ffmpeg pipeline, and the aiogram 3 handler that ties it together.

What Telegram Actually Wants

The Bot API docs cover the basics, but the video avatar requirements are scattered across several pages. Here's what I pieced together from setProfilePhoto with the video parameter:

Container: MP4
Video codec: H.264 (AVC), profile baseline or main, yuv420p pixel format
Resolution: exactly 800x800 (square)
Duration: 10 seconds or less
File size: 2 MB or less
Audio: no audio stream
Frame rate: 30 fps or lower
Moov atom at the front (faststart)

The faststart bit matters more than people realize. If the moov atom sits at the end of the file (the ffmpeg default), Telegram's streaming preview can't seek and the avatar sometimes fails to render even when everything else is correct.

The 800x800 square is also strict. I tried 720x720 and it was rejected, tried 1024x1024 and it was rejected. Telegram wants exactly 800x800.

The FFmpeg Pipeline

The conversion has three stages: detect a useful crop region, scale to 800x800, then re-encode to H.264 with the right pixel format and container flags.

First, cropdetect to find the actual subject in the frame. Phone video often has bars, letterboxing, or a lot of dead space around the center.

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

That outputs something like 1080:1080:0:420, which is width:height:x:y. I parse that in Python and feed it back into the actual encode.

Then the encode itself:

ffmpeg -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 main \
  -preset medium \
  -crf 23 \
  -an \
  -movflags +faststart \
  -y output.mp4

Breaking that down:

-t 10 caps duration at 10 seconds. Cheaper than re-checking with ffprobe.
-vf chain: crop to the detected square, scale to 800x800 with lanczos (sharper than bicubic for downscales), force 30 fps, force yuv420p.
-c:v libx264 -profile:v main is the codec choice. Main profile plays everywhere and stays under the size budget.
-crf 23 is the quality knob. 18 is too big, 28 is too soft, 23 is the sweet spot for 10 seconds at 800x800.
-an strips audio. Telegram rejects the file if there's an audio track.
-movflags +faststart moves the moov atom to the front of the file.

If the output is still over 2 MB (it sometimes is for very fast-motion clips), I rerun with -crf 26. Two passes is rare but worth handling.

Wiring It Into Aiogram 3

The handler is short. Aiogram 3 gives you the file as a Message, you download it, run ffmpeg, send it back. The interesting part is handling video, animation (which is what GIFs become in Telegram), and video_note all through one entry point.

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

router = Router()

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

    status = await message.reply("Converting...")

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

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

        crop = await detect_crop(src)
        await encode(src, dst, crop=crop, crf=23)
        if dst.stat().st_size > 2 * 1024 * 1024:
            await encode(src, dst, crop=crop, crf=26)

        if not dst.exists():
            await status.edit_text("Conversion failed. Try a shorter clip.")
            return

        await message.reply_video(
            video=FSInputFile(dst),
            caption="Long-press the file, then Set as Video Avatar.",
        )
        await status.delete()

detect_crop and encode are thin wrappers around asyncio.create_subprocess_exec that call ffmpeg with the args from the previous section. Just argument plumbing.

The non-obvious thing here: I use reply_video and let the user manually set the avatar, rather than calling setProfilePhoto on their behalf. Bots can't set a user's avatar through the API, only the user can do that from the Telegram client. So the bot delivers a file the user can long-press and apply.

Shipping This as @liveavabot

I packaged this up as https://t.me/LiveAvaBot?start=devto_article_20260528. Send it any video or GIF, get back an 800x800 H.264 clip that Telegram accepts. About 85 people are using it now, mostly from sharing in maker forums.

It runs on a small VPS with ffmpeg compiled with libx264, aiogram 3, and a sqlite db for usage stats. No queue, just async subprocess calls, because conversions take 2 to 4 seconds and the bot is small enough that worker concurrency isn't needed yet.

If a video has non-square pixel aspect ratio (some Android phones do this), the cropdetect output needs normalization. I handle that by running setsar=1 in the filter chain before crop. One-line fix once you know to look for it.

Edge Cases and What's Next

Things that surprised me:

iPhone slow-motion videos report a frame rate of 240 fps, but actual playback is 30 fps with timestamps stretched. ffmpeg handles this correctly if you let it. Don't force -r 30 on the input, only on the output via the fps=30 filter.

Videos shot in portrait often have rotation metadata instead of actually rotated pixels. ffmpeg respects the rotation flag by default in recent builds, but older versions don't. I added an explicit transpose based on the rotation metadata to be safe.

Telegram's 10-second cap is hard. There's no way to ask for an exception. I tried.

Next on the list: handle 4K input properly (it works now but is slow), add a /url command so people can paste YouTube links instead of uploading files, and maybe a Mastodon mirror so non-Telegram users can convert files too.

Built by me, https://t.me/LiveAvaBot?start=devto_article_20260528. Code is on my todo list to open source once the secret handling is cleaned up.

Converting iPhone HEVC Videos to Telegram Avatars with FFmpeg

liveavabot — Tue, 26 May 2026 02:02:58 +0000

The Problem

I tried setting a video avatar on Telegram using a clip from my iPhone. Telegram accepted the upload, the progress bar finished, then nothing happened. No error, no toast, no avatar. The video sat in chat as a regular file.

After digging into Telegram's behavior I found the silent rejection rule: video avatars must be exactly 800x800, H.264 video, no audio track, under 10 seconds, under 2MB. iPhone videos are HEVC (H.265) by default since iOS 11, usually portrait 1080x1920, with audio, and often longer than 10s. Every single criterion fails.

The frustrating part is the silence. Telegram doesn't say "wrong codec" or "too long". The upload just doesn't apply. You think you did something wrong.

So I built a bot.

What Telegram Actually Wants

The spec (you find it in the docs for setProfilePhoto with the animation field, plus reverse-engineered details from people complaining on forums) is strict:

Container: MP4
Video codec: H.264 (libx264)
Pixel format: yuv420p (not yuv420p10le, not yuv422)
Resolution: exactly 800x800, square
Duration: at most 10 seconds
File size: at most 2MB
Audio: must be absent, not muted, fully removed
Faststart: moov atom at the start of the file

The faststart bit caught me out. ffmpeg by default puts the moov atom at the end of the file. Telegram's parser appears to give up rather than seek backwards. Adding -movflags +faststart was the single change that fixed half of my early test cases.

The FFmpeg Pipeline

I let ffmpeg do all the heavy lifting. I just wrote the wrapper. The pipeline is cropdetect, then re-encode with the exact flags Telegram needs.

# Optional first pass: detect the largest centered crop
ffmpeg -i input.mov -vf "cropdetect=24:16:0" -f null - 2>&1 \
  | grep -oP 'crop=\K[0-9:]+' | tail -1

# Main pass: crop to square, scale to 800x800, transcode, strip audio
ffmpeg -i input.mov \
  -vf "crop=in_h:in_h,scale=800:800,format=yuv420p" \
  -c:v libx264 -preset veryfast -crf 28 \
  -an \
  -t 10 \
  -movflags +faststart \
  -y output.mp4

A few notes on the flags:

crop=in_h:in_h crops to a square using the input height as both dimensions. For portrait clips this gives a centered square crop without manually computing offsets.
scale=800:800 resizes to the exact target. No aspect-ratio preservation, we already cropped to square.
format=yuv420p forces 8-bit 4:2:0. iPhone HEVC is often 10-bit (yuv420p10le) which Telegram does not accept.
-an drops audio entirely.
-t 10 caps duration at 10 seconds.
-crf 28 is aggressive but keeps the file under 2MB for typical 10s clips. For 5s clips I drop to crf 23.
+faststart is the magic flag mentioned above.

For files that still exceed 2MB after the first encode I bisect on CRF (28, 30, 32, 34) until the size fits. Crude, but it works for the long tail of weird inputs.

The Aiogram 3 Handler

The bot side is small. Aiogram 3 routes any video, video note, animation, or document to one converter:

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.video_note | F.animation | F.document)
async def convert(msg: Message):
    file = msg.video or msg.video_note or msg.animation or msg.document
    if not file:
        return

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

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

        proc = await asyncio.create_subprocess_exec(
            "ffmpeg", "-i", str(src),
            "-vf", "crop=in_h:in_h,scale=800:800,format=yuv420p",
            "-c:v", "libx264", "-preset", "veryfast", "-crf", "28",
            "-an", "-t", "10", "-movflags", "+faststart",
            "-y", str(dst),
            stdout=asyncio.subprocess.DEVNULL,
            stderr=asyncio.subprocess.DEVNULL,
        )
        await asyncio.wait_for(proc.wait(), timeout=30)

        if dst.exists() and dst.stat().st_size < 2 * 1024 * 1024:
            await msg.answer_video(FSInputFile(dst))
        else:
            await msg.answer("File too big after encode, try a shorter clip.")

asyncio.wait_for with a 30-second timeout is important. ffmpeg occasionally hangs on malformed input (especially screen recordings with odd codecs), and you don't want a stuck process per user piling up.

Shipping It as @liveavabot

I wrapped this into @LiveAvaBot. The user sends a video, the bot replies with the converted MP4, the user forwards that to "Edit profile photo" in Telegram settings. That's the entire flow. No login, no signup, no settings menu.

Practical bits I added on top:

Per-user queue, one ffmpeg process per chat at a time, so spammy uploads don't fork-bomb the server.
30-second ffmpeg timeout (above), with a friendly error if it trips.
Telegram Stars payments for batch conversions, mostly experimental, not a serious revenue path yet.
Logs of input format so I can see what people actually throw at it (mostly iPhone HEVC, occasional Android H.264, a surprising number of screen recordings).

Current state: 84 users, slow organic growth from word of mouth.

Edge Cases and Lessons

HDR (HLG, Dolby Vision) from newer iPhones produces washed-out output when transcoded naively. Adding colorspace=bt709:iall=bt709:fast=1 to the filter chain fixes it for most clips.
Vertical videos under 10 seconds sometimes get over-cropped if the subject sits near the top of the frame. Running cropdetect first costs an extra ffmpeg pass but produces noticeably better framing on portraits.
GIFs route through the same pipeline. ffmpeg reads them fine. The quirk is they often have no duration set in the container, so -t 10 still applies correctly.
2MB limit is the real ceiling. Codec and resolution are easy. Staying under 2MB on a 10-second 800x800 H.264 clip means crf 28 or higher, which looks acceptable for an avatar but would be ugly at full screen.
Screen recordings are the worst case. Variable framerate, weird color spaces, sometimes 10-bit. The bisect-on-CRF fallback exists mainly for these.

Next on the list is detecting "this video is already valid" and skipping the re-encode entirely. About 5% of uploads are already 800x800 H.264 muted (likely from other converters), and re-encoding them is wasted CPU and quality loss.

If you've got an iPhone clip that won't stick as a TG avatar, throw it at the bot and see what comes back: https://t.me/LiveAvaBot?start=devto_article_20260526

Built by me, @liveavabot.

Why Your iPhone Video Avatar Silently Fails in Telegram

liveavabot — Sun, 24 May 2026 01:04:40 +0000

The silent failure that pushed me to build this

I took a 5-second clip on my iPhone, tried to set it as my Telegram avatar, and got nothing. The upload completed. The progress bar finished. My avatar stayed the same boring static photo. No error message, no warning.

Turns out Telegram quietly rejects iPhone videos because iOS records in HEVC (H.265) by default, and Telegram's video avatar pipeline only accepts H.264. The spec is strict, and if your file misses even one constraint, the upload "succeeds" but the avatar never updates.

I got tired of doing the ffmpeg dance by hand every time, so I packaged the conversion into a bot.

What the Telegram video avatar spec actually requires

After reading the Bot API docs and poking at the MTProto layer, here is the exact set of constraints that has to be true for a video avatar to stick:

Container: MP4
Video codec: H.264 (libx264), baseline or main profile
Pixel format: yuv420p
Resolution: 800x800 square, exact
Duration: 10 seconds maximum
File size: 2MB maximum
Audio: must be removed entirely
moov atom: at the start of the file (faststart)

Miss any one of these and the upload "succeeds" but the avatar silently does not change. The 2MB cap is the painful one, because a 10-second 800x800 H.264 clip at decent quality wants to be 3 to 5 MB.

The ffmpeg pipeline that fixes it

Here is the actual command the bot runs. It re-encodes, crops to square, scales to 800x800, strips audio, sets yuv420p, and writes faststart:

ffmpeg -y -i input.mov \
  -t 10 \
  -vf "crop='min(in_w,in_h)':'min(in_w,in_h)',scale=800:800:flags=lanczos,format=yuv420p" \
  -c:v libx264 -profile:v baseline -level 3.1 \
  -preset slow -crf 28 \
  -movflags +faststart \
  -an \
  output.mp4

A few notes on why each flag is there:

-t 10 hard-caps duration to 10 seconds.
The crop filter uses min(in_w,in_h) so portrait and landscape both end up square without distortion.
scale=800:800:flags=lanczos keeps detail better than bilinear on faces.
-profile:v baseline -level 3.1 matches Telegram's playback target across old Android devices.
-crf 28 is the sweet spot for staying under 2MB at 800x800.
-an strips audio. The avatar pipeline rejects files with an audio stream entirely.
+faststart moves the moov atom to the front so the file can stream-decode.

If the result is still above 2MB (rare, but happens on busy scenes), the bot bumps CRF to 30 and re-runs.

The minimal aiogram 3 handler

The bot listens for video, video_note, animation, and document messages, downloads them, runs the pipeline above, and sends back the converted file. Here is 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.video_note | F.animation | F.document)
async def convert(msg: Message):
    file = msg.video or msg.video_note or msg.animation or msg.document
    if not file:
        return

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

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

        proc = await asyncio.create_subprocess_exec(
            "ffmpeg", "-y", "-i", str(src),
            "-t", "10",
            "-vf", "crop='min(in_w,in_h)':'min(in_w,in_h)',"
                   "scale=800:800:flags=lanczos,format=yuv420p",
            "-c:v", "libx264", "-profile:v", "baseline", "-level", "3.1",
            "-preset", "slow", "-crf", "28",
            "-movflags", "+faststart", "-an",
            str(dst),
        )
        await proc.wait()

        if dst.stat().st_size > 2 * 1024 * 1024:
            await msg.reply("Result still over 2MB, try a shorter or simpler clip.")
            return

        await msg.reply_video(FSInputFile(dst), caption="Set this as your video avatar.")

Two things worth flagging here. First, I use F.video | F.video_note | F.animation | F.document because iPhone Live Photos and screen recordings arrive as document with a video mime type, not video. Missing this filter meant about 30% of clips never got processed. Second, the subprocess is awaited via asyncio.create_subprocess_exec, not subprocess.run, otherwise the whole event loop blocks while ffmpeg chews through a 4K source.

How I packaged this as @liveavabot

The whole thing lives at https://t.me/LiveAvaBot?start=devto_article_20260524. Send any video, GIF, video note, or even a screen recording, and you get back a Telegram-spec-compliant 800x800 H.264 file ready to drop into Settings, Edit profile, Set new photo.

The bot runs on a small Hetzner VM. ffmpeg is doing all the heavy lifting, I just wrote the wrapper, the queueing, and the failure messages. About 80 people have used it so far, mostly folks who tried to set an iPhone clip as their avatar and hit the same silent failure I did.

Edge cases and what is next

A few things still trip the pipeline:

4K HDR clips with Dolby Vision metadata sometimes need a tone-mapping pass before the crop filter. I have not wired this in yet because it adds about 8 seconds of encode time per clip.
Live Photos: I currently take the video track, but the trim point Apple stores in the metadata is sometimes off-center. Worth honoring on a future pass.
Very dark scenes get blocky at CRF 28. Bumping the preset to veryslow helps but I do not want to push encode time past 15 seconds per clip on shared hardware.

If you want to extend or fork the converter, the constraints above are the part to memorize. The rest is plumbing. Built by me, @liveavabot.

Converting iPhone HEVC Video Into a Telegram Video Avatar

liveavabot — Fri, 22 May 2026 00:05:13 +0000

The bug that wasted my afternoon

I tried to set a video as my Telegram profile picture. I recorded a short clip on my iPhone, opened Telegram, and picked it as my avatar. Telegram accepted the file, showed a spinner, then quietly fell back to a static frame. No error. No warning. Just a still image where a looping video should have been.

Turns out Telegram has strict rules for video avatars, and iPhone video breaks almost all of them at once. The clip was HEVC, the wrong resolution, too long, and carried an audio track. Telegram does not tell you any of this. It just gives up.

I wanted the actual feature, so I dug into what the spec really needs and wrote a converter. This post is the result.

What Telegram actually requires

A Telegram video avatar is not a normal video upload. The constraints are tight:

Codec: H.264 (AVC). HEVC is rejected.
Container: MP4 with the moov atom at the front (faststart).
Resolution: square. 800x800 is the safe target.
Duration: 10 seconds or less.
Size: roughly 2MB or less.
No audio track.
Pixel format: yuv420p. Some players choke on yuv444p or 10-bit.

iPhone footage fails on codec, shape, duration, audio, and often pixel format. A modern iPhone records HEVC in 10-bit at 1080x1920 or wider. Every one of those points needs fixing before Telegram will animate it.

The silent failure is the worst part. You cannot debug a process that refuses to report what went wrong.

Fixing it with ffmpeg

ffmpeg does all the real work here. The interesting step is cropping a vertical phone video into a centered square without squishing faces.

Detecting the crop region

cropdetect scans frames and prints the largest non-black crop rectangle. I run a quick pass to read it:

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

That prints something like crop=1080:1080:0:420. For a phone clip I usually ignore the detected offset and take a centered square of the shorter side, but cropdetect earns its keep when the video has letterboxing or black bars.

The encode pass

Here is the command that produces a Telegram-ready avatar:

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

Walking through the flags that matter:

-t 10 hard-caps duration at 10 seconds.
-an drops the audio track. Telegram wants none.
crop='min(iw,ih)':'min(iw,ih)' takes the largest centered square that fits.
scale=800:800:flags=lanczos resizes to the target. Lanczos keeps edges sharp.
format=yuv420p plus -pix_fmt yuv420p force 8-bit 4:2:0, which fixes 10-bit HEVC.
-c:v libx264 re-encodes to H.264.
-movflags +faststart moves the moov atom to the front so playback can start immediately.
-crf 26 is the quality knob. If the file lands above 2MB, I raise CRF a few points and re-run.

One pass, and an iPhone clip becomes a file Telegram will actually loop.

Keeping it under 2MB

CRF 26 handles most 10-second clips, but a busy scene with lots of motion can still overshoot. My loop is simple: encode, check the file size, and if it is over 2MB raise CRF by 4 and try again. Two attempts cover almost everything. For stubborn clips I trim duration before touching quality, since 6 seconds at decent quality beats 10 seconds of mush.

Wiring it into a bot

Running ffmpeg by hand is fine once. I wanted to send a video to a chat and get the avatar back, so I wrapped it in an aiogram 3 handler.

from aiogram import Bot, Dispatcher, F
from aiogram.types import Message, FSInputFile
import asyncio, tempfile, os

dp = Dispatcher()


@dp.message(F.video | F.animation | F.document)
async def handle_video(message: Message, bot: Bot):
    file = message.video or message.animation or message.document
    if not file:
        await message.answer("Send me a video or GIF.")
        return

    with tempfile.TemporaryDirectory() as tmp:
        src = os.path.join(tmp, "in")
        dst = os.path.join(tmp, "out.mp4")
        await bot.download(file, destination=src)

        ok = await convert_to_avatar(src, dst)
        if not ok:
            await message.answer("Could not convert that one. Try a shorter clip.")
            return

        await message.answer_video(
            FSInputFile(dst),
            caption="Ready. Set this as your profile video.",
        )


async def convert_to_avatar(src: str, dst: str) -> bool:
    proc = await asyncio.create_subprocess_exec(
        "ffmpeg", "-y", "-i", src, "-t", "10", "-an",
        "-vf", "crop='min(iw,ih)':'min(iw,ih)',scale=800:800:flags=lanczos,format=yuv420p",
        "-c:v", "libx264", "-preset", "slow", "-crf", "26",
        "-movflags", "+faststart", "-pix_fmt", "yuv420p", dst,
        stdout=asyncio.subprocess.DEVNULL,
        stderr=asyncio.subprocess.DEVNULL,
    )
    await proc.wait()
    return proc.returncode == 0 and os.path.exists(dst)

The F.video | F.animation | F.document filter matters. Telegram delivers the same file as different types depending on whether the user sends a video, a GIF, or a file attachment. Catching all three saves a lot of confused users.

asyncio.create_subprocess_exec keeps the bot responsive while ffmpeg runs. A 10-second clip encodes in a couple of seconds on a small VPS, but blocking the event loop would still freeze every other chat.

Packaging it as a bot anyone can use

I cleaned this up and shipped it as @LiveAvaBot. You send a video or GIF, and it returns an 800x800 H.264 file under 2MB with audio stripped, ready to drop in as a profile video. It handles HEVC from iPhones, vertical clips, oversized files, and GIFs pulled from random websites.

Most of the credit goes to ffmpeg. I just wrote the wrapper that picks sane flags and hides the silent-failure problem behind a single message.

Edge cases and what is next

A few things I learned along the way:

Square clips that are already H.264 still need re-encoding for the moov atom and the audio strip. Skipping the convert step because the file looks fine produced more silent failures.
Animated WebP and some GIFs decode with a variable frame rate. Adding -r 30 to the encode smooths playback.
Very dark footage confuses cropdetect. The centered-square crop is a more reliable default than trusting detection on every clip.
4K HEVC is slow to decode on a small VPS. It works, it just takes longer, and that is the next thing I want to speed up.

The whole project started because Telegram would not tell me why my avatar was a still image. Now it is one message to a bot.

I built this one myself. The bot is @liveavabot. If you try it and a clip fails, I want to hear which clip.

Fixing iPhone HEVC Videos for Telegram Avatars With ffmpeg

liveavabot — Tue, 19 May 2026 23:03:43 +0000

The Bug With No Error Message

I tried to set a short clip as my Telegram profile video. Recorded it on my iPhone, opened Telegram, picked the file, hit save. Telegram took it, showed a spinner for a second, then kept my old photo. No error. No toast. Nothing happened.

I tried three more times. Same silent nothing. The file played fine in every other app, so it wasn't corrupt.

The problem is the codec. Since iOS 11, iPhones record video in HEVC (H.265) by default. It's great for storage. It is also not what Telegram wants for a profile video avatar. Telegram's avatar slot expects H.264, and when it gets something it can't decode for that slot, it doesn't tell you. It just drops the upload.

So I wrote a bot that re-encodes the file before it ever reaches that slot. This post is how it works.

What Telegram Actually Wants From a Video Avatar

There is no public error message, so I pieced the spec together by testing files until they stuck. A video avatar that Telegram accepts looks like this:

Container: MP4.
Video codec: H.264. libx264 is fine.
Pixel format: yuv420p. HEVC files are often yuv420p10le (10-bit), which the H.264 avatar path rejects.
Shape: square. I use 800x800. Non-square files get center-cropped by Telegram in ways you don't control.
Duration: 10 seconds or less.
Size: 2 MB or less.
Audio: none. The avatar has no sound, and an audio track sometimes pushes you over the size cap for nothing.
faststart: the moov atom belongs at the front of the file so playback can begin before the whole thing downloads.

Miss any one of these and you get the silent drop. The 10-bit pixel format caught me out the longest, because the file looked completely valid.

Fixing It With ffmpeg

ffmpeg does all the real work here. I just call it correctly.

The first step is finding a square crop. iPhone video is 16:9 or 4:3, never square, so I need a 1:1 region. cropdetect scans a few seconds and reports a crop rectangle:

ffmpeg -i input.mov -t 3 -vf cropdetect=24:16:0 -f null - 2>&1 \
  | awk '/crop=/ { c=$NF } END { print c }'

That prints something like crop=1080:1080:420:0. It centers on the actual content instead of blindly cropping from a corner.

Then the real encode:

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

Going through the flags that matter:

-t 10 hard-caps the clip at 10 seconds.
The -vf chain crops to square, scales to 800x800 with the Lanczos filter (sharper than the default bilinear), and forces format=yuv420p so the 10-bit problem disappears.
-c:v libx264 is the codec swap. HEVC goes in, H.264 comes out.
-crf 28 trades a little quality for size. At 800x800 it looks fine and helps stay under 2 MB.
-an drops the audio track completely.
-movflags +faststart moves the moov atom to the front.

One encode, every requirement satisfied.

Wiring It Into an aiogram 3 Bot

I wrapped this in a Telegram bot with aiogram 3 so I never have to think about it again. The handler accepts video, animation (GIFs arrive as animation), and raw document uploads:

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

dp = Dispatcher()


@dp.message(F.video | F.animation | F.document)
async def handle_video(message: Message, bot: Bot) -> None:
    media = message.video or message.animation or message.document
    if media is None:
        return

    src = Path(f"/tmp/{media.file_unique_id}.src")
    dst = Path(f"/tmp/{media.file_unique_id}.mp4")
    await bot.download(media, destination=src)

    await message.answer("Re-encoding to Telegram avatar format...")
    ok = await convert_to_avatar(src, dst)
    if not ok:
        await message.answer("Couldn't convert that one. 4K and HDR aren't handled yet.")
    else:
        await message.answer_video(FSInputFile(dst))

    src.unlink(missing_ok=True)
    dst.unlink(missing_ok=True)

The conversion runs ffmpeg as a subprocess and checks the output before trusting it:

async def convert_to_avatar(src: Path, dst: Path) -> bool:
    vf = "crop=in_h:in_h,scale=800:800:flags=lanczos,format=yuv420p"
    cmd = [
        "ffmpeg", "-i", str(src), "-t", "10",
        "-vf", vf,
        "-c:v", "libx264", "-preset", "slow", "-crf", "28",
        "-an", "-movflags", "+faststart", "-y", str(dst),
    ]
    proc = await asyncio.create_subprocess_exec(
        *cmd,
        stdout=asyncio.subprocess.DEVNULL,
        stderr=asyncio.subprocess.DEVNULL,
    )
    await proc.wait()
    if proc.returncode != 0 or not dst.exists():
        return False
    return dst.stat().st_size <= 2 * 1024 * 1024

For the bot I use crop=in_h:in_h, a center square based on input height. It skips the separate cropdetect pass and keeps latency low. cropdetect is the better choice when framing matters more than speed.

Packaging It As a Bot Anyone Can Use

Once it worked for me, sharing it was almost free. Send a video to the bot, get back a file that drops straight into the Telegram avatar slot. No app, no settings, no codec knowledge required. It lives here: https://t.me/LiveAvaBot?start=devto_article_20260520

The whole thing is one ffmpeg call behind a message handler. ffmpeg is doing the heavy lifting. I just wrote the wrapper that knows the exact spec Telegram never documents.

Edge Cases And What's Next

A few things I learned shipping it:

Size overshoot. A busy 10-second clip can still land above 2 MB at crf 28. The fix is a second pass with a higher crf, bumping it 4 or 5 at a time until the file fits.
Rotation metadata. iPhone videos carry a rotation flag instead of rotating pixels. ffmpeg honors it by default now, but older builds can hand you a sideways avatar.
GIFs. They arrive as animation, not video, which is why the handler filter includes both. After encoding they behave like any other clip.
4K and HDR. Not handled yet. HDR needs a tone-mapping step before the H.264 conversion or the colors wash out. That is next on the list.

Telegram silently rejecting valid-looking files is annoying. The fix turned out small once you know what the avatar slot wants: one ffmpeg call behind a message handler.

Built by me, @liveavabot.

Converting iPhone HEVC Video to a Telegram Video Avatar With FFmpeg

liveavabot — Sun, 17 May 2026 22:03:46 +0000

The Problem: iPhone Videos Silently Fail as Telegram Avatars

You record a clip on your iPhone, open Telegram, tap your profile picture, pick "Set Video", select the clip. Telegram chews on it for a second, then nothing happens. No error. No upload. Just silence.

I hit this myself last winter. The clip looked fine in the Photos app. Played fine on the Mac. But Telegram refused to accept it as a video avatar. After a lot of poking, the answer turned out to be boring: iPhone records video in HEVC (H.265) inside a .mov container, and Telegram's video-avatar slot only accepts H.264 in a specific shape. The official iOS Telegram client transcodes for you. The desktop client and most third-party uploaders do not. So the file gets rejected with no feedback.

That is the bug I built @liveavabot to fix.

What Telegram Actually Wants From a Video Avatar

The Telegram video-avatar slot (setProfilePhoto with video) is fussy. After reading the API docs and breaking things several times, here is what actually works:

Codec: H.264 (libx264), not HEVC.
Container: .mp4 with +faststart so the moov atom is at the front.
Pixel format: yuv420p. Anything else and clients downstream get unhappy.
Resolution: square, ideally 800x800. 640x640 works too but 800 is the sweet spot.
Duration: 10 seconds maximum, hard cap.
Audio: stripped. Avatars are silent.
File size: under ~2 MB for clean upload on slow connections.

If any one of these is off, Telegram rejects the upload silently or shows a generic error. The HEVC issue is the most common because HEVC has been the iPhone default since iOS 11.

Using FFmpeg cropdetect to Find the Square

Phone videos are 9:16 or 16:9. A naive scale=800:800 stretches the image into a squashed mess. I needed a smart crop that finds the meaningful part of each frame.

FFmpeg has cropdetect for exactly this. You run it in analysis mode first, parse the output for the suggested crop box, then use that crop in the real encode. Two passes, but cheap on small clips.

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

That prints something like crop=720:720:0:480. Then you apply it, scale to 800x800, and encode:

ffmpeg -i input.mov \
  -vf "crop=720:720:0:480,scale=800:800,format=yuv420p" \
  -c:v libx264 -preset veryfast -crf 28 \
  -movflags +faststart \
  -t 10 -an \
  output.mp4

The flags worth knowing: -t 10 caps duration, -an drops audio, -movflags +faststart puts the moov atom at the file start so Telegram can begin upload validation without reading the whole file. crf 28 is aggressive but keeps most clips under 2 MB. Bump to 30 if you need smaller.

Wrapping FFmpeg in Python

I shell out to ffmpeg with asyncio.create_subprocess_exec. No PyAV, no MoviePy. Both add weight and neither gives me anything the CLI does not.

import asyncio
import re
from pathlib import Path

CROPDETECT_RE = re.compile(r"crop=(\d+:\d+:\d+:\d+)")

async def detect_crop(src: Path) -> str:
    proc = await asyncio.create_subprocess_exec(
        "ffmpeg", "-i", str(src),
        "-vf", "cropdetect=24:16:0",
        "-f", "null", "-",
        stdout=asyncio.subprocess.DEVNULL,
        stderr=asyncio.subprocess.PIPE,
    )
    _, stderr = await proc.communicate()
    matches = CROPDETECT_RE.findall(stderr.decode("utf-8", "ignore"))
    return matches[-1] if matches else "in_w:in_h:0:0"

async def to_avatar(src: Path, dst: Path) -> None:
    crop = await detect_crop(src)
    vf = f"crop={crop},scale=800:800,format=yuv420p"
    proc = await asyncio.create_subprocess_exec(
        "ffmpeg", "-y", "-i", str(src),
        "-vf", vf,
        "-c:v", "libx264", "-preset", "veryfast", "-crf", "28",
        "-movflags", "+faststart",
        "-t", "10", "-an",
        str(dst),
    )
    await proc.wait()

Two passes, two subprocesses. Total runtime on a 5 second iPhone HEVC clip: about 1.2 seconds on a cheap VPS. Good enough.

The aiogram 3 Handler

The bot side is short. aiogram 3 makes this almost boring, which is the whole point.

import tempfile, uuid
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:
        return

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

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

    await to_avatar(src, dst)

    if dst.stat().st_size > 2_000_000:
        await message.answer("Output is over 2 MB. Try a shorter clip.")
        return

    await message.answer_video(
        FSInputFile(dst),
        caption="Ready. Save this, then set it as your profile video.",
    )

The F.video | F.animation | F.document filter catches the three ways Telegram delivers video: native video, GIF (animation), or raw document upload (which is how most iPhone clips arrive from desktop). One handler, three sources.

Packaging It as @liveavabot

The whole thing lives on a $4 Hetzner VPS. Bot framework: aiogram 3. Queue: just asyncio, no Redis, no Celery. Storage: tempfile, deleted after send. Stars billing wired in through Telegram's native invoice flow, no Stripe.

You can try it here: https://t.me/LiveAvaBot?start=devto_article_20260518. Send a video, get back a square clip that actually works as your profile video.

Lessons and Edge Cases

A few things that bit me along the way.

Portrait clips often need a top-anchored crop, not center. cropdetect handles this if you let it look at enough frames. The default of 2 seconds is too short for some clips, so I bumped the analysis window to 4 seconds.

4K input is slow on a $4 VPS. I added an upfront scale=-2:1080 downscale before cropdetect when the source is huge. Quality stays fine because the output is 800x800 anyway.

Some users send .mov files renamed to .mp4. Do not trust the extension. ffmpeg sniffs the container correctly, so just let it.

If the source is shorter than 1 second, Telegram rejects the avatar as too short. I now refuse anything under 1 second on the bot side with a clear error message instead of letting ffmpeg produce a broken file.

Next on the list: HDR tone-mapping for newer iPhone clips, which currently come out flat after the H.264 conversion. ffmpeg has a zscale filter for this but it needs a custom build on Debian, which I have been putting off.

Built by me, @liveavabot. Code is messier than the snippets here but the shape is the same.

Fitting 10 Seconds of Video Into 2 MB for Telegram Avatars

liveavabot — Fri, 15 May 2026 21:06:06 +0000

I shipped a Telegram bot that converts any video into a video avatar. The ffmpeg command took an afternoon. Getting every output under 2 MB took a week.

The spec

Telegram video avatars have rigid constraints: 800×800 pixels (square), H.264 codec, yuv420p pixel format, 10 seconds max, no audio, 2 MB file size ceiling, MP4 container with faststart.

Miss any of these and Telegram silently rejects the file. No error message, no warning. The upload just fails.

The resolution, codec, and duration rules are straightforward ffmpeg flags. The 2 MB ceiling is where things get interesting.

The bitrate math

2 MB equals roughly 16.7 million bits. Over 10 seconds, that gives you about 1,677 kbps for everything: video stream, container overhead, metadata.

I target 900 kbps for the video stream with a max rate of 1200 kbps. That produces roughly 1.1 MB for a 10-second clip. Plenty of headroom.

Why not push closer to the limit? Because rate control isn't truly constant. Complex frames spike above the target. The maxrate flag caps the peaks, but I'd rather have a comfortable margin than chase the ceiling and occasionally overshoot.

Here's the math for different durations:

3 seconds at 900 kbps: ~330 KB
5 seconds at 900 kbps: ~550 KB
10 seconds at 900 kbps: ~1.1 MB
10 seconds at 1400 kbps: ~1.7 MB (tight)

The 900k target works for almost everything. The only time I've seen it produce bad output is extremely dark or noisy footage, where H.264 needs more bits to avoid banding. For avatars (usually faces, pets, memes), 900k looks good.

The ffmpeg command

This is the full pipeline I run for every conversion:

ffmpeg -y -i input.mp4 -t 10 \
  -vf "crop=min(iw\,ih):min(iw\,ih),scale=800:800,fps=30,format=yuv420p" \
  -c:v libx264 -preset medium \
  -b:v 900k -maxrate 1200k -bufsize 2M \
  -an -movflags +faststart \
  output.mp4

crop=min(iw\,ih):min(iw\,ih) squares the video by cropping to the shorter dimension. Centers the crop automatically.

scale=800:800 resizes to Telegram's exact requirement.

fps=30 normalizes the frame rate. This matters more than you'd expect. iPhone slow-mo videos come in at 120 or 240 fps. Without this flag, you get a 10-second clip with 4x the frames, blowing the file size.

format=yuv420p forces the pixel format. Some inputs (screen recordings, ProRes) use yuv444p or yuv422p. Telegram needs 420p.

-b:v 900k -maxrate 1200k -bufsize 2M is the rate control trio. Target 900 kbps, peaks capped at 1200 kbps, VBV buffer 2 MB. The buffer size matters: too small and quality oscillates visibly between keyframes.

-an strips audio. Video avatars can't have it, and leaving it in wastes bytes.

-movflags +faststart moves the moov atom to the front of the file. Without this, Telegram sometimes can't seek or preview the video.

Running ffmpeg inside an async bot

The bot uses aiogram 3 with asyncio. Running synchronous ffmpeg subprocesses inside an async event loop needs some care.

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

router = Router()
_SEM = asyncio.Semaphore(4)

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

    async with _SEM:
        with tempfile.TemporaryDirectory() as td:
            inp = Path(td) / "in.bin"
            out = Path(td) / "out.mp4"

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

            cmd = [
                "ffmpeg", "-y", "-i", str(inp), "-t", "10",
                "-vf", "crop=min(iw\\,ih):min(iw\\,ih),"
                       "scale=800:800,fps=30,format=yuv420p",
                "-c:v", "libx264", "-preset", "medium",
                "-b:v", "900k", "-maxrate", "1200k",
                "-bufsize", "2M", "-an",
                "-movflags", "+faststart", str(out),
            ]

            proc = await asyncio.create_subprocess_exec(
                *cmd,
                stdout=asyncio.subprocess.DEVNULL,
                stderr=asyncio.subprocess.PIPE,
            )
            _, stderr = await asyncio.wait_for(
                proc.communicate(), timeout=60
            )

            if proc.returncode != 0:
                await message.reply("Conversion failed, sorry.")
                return

            if out.stat().st_size > 2 * 1024 * 1024:
                await message.reply("Output too large. Try a shorter clip.")
                return

            await message.answer_video(FSInputFile(out))

Three things worth calling out here.

asyncio.Semaphore(4) limits concurrent ffmpeg processes to four. Without it, a burst of messages spawns dozens of ffmpeg instances and your VPS runs out of memory. I learned this on a 2 GB droplet when someone forwarded a batch of 20 videos at once.

asyncio.wait_for with a 60-second timeout prevents zombie processes. Some corrupted inputs cause ffmpeg to hang indefinitely. The timeout kills them cleanly.

The explicit file size check after encoding is a safety net. If rate control fails on an unusual input (rare, but I've seen it with certain screen recordings), the bot catches it before sending an oversized file that Telegram would silently reject.

Edge cases that burned me

iPhone HEVC. About 68% of my users send videos from iPhones, which record in HEVC (H.265) by default. Telegram video avatars require H.264. The ffmpeg command handles this transparently because -c:v libx264 forces a full re-encode regardless of input codec. But if you're checking whether to re-encode, don't trust the file extension. Use ffprobe to read the actual codec.

Variable frame rate. Game capture software (OBS, ShadowPlay) often produces VFR files. The fps=30 filter normalizes this. Without it, ffmpeg's duration estimation goes wrong and you get truncated or weirdly stretched output.

Animated stickers. About 11% of users send Telegram animated stickers (WebM/VP9). These decode fine, but some stickers are a single frame. The output becomes a 10-second still image. Technically valid, not what anyone wants. I added a frame count check and return a warning for single-frame inputs.

GIFs with absurd frame counts. Some GIFs pack 500+ frames into 3 seconds. The fps=30 filter saves you here too, dropping excess frames before encoding. Without it, the encoder sees way too many frames and the output blows past 2 MB.

Try it

I packaged all of this as @liveavabot. Send any video, GIF, or sticker and it returns a properly formatted video avatar. 55 users so far, still iterating on edge cases.

Built by me, @liveavabot: https://t.me/LiveAvaBot?start=devto_article_20260516

HeyGen + Telegram video avatar

liveavabot — Wed, 13 May 2026 14:00:59 +0000

HeyGen creates compelling talking-head videos — but the output is not directly usable as a Telegram video avatar. Here is the mismatch and how to bridge it.

The mismatch

Property	HeyGen output	Telegram avatar spec
Aspect	16:9 or 9:16	1:1 exactly
Duration	10-120s	max 10s
Codec	H.264 or HEVC	H.264 only
Audio	stereo	none

The ffmpeg bridge

ffmpeg -y -i heygen_output.mp4 -t 10 \
  -vf "crop=min(iw\,ih):min(iw\,ih),scale=800:800,fps=30,format=yuv420p" \
  -c:v libx264 -preset medium -b:v 900k \
  -an -movflags +faststart \
  telegram_avatar.mp4

The instant path

Drop the HeyGen export into @liveavabot. The same ffmpeg pipeline runs server-side.

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

Why iPhone Videos Silently Fail as Telegram Video Avatars

liveavabot — Mon, 11 May 2026 13:07:00 +0000

I recorded a 5-second clip on my iPhone, opened Telegram, tried to set it as my video avatar, and nothing happened. No error, no warning. Telegram just quietly rejected the file and moved on.

Turns out the problem is HEVC. iPhones shoot in HEVC (H.265) by default since iPhone 7. Telegram video avatars require H.264. When you send an HEVC video as a profile avatar, Telegram's client silently drops it. No feedback, no conversion, just nothing.

I spent an evening figuring out the exact spec, wrote an ffmpeg pipeline to handle any input video, and then wrapped it in a Telegram bot with aiogram 3. Here's everything I learned.

What Telegram video avatars actually require

Telegram doesn't document this well, so I had to reverse-engineer it from failed uploads and the Telegram Desktop source.

Codec: H.264 (libx264). HEVC, VP9, AV1 all get rejected silently.
Resolution: Square. 800x800 is the documented max. Some clients accept larger, but 640x640 works on every device including old Android phones.
Duration: 10 seconds max. The client loops the video, so shorter clips (3-7s) tend to look better.
File size: Under 2 MB. This is the hard limit that catches most people.
Audio: Must be stripped entirely. Even a silent audio track adds overhead and can cause issues on some clients.
Pixel format: yuv420p. Some encoders default to yuv444p or yuv422p, and Telegram won't accept those.
Container: MP4 with faststart (moov atom at the beginning so the client can preview before full download).

If any of these are wrong, Telegram does nothing. No error popup, no "unsupported format" message. The upload silently fails.

The ffmpeg pipeline

Here's the command I landed on after testing dozens of combinations:

ffmpeg -y -v error \
  -i input.mov \
  -t 9 \
  -vf "crop='min(iw,ih)':'min(iw,ih)',scale=640:640:flags=lanczos,fps=30,format=yuv420p" \
  -an \
  -c:v libx264 -profile:v high -level 4.0 \
  -preset medium -crf 23 \
  -maxrate 1400k -bufsize 2800k \
  -pix_fmt yuv420p \
  -movflags +faststart \
  output.mp4

Let me break down what each part does.

crop='min(iw,ih)':'min(iw,ih)' takes the center square from any aspect ratio. A 1920x1080 landscape video becomes 1080x1080 from the center. A 1080x1920 portrait video also becomes 1080x1080. This handles every phone orientation without needing to detect it first.

scale=640:640:flags=lanczos downscales to the target resolution. Lanczos resampling keeps text and sharp edges looking clean at small sizes. Bilinear would be faster but visibly blurry on a 640px square.

fps=30,format=yuv420p normalizes frame rate and pixel format. iPhones shoot at varying rates (24, 30, 60fps), and some screen recordings use odd color formats. Forcing 30fps and yuv420p ensures compatibility everywhere.

-an strips all audio tracks. Simple but easy to forget.

-c:v libx264 -profile:v high -level 4.0 encodes H.264 at High profile, Level 4.0. This combination works on every Telegram client I've tested, from Desktop to the oldest Android version I could find.

-crf 23 -maxrate 1400k -bufsize 2800k controls quality and file size. CRF 23 is the sweet spot for 640x640. At 9 seconds, this typically produces files between 400KB and 800KB, well under the 2MB limit. The maxrate cap prevents quality spikes from blowing the budget on complex scenes.

-movflags +faststart relocates the MP4 moov atom to the beginning of the file. Without this, Telegram can't preview the video until the full file downloads.

Wiring it up with aiogram 3

The bot side is straightforward. Accept a video or document, run ffmpeg, send back the converted file:

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

router = Router()

@router.message(F.video | F.document | F.animation)
async def handle_video(msg: Message) -> None:
    file_id = (msg.video or msg.document or msg.animation).file_id
    src = Path(f"/tmp/{uuid.uuid4().hex}.mov")
    dst = Path(f"/tmp/{uuid.uuid4().hex}.mp4")

    await msg.bot.download(file_id, destination=src)
    await msg.answer("Converting, one sec...")

    vf = (
        "crop='min(iw,ih)':'min(iw,ih)',"
        "scale=640:640:flags=lanczos,"
        "fps=30,format=yuv420p"
    )
    proc = await asyncio.create_subprocess_exec(
        "ffmpeg", "-y", "-v", "error",
        "-i", str(src), "-t", "9",
        "-vf", vf, "-an",
        "-c:v", "libx264", "-profile:v", "high", "-level", "4.0",
        "-preset", "medium", "-crf", "23",
        "-maxrate", "1400k", "-bufsize", "2800k",
        "-pix_fmt", "yuv420p", "-movflags", "+faststart",
        str(dst),
        stdout=asyncio.subprocess.PIPE,
        stderr=asyncio.subprocess.PIPE,
    )
    await proc.wait()

    if proc.returncode == 0 and dst.exists():
        await msg.answer_video_note(FSInputFile(dst))
        await msg.answer(
            "Done. Save this as your video avatar "
            "in Settings > Profile."
        )
    else:
        await msg.answer("Conversion failed. Try a different video?")

    src.unlink(missing_ok=True)
    dst.unlink(missing_ok=True)

A few things worth noting.

F.video | F.document | F.animation catches all three ways users send media in Telegram. Videos arrive as video, screen recordings sometimes arrive as document, and GIFs come as animation. Missing any of these means confused users asking why it doesn't work with their GIF.

answer_video_note sends the result as a circular video note. This gives users a preview of what the avatar will actually look like. You could also use answer_document to send the raw file for manual upload.

Cleanup matters. ffmpeg temp files pile up fast if you forget to unlink. On a VPS with limited disk, this becomes a problem within hours.

Packaging it as @liveavabot

I took this basic pipeline and turned it into @LiveAvaBot. The bot adds a few things on top of the bare conversion.

Concurrency control. ffmpeg is CPU-heavy. Running 10 simultaneous conversions on a 2-core VPS makes everything unusable. I use an asyncio.Semaphore to cap concurrent ffmpeg processes.

Freemium model. First two conversions are free. After that, users pay with Telegram Stars, Telegram's built-in payment system. No Stripe integration, no payment form. Users tap "Pay" in the chat, confirm with Google Pay or Apple Pay, done.

Error recovery. The production version retries with lower quality settings if the first attempt exceeds 2MB. Drop CRF from 23 to 26, reduce maxrate to 1000k, try again. This handles high-motion content like sports clips that compress poorly.

Edge cases that bit me

Vertical videos with black bars. Some screen recordings have black letterboxing baked into the video stream. The center crop takes those bars with it, giving you a square of mostly black. I added cropdetect as a pre-pass to find the actual content bounds before cropping.

GIFs with weird frame rates. Telegram GIF animations are actually silent MP4s internally, but the metadata sometimes reports 50fps or higher. The fps=30 filter handles this, but without it ffmpeg would generate way more frames than needed and blow past the 2MB limit.

0-byte files on error. When ffmpeg fails (corrupt input, unsupported codec), it sometimes creates a 0-byte output file. The dst.exists() check alone isn't enough. You need dst.stat().st_size > 0 in production.

yuv420p set twice on purpose. I set yuv420p in both the video filter chain (format=yuv420p) and as a top-level flag (-pix_fmt yuv420p). Belt and suspenders. Some ffmpeg builds ignore one or the other depending on the input format.

Built by me. @LiveAvaBot: send it any video, get back a Telegram-ready avatar. First two conversions are free.

Telegram inline bots: avatar template picker with aiogram 3

liveavabot — Sun, 03 May 2026 18:02:33 +0000

Inline mode is underused. Most bots ignore it. For a template-selection flow, it is the best UX Telegram offers.

How it works

When a user types @LiveAvaBot query in any chat, Telegram sends an inline_query to your bot. You respond with up to 50 results.

The aiogram 3 handler

from aiogram import Router
from aiogram.types import InlineQuery, InlineQueryResultCachedMpeg4Gif

router = Router()
TEMPLATES = [...]  # list of (file_id, title) tuples

@router.inline_query()
async def handle_inline(query: InlineQuery):
    q = query.query.lower().strip()
    results = [
        InlineQueryResultCachedMpeg4Gif(
            id=str(i),
            mpeg4_file_id=fid,
            title=title,
        )
        for i, (fid, title) in enumerate(TEMPLATES)
        if not q or q in title.lower()
    ]
    await query.answer(results[:25], cache_time=300, is_personal=False)

Caching file_ids

Upload each template once via bot.send_animation, save the file_id. Never re-upload.

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