DEV Community: liveavabot

Why iPhone Videos Fail as Telegram Avatars (and How I Fixed It)

liveavabot — Sun, 27 Sep 2026 00:04:55 +0000

You record a 5-second clip on your iPhone, open Telegram, try to set it as your video avatar, and nothing happens. No error, no feedback. Telegram quietly refuses HEVC (H.265) video without telling you why.

I ran into this while building @liveavabot, a bot that converts any video or GIF into the exact format Telegram requires for video avatars. The HEVC problem caused more confusion than anything else in the first week.

What Telegram Actually Requires

The video avatar spec is strict and mostly undocumented. Through testing and reading API error responses, here's what works:

Codec: H.264 (not HEVC/H.265, not VP9, not AV1)
Container: MP4 with the faststart flag set
Resolution: 800x800 pixels, square
Duration: 10 seconds maximum
File size: 2 MB maximum
Audio: Must be absent (video avatars are silent)
Pixel format: yuv420p

iPhones default to HEVC since iOS 11 to save storage. Most Telegram clients silently discard HEVC input when setting a video avatar. The desktop client occasionally shows a generic "file format not supported" message. Mobile just does nothing.

The ffmpeg Pipeline

The conversion runs in two steps. First, cropdetect to find actual content boundaries (many clips have letterboxing or pillarboxing). Second, encode with the detected crop applied.

# Pass 1: detect crop (look for "crop=" lines in stderr output)
ffmpeg -i input.mov -vf "cropdetect=24:2:0" -f null - 2>&1

# The last crop= line gives the rectangle: crop=W:H:X:Y
# Example: crop=1080:1080:0:0

# Pass 2: apply crop, scale to 800x800, encode as H.264
ffmpeg -i input.mov \
  -vf "crop=1080:1080:0:0,scale=800:800:flags=lanczos,fps=30" \
  -c:v libx264 -preset fast -crf 23 \
  -pix_fmt yuv420p -an \
  -movflags +faststart \
  -t 10 \
  output.mp4

Key flags:

-pix_fmt yuv420p forces the pixel format Telegram expects
-an strips audio completely
-movflags +faststart moves the moov atom to the file front, required for streaming
-t 10 hard-caps at 10 seconds
fps=30 normalizes frame rate (Cinematic mode clips are often 24fps or variable)

If cropdetect returns nothing useful (uniform borders or no borders at all), I fall back to center-crop: scale=800:800:force_original_aspect_ratio=increase,crop=800:800.

aiogram 3 Handler

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

router = Router()

async def convert_for_tg_avatar(src: str, dst: str) -> bool:
    # Pass 1: cropdetect
    p1 = await asyncio.create_subprocess_exec(
        'ffmpeg', '-i', src, '-vf', 'cropdetect=24:2:0', '-f', 'null', '-',
        stderr=asyncio.subprocess.PIPE,
    )
    _, err = await p1.communicate()
    lines = [l for l in err.decode().splitlines() if 'crop=' in l]
    crop = lines[-1].rsplit('crop=', 1)[1].split()[0] if lines else 'iw:ih:0:0'
    crop_filter = f'crop={crop}'

    # Pass 2: encode
    vf = f'{crop_filter},scale=800:800:flags=lanczos,fps=30'
    p2 = await asyncio.create_subprocess_exec(
        'ffmpeg', '-y', '-i', src,
        '-vf', vf, '-c:v', 'libx264', '-preset', 'fast', '-crf', '23',
        '-pix_fmt', 'yuv420p', '-an', '-movflags', '+faststart', '-t', '10',
        dst, stderr=asyncio.subprocess.PIPE,
    )
    await p2.communicate()
    return os.path.exists(dst) and os.path.getsize(dst) > 0


@router.message(F.video | F.animation | F.document)
async def handle_video(message: Message, bot: Bot):
    status = await message.reply('Converting...')
    file_id = (message.video or message.animation or message.document).file_id

    with tempfile.TemporaryDirectory() as tmp:
        src = os.path.join(tmp, 'src')
        dst = os.path.join(tmp, 'out.mp4')
        f = await bot.get_file(file_id)
        await bot.download_file(f.file_path, src)

        if not await convert_for_tg_avatar(src, dst):
            await status.edit_text('Conversion failed. Try a shorter clip.')
            return

        size = os.path.getsize(dst)
        if size > 2 * 1024 * 1024:
            await status.edit_text(
                f'Output is {size // 1024} KB, over the 2 MB limit. Try a shorter clip.'
            )
            return

        await status.delete()
        await message.reply_video(
            FSInputFile(dst),
            caption='Ready. Set it in Telegram: Profile > Edit > Set Video.'
        )

The handler doesn't retry with a lower CRF when the output is too large. I tried auto-lowering CRF early on and the result looked noticeably bad. Better to reject and ask for a shorter clip.

Packaging This as @liveavabot

The bot runs on a small VPS with aiogram 3.x, a systemd service, and ffmpeg 6.x from apt. No GPU, no cloud functions. Conversion takes 2-5 seconds for a 10-second 1080p clip.

A few things I added after the first 100 users:

Check file.file_size before downloading. The bot API includes file size in the message object. If it's over 20 MB, reject before downloading anything.
Accept .mov documents. When someone drags a .mov into Telegram as a file, it arrives as a document with mime type video/quicktime. The handler accepts it.
Per-user rate limit. One conversion per 10 seconds, tracked in a simple in-memory dict. Prevents accidental spam.

The bot is at https://t.me/LiveAvaBot?start=devto_article_20260927. Basic conversion is free. Currently at 430 users.

Edge Cases and Loose Ends

HEVC with Dolby Vision metadata. Some iPhone clips embed Dolby Vision HDR metadata. ffmpeg re-encodes fine, but output occasionally looks washed out. Adding -colorspace bt709 -color_trc bt709 -color_primaries bt709 helps but doesn't fully fix it. Still debugging.

Variable frame rate video. Cinematic mode and Slo-Mo produce VFR clips. The fps=30 filter normalizes them, but cropdetect can misfire on the first pass if there are blank leading frames. Adding -vsync vfr to the cropdetect pass helps.

GIF inputs. Animated GIFs need -ignore_loop 0 or ffmpeg encodes only the first frame.

2 MB limit on busy clips. CRF 23 at 800x800 for 10 seconds of high-motion content can exceed 2 MB at this quality level. I'm planning a two-pass VBR fallback targeting 1.8 MB for clips that fail the size check, instead of hard rejecting.

ffmpeg handles all the real work here. I wrote the async wrapper and Telegram handler around it.

Built by me. The bot: https://t.me/LiveAvaBot?start=devto_article_20260927.

How I Built a Telegram Bot to Fix iPhone HEVC Video Avatars

liveavabot — Thu, 24 Sep 2026 22:02:53 +0000

The Problem Nobody Explains

You record a video on your iPhone. You try to set it as your Telegram video avatar. The upload spinner runs, then nothing happens. No error message. Telegram just silently ignores the file.

The culprit is HEVC. iPhones default to H.265/HEVC recording since iOS 11, and Telegram's video avatar pipeline doesn't transcode on ingest. It drops the file without telling you why.

I hit this while setting up an avatar for a Telegram channel. Took me an embarrassing amount of time to figure out what was happening. Once I understood the actual spec, I built a bot so nobody else has to go through the same debugging session.

What Telegram Actually Requires

Telegram video avatars have a strict technical spec. I assembled this partly from docs, partly from trial and error:

Codec: H.264 (not HEVC, not VP9, not AV1)
Resolution: 800x800 pixels, square
Duration: 10 seconds maximum
File size: 2MB maximum
Audio: must be removed (audio tracks cause rejection)
Pixel format: yuv420p (some encoders default to yuv444p, which breaks playback on older clients)
Container: MP4 with faststart flag (moov atom at the front, required for streaming)

The square crop is the tricky part. Source footage is almost never 1:1, and naive scaling produces letterboxing instead of a proper crop to fill the avatar circle.

ffmpeg Pipeline: Cropdetect, Scale, Encode

I use a two-pass approach. First, cropdetect finds the actual content region and removes any letterboxing already in the source. Then scale-and-crop to 800x800.

Detect crop parameters first:

ffmpeg -i input.mp4 \
  -vf "cropdetect=24:2:0" \
  -f null - 2>&1 | grep cropdetect | tail -1

Then encode with the detected values (or skip cropdetect if the source is already full-frame):

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

A few decisions worth explaining:

scale=800:800:force_original_aspect_ratio=increase scales so the smaller dimension reaches 800. Then crop=800:800 center-crops the excess. No black bars, no distortion.

crf 26 keeps file size reasonable. Most 10s clips land well under 2MB. For high-motion content I add -maxrate 1.5M -bufsize 3M as a ceiling.

-an removes audio unconditionally. Telegram rejects files with audio tracks.

-movflags +faststart rewrites the container so the moov atom sits at the front, which Telegram's servers require for video avatars.

In the bot, I run cropdetect first, parse the last crop= line from stderr, then feed those values into the main encode. That handles already-letterboxed iPhone footage without double-cropping.

The aiogram 3 Handler

The bot runs on aiogram 3. Here's a simplified version of the video handler:

import os, tempfile, subprocess
from aiogram import Router, F
from aiogram.types import Message, FSInputFile

router = Router()

@router.message(F.video | F.document | F.animation)
async def handle_video(message: Message):
    status = await message.answer("Processing...")

    file_id = (
        message.video.file_id if message.video
        else message.document.file_id if message.document
        else message.animation.file_id
    )

    with tempfile.TemporaryDirectory() as tmp:
        src = os.path.join(tmp, "input")
        dst = os.path.join(tmp, "avatar.mp4")

        bot_file = await message.bot.get_file(file_id)
        await message.bot.download_file(bot_file.file_path, src)

        result = encode_for_avatar(src, dst)

        if result["ok"]:
            await message.answer_video(
                FSInputFile(dst),
                caption="Ready. Set this as your video avatar in Telegram Settings."
            )
        else:
            await message.answer(f"Encoding failed: {result['error']}")

    await status.delete()


def encode_for_avatar(src: str, dst: str) -> dict:
    cmd = [
        "ffmpeg", "-y", "-i", src,
        "-vf", (
            "scale=800:800:force_original_aspect_ratio=increase,"
            "crop=800:800,"
            "format=yuv420p"
        ),
        "-c:v", "libx264",
        "-preset", "fast",
        "-crf", "26",
        "-t", "10",
        "-an",
        "-movflags", "+faststart",
        dst
    ]
    proc = subprocess.run(cmd, capture_output=True, timeout=60)
    if proc.returncode != 0:
        return {"ok": False, "error": proc.stderr.decode()[-200:]}

    size = os.path.getsize(dst)
    if size > 2 * 1024 * 1024:
        return {"ok": False, "error": f"Output too large: {size // 1024}KB"}

    return {"ok": True}

The explicit size check at the end matters. CRF 26 is not a bitrate ceiling. High-motion clips can still produce files over 2MB. In production I retry with CRF 32 plus -maxrate 1.4M if the first pass exceeds the limit. That covers 99% of inputs.

Packaging It as @liveavabot

The bot is live at https://t.me/LiveAvaBot?start=devto_article_20260925. Send it a video, HEVC recording, or GIF, and it replies with an 800x800 H.264 MP4 ready to set as a video avatar.

The stack is thin: aiogram 3, ffmpeg, Python 3.11, running on a 2-core VPS. No GPU. Encoding a 10s clip takes 2-3 seconds on this hardware, which is fast enough that users rarely notice the wait.

One thing I didn't anticipate: GIFs are a significant chunk of traffic. People want to convert animated stickers and reaction GIFs into video avatars. ffmpeg handles these without any special casing, since it reads GIF as a video input.

The bot has 428 users now. Growth has been entirely organic, mostly from Telegram groups where someone posts their new video avatar and others ask how they made it.

Built by me: @liveavabot

Edge Cases Worth Knowing

HEVC from non-iPhone sources. Android devices in "high efficiency" mode, screen recorders, some mirrorless cameras. The pipeline doesn't care about the source. If ffmpeg decodes it, the bot handles it.

Oversized output. My two-attempt retry (CRF 26, then CRF 32 with maxrate) handles most cases. The only real failures are extreme slow-motion clips with very high frame counts, which I haven't seen in practice yet.

GIF transparency. Some GIFs use palette entry 0 as transparent. When converted to yuv420p, those areas render black. The correct fix is compositing over a solid background before encoding. I know about this bug but haven't shipped the fix yet.

Source longer than 10 seconds. ffmpeg's -t 10 trims to the first 10 seconds. Users sometimes expect a clip selector. I added a note in the reply when the source exceeds 10s so people know only the first 10s were used.

What's next: considering a small web UI for people who want to convert videos for Telegram without using Telegram. The irony is not lost on me, but the demand shows up in feedback messages regularly.

How to Convert iPhone HEVC Video to Telegram Video Avatar

liveavabot — Tue, 22 Sep 2026 21:03:31 +0000

The Bug I Didn't Expect

I was testing my own bot and sent it a video shot on an iPhone. Nothing happened. The bot accepted the file, ran ffmpeg, and returned what looked like a valid MP4. But Telegram silently rejected it as a video avatar. No error message, just silence.

Spent an hour before I realized: iPhone records in HEVC (H.265) by default. Telegram's video avatar spec requires H.264. The container is .mp4, everything looks fine, but the codec inside is wrong. Telegram doesn't tell you this. It just ignores the file.

That's the whole problem. What Telegram actually requires, and how ffmpeg solves it.

What Telegram Actually Requires

Telegram's video profile photo spec is tighter than you'd expect:

Codec: H.264 (libx264). Not H.265/HEVC, not VP9, not AV1.
Resolution: exactly 800x800 pixels, square.
Duration: 10 seconds maximum.
File size: 2 MB maximum.
Audio: must be removed. Video avatars are silent.
Pixel format: yuv420p. Some encoders default to yuv444p, which Telegram rejects.
Container: MP4 with the faststart flag (moov atom first, or in-app preview breaks).

Four of those are non-obvious. HEVC is the silent killer for iPhone users. yuv420p matters because libx264 can output yuv444p when you're not explicit. faststart matters for smooth in-app preview. Stripping audio is required, not optional cleanup.

The ffmpeg Pipeline

The naive approach:

ffmpeg -i input.mp4 -vf "scale=800:800" -c:v libx264 output.mp4

This fails in several ways. The video might not be square (letterbox bars, portrait crop, arbitrary aspect ratio). It doesn't strip audio. It doesn't enforce yuv420p. It doesn't cap duration. File size can still exceed 2 MB.

Here's the two-pass pipeline I use in production. First, detect the actual content bounds:

ffmpeg -i input.mp4 \
  -vf "cropdetect=limit=24:round=2:reset=0" \
  -f null - 2>&1 | grep cropdetect | tail -1

Parse the crop= value from that output, then use it in the encode pass:

ffmpeg -i input.mp4 \
  -t 10 \
  -vf "crop=<detected>,scale=800:800:force_original_aspect_ratio=disable,fps=30" \
  -c:v libx264 \
  -pix_fmt yuv420p \
  -crf 28 \
  -preset fast \
  -an \
  -movflags +faststart \
  output.mp4

Key flags:

-t 10: hard cap at 10 seconds
crop=<detected>: removes letterbox and pillarbox bars from the first pass
scale=800:800:force_original_aspect_ratio=disable: stretches to exact 800x800
-pix_fmt yuv420p: explicit, never rely on encoder default
-crf 28: quality-based encoding, keeps output under 2 MB for most 10s clips
-an: strips all audio tracks
-movflags +faststart: moov atom first

For clips that still exceed 2 MB at CRF 28 (high-motion 10s content), a second pass targeting -b:v 1400k reliably fits within 2 MB.

The aiogram 3 Handler

The handler downloads the file, runs the two-pass pipeline, and replies with the result.

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

router = Router()


async def run_ffmpeg(input_path: str, output_path: str) -> bool:
    detect_cmd = [
        "ffmpeg", "-i", input_path,
        "-vf", "cropdetect=limit=24:round=2:reset=0",
        "-f", "null", "-",
    ]
    proc = await asyncio.create_subprocess_exec(
        *detect_cmd,
        stdout=asyncio.subprocess.PIPE,
        stderr=asyncio.subprocess.PIPE,
    )
    _, stderr = await proc.communicate()

    crop_filter = ""
    for line in stderr.decode().splitlines():
        if "cropdetect" in line and "crop=" in line:
            crop_val = line.split("crop=")[-1].split()[0]
            crop_filter = f"crop={crop_val},"

    vf = f"{crop_filter}scale=800:800:force_original_aspect_ratio=disable,fps=30"
    encode_cmd = [
        "ffmpeg", "-i", input_path,
        "-t", "10",
        "-vf", vf,
        "-c:v", "libx264",
        "-pix_fmt", "yuv420p",
        "-crf", "28",
        "-preset", "fast",
        "-an",
        "-movflags", "+faststart",
        "-y", output_path,
    ]
    proc = await asyncio.create_subprocess_exec(
        *encode_cmd,
        stdout=asyncio.subprocess.PIPE,
        stderr=asyncio.subprocess.PIPE,
    )
    await proc.communicate()
    size = Path(output_path).stat().st_size if Path(output_path).exists() else 0
    return proc.returncode == 0 and size > 10_000 and size <= 2 * 1024 * 1024


@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

    await message.reply("Processing...")

    with tempfile.TemporaryDirectory() as tmpdir:
        input_path = os.path.join(tmpdir, "input.mp4")
        output_path = os.path.join(tmpdir, "output.mp4")

        await message.bot.download(file, destination=input_path)
        ok = await run_ffmpeg(input_path, output_path)

        if not ok:
            await message.reply("Couldn't convert this file. Try a shorter or smaller clip.")
            return

        with open(output_path, "rb") as f:
            data = f.read()

        await message.reply_video(
            video=BufferedInputFile(data, filename="avatar.mp4"),
            caption="Set this as your video avatar in Telegram profile settings.",
        )

Real production version adds download size checks before the temp file is written, per-user queue limits, and a bitrate retry pass if the first encode exceeds 2 MB. But this core runs.

How I Packaged It as @liveavabot

The bot is live at https://t.me/LiveAvaBot?start=devto_article_20260923. Send it any video or GIF, get back a ready-to-use 800x800 H.264 MP4. No app, no upload form, just a bot message.

424 users so far, 5 new in the last 24 hours. It's a small tool. VPS cost is under $5/month.

The reason I built it: people keep running into silent HEVC rejection with no explanation from Telegram. Settings > Camera > Formats > High Efficiency is on by default on most iPhones. Most users have no idea their video is H.265. The bot handles it transparently.

Built by me, https://t.me/LiveAvaBot?start=devto_article_20260923.

Edge Cases Worth Knowing

GIF files from Telegram are already MP4. When Telegram sends an "animation", it has already converted it to a silent MP4 internally. The handler treats it the same as video, which works.

Some vertical phone videos have no letterbox bars. cropdetect returns the full frame. scale=800:800 handles it fine.

Very short clips produce empty output. ffmpeg exits 0 but writes a 4 KB stub. Checking size > 10_000 before sending catches this.

libx264 preset tradeoffs. fast is the right balance. ultrafast produces noticeably larger files at the same CRF. slow rarely buys enough quality to matter for a 10s avatar clip.

Next thing I want to add: a manual crop selector so users can pick the frame window rather than relying on cropdetect. Not built yet. Auto-crop handles around 95% of cases well enough.

Why iPhone Videos Silently Fail as Telegram Avatars

liveavabot — Sun, 20 Sep 2026 20:04:25 +0000

The Silent Failure

You record a video on your iPhone, try to set it as your Telegram video avatar, and nothing happens. No error message. Telegram just ignores the file.

This is not a Telegram bug. iPhone records in HEVC (H.265) by default since iOS 11. Telegram's video avatar processor expects H.264. When it gets H.265, it silently fails on most clients, or shows a broken thumbnail with no explanation.

I ran into this when testing @liveavabot with different devices. iPhone videos were the main failure case. The fix is a specific ffmpeg pipeline, but getting all the parameters right took more trial and error than I expected.

What Telegram Actually Requires

Telegram's video avatar spec is stricter than most people realize:

Codec: H.264, yuv420p color space
Resolution: 800x800 (square)
Duration: 10 seconds maximum
File size: 2MB maximum
Audio: must be absent (streams removed, not muted)
Container: MP4 with the faststart flag set

The "no audio" requirement is easy to miss. A video with an empty audio stream still fails. You need to remove the audio track with -an, not just mute it.

The faststart flag (-movflags +faststart) moves the moov atom to the front of the file. Without it, Telegram's processor needs to buffer the entire file before it can read the metadata, and it often times out on larger uploads.

The yuv420p requirement matters for compatibility. Some encoders default to yuv444p or other chroma formats. Adding -pix_fmt yuv420p forces the correct subsampling.

The square format is non-negotiable. Telegram displays profile videos cropped to a circle. Any content outside the central square gets cut. Tall portrait videos (9:16) look fine as avatars. Landscape videos (16:9) show only a thin horizontal slice of the original, which is usually not what you want.

The ffmpeg Pipeline

After testing about 30 different iPhone videos, here's the command that handles all of them correctly:

ffmpeg -i input.mp4 \
  -vf "cropdetect=24:16:0,crop=w='iw-mod(iw,2)':h='ih-mod(ih,2)',scale=800:800:force_original_aspect_ratio=decrease,pad=800:800:(ow-iw)/2:(oh-ih)/2:black" \
  -c:v libx264 -profile:v baseline -level 3.0 \
  -pix_fmt yuv420p \
  -movflags +faststart \
  -an \
  -t 10 \
  -fs 2097152 \
  output.mp4

A few things worth explaining:

cropdetect scans the first few frames and detects letterboxing. Some iPhone slow-mo clips have black bars baked into the frame. Without removing them first, the square pad ends up with thin horizontal strips instead of clean black borders.

scale + pad resizes to fit within 800x800 while preserving aspect ratio, then fills the remaining space with black. A 9:16 portrait video becomes 800x800 with side bars. The force_original_aspect_ratio=decrease prevents any stretching.

-profile:v baseline -level 3.0 is belt-and-suspenders for older Telegram clients. The baseline profile has the widest decoder support across platforms.

-fs 2097152 is a hard 2MB cap at the ffmpeg level. Combined with -t 10, this handles most videos. For very high-bitrate content (iPhone 4K ProRes) you may need to add -b:v to explicitly target a lower bitrate before the size limit kicks in.

A Minimal aiogram 3 Handler

Here's the core handler that takes a video, runs it through the pipeline, and returns the converted file:

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

    file_info = await bot.get_file(file_obj.file_id)
    tmp_in = Path(f"/tmp/{file_info.file_id}_in.mp4")
    tmp_out = Path(f"/tmp/{file_info.file_id}_out.mp4")

    try:
        await bot.download_file(file_info.file_path, destination=tmp_in)

        proc = await asyncio.create_subprocess_exec(
            "ffmpeg", "-i", str(tmp_in),
            "-vf",
            "cropdetect=24:16:0,"
            "crop=w='iw-mod(iw,2)':h='ih-mod(ih,2)',"
            "scale=800:800:force_original_aspect_ratio=decrease,"
            "pad=800:800:(ow-iw)/2:(oh-ih)/2:black",
            "-c:v", "libx264", "-profile:v", "baseline", "-level", "3.0",
            "-pix_fmt", "yuv420p",
            "-movflags", "+faststart",
            "-an", "-t", "10", "-fs", "2097152",
            str(tmp_out),
            stdout=asyncio.subprocess.PIPE,
            stderr=asyncio.subprocess.PIPE,
        )
        await proc.communicate()

        if proc.returncode != 0 or not tmp_out.exists():
            await message.reply("Couldn't convert this file. Try a shorter clip.")
            return

        await message.reply_video(
            FSInputFile(tmp_out),
            caption="Ready. Go to your profile, tap the avatar, choose video.",
        )
    finally:
        tmp_in.unlink(missing_ok=True)
        tmp_out.unlink(missing_ok=True)

missing_ok=True on unlink matters. If ffmpeg fails before writing the output file, the finally block was throwing FileNotFoundError and swallowing the real error in the logs.

GIFs from Telegram arrive as .mp4 containers (Telegram converts them server-side). The handler treats them identically to regular videos, which works correctly.

I packaged this as @LiveAvaBot. Send it any video, GIF, or document up to Telegram's 50MB cap and it returns a ready 800x800 H.264 avatar. The bot is at 417 users now. Most discovery happens from people sharing their converted avatars and getting asked how they did it.

Edge Cases Worth Knowing

4K HEVC from iPhone Pro models can exceed 2MB even at 10 seconds. The -fs flag stops the encode mid-stream rather than failing outright, so the output is a valid (but shorter) file. A pre-pass with ffprobe to calculate a safe target bitrate would be cleaner than relying on the size cutoff.

Vertical 4:3 videos from some Android cameras can have a SAR/DAR mismatch. The cropdetect pass helps but doesn't fully solve it. I check the ffprobe output and warn the user when the stored sample aspect ratio doesn't match the display aspect ratio.

Round-trip uploads from Telegram Desktop sometimes arrive with a corrupted moov atom. Adding -ignore_unknown to the ffmpeg input flags fixes most of these without needing separate repair tooling.

Files above 20MB hit Telegram's Bot API download limit for bots. The handler catches this and tells the user to trim or compress the clip before uploading. There's no workaround on the server side for that limit.

What's Next

A web fallback so people can convert videos without a Telegram account. The ffmpeg pipeline would be identical; only the delivery changes (a download link instead of a bot message).

I also want to add a preview mode: send a still frame first, ask if the crop looks right, then run the full encode. Some videos have important content near the edges that the square format cuts off.

ffmpeg is doing most of the heavy lifting here. I just wrote the wrapper and hooked it up to a bot. But the devil is in the parameter combinations, and those took a while to get right.

Disclosure: I built this. The bot is @liveavabot.

Fixing iPhone HEVC Videos for Telegram Video Avatars with ffmpeg

liveavabot — Fri, 18 Sep 2026 19:04:20 +0000

The Silent Failure

You shoot a clip on an iPhone, send it to Telegram, tap "Set as profile video" and nothing happens. No error message, no explanation. The avatar just doesn't update.

The cause is HEVC. Apple switched iPhones to H.265 recording by default starting with iOS 11. It saves storage and the quality is good. Telegram's profile video pipeline doesn't accept H.265. It receives the file, processes it, and silently discards it.

I ran into this while building a bot that converts videos for Telegram avatars. About half the test videos from iPhones were failing. I spent a day digging through the Telegram client source and testing edge cases until I understood the full spec.

What Telegram's Video Avatar Spec Actually Requires

Telegram doesn't publish this anywhere, but here's what I found through testing:

Codec: H.264 (AVC). Not H.265/HEVC, not VP9, not AV1.
Resolution: exactly 800x800 pixels, square crop.
Duration: 10 seconds max. It loops.
File size: under 2MB.
Pixel format: yuv420p. Not yuv422p, not yuv444p, not 10-bit.
Audio: none. An audio track causes silent rejection.

Every one of these is a silent failure mode. H.264 with yuv444p? Rejected. H.264 at 1080x800? Rejected. Correct format but with an audio track? Rejected. You get no feedback.

The ffmpeg Pipeline

The main challenge is squaring a non-square video without stretching it. I use cropdetect to find the content area first, then scale to 800x800.

# Step 1: detect crop bounds
ffmpeg -i input.mp4 -vf "cropdetect=24:16:0" -frames:v 1 -f null - 2>&1 | grep -oP "crop=\S+"

That outputs something like crop=1080:1080:0:0. Then encode with those values:

ffmpeg -i input.mp4 \
  -vf "crop=1080:1080:0:0,scale=800:800,setsar=1,fps=30" \
  -c:v libx264 \
  -profile:v baseline \
  -level 3.0 \
  -pix_fmt yuv420p \
  -movflags +faststart \
  -an \
  -t 10 \
  -crf 28 \
  output.mp4

The flags that matter:

-pix_fmt yuv420p: forces the pixel format Telegram requires. Don't skip this.
-profile:v baseline -level 3.0: maximally compatible H.264 profile.
-movflags +faststart: puts the MOOV atom at the front, required for streaming playback.
-an: strips all audio tracks.
-t 10: hard cap at 10 seconds.

For HEVC input, ffmpeg decodes it automatically during the input stage. No special flag needed on the input side. The -c:v libx264 on the output handles re-encoding regardless of source codec.

The Aiogram 3 Handler

I wrote the bot in Python with aiogram 3. The message handler accepts video, animation, or document types, downloads the file, runs ffmpeg, and returns the result.

@router.message(F.video | F.animation | F.document)
async def handle_video(message: Message, bot: Bot):
    if message.video:
        file_id = message.video.file_id
    elif message.animation:
        file_id = message.animation.file_id
    else:
        file_id = message.document.file_id

    file = await bot.get_file(file_id)
    if file.file_size and file.file_size > 50 * 1024 * 1024:
        await message.reply("File too large (50MB Bot API limit).")
        return

    with tempfile.TemporaryDirectory() as tmpdir:
        input_path = Path(tmpdir) / "input"
        output_path = Path(tmpdir) / "output.mp4"

        await bot.download_file(file.file_path, str(input_path))
        ok = await convert_to_avatar(input_path, output_path)

        if not ok:
            await message.reply("Conversion failed, try a different clip.")
            return

        if output_path.stat().st_size > 2 * 1024 * 1024:
            await message.reply("Output exceeds 2MB, try a shorter clip.")
            return

        await message.reply_video(
            FSInputFile(output_path),
            caption="Done. Set this as your Telegram profile video."
        )

convert_to_avatar wraps the ffmpeg call in asyncio.create_subprocess_exec. Running it as a subprocess keeps the event loop unblocked during encodes, which typically take 2-4 seconds for a 10-second clip.

How I Packaged This as @liveavabot

The bot is live at https://t.me/LiveAvaBot?start=devto_article_20260918. Send it a video or GIF and it returns an 800x800 H.264 MP4 ready to set as a Telegram profile video.

Supported inputs:

iPhone HEVC videos (.mov, .mp4 with H.265)
GIFs (Telegram delivers these as animation type)
Vertical and horizontal videos (square-cropped, not stretched)
Documents (some clients forward videos as raw files rather than video messages)

The stack is Python, aiogram 3, ffmpeg, running on a small VPS. Current numbers: 409 total users, 4-5 new users per day.

Edge Cases That Bit Me

4K input ran out of memory. The VPS has 2GB RAM. Cropdetect on a 4K frame allocates enough to OOM the process. I added a pre-pass that checks resolution and downsamples anything above 1080p before the main encode.

Variable frame rate GIFs. Certain GIFs and Telegram animated stickers have irregular timing data that makes output duration unpredictable. Adding fps=30 to the filter chain normalizes this.

Output over 2MB. A 10-second 800x800 H.264 clip at CRF 28 typically lands around 1.2-1.8MB. High-motion clips push it over. I handle this with a second encode pass at CRF 35 if the first output exceeds 2MB.

Omitting -pix_fmt yuv420p on HDR input. HDR videos often use 10-bit yuv2020 color. Without the explicit pixel format flag, ffmpeg may preserve that, producing output Telegram silently rejects. The flag is not optional.

ffmpeg handles all the real work. I wrote the glue code and spent most of the time understanding the spec.

Built by me, @liveavabot on Telegram. If you've hit silent rejection with a different cause, I'd like to hear what fixed it.

Converting iPhone HEVC Videos to Telegram Video Avatars With ffmpeg

liveavabot — Wed, 16 Sep 2026 17:04:25 +0000

The Silent Failure Nobody Documents

I was helping a friend set a video avatar on Telegram. She recorded a 5-second clip on her iPhone, sent it to the bot, and nothing happened. No error. Just silence.

After about an hour of debugging I found the problem: her iPhone records in HEVC (H.265) by default since iOS 11, and Telegram's video avatar pipeline rejects H.265 without any user-facing message. The file passes the upload step, appears to process, then gets quietly dropped.

That's what pushed me to build @liveavabot.

What Telegram Video Avatars Actually Require

Telegram's documentation on this is sparse. I pieced together the spec from their API docs, bot API behavior, and a lot of trial and error:

Codec: H.264 (AVC), not H.265/HEVC
Pixel format: yuv420p (not yuv420p10le, not yuvj420p)
Resolution: exactly 800x800
Duration: 10 seconds maximum
File size: 2MB maximum
Audio: none (audio tracks cause a "Bad Request: VIDEO_NOTE_AUDIO" error)

The resolution requirement is the tricky part. Most videos aren't square. You can't just scale to 800x800 without distorting the content. You need to crop to a square first, then scale up.

The ffmpeg Pipeline

The approach is two steps: detect the optimal square crop region, then encode to spec.

ffmpeg has a cropdetect filter that finds the largest non-black region in a video. I use it in a no-output probe pass to compute the crop rectangle, then apply it in the encode pass:

# Step 1: detect the crop rectangle (scans first 10 seconds)
ffmpeg -i input.mov -vf "cropdetect=24:2:0" -t 10 -f null - 2>&1 | grep "crop="
# Sample output: ... crop=1080:1080:0:420 ...

# Step 2: encode to Telegram spec (portrait 1080x1920 example)
ffmpeg -i input.mov \
  -vf "crop=1080:1080:0:420,scale=800:800:flags=lanczos,format=yuv420p" \
  -c:v libx264 -preset fast -crf 28 \
  -an -t 10 -movflags +faststart \
  output.mp4

Key flags in the encode pass:

crop=1080:1080:0:420 cuts to a 1080x1080 square starting at x=0, y=420
scale=800:800:flags=lanczos upscales to 800x800 with Lanczos resampling
format=yuv420p forces the exact pixel format Telegram expects (not 10-bit, not JPEG chroma)
-an strips the audio track
-movflags +faststart moves the MP4 moov atom to the front, required for streaming

In my bot I compute the crop in Python using ffprobe rather than parsing cropdetect output. For a portrait 1080x1920 video: side = min(1080, 1920) = 1080, x = 0, y = (1920 - 1080) // 2 = 420. Cropdetect is useful for videos with letterboxing where you want to remove black bars too.

The aiogram 3 Handler

The bot is built on aiogram 3.x. Here's the core handler, simplified:

import asyncio, os, tempfile
from aiogram import Bot, Router, F
from aiogram.types import Message, BufferedInputFile
import ffmpeg  # pip install ffmpeg-python

router = Router()

def build_avatar(src: str, dst: str) -> None:
    probe = ffmpeg.probe(src)
    vs = next(s for s in probe["streams"] if s["codec_type"] == "video")
    w, h = int(vs["width"]), int(vs["height"])
    side = min(w, h)
    x = (w - side) // 2
    y = (h - side) // 2
    (
        ffmpeg
        .input(src, ss=0, t=10)
        .video
        .filter("crop", side, side, x, y)
        .filter("scale", 800, 800, flags="lanczos")
        .filter("format", "yuv420p")
        .output(
            dst,
            vcodec="libx264",
            preset="fast",
            crf=28,
            an=None,
            movflags="+faststart",
        )
        .overwrite_output()
        .run(quiet=True)
    )

@router.message(F.video | F.animation | F.document)
async def handle_video(msg: Message, bot: Bot) -> None:
    file_id = (msg.video or msg.animation or msg.document).file_id
    with tempfile.TemporaryDirectory() as tmp:
        src = os.path.join(tmp, "in.mp4")
        dst = os.path.join(tmp, "out.mp4")
        await bot.download(file_id, destination=src)
        await asyncio.to_thread(build_avatar, src, dst)
        size = os.path.getsize(dst)
        if size > 2 * 1024 * 1024:
            await msg.reply("Still over 2MB after encoding. Try a shorter clip.")
            return
        data = open(dst, "rb").read()
        await msg.reply_video_note(
            BufferedInputFile(data, filename="avatar.mp4")
        )

A few things worth noting:

asyncio.to_thread keeps ffmpeg off the event loop so the bot stays responsive under concurrent requests.
The handler matches F.video | F.animation | F.document because iPhone .mov files forwarded as documents arrive with type Document, not Video. Checking only F.video silently drops a common case.
reply_video_note sends the result as a round video, which Telegram accepts as a video avatar source.
The 2MB check after encoding catches edge cases. CRF 28 handles clips under 10 seconds well, but a fast-moving scene at high resolution can still push past the limit.

Packaging It as @liveavabot

The handler above is the core. The deployed bot adds a few things:

Duration check before encoding. I probe the source and warn if it's over 30 seconds. Encoding a 5-minute video to discover it still exceeds 2MB wastes server CPU and user patience.

Per-user rate limiting. The bot runs on a single VPS with 2 vCPUs. ffmpeg is CPU-bound. One user queuing 10 videos in parallel blocks everyone else.

Stars-based paid tier for users who convert more than 3 videos per day. The aiogram invoice flow handles this cleanly, no external payment library needed.

The bot is live at https://t.me/LiveAvaBot?start=devto_article_20260916. Currently at 403 registered users.

Edge Cases I Didn't Expect

yuv420p10le rejections. Some screen recordings and GoPro footage comes in at 10-bit color depth. ffmpeg's format=yuv420p filter handles the downconversion, but you have to explicitly add it to the filter chain. I forgot it once and Telegram returned a cryptic "wrong dimensions" error that took 20 minutes to diagnose.

4K source videos. CRF 28 with the fast preset doesn't reliably keep 4K footage under 2MB for 10 seconds. A two-pass encode with a target bitrate would fix it but adds latency. For now I document the limitation. ffmpeg is doing the heavy lifting; I just wrote the wrapper.

GIF loops. Animated GIFs convert cleanly but they loop. A 2-second GIF becomes a 2-second looping video avatar. Users expect this, so it's not a bug.

HEVC audio rejection. iPhone HEVC videos almost always have an AAC audio track. Without -an, the bot API returns "Bad Request: VIDEO_NOTE_AUDIO" with no further context. That error message would be a lot more useful if Telegram documented it anywhere.

Built by me. Bot: https://t.me/LiveAvaBot?start=devto_article_20260916. Drop a comment if your video is still failing after this pipeline.

Why iPhone Videos Fail as Telegram Avatars (and How to Fix It)

liveavabot — Mon, 14 Sep 2026 15:03:40 +0000

The Video That Won't Upload

You recorded a clip on your iPhone, tried to set it as your Telegram video avatar, and nothing happened. No error. Just a spinner. You trimmed it. Still nothing. You exported it again. Nothing.

The problem is HEVC. iPhones default to HEVC (H.265) since iOS 11, and Telegram's video avatar endpoint rejects H.265 silently. No feedback to the user. The video just doesn't apply.

I hit this myself when building a small tool. Then I read the actual spec.

What Telegram Actually Requires

Telegram's video avatar has strict requirements. Most aren't documented in one place:

Codec: H.264 (libx264), not H.265/HEVC
Container: MP4
Resolution: exactly 800×800 pixels, square
Duration: 10 seconds maximum
File size: 2 MB maximum
Audio: none (strip with -an)
Pixel format: yuv420p
Streaming: moov atom at front (-movflags +faststart)

The audio requirement trips people up. Even a video with no audible sound will fail if the container has an empty audio stream. You have to explicitly drop it.

Converting With ffmpeg

ffmpeg handles all of this. The tricky part is the crop. Vertical phone videos need centering before squaring, and some have black borders from export.

A two-pass approach: first detect the actual content bounds, then encode to spec.

Step 1: detect crop bounds

ffmpeg -i input.mov -vf cropdetect=24:2:0 -f null - 2>&1 | grep crop

This outputs something like crop=1080:1080:0:120. The cropdetect filter finds where actual image content starts and ends.

Step 2: encode to Telegram spec

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

Breaking that down:

crop=1080:1080:0:120 uses the bounds from step 1 (adjust per video)
scale=800:800:flags=lanczos resizes to exactly 800×800
format=yuv420p forces the pixel format
-c:v libx264 sets the H.264 encoder
-crf 28 trades quality for size (23 is ffmpeg default, 28 gets most clips under 2 MB)
-an drops audio, no exceptions
-t 10 caps at 10 seconds
-movflags +faststart moves the moov atom to front for streaming

For most iPhone clips (1080×1920), you can skip cropdetect entirely and hardcode crop=1080:1080:0:420 for a center-square crop.

The Aiogram 3 Handler

The bot receives a video or GIF, runs ffmpeg, sends the result back. Here's the core handler:

import asyncio
import os
import tempfile
from aiogram import Router, F
from aiogram.types import Message, BufferedInputFile

router = Router()

FFMPEG_CMD = [
    "ffmpeg", "-y", "-i", "{input}",
    "-vf", "crop=ih:ih,scale=800:800:flags=lanczos,format=yuv420p",
    "-c:v", "libx264", "-crf", "28", "-preset", "fast",
    "-an", "-t", "10", "-movflags", "+faststart",
    "{output}"
]

@router.message(F.video | F.animation | F.document)
async def handle_video(message: Message):
    file_id = (
        message.video or message.animation or message.document
    ).file_id

    await message.answer("Converting...")

    with tempfile.TemporaryDirectory() as tmp:
        input_path = os.path.join(tmp, "input")
        output_path = os.path.join(tmp, "output.mp4")

        file = await message.bot.get_file(file_id)
        await message.bot.download_file(file.file_path, input_path)

        cmd = [
            part.replace("{input}", input_path).replace("{output}", output_path)
            for part in FFMPEG_CMD
        ]

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

        if proc.returncode != 0 or not os.path.exists(output_path):
            await message.answer("Conversion failed. Is this a valid video?")
            return

        size = os.path.getsize(output_path)
        if size > 2 * 1024 * 1024:
            await message.answer(f"File still too large ({size // 1024} KB). Try a shorter clip.")
            return

        with open(output_path, "rb") as f:
            data = f.read()

        await message.answer_document(
            BufferedInputFile(data, filename="avatar.mp4"),
            caption="Ready. Set this as your Telegram video avatar in profile settings."
        )

The crop=ih:ih filter takes a center square without a cropdetect pre-pass. Works for most phone videos. For wide landscape clips with black bars, add a cropdetect step first.

Packaging It as @liveavabot

I wrapped this into a production bot, currently at 398 users. The core logic is exactly the code above, plus:

A queue so multiple simultaneous uploads don't fork a hundred ffmpeg processes
Size checks before downloading (Telegram caps bot file downloads at 20 MB)
GIF support (Telegram delivers GIFs as animation type, same handler path)
A /start message with explicit instructions

The ffmpeg piece is straightforward. Most of the production work was handling people who send 200 MB screen recordings and videos that are already H.264 but still fail because of an empty audio stream.

Built by me: @LiveAvaBot.

Edge Cases and Lessons

HEVC with Dolby Vision: some recent iPhones tag clips with Dolby Vision HDR metadata. libx264 doesn't support it and ffmpeg fails on the HDR pass. Adding -vf "zscale=transfer=709:primaries=709:matrix=709,format=yuv420p" before the scale step converts colorspace first. Rare, but worth knowing.

GIFs use more temp disk than you expect: a 3-second GIF can decode to 150 MB of raw frames before re-encoding. ffmpeg handles it, but disk usage spikes. Keep temp dirs on SSD if running this at any scale.

4K input is slow: the scale step on 4K source takes 10-15 seconds. Most avatar clips are phone-format anyway, so I haven't optimized for it. The bot accepts them but warns about conversion time.

CRF 28 isn't always enough: for dense 10-second 1080p clips, CRF 28 occasionally produces a file just over 2 MB. The bot checks size after conversion and replies with an error. Dropping to -t 8 or bumping to CRF 32 usually fixes it.

The main lesson: read the spec before debugging. Telegram's silent HEVC rejection is intentional on their end. ffmpeg is doing the heavy lifting here. I just wrote the wrapper.

Fixing iPhone HEVC Videos for Telegram Video Avatars

liveavabot — Sat, 12 Sep 2026 14:06:04 +0000

The Problem

I uploaded an iPhone video to Telegram as my profile video avatar. Telegram accepted the file, showed a spinner, then silently did nothing. No error. The avatar stayed unchanged.

Turns out Telegram video avatars have a strict spec, and iPhone video files violate almost every requirement. iPhone records in HEVC (H.265) by default. Telegram requires H.264. iPhone videos are often 16:9 or 9:16 portrait. Telegram requires 800x800 square. iPhone videos record audio. Telegram video avatars must have no audio track.

Telegram doesn't tell you any of this. It just quietly rejects the upload.

What Telegram Actually Requires

The video avatar spec (from Telegram's own client behavior, not official docs) is:

Codec: H.264 (libx264), yuv420p pixel format
Resolution: exactly 800x800 square
Duration: 10 seconds or less
File size: 2 MB or less
Audio: none (leaving an audio track in causes silent failures on some clients)

The audio requirement is the silent killer. Even if you re-encode to H.264 and resize to 800x800, leaving an audio track causes the upload to appear to succeed but never apply on older Telegram clients.

How ffmpeg Solves This

The pipeline I use:

Detect the actual content area (cropdetect removes letterboxing and pillarboxing)
Scale to 800x800, padding to keep aspect ratio
Re-encode as H.264, yuv420p
Strip all audio tracks
Move the moov atom to the start (faststart) so it streams properly

First pass: detect the crop rectangle.

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

Then the actual encode, substituting the crop value from the first pass:

ffmpeg -i input.mov \
  -vf "crop=w:h:x:y,scale=800:800:force_original_aspect_ratio=decrease,pad=800:800:(ow-iw)/2:(oh-ih)/2,setsar=1" \
  -c:v libx264 -pix_fmt yuv420p \
  -t 10 \
  -an \
  -movflags +faststart \
  -crf 28 \
  output.mp4

-an removes audio. -t 10 enforces the duration cap. -crf 28 keeps the file under 2 MB for typical clips. faststart moves metadata to the front.

For very long input videos or high-resolution sources, CRF 28 sometimes isn't enough to hit 2 MB. In that case I drop to CRF 32 and retry.

The aiogram 3 Handler

The bot is built with aiogram 3. The handler receives a video or animation (GIF) message, downloads it, runs ffmpeg, and sends back the converted file.

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

router = Router()

async def run_ffmpeg(input_path: str, output_path: str) -> bool:
    crop_proc = await asyncio.create_subprocess_exec(
        "ffmpeg", "-i", input_path,
        "-vf", "cropdetect=24:16:0",
        "-frames:v", "1", "-f", "null", "-",
        stderr=asyncio.subprocess.PIPE,
    )
    _, stderr = await crop_proc.communicate()

    crop = "in_w:in_h:0:0"
    for line in stderr.decode().splitlines():
        if "crop=" in line:
            crop = line.split("crop=")[-1].split()[0]

    encode_proc = await asyncio.create_subprocess_exec(
        "ffmpeg", "-i", input_path,
        "-vf", f"crop={crop},scale=800:800:force_original_aspect_ratio=decrease,"
               "pad=800:800:(ow-iw)/2:(oh-ih)/2,setsar=1",
        "-c:v", "libx264", "-pix_fmt", "yuv420p",
        "-t", "10", "-an", "-movflags", "+faststart",
        "-crf", "28", "-y", output_path,
        stderr=asyncio.subprocess.PIPE,
    )
    await encode_proc.communicate()
    return encode_proc.returncode == 0

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

    with tempfile.TemporaryDirectory() as tmpdir:
        input_path = os.path.join(tmpdir, "input")
        output_path = os.path.join(tmpdir, "output.mp4")

        await message.bot.download(file, destination=input_path)
        ok = await run_ffmpeg(input_path, output_path)

        if ok and os.path.getsize(output_path) <= 2 * 1024 * 1024:
            await message.reply_video(
                FSInputFile(output_path),
                caption="Ready. Set as your Telegram video avatar."
            )
        else:
            await message.reply("Couldn't convert this one. Try a shorter clip.")

The handler works for videos, GIFs (Telegram sends those as animation), and raw document uploads. Document upload is useful when Telegram recompresses the video before sending it as a regular video message, which can change the container format.

Packaging It as @liveavabot

I deployed the bot to a VPS. The whole thing is under 300 lines of Python including the ffmpeg wrapper, error handling, and a /start message.

One thing I added after the first few users: a file size check before download. Telegram bots can receive files up to 20 MB via getFile. I reject anything over 50 MB early with a message to trim the clip first. This saves VPS disk on oversized uploads.

The bot handles concurrent requests fine because each ffmpeg invocation runs in its own temp directory. Async subprocess means the event loop isn't blocked while ffmpeg runs.

You can try it at https://t.me/LiveAvaBot?start=devto_article_20260912. Send any video or GIF and it returns an 800x800 H.264 file ready to upload as your Telegram video avatar.

Built by me, @liveavabot.

Edge Cases I Hit

HEVC 10-bit. Some newer iPhones record 10-bit HEVC for HDR. libx264 doesn't encode 10-bit yuv420p directly. I added -vf "format=yuv420p" before the scale step to force 8-bit conversion. Without this, ffmpeg errors on the encode with a cryptic pixel format mismatch.

GIFs with no audio track. The -an flag on a file that has no audio causes a warning but not an error. Safe to always include it unconditionally.

Very short clips under 1 second. Telegram sometimes won't set them as avatars. I added a minimum duration check and warn the user if the input is too short before running the full encode.

Portrait iPhone videos. A 9:16 portrait video gets padded to 1:1 before the 800x800 encode. The scale=800:800:force_original_aspect_ratio=decrease,pad=800:800:... handles this automatically. Users sometimes expect the full portrait frame to appear; I explain in the /start message that the bot pads rather than crops.

What's next: I want to add an optional crop mode where the user picks a square region from the source video. That's a UI problem more than a technical one, probably a callback keyboard with a preview thumbnail.

HeyGen + Telegram Avatar: Fixing the Format Gap with ffmpeg

liveavabot — Thu, 10 Sep 2026 12:12:03 +0000

I've been using HeyGen to create talking-head clips for product demos. The results look good. But when I tried to set one as my Telegram video avatar, Telegram showed a spinning indicator and quietly dropped the file. No error message.

Took me a while to figure out why.

What Telegram Actually Requires

Telegram's video avatar spec is stricter than most people expect. All four constraints have to be met simultaneously:

Codec: H.264 (libx264). HEVC/H.265 is silently rejected.
Resolution: exactly 800x800 pixels, square.
Duration: 10 seconds maximum.
Audio: must be absent. A muted track still fails.

HeyGen exports 16:9 or 9:16 video in H.264 or HEVC, with stereo audio, anywhere from 10 to 120 seconds long. That's a four-way mismatch.

The Mismatch, Spelled Out

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 aspect ratio is the tricky one. Cropping a talking head from 16:9 to 1:1 cuts off part of the frame. You want the largest possible square, centered, before scaling to 800x800.

The ffmpeg Pipeline

ffmpeg handles all four constraints in one pass:

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

What each part does:

-t 10: hard-cuts at 10 seconds before encoding.
crop=min(iw\,ih):min(iw\,ih): takes the largest centered square from whatever aspect ratio you feed in.
scale=800:800: resizes to the exact spec.
fps=30: normalizes frame rate. Some HeyGen exports come in at 24fps.
format=yuv420p: broad device compatibility. Some encoders default to yuv444p, which older iOS players reject.
-c:v libx264 -preset medium -b:v 900k: H.264 at 900kbps. A 10-second 800x800 clip comes out around 1.1MB, under the 2MB cap.
-an: strips all audio tracks.
-movflags +faststart: moves the moov atom to the front so Telegram can stream before the file fully downloads.

If your source has letterboxing baked in (black bars from HeyGen rendering), run a cropdetect pre-pass first:

# detect content bounds
ffmpeg -i heygen_output.mp4 -vf cropdetect=24:16:0 -t 5 -f null - 2>&1 | grep -oP "crop=\S+"

That outputs a crop string like crop=720:720:0:180. Feed that into the encode pass instead of the min(iw,ih) expression. Most HeyGen exports don't have letterboxing, but it matters when processing a batch of mixed sources.

An aiogram 3 Handler

If you want to accept HeyGen exports directly in Telegram and return an avatar-ready file, here's a minimal aiogram 3 handler:

import asyncio
import tempfile
import os
from aiogram import Router, F
from aiogram.types import Message, BufferedInputFile

router = Router()

async def run_ffmpeg(input_path: str, output_path: str) -> bool:
    cmd = [
        'ffmpeg', '-y', '-i', input_path, '-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',
        output_path
    ]
    proc = await asyncio.create_subprocess_exec(
        *cmd,
        stdout=asyncio.subprocess.DEVNULL,
        stderr=asyncio.subprocess.PIPE,
    )
    _, stderr = await proc.communicate()
    return proc.returncode == 0

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

    bot = message.bot
    tg_file = await bot.get_file(file.file_id)

    with tempfile.TemporaryDirectory() as tmpdir:
        input_path = os.path.join(tmpdir, 'input.mp4')
        output_path = os.path.join(tmpdir, 'avatar.mp4')

        await bot.download_file(tg_file.file_path, destination=input_path)

        ok = await run_ffmpeg(input_path, output_path)
        if not ok:
            await message.reply('ffmpeg failed on this file.')
            return

        with open(output_path, 'rb') as f:
            data = f.read()

        await message.reply_video(
            BufferedInputFile(data, filename='avatar.mp4'),
            caption='Set this as your Telegram video avatar in Profile settings.'
        )

asyncio.create_subprocess_exec keeps ffmpeg off the event loop. The handler accepts both F.video and F.document because Telegram sometimes stores video as document depending on how the user shares it. In production, add a file size check before download and a timeout around the ffmpeg call.

How I Packaged This

I wrapped this pipeline in a Telegram bot at https://t.me/LiveAvaBot?start=devto_article_20260910. Send it any video or GIF, it runs the ffmpeg pipeline server-side and returns an avatar-ready file. No app, no account.

The HeyGen use case came up because a few users mentioned they were trying to use AI avatar clips as Telegram profile videos. The same pipeline handles iPhone HEVC exports too, for the same codec reason: libx264 transcodes anything ffmpeg can decode.

The server runs on a Hetzner VPS. ffmpeg does the actual work. I just wrote the glue, the Telegram handler, and the queue.

Edge Cases Worth Knowing

HEVC source: Telegram rejects it silently. The pipeline transcodes to H.264 regardless of input codec, so HEVC HeyGen exports and iPhone videos both work.

File over 2MB after encoding: Usually happens with very high-bitrate source files. The 900kbps target keeps 800x800 10-second clips around 1.1MB. If you hit the cap, drop to 600kbps and retry.

Duration at exactly 10 seconds: Telegram's limit is inclusive. -t 10 in ffmpeg is fine. A 10.1-second clip fails.

Portrait 9:16 output: crop=min(iw,ih):min(iw,ih) handles both orientations. For portrait it crops top and bottom; for landscape it crops both sides.

Black bars in HeyGen export: Some HeyGen templates render with letterboxing. Use cropdetect as described above. Without it you end up with black bars inside the 800x800 frame.

Built by me: @liveavabot is a side project. Try it at https://t.me/LiveAvaBot?start=devto_article_20260910.

Converting iPhone HEVC Videos to Telegram Video Avatars With FFmpeg

liveavabot — Tue, 08 Sep 2026 09:04:52 +0000

The bug that took me a weekend

I recorded a 6-second clip on my iPhone, tried to set it as a Telegram video avatar, and got nothing. No error, no toast, no progress bar. Just the old avatar sitting there. I tried again. Same silence. I opened the file in QuickTime, it played fine. I checked the size, 1.4 MB, well under any limit I could imagine. So why did Telegram just swallow the request without a word?

Turns out iPhone records in HEVC (H.265) by default since iOS 11, and Telegram's video avatar endpoint only accepts H.264. The client uploads the file, the server rejects it silently, the UI shows nothing. If you have never dug into this, you assume your bot is broken or the network is flaky. It is neither. The codec is wrong.

What Telegram actually wants for a video avatar

The Bot API docs on this are thin, but the effective spec (confirmed by about forty test uploads) is:

Codec: H.264 (libx264), yuv420p pixel format
Container: MP4 with faststart
Resolution: 800x800, square, exact
Duration: 1 to 10 seconds
Frame rate: 25 to 30 fps is safest
Audio: must be absent (not just muted, absent)
File size: under about 2 MB in practice

Miss any one of these and the avatar update just fails quietly. No error is returned from the API in most client paths.

The ffmpeg pipeline that actually works

The tricky part is not the codec swap, that is one flag. The tricky part is the crop. Most iPhone clips are portrait (1080x1920) or landscape (1920x1080), and a naive scale=800:800 squashes them into a distorted square. What you want is: detect the interesting region, center-crop to a square, then scale.

I run cropdetect on a probe pass, then apply the crop and scale in a single encode pass.

# probe pass, 2 seconds of input is enough
ffmpeg -ss 0 -t 2 -i input.mov -vf cropdetect=24:16:0 -f null - 2>&1 \
  | grep -oE 'crop=[0-9:]+' | tail -1
# yields something like: crop=1080:1080:0:420

# encode pass
ffmpeg -y -i input.mov \
  -vf "crop=1080:1080:0:420,scale=800:800,format=yuv420p" \
  -c:v libx264 -profile:v baseline -level 3.1 \
  -preset veryfast -crf 26 \
  -movflags +faststart \
  -an \
  -t 10 \
  output.mp4

Notes on the flags:

format=yuv420p inside the filter chain forces the pixel format before encode. Some libx264 builds pick yuv444p from HEVC sources and Telegram rejects that.
-an strips audio. If you leave -c:a copy by mistake you get an AAC track and Telegram rejects the whole file.
+faststart moves the moov atom to the front so the file streams. Without it Telegram sometimes times out on the fetch.
-t 10 hard-caps duration. A 15-second input becomes the first 10 seconds.
-preset veryfast -crf 26 gives me files under 2 MB for almost all 10-second clips.

The aiogram 3 handler

I use aiogram 3 with the router pattern. The handler accepts video, video_note, animation (GIF), and document (for people who forward as file). It downloads to a temp file, runs the pipeline in a subprocess, uploads the result.

from aiogram import Router, F
from aiogram.types import Message, FSInputFile
from aiogram.enums import ContentType
import asyncio, os, uuid

router = Router()

MEDIA = F.content_type.in_({
    ContentType.VIDEO,
    ContentType.VIDEO_NOTE,
    ContentType.ANIMATION,
    ContentType.DOCUMENT,
})

@router.message(MEDIA)
async def on_media(msg: Message):
    file = msg.video or msg.video_note or msg.animation or msg.document
    if not file:
        return
    src = f"/tmp/{uuid.uuid4()}_in"
    dst = f"/tmp/{uuid.uuid4()}_out.mp4"
    await msg.bot.download(file, destination=src)

    proc = await asyncio.create_subprocess_exec(
        "ffmpeg", "-y", "-i", src,
        "-vf", "scale=800:800:force_original_aspect_ratio=increase,crop=800:800,format=yuv420p",
        "-c:v", "libx264", "-profile:v", "baseline", "-level", "3.1",
        "-preset", "veryfast", "-crf", "26",
        "-movflags", "+faststart",
        "-an", "-t", "10",
        dst,
        stdout=asyncio.subprocess.DEVNULL,
        stderr=asyncio.subprocess.PIPE,
    )
    await proc.communicate()
    if proc.returncode != 0:
        await msg.answer("ffmpeg failed, try a shorter clip")
        return

    if os.path.getsize(dst) > 2 * 1024 * 1024:
        await msg.answer("output too big, try a shorter clip")
        return

    await msg.answer_video(FSInputFile(dst), caption="use this as your profile video")
    os.remove(src); os.remove(dst)

I skipped cropdetect in this inline snippet and leaned on ffmpeg's built-in scale-and-crop combo (force_original_aspect_ratio=increase then center-crop). It works for about 90% of clips. The full bot uses the two-pass cropdetect version for anything with letterboxing.

How this became @liveavabot

I wrapped the pipeline as a public Telegram bot: @LiveAvaBot. Send it any video or GIF, get back a file you can set as your Telegram video avatar. No signup, no watermark. Users so far: 382. Runs on a small Hetzner box with ffmpeg 6.1 and Python 3.11.

Bot state (rate limits, per-user cooldowns, error logs) lives in SQLite. I did not reach for Redis at this scale. If traffic ever gets serious I will swap it out, but 382 users generate about 10 conversions a day, well within what a single asyncio worker handles.

Edge cases and what is next

Things that broke along the way:

10-bit HEVC from iPhone Pro cameras: libx264 handles it if you have a recent ffmpeg. Older builds throw Unsupported pixel format. Force format=yuv420p in the filter chain.
Portrait videos with subtitles baked in at the bottom: cropdetect includes them, the resulting square looks off. I added a heuristic to prefer top-anchored crops for portrait input.
Live Photos exported as .mov: they include a still image track that ffmpeg treats as a second video stream. -map 0:v:0 fixes it.
GIFs with transparent backgrounds: I flatten to black. Telegram avatars have no alpha channel.

Next up: batch mode (drop five clips, get the best one back based on a simple sharpness score) and a mini WebApp preview so users can pick their favorite crop before it lands on their profile.

Built by me, @LiveAvaBot. If you hit an edge case, DM me, I read every message.

Converting iPhone HEVC Videos to Telegram Video Avatars With FFmpeg

liveavabot — Wed, 19 Aug 2026 12:03:05 +0000

The problem nobody explains

I recorded a short clip on my iPhone, opened Telegram, tapped my avatar, picked "Set video". Nothing happened. No error. No toast. The old avatar stayed. I tried again with a screen recording. Same silence.

Turns out Telegram has a very narrow spec for video avatars, and the iPhone camera app violates almost every part of it by default. iPhone shoots HEVC (H.265) in .mov. Telegram wants H.264 in .mp4. iPhone shoots portrait 1080x1920. Telegram wants 800x800 square. iPhone records with audio. Telegram wants no audio track at all. And there's a 2 MB hard cap on the file.

If any of these fail, Telegram just refuses without telling you why. I lost an hour before I read the raw Bot API docs and found the requirements buried in the setUserProfilePhoto notes.

I built a bot to fix this once and never think about it again. This post walks through what the spec actually is, how ffmpeg solves it, and the minimal aiogram 3 handler that ties it together.

The Telegram video avatar spec

Straight from testing and the Bot API source:

Container: mp4 with faststart (moov atom at the front)
Video codec: H.264, profile Main or Baseline, pixel format yuv420p
Resolution: exactly 800x800, square
Duration: 3 to 10 seconds
File size: 2 MB or less
Audio: no audio stream. Not muted. Removed.
Frame rate: 30 fps works, 60 is risky at this size cap

The two silent killers are HEVC and audio. If your file has an audio track, even a silent one, Telegram rejects the upload without any status message.

The ffmpeg pipeline

Two passes. First a cropdetect to figure out what's actually inside the frame (portrait iPhone videos leave huge black bars if you center-crop naively). Then the real encode.

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

That prints something like crop=1080:1080:0:420. Feed it back into the real command:

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

Key flags:

-t 10 clips duration to 10s.
crop,scale in the same filter chain: crop to square first, scale to 800.
format=yuv420p forces the pixel format Telegram wants.
-an strips audio.
-movflags +faststart puts the moov atom up front so Telegram can start reading before the download completes.
-crf 26 is the sweet spot for staying under 2 MB on a 10s clip. If the input is a busy scene, drop to 28.

I also run ffprobe after encoding to double-check the file is actually under 2 MB. If it's over, I re-encode with -crf 30 and warn the user that quality took a hit.

Minimal aiogram 3 handler

The bot accepts video, document (with video mime), or animation (mp4 GIF). Here's the routing:

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.animation | F.document)
async def handle_media(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 over 20 MB, please trim first.")
        return

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

        ok = await convert_to_avatar(src, dst)
        if not ok:
            await msg.reply("Conversion failed. Try a shorter or simpler clip.")
            return

        await msg.reply_video(
            video=FSInputFile(dst),
            caption="Ready. In Telegram, tap your avatar then Set Video.",
        )

async def convert_to_avatar(src: Path, dst: Path) -> bool:
    crop = await detect_crop(src)
    vf = f"{crop},scale=800:800:flags=lanczos,format=yuv420p,setsar=1"
    proc = await asyncio.create_subprocess_exec(
        "ffmpeg", "-y", "-i", str(src),
        "-t", "10",
        "-vf", vf,
        "-c:v", "libx264", "-profile:v", "main", "-level", "4.0",
        "-preset", "slow", "-crf", "26",
        "-movflags", "+faststart",
        "-an",
        str(dst),
        stdout=asyncio.subprocess.DEVNULL,
        stderr=asyncio.subprocess.DEVNULL,
    )
    await proc.wait()
    return (
        proc.returncode == 0
        and dst.exists()
        and dst.stat().st_size < 2 * 1024 * 1024
    )

detect_crop runs the cropdetect pass and returns the last crop= value. If none is found (already square input), it falls back to crop=in_h:in_h:(in_w-in_h)/2:0.

How I packaged this as @liveavabot

I put the whole pipeline behind a Telegram bot so people don't have to install ffmpeg or figure out flags. Send a video or GIF, get back a file ready to set as your avatar. Handles iPhone HEVC, portrait clips, over-long clips, oversized files. Link: https://t.me/LiveAvaBot?start=devto_article_20260819.

The bot runs in Python with aiogram 3 on a small VPS, using ffmpeg 6 from the system package. No queue for now, just async subprocess with a semaphore capping parallel encodes at 3 so a burst doesn't OOM the box.

Edge cases and lessons

A few things I got wrong the first time:

I forgot format=yuv420p at first. Some inputs (especially from cameras) come as yuv422p or yuv444p. H.264 Main profile at those pixel formats encodes fine but Telegram won't accept it.
-preset slow matters. -preset veryfast at the same CRF produces files roughly 30% larger, which pushes 10s clips over 2 MB.
Animation stickers exported as mp4 sometimes have zero-duration streams that break -t 10. I now clamp with a duration computed from ffprobe first.
If the input has a weird SAR (sample aspect ratio), the scale to 800x800 stretches. setsar=1 before scale fixes it.

Still on the todo list: 4K HDR clips need tone-mapping before H.264 encode or the colors look washed. I skip those for now and reply asking for a lower-res source.

That's the whole thing. ffmpeg is doing the heavy lifting, the bot is a thin wrapper that hides the flags. If you're building anything similar, the cropdetect + explicit pixel format + -an combo is the part I'd focus on first.

Built by me, @liveavabot.

Converting iPhone HEVC to Telegram Video Avatars with FFmpeg

liveavabot — Mon, 17 Aug 2026 11:04:33 +0000

The problem: Telegram silently rejects your iPhone videos

If you have tried uploading an iPhone video as your Telegram profile picture (the animated one), you know the deal. The upload goes through. The progress bar fills up. Then nothing. Your avatar stays as it was. No error, no toast, no explanation.

The video looked fine in your camera roll. It plays in Photos. It plays in QuickTime. But Telegram treats it like it does not exist.

The reason is HEVC. Since iOS 11, iPhones record video in HEVC (H.265) by default. Telegram's video avatar pipeline expects H.264. When the codec check fails, the server drops the file on the floor without telling the client.

I built @LiveAvaBot to fix this. Send it any video or GIF, get back a valid Telegram video avatar. This is a walkthrough of what the format actually requires and how ffmpeg gets you there.

What the Telegram video avatar spec actually requires

Telegram does not publish this as a single page, but from bot testing and API docs, here is what a video avatar has to be:

Container: MP4
Video codec: H.264 (avc1), yuv420p pixel format
Resolution: exactly 800x800, square
Duration: 10 seconds maximum
File size: 2 MB maximum
Audio: none, must be stripped
Faststart: moov atom at the front

Miss any of these and the upload either fails silently (codec, resolution) or gets rejected with a size error (over 2 MB). The 2 MB cap is the tightest constraint. At 800x800 H.264 you have roughly 200 KB per second to work with for 10 seconds of video.

Cropping to square without cutting off the subject

Most phone videos are 9:16 or 16:9. You cannot just resize to 800x800, that stretches faces into pancakes. You need a center crop to a square, then scale down.

FFmpeg has a cropdetect filter that can find content bounds, but for phone video the whole frame is usually the content. The pragmatic approach is a centered square crop based on the shorter side.

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

Breaking that down:

crop=min(iw,ih):min(iw,ih):... takes a centered square from the smallest dimension of the source.
scale=800:800 downsamples to Telegram's exact resolution.
format=yuv420p forces the pixel format Telegram expects. Without this you might end up with yuv420p10le on some HDR sources and the file will be rejected.
-c:v libx264 re-encodes to H.264 regardless of input codec, which handles the HEVC case.
-crf 28 targets decent quality that fits in 2 MB for most 10 second clips. Bump to 30 if you overshoot, drop to 24 if you have headroom.
-movflags +faststart puts the moov atom at the start so Telegram can begin decoding without a full download.
-an strips audio.
-t 10 caps duration.

If you still bust the 2 MB budget, the next lever is a bitrate cap with -b:v 1500k -maxrate 1500k -bufsize 3000k and a second pass. For 90% of iPhone clips the crf 28 single pass is enough.

The aiogram 3 handler

I built the bot on aiogram 3. Here is the trimmed video handler.

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

router = Router()

FFMPEG_TEMPLATE = [
    "ffmpeg", "-y", "-i", "{input}",
    "-vf",
    "crop='min(iw,ih)':'min(iw,ih)':(iw-min(iw,ih))/2:(ih-min(iw,ih))/2,"
    "scale=800:800,format=yuv420p",
    "-c:v", "libx264", "-profile:v", "high", "-level", "4.0",
    "-preset", "veryfast", "-crf", "28",
    "-movflags", "+faststart",
    "-an", "-t", "10",
    "{output}",
]

@router.message(F.video | F.animation | F.document)
async def convert(msg: Message):
    file = msg.video or msg.animation or msg.document
    if not file:
        return
    with tempfile.TemporaryDirectory() as tmp:
        src = Path(tmp) / "in.bin"
        dst = Path(tmp) / "out.mp4"
        await msg.bot.download(file, destination=src)
        cmd = [c.format(input=str(src), output=str(dst)) for c in FFMPEG_TEMPLATE]
        proc = await asyncio.create_subprocess_exec(
            *cmd,
            stdout=asyncio.subprocess.DEVNULL,
            stderr=asyncio.subprocess.PIPE,
        )
        _, err = await proc.communicate()
        if proc.returncode != 0:
            await msg.reply(f"ffmpeg failed: {err.decode()[:400]}")
            return
        size_mb = dst.stat().st_size / 1024 / 1024
        if size_mb > 2:
            await msg.reply(f"Output is {size_mb:.1f} MB, over the 2 MB cap. Try a shorter clip.")
            return
        await msg.reply_video(FSInputFile(dst), caption="Upload this as your profile video.")

A few things worth noting:

I accept document too because iOS sometimes sends MOV files as documents when the size is above a threshold.
The reply is reply_video, not reply_document. Telegram will show the correct preview and the user can forward it straight to their profile settings.
The 2 MB check is a client side courtesy. Telegram will reject bigger files, but the error the user sees is cleaner if I catch it first.

Packaging it as @liveavabot

The full bot lives at https://t.me/LiveAvaBot?start=devto_article_20260817. It runs on a small VPS, uses aiogram 3, and stores nothing except a per user conversion counter for rate limiting. The ffmpeg call is the same as above, plus a queue so a burst of uploads does not spawn 20 parallel encodes on a 2 vCPU box.

Things I punted on for v1:

4K HDR sources with wide color gamut. Right now they get tone mapped to SDR with mixed results.
Vertical crop mode. Center square works for most clips but a face detector would beat it for portrait video.
GIF audio. GIFs do not have audio, so -an is a no op, but Telegram animation files can carry audio. It gets stripped anyway.

Lessons

The main takeaway from shipping this: ffmpeg is doing 95% of the work, I just wrote a wrapper. The tricky part was not the encoding, it was figuring out the exact spec Telegram wants. There is no error message when you get it wrong. The upload succeeds, the avatar does not change, and you go debug for an hour.

If you are building anything that produces media for Telegram, test with getUserProfilePhotos after the upload. If the new avatar is not there, your file was silently dropped, and you have a spec bug somewhere.

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