Forem: liveavabot

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

Telegram Stars: zero-friction micro-monetization for bots

liveavabot — Fri, 01 May 2026 18:01:42 +0000

When I added Stars support to @liveavabot, I expected the usual friction — card forms, KYC prompts, payment failures. What I got instead was a payment flow that feels like clicking a reaction.

What the flow looks like for users

User taps "Buy Pack 20"
Telegram shows native payment sheet (Google Pay, Apple Pay, or Stars wallet)
One confirmation tap
Credits appear in bot

No card form. No redirect to external site. No KYC for small amounts. Total time: under 30 seconds.

Why this matters for utility bots

Utility bots have low average order value and high price sensitivity. Any extra step in the checkout kills conversion. Stars removes friction at exactly the point where users drop off.

For Hindi-speaking users in India, the Google Pay integration is natural.

NATIVE Partnership on top

Telegram NATIVE Partnership pays 20% of referred Stars spend for 6 months. For a utility bot with steady daily use, this compounds.

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

Converting iPhone HEVC Videos to Telegram Avatars With ffmpeg

liveavabot — Wed, 29 Apr 2026 17:09:46 +0000

The Problem Nobody Warns You About

You open Telegram, try to set a video avatar, upload a clip from your iPhone, and nothing happens. No error. The upload completes, Telegram just silently ignores it. If you're lucky, you get a generic "wrong format" toast. Usually you get nothing.

The issue is HEVC (H.265). Every iPhone since 2017 records in HEVC by default. Telegram's video avatar feature requires H.264, yuv420p pixel format, 800x800 resolution, under 10 seconds, under 2MB, and no audio track. HEVC satisfies zero of those constraints. Telegram doesn't tell you any of this.

I ran into this personally, got annoyed, and built a bot to fix it.

What Telegram Actually Requires

The spec (pulled from the Bot API docs and empirical testing) is specific:

Codec: H.264 baseline or main profile
Pixel format: yuv420p (4:2:0 chroma subsampling)
Resolution: exactly 800x800
Duration: 10 seconds max (Telegram crops longer clips client-side, but better to cut at encode)
File size: 2MB max
Audio: must be absent (not muted, actually absent from the container)
Container: MP4 with moov atom at front (faststart)

The 800x800 requirement is strict. 799x800 fails. The audio requirement catches a lot of people who convert the video but forget -an.

The ffmpeg Pipeline

Naive scaling to 800x800 squishes the video. Most source clips are 9:16 (portrait) or 16:9 (landscape), neither of which is square. The right approach is to scale up so the shorter dimension reaches 800, then center-crop to exactly 800x800.

ffmpeg -i input.mov \
  -vf "scale=800:800:force_original_aspect_ratio=increase,crop=800:800" \
  -c:v libx264 \
  -profile:v baseline \
  -level:v 3.0 \
  -pix_fmt yuv420p \
  -t 9 \
  -an \
  -crf 26 \
  -movflags +faststart \
  -y output.mp4

force_original_aspect_ratio=increase scales the video up so the shorter dimension reaches 800. Then crop=800:800 takes the center 800x800 square. No padding, no letterboxing.

-profile:v baseline -level:v 3.0 ensures compatibility. Some older Android devices choke on High profile H.264 even when the codec is technically correct.

-pix_fmt yuv420p is non-negotiable. ffmpeg defaults to yuv420p for most inputs, but HEVC files sometimes carry yuv422p or yuv444p. The default passthrough will preserve that and break the Telegram requirement silently.

-t 9 rather than 10 gives a safety margin for container overhead. Testing showed that a 10.0s source sometimes produces a 10.03s output due to frame rounding at certain framerates.

-crf 26 is a reasonable quality/size tradeoff for 800x800 at under 2MB. For longer clips near the 9s limit, you may need -crf 30 to stay under the size cap. I added an automatic retry at lower quality if the first pass exceeds 2MB.

-movflags +faststart moves the moov atom to the front of the file. Without this, Telegram's server-side validation sometimes rejects the upload even when the codec is correct. This one bit me for two hours.

The aiogram 3 Handler

I used aiogram 3. The handler accepts videos, documents (some clients send MP4 as documents rather than videos), and animations (Telegram GIFs, which are actually MP4 under the hood):

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

router = Router()

@router.message(F.video | F.document | F.animation)
async def handle_video(message: Message, bot: Bot):
    obj = message.video or message.document or message.animation
    file = await bot.get_file(obj.file_id)
    if file.file_size > 20 * 1024 * 1024:
        await message.reply("File too large (20MB Telegram API limit).")
        return

    with tempfile.TemporaryDirectory() as tmp:
        src = os.path.join(tmp, "input")
        dst = os.path.join(tmp, "output.mp4")
        await bot.download_file(file.file_path, destination=src)

        proc = await asyncio.create_subprocess_exec(
            "ffmpeg", "-i", src,
            "-vf", "scale=800:800:force_original_aspect_ratio=increase,crop=800:800",
            "-c:v", "libx264", "-profile:v", "baseline", "-level:v", "3.0",
            "-pix_fmt", "yuv420p", "-t", "9", "-an", "-crf", "26",
            "-movflags", "+faststart", "-y", dst,
            stdout=asyncio.subprocess.DEVNULL,
            stderr=asyncio.subprocess.PIPE,
        )
        _, stderr = await proc.communicate()

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

        if os.path.getsize(dst) > 2 * 1024 * 1024:
            await message.reply("Output over 2MB. Try a shorter clip.")
            return

        await message.reply_video_note(
            video_note=FSInputFile(dst),
            duration=9,
            length=800,
        )

reply_video_note is the correct method for video avatars (what Telegram calls "video notes" or round videos). reply_video sends a regular video, not the round format.

One gotcha: the length parameter in reply_video_note expects the pixel dimension of the square, not a duration. It's confusingly named.

Packaging It as a Bot

The bot is live at https://t.me/LiveAvaBot?start=devto_article_20260429. You send it any video, GIF, or short clip, it converts and replies with a round video note ready to set as your avatar.

The stack is minimal: Python 3.12, aiogram 3.x, ffmpeg installed via apt, systemd for process supervision. No database for the core conversion flow (stateless request/response). I added SQLite later for usage tracking and per-user rate limiting, but the happy path has zero persistence requirements.

Deployment is a single VPS at about $5/month. The bot runs under systemd with Restart=on-failure. Total setup took an afternoon once the ffmpeg flags were sorted.

Edge Cases and What I Learned

GIFs are already videos. Telegram re-encodes GIFs as MP4 on upload. When a user sends a GIF, you receive an Animation object with a video file, not a GIF89a. The conversion pipeline handles them fine, but you need to check message.animation explicitly.

HEVC from iPhones comes in .mov containers. ffmpeg handles this, but some inputs have metadata tracks, data tracks, and other non-video streams. Adding -map 0:v:0 selects only the first video stream and avoids muxing junk into the output.

2MB is tight for 9 seconds at 800x800. Average bitrate works out to about 1.8 Mbps. Fine for talking-head footage or simple animations. Screen recordings with lots of fine text detail hit the limit reliably. The automatic CRF retry helps, but adds a couple seconds of latency.

The Bot API download limit is 20MB. Files over 20MB require running the local Bot API server. I haven't set that up yet. Large files get a clear error message rather than a silent failure, which I consider the minimum acceptable behavior.

Currently 22 users have tried the bot, with 5 active in the last 24 hours. The conversion success rate is high. Every rejection now has an explanation attached.

Built by me, @liveavabot.

Why iPhone Videos Silently Fail as Telegram Video Avatars

liveavabot — Mon, 27 Apr 2026 16:06:07 +0000

The Silent Failure Nobody Explains

I was setting up a Telegram video avatar and uploaded a recent iPhone clip. No error, no feedback, just the upload spinner disappeared and my profile photo stayed the same. Tried again. Same result.

It took about an hour to figure out. iPhone records HEVC (H.265) by default. Telegram's video avatar API silently rejects it. No error message, nothing.

What Telegram Actually Requires

The spec for video avatars is specific:

Codec: H.264 (not HEVC/H.265, not VP9, not AV1)
Resolution: 800x800 pixels, square
Duration: 10 seconds maximum
File size: 2 MB maximum
Audio: must be stripped
Pixel format: yuv420p

Most modern iPhone videos are HEVC at 1080x1920 or 4K. All of those properties need fixing before Telegram accepts the file.

How ffmpeg Handles It

The tricky part isn't the encode, it's the crop. A 9:16 portrait video fed directly into scale=800:800 produces a squished result. You need cropdetect first.

# Detect crop bounds from the first 5 seconds
crop=$(ffmpeg -i input.mov -vf cropdetect=24:16:0 -t 5 -f null - 2>&1 \
  | grep -oP 'crop=\d+:\d+:\d+:\d+' | tail -1)

# Encode: crop, square scale, H.264, no audio
ffmpeg -i input.mov \
  -vf "${crop},scale=800:800:force_original_aspect_ratio=decrease,pad=800:800:(ow-iw)/2:(oh-ih)/2" \
  -c:v libx264 -profile:v baseline -level 3.0 \
  -pix_fmt yuv420p \
  -b:v 1500k \
  -t 10 \
  -an \
  -movflags +faststart \
  output.mp4

-an strips audio entirely. -movflags +faststart moves the moov atom to the front so Telegram can start reading before the full download finishes. Targeting 1500k bitrate keeps a 10-second clip under 2 MB (1500 * 10 / 8 = 1875 KB).

force_original_aspect_ratio=decrease plus pad scales the source down to fit inside 800x800, then pads with black. Letterboxing, but Telegram accepts it without complaints.

GIFs go through the same pipeline. The palette-to-yuv420p conversion happens automatically with libx264. No special flags needed.

The aiogram 3 Handler

I built the bot with aiogram 3. The handler downloads the file, runs ffmpeg as a subprocess, checks output size, and returns the result.

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

router = Router()

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

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

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

        # detect crop
        probe = await asyncio.create_subprocess_exec(
            "ffmpeg", "-i", src, "-vf", "cropdetect=24:16:0",
            "-t", "5", "-f", "null", "-",
            stderr=asyncio.subprocess.PIPE
        )
        _, stderr_bytes = await probe.communicate()
        matches = re.findall(r"crop=\d+:\d+:\d+:\d+", stderr_bytes.decode())
        crop = matches[-1] if matches else ""

        vf = (
            f"{crop},scale=800:800:force_original_aspect_ratio=decrease,"
            "pad=800:800:(ow-iw)/2:(oh-ih)/2"
        ) if crop else "scale=800:800"

        proc = await asyncio.create_subprocess_exec(
            "ffmpeg", "-i", src, "-vf", vf,
            "-c:v", "libx264", "-profile:v", "baseline",
            "-pix_fmt", "yuv420p", "-t", "10", "-an",
            "-movflags", "+faststart", "-b:v", "1500k",
            dst, stderr=asyncio.subprocess.PIPE
        )
        await proc.communicate()

        size = os.path.getsize(dst) if os.path.exists(dst) else 0
        if size == 0 or size > 2_000_000:
            await status.edit_text("Conversion failed or output over 2 MB.")
            return

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

    await status.edit_text("Done. Set this as your video avatar in profile settings.")
    await message.answer_video(BufferedInputFile(data, filename="avatar.mp4"))

ffmpeg runs via asyncio.create_subprocess_exec so it doesn't block the event loop. The size check after encoding is important: a dense 10-second clip can still exceed 2 MB at 1500k. Better to tell the user than upload a file Telegram will silently reject.

Packaging It as @liveavabot

After building this for my own use, I turned it into a public bot. You send a video, GIF, or document to https://t.me/LiveAvaBot?start=devto_article_20260427 and it replies with a ready-to-use 800x800 H.264 MP4, no settings required.

It runs on a Hetzner VPS, Python 3.12, aiogram 3.x, system ffmpeg. Infrastructure cost is around 5 EUR/month. It handles iPhone HEVC clips, Android VP9 exports, GIFs from Giphy, and screen recordings without any manual flags from the user.

Edge Cases

A few things came up during testing:

Large GIFs time out on slow connections. I added a pre-download file size check and reject anything over 50 MB with a message.

Some sources produce no cropdetect output (already square content, or solid borders ffmpeg misses). The fallback is plain scale=800:800, which works for square video but distorts widescreen. I'm considering making letterbox-pad the default regardless of cropdetect.

The -t 10 cut happens at encode time, not download time. A 3-minute video gets fully downloaded before ffmpeg trims it. Fixing that means probing duration first and deciding whether to reject early.

4K sources look rough at 1500k on motion-heavy clips. No clean fix yet short of bumping bitrate and hoping the clip is short enough to stay under 2 MB.

Built by me, @liveavabot.

How I Built a Bot to Fix Telegram's Silent Video Avatar Failures

liveavabot — Sat, 25 Apr 2026 15:09:28 +0000

I wanted to set a video avatar on Telegram. Recorded a short clip on my iPhone, uploaded it, and nothing happened. No error message. No warning. Telegram just silently ignored my video.

Took me way too long to figure out why. iPhones record in HEVC (H.265) by default. Telegram video avatars only accept H.264. But instead of telling you that, Telegram accepts the upload, returns a success response, and then quietly does nothing with your file.

I built @LiveAvaBot to fix this. Send it any video or GIF, get back a file ready to use as your Telegram video avatar. Here's how the conversion pipeline works.

What Telegram Actually Requires

The documentation for video avatars is thin. After testing and reading Telegram client source code, here's the actual spec:

Codec: H.264 (libx264), High profile
Resolution: 800x800 pixels, must be square
Duration: 10 seconds max
File size: 2 MB max
Audio: none, must be stripped entirely
Pixel format: yuv420p
Container: MP4 with faststart flag

The tricky part: Telegram's API returns success even when the video doesn't meet these requirements. Your client shows a spinner, maybe a checkmark, and then the avatar just doesn't update. No error callback, no webhook failure. Nothing in the logs.

The FFmpeg Pipeline

The conversion needs to handle several things at once: crop to square, scale down, re-encode to H.264, strip audio, and keep the file under 2 MB.

Here's the production command:

ffmpeg -y -v error \
  -i input.mp4 \
  -t 9 \
  -vf "crop='min(iw,ih)':'min(iw,ih)',scale=800:800: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

Breaking this down piece by piece.

crop='min(iw,ih)':'min(iw,ih)' takes a square crop from the center of the frame. Works for both landscape and portrait inputs without separate logic per aspect ratio.

scale=800:800:flags=lanczos resizes to the target resolution with Lanczos resampling. Noticeably sharper than bilinear at this size.

-t 9 caps duration at 9 seconds, not 10. One second of safety margin because some containers report duration slightly longer than the actual stream content.

-an strips all audio tracks. This is critical. Even a silent audio track can cause Telegram to reject the file without any error message.

-maxrate 1400k -bufsize 2800k is the VBV (Video Buffering Verifier) constraint. At 9 seconds and 1400 kbps peak, the math works out to well under 2 MB. The bufsize at 2x maxrate gives ffmpeg room to allocate bits to complex frames without overshooting the limit.

-movflags +faststart moves the MP4 moov atom to the beginning of the file. Lets Telegram start processing before the full download completes.

Handling It in Aiogram 3

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

from aiogram import Router, F, types, Bot
from pathlib import Path
import asyncio

router = Router()

@router.message(F.video | F.animation | F.document)
async def handle_video(message: types.Message, bot: Bot):
    if message.video:
        file_id = message.video.file_id
    elif message.animation:
        file_id = message.animation.file_id
    elif message.document and message.document.mime_type \
         and message.document.mime_type.startswith("video"):
        file_id = message.document.file_id
    else:
        return

    file = await bot.get_file(file_id)
    src = Path(f"/tmp/{file_id}.mp4")
    dst = Path(f"/tmp/{file_id}_avatar.mp4")

    await bot.download_file(file.file_path, src)

    proc = await asyncio.create_subprocess_exec(
        "ffmpeg", "-y", "-v", "error",
        "-i", str(src), "-t", "9",
        "-vf", "crop='min(iw,ih)':'min(iw,ih)',"
               "scale=800:800: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",
        str(dst),
        stderr=asyncio.subprocess.PIPE,
    )
    await proc.wait()

    if proc.returncode == 0 and dst.exists():
        await message.reply_document(
            types.FSInputFile(dst),
            caption="Your video avatar is ready. "
                    "Download it, then set it in Telegram settings.",
        )
    else:
        await message.reply("Conversion failed. Try a shorter clip.")

I accept F.video | F.animation | F.document because users send files in all three ways. GIFs come through as animation. Some clients send videos as document when the file extension is unusual. Covering all three catches most inputs.

The conversion runs as a subprocess with asyncio.create_subprocess_exec. This keeps the event loop free while ffmpeg does the heavy lifting. Median conversion time is around 11 seconds on a cheap VPS.

Edge Cases I Hit Along the Way

HEVC detection matters before you even start. If someone sends a .mov from an iPhone, ffmpeg handles the transcode fine on most systems. But some builds of ffmpeg don't include the HEVC decoder. I added a pre-check with ffprobe -v error -select_streams v:0 -show_entries stream=codec_name to identify the codec before running the main pipeline. If you don't have HEVC support, you can at least return a useful error instead of a garbled output.

GIFs need normalization. Telegram "GIFs" are actually MP4s with no audio. But real GIF files from other sources can have variable frame rates that confuse the encoder. The fps=30 filter in the chain normalizes this.

CRF alone doesn't guarantee file size. CRF 23 usually produces files under 2 MB at 800x800 for 9 seconds. But high-motion clips (confetti, water, fast camera panning) can exceed it. That's why the maxrate/bufsize pair exists as a hard ceiling. The tradeoff is slightly lower quality on those specific frames, but the file stays within Telegram's spec.

Silent audio tracks are the sneakiest failure. Some screen recordings include a silent audio stream by default. The file plays fine everywhere, but Telegram rejects it as a video avatar with zero feedback. -an is not optional.

What I Shipped

The bot has 8 users right now. Small, but it works. Send it a video, get back an avatar-ready file.

If you're building something similar, the ffmpeg pipeline above is the core of it. The rest is plumbing: downloading files from Telegram's API, cleaning up temp files, handling timeouts.

Built by me. Try it: https://t.me/LiveAvaBot?start=devto_article_20260425

The source of most "broken" Telegram video avatars is just codec mismatch. Once you know the exact spec, ffmpeg does the rest.

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

liveavabot — Thu, 23 Apr 2026 14:03:42 +0000

The Problem Nobody Warns You About

I recorded a 5-second clip on my iPhone, went to set it as my Telegram profile video, and nothing happened. No error. No feedback. Telegram just silently rejected it.

Turns out, iPhones record in HEVC (H.265) by default since the iPhone 7. Telegram video avatars only accept H.264. There's no warning dialog. The upload looks like it works, then the avatar stays unchanged.

I kept running into this, figured other people did too, and built a Telegram bot that fixes it automatically.

What Telegram Actually Requires

Telegram's docs on video avatar specs are basically nonexistent. After testing dozens of files, here's what I found works:

Codec: H.264 (libx264). Not HEVC, not VP9, not AV1.
Resolution: Square. 640x640 is the sweet spot for file size.
Duration: Under 10 seconds, looped on the profile.
File size: Under 2 MB.
Audio: None. Telegram strips it anyway, but leaving it in wastes bytes.
Pixel format: yuv420p. Anything else (yuv444p, yuv422p) gets rejected.
Container: MP4 with the moov atom at the front (faststart).

Miss any single requirement and Telegram silently drops the file. That silent failure is the entire reason this bot exists.

The FFmpeg Pipeline

Here's the actual ffmpeg command the bot runs in production:

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 walk through the filter chain.

crop='min(iw,ih)':'min(iw,ih)' takes the shorter dimension and center-crops to a square. Handles portrait (1080x1920) and landscape (1920x1080) the same way. No hardcoded pixel values.

scale=640:640:flags=lanczos downscales with Lanczos resampling instead of the default bilinear. The quality difference is visible when you go from 1080p down to 640px, especially on text or sharp edges.

fps=30,format=yuv420p normalizes frame rate and chroma subsampling. Some screen recordings come in at 24fps or even variable frame rate, which confuses Telegram's player.

For rate control, CRF 23 alone isn't enough. Some high-motion clips (sports, fast panning) exceeded 2 MB at CRF 23. Adding -maxrate 1400k -bufsize 2800k caps bitrate on complex scenes without destroying quality on static ones. The VBV buffer at 2x maxrate gives ffmpeg room to allocate bits where they matter.

-movflags +faststart moves the MP4 moov atom to the beginning of the file. Without this, Telegram can't generate a thumbnail until the entire file downloads.

Wiring It Into Aiogram 3

The bot uses aiogram 3 with async subprocess calls to ffmpeg:

import asyncio
import os
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(msg: Message, bot):
    if msg.video:
        file_id = msg.video.file_id
    elif msg.animation:
        file_id = msg.animation.file_id
    else:
        file_id = msg.document.file_id

    file = await bot.get_file(file_id)
    input_path = f"/tmp/{file_id}.mp4"
    output_path = f"/tmp/{file_id}_avatar.mp4"
    await bot.download_file(file.file_path, input_path)

    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", input_path, "-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", output_path,
        stdout=asyncio.subprocess.PIPE,
        stderr=asyncio.subprocess.PIPE,
    )
    _, stderr = await proc.communicate()

    if proc.returncode != 0:
        await msg.reply("Conversion failed. Try a different file.")
        return

    await msg.reply_video(FSInputFile(output_path))
    os.unlink(input_path)
    os.unlink(output_path)

The important decision here: asyncio.create_subprocess_exec instead of subprocess.run. Aiogram runs on asyncio. A blocking ffmpeg call would freeze the entire bot for 5 to 15 seconds per conversion. The async subprocess lets other messages get processed while ffmpeg encodes.

The handler matches F.video | F.animation | F.document because Telegram represents incoming media in three different ways depending on how the user sends it. A video from the camera roll comes as video. A GIF forwarded from a chat comes as animation (actually an MP4, not a real GIF). A file dragged from the file picker comes as document.

Edge Cases That Bit Me

Portrait videos crop faces off. My first version used crop=640:640 with hardcoded dimensions. On a 1080x1920 phone recording, that grabbed a 640x640 chunk from the top-left corner. Switching to min(iw,ih) center-crop fixed it for any aspect ratio.

GIFs are secretly MP4s. Telegram converts GIFs to H.264 MP4 on upload and delivers them as message.animation. The bot needs to handle this type explicitly, or GIF-to-avatar conversions silently fail.

Variable frame rate from screen recordings. Android screen recordings sometimes use variable frame rate. FFmpeg handles this, but Telegram's player stutters on VFR files. Forcing fps=30 normalizes everything.

CRF 23 overflows on action clips. A 9-second skateboarding clip at CRF 23 came out to 2.4 MB. The maxrate/bufsize constraint solved this without needing a two-pass encode, which would double processing time.

Try It

Send any video, GIF, or screen recording to @LiveAvaBot in Telegram. It handles HEVC from iPhones, screen recordings from Android, GIFs from the web. Conversion takes about 5 seconds. You get back a properly formatted MP4 you can set directly as your profile video.

The production bot handles a few more things I didn't cover here (file size validation, duration detection, retry logic for Telegram API rate limits), but the ffmpeg pipeline above is the real one.

Built by me. Try @LiveAvaBot.

How I Built a Telegram Video Avatar Bot With Python and FFmpeg

liveavabot — Tue, 21 Apr 2026 13:05:20 +0000

I tried to set a video avatar on Telegram last month. Recorded a short clip on my iPhone, uploaded it, and nothing happened. No error message. No toast notification. Telegram just silently rejected it.

Turns out iPhone records in HEVC (H.265) by default since the iPhone 7. Telegram's video avatar system only accepts H.264. When you upload HEVC, the server validates it, fails, and tells you absolutely nothing.

I spent two hours thinking my internet connection was broken before I figured this out.

What Telegram Video Avatars Actually Require

The documentation is sparse, so I had to reverse-engineer the constraints by testing every variable independently:

Codec: H.264 only (libx264). HEVC, VP9, AV1 all rejected silently.
Resolution: Exactly 800x800 pixels, square.
Duration: 10 seconds max.
File size: 2 MB max.
Audio: None. Any audio track means rejection.
Pixel format: yuv420p.
Container: MP4 with the faststart flag set.

Miss any single one of these and Telegram drops the file without telling you why. The yuv420p requirement caught me off guard because I couldn't find it documented anywhere.

The FFmpeg Pipeline

Here's the command I landed on after a lot of trial and error:

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

Let me break it down piece by piece.

crop=min(iw\,ih):min(iw\,ih) takes a center-square crop from any aspect ratio. A 16:9 landscape video becomes 1:1 without stretching or distorting faces. This handles portrait phone recordings and widescreen clips equally well.

scale=800:800 hits Telegram's exact resolution requirement. Not 799, not 801. Exactly 800.

fps=30 normalizes variable frame rate sources. VFR game captures from OBS were breaking duration detection without this.

format=yuv420p forces the pixel format. Some sources use yuv444p or yuv422p, and Telegram rejects both.

-c:v libx264 -preset medium re-encodes everything to H.264. This is where HEVC from iPhones gets converted. The medium preset balances encoding speed and compression quality.

-b:v 900k -maxrate 1200k -bufsize 2M targets 900 kbps with a ceiling at 1200 kbps. This keeps most 10-second clips under the 2 MB cap. If the output still exceeds 2 MB (high-motion content, lots of fine detail), I retry at a lower bitrate until it fits.

-an strips all audio tracks completely.

-movflags +faststart moves the moov atom to the front of the file. Required for proper streaming playback.

The 900 kbps target is a sweet spot I found empirically. High enough for decent quality at 800x800, low enough that most clips fit under 2 MB on the first encode pass.

Wrapping It in an Aiogram 3 Handler

I wanted users to just send a video and get a result back. No commands, no menus. Here's the handler:

import asyncio, subprocess, 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
    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=subprocess.DEVNULL,
                stderr=subprocess.DEVNULL,
            )
            await proc.wait()

            await message.answer_video(FSInputFile(out))

A few things worth noting here.

The asyncio.Semaphore(4) caps concurrent ffmpeg processes. Without it, a burst of uploads would eat all CPU and memory on a small VPS. Each conversion takes 2 to 5 seconds depending on input length and codec.

tempfile.TemporaryDirectory() handles cleanup automatically. No orphaned files accumulating on disk after crashes.

I use .bin for the input file extension because Telegram doesn't always provide a useful filename. FFmpeg detects the container format from the file header, not the extension, so it doesn't matter.

The handler accepts three input types: F.video for direct video uploads, F.animation for GIFs, and F.document for files sent as documents (which happens when people forward large videos).

Shipping It as @liveavabot

I deployed this on a Hetzner VPS running Python 3.11 with aiogram 3. The typical flow is simple: someone records a 15-second iPhone clip, sends it to the bot, gets back a 10-second 800x800 H.264 MP4 with no audio. They long-press their profile picture in Telegram, select the video, done.

The bot handles a bunch of input formats transparently. iPhone HEVC recordings (the original problem), Samsung HEVC mode videos, OBS captures in VP9 or MKV, Telegram animated stickers in WebM, Instagram Reels that are already H.264 but have the wrong aspect ratio. Everything goes through the same pipeline: crop, scale, re-encode, strip audio.

Edge Cases That Bit Me

Variable frame rate

Game capture software like OBS sometimes produces VFR video. The fps=30 filter normalizes this, but I had a few cases where ffprobe metadata was corrupted and duration detection failed entirely. I added a fallback that skips the probe and just runs the conversion blind.

The 2 MB wall

Some inputs with dense visual content (confetti, particle effects, fast camera pans) exceed 2 MB even at 900 kbps for 10 seconds of footage. The retry logic drops the bitrate incrementally until the output fits. Most clips work on the first pass. Dense footage sometimes needs a second encode at 600 to 700 kbps.

Looping artifacts

Telegram plays video avatars on repeat. If the last frame looks very different from the first frame, you get a visible jump on every loop. I don't do anything smart about this yet (like cross-fading the boundary), but it's on the list.

Silent failures in production

The hardest bugs to track down were all silent rejections from Telegram's server. No error codes, no status messages. I had to test each constraint in isolation to build the spec I described above. The yuv420p pixel format requirement took the longest to discover.

What I Learned

FFmpeg is doing the heavy lifting here. I wrote the wrapper, the queue management, and the Telegram integration. The actual video processing is entirely ffmpeg with the right flags.

The biggest insight: Telegram's video avatar format is strict but undocumented. Once you know the exact spec (800x800, H.264, yuv420p, no audio, under 2 MB, faststart), the conversion is straightforward. The pain was discovering those constraints in the first place.

If you want to try it, send any video to @LiveAvaBot on Telegram.

Built by me. Feedback welcome.

How to make a Telegram video avatar that actually uploads

liveavabot — Sat, 18 Apr 2026 13:01:11 +0000

If you've ever tried to set a video as your Telegram profile picture and watched nothing happen, you're not alone. Telegram has a narrow, undocumented media spec.

The spec

Dimensions: exactly 800x800 pixels
Codec: H.264 only
Duration: at most 10.0 seconds
File size: at most 2 MB
Audio: no audio track
Pixel format: yuv420p
Container: MP4 with faststart

Any violation = silent rejection.

The iPhone problem

iPhone records in HEVC by default. HEVC is unusable as a Telegram avatar.

The ffmpeg command

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

Wrapping it in a bot

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

router = Router()

@router.message(F.video | F.animation | F.document)
async def handle_video(message: Message):
    file = message.video or message.animation or message.document
    with tempfile.TemporaryDirectory() as td:
        inp = Path(td) / "in.bin"
        out = Path(td) / "out.mp4"
        await message.bot.download(file, destination=inp)
        # ffmpeg subprocess here
        await message.answer_video(FSInputFile(out))

Try it

Skip writing ffmpeg yourself: https://t.me/LiveAvaBot?start=devto_article_20260418

[no template for devto_article]

liveavabot — Thu, 16 Apr 2026 06:38:19 +0000