DEV Community: liveavabot

HeyGen + Telegram Video Avatar: Fixing the Format Mismatch

liveavabot — Mon, 09 Nov 2026 09:05:17 +0000

Why HeyGen Output Fails as a Telegram Video Avatar

I've been using HeyGen to generate talking-head videos, and the exports look good. But when I tried to use one as a Telegram video avatar, it failed silently. No error message, the bot just did nothing.

After debugging, the problem is straightforward: HeyGen and Telegram have incompatible format requirements on four separate properties.

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

Telegram's mobile and desktop clients handle format errors differently. Mobile silently rejects the upload. Desktop shows a vague error. Neither tells you which parameter caused the failure.

What Telegram Actually Requires

The video avatar spec is stricter than the official docs suggest. The constraints:

MP4 container, H.264 video codec
Exactly 800x800 pixels (square)
Maximum 10 seconds
Maximum 2 MB file size
Audio stream must be absent entirely

The aspect ratio constraint is the main trap with HeyGen output. A 16:9 clip scaled to 800x800 without cropping first produces a horizontally-stretched face. The fix is to crop to a square first, then scale.

HEVC (H.265) is the other common failure mode. iPhones record in HEVC by default. HeyGen's higher-quality export presets also use HEVC. Telegram's avatar pipeline only accepts H.264, so HEVC files need a full transcode.

The ffmpeg Command

This handles the full conversion:

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

-t 10 trims to the first 10 seconds before any video processing. crop=min(iw,ih):min(iw,ih) takes the largest centered square from the input, which works correctly for both landscape and portrait HeyGen exports. scale=800:800 hits the target resolution. fps=30 normalizes the frame rate. format=yuv420p ensures H.264 compatibility across all players including older Android clients.

-c:v libx264 -preset medium -b:v 900k encodes H.264 at a bitrate that keeps a 10-second clip under 2 MB. At 900k, a 10s clip is about 1.1 MB. -an removes the audio stream entirely rather than just muting it. -movflags +faststart moves the MOOV atom to the front of the file for faster progressive playback in Telegram.

The backslashes before commas in -vf are shell escaping. In a Python subprocess call with a list argument, you pass crop=min(iw,ih):min(iw,ih) directly without them.

Handling This in a Telegram Bot

Here's the aiogram 3 handler pattern:

import asyncio
import tempfile
from pathlib import Path

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

dp = Dispatcher()

@dp.message(F.video | F.animation | F.document)
async def handle_video(message: Message, bot: Bot):
    media = message.video or message.animation or message.document
    file_id = media.file_id

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

        await bot.download(file_id, destination=in_path)

        cmd = [
            "ffmpeg", "-y", "-i", str(in_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",
            str(out_path),
        ]
        proc = await asyncio.create_subprocess_exec(
            *cmd,
            stdout=asyncio.subprocess.DEVNULL,
            stderr=asyncio.subprocess.PIPE,
        )
        await proc.communicate()

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

        if out_path.stat().st_size > 2 * 1024 * 1024:
            await message.reply("Output exceeds 2 MB. Try a shorter source.")
            return

        await message.reply_video(
            video=FSInputFile(out_path),
            caption="Ready. Set it as your Telegram video avatar.",
        )

F.video | F.animation | F.document catches all video types. HeyGen exports come through as video or document. iPhone HEVC recordings always arrive as document because Telegram doesn't recognize the codec client-side.

Using create_subprocess_exec with a list avoids shell injection and skips the backslash-escaping that the shell command requires.

How @liveavabot Packages This

I wrapped this pipeline into a Telegram bot: @LiveAvaBot.

Beyond the base ffmpeg command, real usage pushed me to add a few things.

A cropdetect pre-pass removes black bars before the square crop. Some HeyGen exports have letterboxing baked in. Without this step, crop=min(iw,ih) squares the letterboxed frame, not the actual video content.

A codec probe via ffprobe detects HEVC inputs and forces a full transcode. Without it, ffmpeg sometimes passes through a codec stream copy that Telegram rejects.

A retry loop drops the bitrate if the first encode exceeds 2 MB. At 900k, a typical 10s talking-head clip is around 1.1 MB. High-motion clips can push past 2 MB. The retry drops to 600k, which covers most cases.

The bot currently has 511 users, mostly uploading iPhone videos and HeyGen exports.

Edge Cases Worth Knowing

The crop=min(iw,ih):min(iw,ih) formula crops from the center. If the talking head is off-center in a 16:9 frame (common with HeyGen's default camera framing), the crop might cut part of the face. HeyGen's 1:1 export option sidesteps this if your plan includes it.

The 2 MB ceiling is easier to hit than it looks. A 900kbps H.264 stream at 30fps for 10 seconds is about 1.1 MB. That's comfortable for talking-head content but tight for screen recordings or high-motion clips. If you hit the ceiling, drop to 600k or 400k. At 800x800, the quality difference is small.

HeyGen's free tier adds a watermark at a fixed corner. Depending on the aspect ratio, the centered crop might cut it out or leave it in. I didn't add watermark detection since it's a plan decision for the user, not a format problem.

Built by me: @LiveAvaBot.

Why Telegram Silently Rejects iPhone Videos as Avatars

liveavabot — Tue, 03 Nov 2026 20:05:20 +0000

The Problem: Your iPhone Video Gets Silently Rejected

You send a 4-second clip to set as your Telegram video avatar. Telegram accepts it, shows a spinner, then does nothing. No error message. The avatar never updates.

This happens to almost everyone shooting on iPhone. iOS 11+ records in HEVC (H.265) by default to save storage. Telegram's video avatar API requires H.264. When you upload HEVC, the API silently fails or returns a generic error with zero information about what went wrong.

I ran into this while building a bot that converts videos to Telegram avatars. The first version worked fine on test videos I encoded myself, then broke the moment any real user uploaded an iPhone recording.

What Telegram Actually Requires

The animated profile photo endpoint has hard constraints:

Codec: H.264 (libx264). No HEVC, no VP9, no AV1.
Pixel format: yuv420p (8-bit). No HDR, no 10-bit color.
Resolution: exactly 800x800. Square.
Duration: 5-10 seconds. Clips under 5 seconds need to be looped up to 5s.
File size: under 2 MB.
Audio: must be absent. A video with an audio stream is rejected.
Moov atom: must be at the start of the file (faststart).

Every item on that list can individually cause a silent failure. A typical iPhone video hits four of them at once: HEVC codec, possible 10-bit HDR color, arbitrary aspect ratio, and audio.

Solving It With ffmpeg

The pipeline runs in two steps: detect any letterboxing or pillarboxing, then encode.

First, get the crop parameters:

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

That outputs a crop=w:h:x:y string. Then the actual encode, substituting the crop result:

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

What each flag does:

crop=720:720:0:180 applies the cropdetect result.
scale=800:800 forces the square output. No-op if already square.
format=yuv420p converts 10-bit HDR to 8-bit. This is the critical flag for iPhone footage.
-c:v libx264 -profile:v baseline -level 3.1 forces H.264 compatible with Telegram.
-crf 28 controls quality. Lower = better quality, larger file. 28 stays comfortably under 2 MB for a 10-second 800x800 clip.
-movflags +faststart moves the moov atom to the file start.
-an strips all audio.
-t 10 hard caps at 10 seconds.

For clips under 5 seconds, add -stream_loop -1 before -i and set -t 5 to loop the input up to the minimum duration.

The aiogram 3 Handler

I use aiogram 3. The handler downloads the file, runs ffmpeg as a subprocess, and uploads the result.

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

router = Router()

@router.message(F.video | F.animation | F.document)
async def handle_video(message: Message):
    await message.answer("Converting, give me a second...")

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

    with tempfile.NamedTemporaryFile(suffix=".mp4", delete=False) as tmp_in:
        await message.bot.download_file(file.file_path, destination=tmp_in)
        input_path = tmp_in.name

    output_path = input_path.replace(".mp4", "_out.mp4")

    probe = subprocess.run(
        ["ffmpeg", "-i", input_path, "-vf", "cropdetect=24:16:0", "-f", "null", "-"],
        capture_output=True, text=True
    )
    crop = None
    for line in probe.stderr.splitlines():
        if "crop=" in line:
            crop = line.split("crop=")[1].split()[0]

    vf = f"crop={crop},scale=800:800,format=yuv420p" if crop else "scale=800:800,format=yuv420p"

    result = subprocess.run([
        "ffmpeg", "-y", "-i", input_path,
        "-vf", vf,
        "-c:v", "libx264", "-profile:v", "baseline", "-level", "3.1",
        "-crf", "28", "-preset", "fast",
        "-movflags", "+faststart",
        "-an", "-t", "10",
        output_path
    ], capture_output=True)

    if result.returncode != 0:
        await message.answer("Conversion failed. Try a shorter clip.")
        return

    with open(output_path, "rb") as f:
        await message.answer_video(
            BufferedInputFile(f.read(), filename="avatar.mp4"),
            caption="Ready. Set this as your Telegram video avatar."
        )

    os.unlink(input_path)
    os.unlink(output_path)

This is close to the production handler, minus retry logic and file size validation. In practice I also check the output file size and retry with -crf 32 if it's over 2 MB.

How I Packaged This as @liveavabot

The bot has been running since early 2025. The flow is one step: send a video or GIF, get back an 800x800 H.264 mp4 under 2 MB. No account, no signup, no configuration.

At 495 users with a steady trickle of new ones each week, it's not a massive project. But every person who uses it ran into the same thing: Telegram rejecting their iPhone video with zero feedback. The bot exists because fixing that one specific problem is genuinely useful.

Try it: LiveAvaBot

Edge Cases Worth Knowing

Vertical video. Portrait iPhone clips are 1080x1920. cropdetect doesn't help here since there's no letterboxing to detect. I use scale=800:800:force_original_aspect_ratio=decrease,pad=800:800:(ow-iw)/2:(oh-ih)/2 to add black bars instead of stretching the frame.

GIFs. Telegram delivers GIFs as animation type, not video. Same pipeline handles them, but small GIFs (320x240) look blocky upscaled to 800. I added unsharp=5:5:0.8 after the scale filter to recover some detail.

Large files. A 4K iPhone clip at 10 seconds is around 200 MB. Downloading 200 MB per request isn't practical. I check file size before downloading and reject files over 50 MB with an explanation.

The moov atom. I forgot -movflags +faststart in the first version. Telegram's API silently failed on about 30% of videos. Adding that one flag fixed all of them.

Short clips. Telegram requires at least 5 seconds. I loop short clips with -stream_loop -1 -i input -t 5. Works for most GIFs. Complex ones sometimes show a visible jump at the loop point.

What I Would Do Differently

The ffmpeg call is synchronous inside an async handler. At current load that's fine. For thousands of concurrent users I'd move encoding to a task queue (arq or Celery). A 2-5 second blocking call is acceptable at low volume and painful at high volume.

I'd also use -ss seek before input for long files. It skips decoding the trimmed portion entirely and is noticeably faster than post-decode -t for large inputs.

For now it works. iPhone videos convert cleanly, GIFs loop correctly, and the moov atom is always in the right place.

Built by me. @liveavabot on Telegram.

Convert iPhone HEVC Videos to Telegram Avatars with ffmpeg

liveavabot — Sun, 01 Nov 2026 18:03:52 +0000

Why iPhone Videos Fail as Telegram Avatars

Telegram added animated profile pictures a while back. You can set a short video as your avatar. In the app it looks great. But if you try to upload a video recorded on an iPhone, Telegram silently rejects it. No error message, no feedback. The upload just sits there, then fails.

I ran into this while building a side project. The issue is HEVC (H.265). iPhone has been recording in HEVC by default since iOS 11. Telegram's video avatar spec requires H.264. The app doesn't tell you this. It just fails.

So I built a Telegram bot that handles the conversion.

What Telegram Actually Requires

The spec, pieced together from the API docs and a lot of trial and error:

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

All five conditions need to hold. Miss one and the upload silently fails. The size limit is the sneaky one: a 10-second 800x800 H.264 video at default ffmpeg settings can easily hit 4-5 MB. You need to tune the bitrate.

The ffmpeg Pipeline

Here's the core command. It does everything in one pass:

ffmpeg -i input.mov \
  -vf "cropdetect,crop='iw:ih',scale=800:800:force_original_aspect_ratio=disable" \
  -c:v libx264 -profile:v baseline -level 3.1 \
  -pix_fmt yuv420p \
  -b:v 800k -maxrate 800k -bufsize 1600k \
  -t 10 \
  -an \
  -movflags +faststart \
  output.mp4

Breaking it down:

cropdetect + crop='iw:ih' handles letterboxed or portrait videos. It detects black bars and crops them before scaling.
scale=800:800:force_original_aspect_ratio=disable scales the result to exactly 800x800. Telegram center-crops on display so this works fine.
-profile:v baseline -level 3.1 ensures the widest device compatibility.
-pix_fmt yuv420p is mandatory. Without it, some encoders pick yuv444p and Telegram silently rejects the file.
-b:v 800k keeps the output under 2 MB for a 10-second clip with buffer to spare.
-t 10 hard-caps at 10 seconds.
-an strips audio entirely.
-movflags +faststart moves the moov atom to the front of the file. Telegram requires this to start streaming before the full file lands.

I tested this on iPhone 14 Pro videos (HEVC, HDR), Android H.264 videos, and desktop screen recordings. All convert cleanly.

The aiogram 3 Handler

Here's a stripped-down version of the bot handler:

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

router = Router()

VF_FILTER = "cropdetect,crop='iw:ih',scale=800:800:force_original_aspect_ratio=disable"

@router.message(F.video | F.document | F.video_note)
async def handle_video(message: Message, bot: Bot):
    file_id = None
    if message.video:
        file_id = message.video.file_id
    elif message.document and message.document.mime_type.startswith("video/"):
        file_id = message.document.file_id
    elif message.video_note:
        file_id = message.video_note.file_id

    if not file_id:
        return

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

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

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

        cmd = [
            "ffmpeg", "-i", input_path,
            "-vf", VF_FILTER,
            "-c:v", "libx264", "-profile:v", "baseline", "-level", "3.1",
            "-pix_fmt", "yuv420p",
            "-b:v", "800k", "-maxrate", "800k", "-bufsize", "1600k",
            "-t", "10", "-an",
            "-movflags", "+faststart",
            output_path, "-y"
        ]
        proc = await asyncio.create_subprocess_exec(
            *cmd,
            stdout=asyncio.subprocess.DEVNULL,
            stderr=asyncio.subprocess.PIPE,
        )
        _, stderr = await proc.communicate()

        if proc.returncode != 0:
            await message.reply("Conversion failed. Is this a valid video file?")
            return

        size = os.path.getsize(output_path)
        if size > 2 * 1024 * 1024:
            await message.reply(f"Output is {size // 1024} KB, over the 2 MB limit.")
            return

        with open(output_path, "rb") as f:
            await message.reply_document(f, filename="avatar.mp4")

The handler accepts video, video_note, and document types. GIFs come in as document with mime_type=video/mp4 because Telegram converts them server-side before delivery. The TemporaryDirectory context manager cleans up automatically.

One thing worth noting: aiogram 3 uses magic filters (F.video) rather than the string key syntax from v2. If you're migrating from v2, expect to rewrite most of your filter expressions.

I'm using create_subprocess_exec with a list rather than create_subprocess_shell with a string. This avoids shell quoting issues entirely, which matters because the -vf value contains both single and double quotes.

@liveavabot

I packaged this into @LiveAvaBot. Send it any video or GIF and it returns an 800x800 H.264 mp4 ready to upload directly as a Telegram profile video.

488 users so far. The bot handles around 7 conversions per day. It runs on a small VPS with ffmpeg installed.

I added a free tier (3 conversions per day) and a paid tier via Telegram Stars for heavier users. The Stars integration in aiogram 3 is straightforward: a PreCheckoutQuery handler, an invoice with LabeledPrice, and that's basically it.

Edge Cases and What's Next

HDR input from iPhone 14+ uses HDR10 or Dolby Vision. The conversion strips the color profile and tone-maps to SDR implicitly. The output looks slightly desaturated on some clips. I haven't added explicit -vf zscale tone-mapping yet, but it's on the list.

4K input (3840x2160) converts fine, but ffmpeg takes a few extra seconds per clip. I don't currently check file size before accepting the upload, so a 500 MB 4K video would sit in the queue for a while. A file size guard on the Document handler is the next thing to add.

Very short clips (under 1 second) pass through cleanly but look odd as a looping avatar. I don't filter these out.

The bot runs on CPU-only hardware. libx264 at 800x800 takes about 1-2 seconds per clip, which is fine at current load. I'd need hardware acceleration if volume picks up significantly.

Built by me. Try it: @LiveAvaBot

Telegram Inline Bots: Avatar Template Picker with aiogram 3

liveavabot — Thu, 29 Oct 2026 21:04:48 +0000

The Problem: Telegram Video Avatars Are Picky

Setting a video avatar in Telegram sounds simple until you try it on an iPhone. Telegram silently rejects HEVC (H.265) files, which is what every modern iOS device records by default. No error message. Just nothing happens. Users think the bot is broken.

The actual Telegram spec for video avatars: codec H.264, resolution 800x800 (square), max 10 seconds, max 2MB, no audio. Getting all five constraints right simultaneously is what I built @liveavabot for. But once you have a working converter, the next question is: how do users pick templates without leaving their current chat?

That's where inline mode comes in.

Why Inline Mode Is the Right UX

Most bots ignore inline_query. The handler isn't complicated, but it requires a separate registration flow: enable inline mode in @botfather, handle the InlineQuery update type, respond within a timeout. Most bot developers skip it.

For a template-selection flow, inline mode is the best UX Telegram offers. The user types @LiveAvaBot cute in any chat, sees a grid of matching templates instantly, taps one. No deep link, no private chat redirect, no friction.

When a user types @botname text in any Telegram chat, Telegram sends an InlineQuery update to your bot. You have about 5 seconds to respond with up to 50 results. Each result is a pre-built message the user can insert.

For video content, InlineQueryResultCachedMpeg4Gif is the right type. Despite the name, Telegram uses this for any short looping video, including the video sticker format. The key field is mpeg4_file_id, which references a file already on Telegram's servers. Upload each template once, save the file_id, reference it forever.

The aiogram 3 Handler

Here's a minimal working inline handler:

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

router = Router()

# Pre-uploaded templates: list of (file_id, title) tuples
TEMPLATES = [
    ("BQACAGIAAXXX...", "neon pulse"),
    ("BQACAGIAAXXY...", "soft glow"),
    ("BQACAGIAAXXZ...", "glitch loop"),
]

@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)

cache_time=300 tells Telegram to cache the results for 5 minutes. is_personal=False means the same results are served to all users with the same query string. That's fine for public templates. Flip it to True if results depend on user state.

The results[:25] cap exists because rendering more than 25 GIF previews in a grid noticeably slows the picker on older phones.

One note on types: InlineQueryResultCachedMpeg4Gif takes a file_id. Its non-Cached sibling takes a URL. Use the Cached variant. Remote URLs get re-fetched by Telegram on every query, add latency, and break when URLs change.

The ffmpeg Pipeline Behind Each Template

Each template starts as a raw video file, often an iPhone .MOV with HEVC encoding. The conversion pipeline uses ffmpeg with cropdetect to find the actual content area before scaling:

# Step 1: detect crop bounds
ffmpeg -ss 0 -i input.mov -vf "cropdetect=24:2:0" -t 5 -f null - 2>&1 \
  | grep -oP 'crop=\S+' | tail -1

# Step 2: encode to Telegram spec
ffmpeg -i input.mov \
  -vf "crop=720:720:0:180,scale=800:800,format=yuv420p" \
  -c:v libx264 -profile:v baseline -level 3.1 \
  -pix_fmt yuv420p \
  -movflags +faststart \
  -an \
  -t 10 \
  -fs 2000000 \
  output.mp4

-an removes audio. -fs 2000000 hard-stops at 2MB. faststart moves the moov atom to the front so Telegram starts playing before the full file loads. The baseline profile keeps compatibility with older Android decoders.

yuv420p is explicit because ffmpeg sometimes defaults to yuv444p for certain input files, and Telegram's player rejects that silently.

Packaging This as @liveavabot

The bot handles two flows. Primary: user sends a video, bot converts it and returns an 800x800 H.264 MP4 ready to set as a video avatar. Secondary: inline mode template picker shown above.

Inline mode was faster to ship. Upload templates once, done. The conversion flow took more work: probing input files for codec and color space, handling portrait vs landscape crops, capping output size without visible quality loss.

481 users have tried the bot. Conversion takes 3-8 seconds depending on input length. The most common failure mode is videos over 30 seconds where the user expects smart trimming. It currently takes the first 10 seconds. That's next on the list.

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

Type @LiveAvaBot in any chat to see the template picker.

What I Learned

Inline results are cached aggressively by Telegram clients. Set cache_time=0 during development or you'll spend time wondering why updated templates aren't showing.

File IDs are bot-specific. A file_id from one bot can't be used by another. If you ever migrate bots, re-upload everything.

Enable inline feedback in @botfather via /setinlinefeedback. Without it, you won't get chosen_inline_result updates, which is the only way to track which templates actually get used.

The is_personal=False default is a useful optimization. Telegram caches results at the server level and serves them to multiple users with the same query string, reducing traffic to your bot. For personalized results, set is_personal=True and Telegram caches per-user instead.

Built by me: @LiveAvaBot

Telegram Stars: Zero-Friction Micro-Payments for Utility Bots

liveavabot — Tue, 27 Oct 2026 20:03:14 +0000

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

Here's what I learned building it, including the actual aiogram 3 code.

The Problem With Micropayments for Utility Bots

@liveavabot does one thing: convert videos and GIFs to Telegram's video avatar format (800x800, H.264, max 10 seconds, max 2MB, no audio). It's a tool, not a SaaS. Average order value is low. Users are price-sensitive.

Any friction in the checkout kills conversion. I've tested this with other payment setups: a card form alone cuts the funnel by more than half. An external redirect loses more on top of that. Stars removes both.

What Telegram Stars Actually Is

Stars is Telegram's native virtual currency. Users buy Stars with fiat (card, Google Pay, Apple Pay) through the Telegram app itself, then spend them inside bots. From a developer perspective, receiving Stars is just handling a webhook event.

The Stars ecosystem has been growing since Telegram introduced it in 2024. More users already have Stars in their wallet than you'd expect, because many have bought them for sticker packs or channel subscriptions. A user who already has Stars treats your payment as a one-tap transfer, not a purchase decision. That changes the psychology.

The user-facing flow: tap "Buy Pack 20", Telegram shows a native payment sheet (Google Pay, Apple Pay, or Stars wallet), one confirmation tap, credits appear in the bot. There's no card form on your side, no redirect to an external site, and no KYC for small amounts. Under 30 seconds total.

Implementing Stars in aiogram 3

You create an invoice, Telegram handles the payment UI, then you handle the pre_checkout_query and successful_payment events.

Creating an Invoice

from aiogram.types import LabeledPrice, Message

async def cmd_buy(message: Message):
    await message.bot.send_invoice(
        chat_id=message.chat.id,
        title="20 conversions",
        description="Convert 20 videos or GIFs to Telegram avatar format",
        payload="pack_20",
        currency="XTR",          # XTR is the currency code for Telegram Stars
        prices=[LabeledPrice(label="20 conversions", amount=50)],  # 50 Stars
        # No provider_token needed for Stars
    )

Key detail: currency="XTR" and no provider_token. Telegram routes the payment through its own wallet. No payment gateway to configure.

Handling the Payment

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

router = Router()

@router.pre_checkout_query()
async def pre_checkout(query: PreCheckoutQuery):
    # Must answer within 10 seconds or Telegram cancels the transaction
    # Don't put heavy DB calls here
    await query.answer(ok=True)

@router.message(F.successful_payment)
async def payment_confirmed(message: Message):
    payload = message.successful_payment.invoice_payload
    stars_paid = message.successful_payment.total_amount

    if payload == "pack_20":
        await add_credits(message.from_user.id, 20)
        await message.answer(
            f"Got it. 20 conversions added. ({stars_paid} Stars charged)"
        )

The 10-second deadline on pre_checkout_query is real. I got bitten by this in testing when I added a DB lookup inside the handler. Answer first, do heavy work in successful_payment. Also: validate the payload in successful_payment, not pre_checkout_query. Returning ok=False in pre-checkout shows a generic Telegram error to the user. Better to accept, then handle unexpected payloads gracefully in the confirmation handler.

The NATIVE Partnership Program

Telegram's NATIVE Partnership pays 20% of referred Stars spend back to the developer for 6 months after each user's first Stars payment in your bot. Enrollment is through BotFather and takes about 2 minutes. For a utility bot with steady daily use, this compounds even at small scale. Worth setting up before you launch Stars, so you don't leave early users uncounted.

Lessons From 478 Users

@liveavabot currently has 478 users. Stars revenue is proportional to that scale, so I can't report large numbers. What I can say:

The funnel from "sees buy button" to "completes payment" is the shortest I've built. Users in India going through Google Pay have zero friction points I control. If they don't buy, it's a pricing issue, not a UX issue. That's a useful signal to isolate.

A few specific things that caught me:

Refunds are manual. No API to refund Stars programmatically yet. When a user hits a bug and loses a credit, I credit the account directly and issue a manual Stars refund via BotFather.

Invoice amount is in whole Stars. No fractional prices. I went with 50 Stars for 20 conversions, roughly $0.05 per conversion at current exchange rates.

Test mode uses a separate BotFather test bot. To test without spending real Stars, create a test bot via BotFather's test environment. The Telegram docs describe this but it's easy to miss on first read.

Stars don't expire. Users can hold credits indefinitely. Not a problem at my scale, but worth noting if you're building something with financial weight on either side.

What's Next

I want to add a smaller pack (5 Stars for 2 conversions) for users who want to try before committing to a larger pack. I'm also adding a credits command so users can check their balance without doing a conversion first.

The current pricing is rough. I'll adjust after a month of real data.

Try it at https://t.me/LiveAvaBot?start=devto_article_20261028 if you want to see the Stars flow live.

Built by me: @liveavabot is a side project to explore Telegram's monetization stack.

Why iPhone Videos Break Telegram Video Avatars (and How to Fix It)

liveavabot — Sun, 25 Oct 2026 19:02:54 +0000

The Problem Nobody Warns You About

Telegram supports video avatars. You record a clip on your iPhone, try to upload it as your profile video, and nothing happens. No error, no warning. The upload just silently fails.

The culprit is HEVC (H.265). Every iPhone since the iPhone 7 records in HEVC by default. Telegram's video avatar processor doesn't support it. The file gets dropped without explanation.

There's also the resolution problem. Telegram requires exactly 800x800 pixels. Most video is 16:9, and most people don't know to square-crop it first.

What Telegram Actually Requires

The spec for Telegram video profile pictures is specific:

Codec: H.264, not H.265/HEVC
Resolution: 800x800 pixels
Duration: 10 seconds maximum
File size: 2MB maximum
Audio: none (even a muted audio track causes rejection)

Most iPhone videos fail on at least three of those simultaneously: HEVC codec, 16:9 aspect ratio, and often longer than 10 seconds.

Fixing It with ffmpeg

The conversion pipeline has four jobs: decode whatever codec the input uses, smart-crop the frame to a square, scale to 800x800, and re-encode to H.264 with yuv420p while stripping audio.

I use ffmpeg's cropdetect filter to find the content bounds in pass 1, then apply the crop in pass 2. This matters for portrait iPhone videos where a naive center-crop would cut the subject's face.

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

# Pass 2: apply crop + encode to spec
ffmpeg -i input.mov \
  -vf "crop=720:720:0:180,scale=800:800:flags=lanczos,format=yuv420p" \
  -c:v libx264 -crf 23 -preset slow \
  -an \
  -movflags +faststart \
  -t 10 \
  output.mp4

The -an flag removes audio completely. The movflags +faststart moves the moov atom to the front so Telegram can start playing before the full download completes. The -t 10 hard-clips at 10 seconds.

The crop values from pass 1 (like crop=720:720:0:180) go directly into pass 2. If the source is already square, skip the crop filter.

Handling 2MB Overage

CRF 23 usually keeps output under 2MB for 10 seconds at 800x800. For high-motion content it sometimes doesn't. If the first pass comes in over 2MB, I calculate a target bitrate and re-encode:

def max_bitrate_kbps(duration_s: float, headroom_kb: int = 48) -> int:
    budget_bits = (2 * 1024 * 1024 - headroom_kb * 1024) * 8
    return int(budget_bits / duration_s / 1000)

Then pass -b:v {kbps}k -maxrate {kbps}k -bufsize {kbps * 2}k to ffmpeg on the second attempt.

Wiring It Up in aiogram 3

Here's a minimal handler in aiogram 3. It accepts video, document, or animation (Telegram sends GIFs as Animation type), runs the ffmpeg pipeline, and sends back the converted file.

from aiogram import Router, F
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):
    status = await message.answer("Converting...")

    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 tmpdir:
        src = os.path.join(tmpdir, "input")
        dst = os.path.join(tmpdir, "output.mp4")

        file = await message.bot.get_file(file_id)
        await message.bot.download_file(file.file_path, 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", "-crf", "23", "-preset", "fast",
            "-an", "-movflags", "+faststart", "-t", "10",
            dst,
            stdout=asyncio.subprocess.DEVNULL,
            stderr=asyncio.subprocess.PIPE,
        )
        _, stderr = await proc.communicate()

        if proc.returncode != 0:
            await status.edit_text("Conversion failed.")
            return

        await message.answer_video(
            video=FSInputFile(dst),
            caption="Ready. Set it as your Telegram video avatar.",
        )
        await status.delete()

The scale=...:force_original_aspect_ratio=increase,crop=800:800 chain scales up until the shorter dimension hits 800, then crops the overflow. This is the CSS object-fit: cover equivalent for video, and it gives better results than letterboxing.

Building @liveavabot

I packaged this pipeline into @LiveAvaBot. Send it any video, GIF, or document file. It converts and sends back an 800x800 H.264 mp4 ready to set as your Telegram video avatar.

A few things the bot handles beyond the basic pipeline:

GIFs: Telegram delivers them as Animation type with no duration field. I cap them at 10 seconds with -t 10 regardless.
HEVC color space: iPhone HDR videos need colorspace=bt709 in the filter chain. Without it, the re-encoded file looks washed out on standard displays.
File size gate: Telegram's bot API caps downloads at 50MB. Files over that get a clear rejection message, not a silent timeout.

The bot has 477 registered users at the time of writing.

Edge Cases I Got Wrong the First Time

Forgetting -an was the first mistake. The initial version kept a muted audio stream. Telegram still rejected the output. You need zero audio tracks, not just zero volume.

format=yuv420p is also non-negotiable. Some source files produce yuv422p or yuv444p. Certain Telegram clients won't render those correctly. Always force yuv420p on output.

Portrait iPhone videos (1080x1920) break a naive scale=800:800. It squishes the frame horizontally into a distorted square. The two-pass cropdetect approach handles these correctly.

I currently run ffmpeg inline during the request handler. For long source files this sometimes hits Telegram's response timeout. The right fix is a background worker queue with job polling. That's on the list.

Built by me: the bot is @LiveAvaBot.

Building a Telegram Video Avatar Bot With ffmpeg and aiogram

liveavabot — Thu, 22 Oct 2026 20:03:42 +0000

The Problem: iPhone Videos Silently Fail

Telegram supports video avatars. The spec: 800x800, H.264, max 10 seconds, max 2 MB, no audio.

iPhones have recorded in HEVC (H.265) since iOS 11. When someone sends an iPhone .mov to Telegram and tries to set it as their profile video, nothing happens. No error. The upload completes and the avatar just doesn't update.

I found this out because a friend spent 20 minutes trying different files before giving up and asking me why it didn't work.

What Telegram Actually Requires

For a video to be accepted as a profile avatar, it needs to meet all of these:

Codec: H.264 (yuv420p pixel format)
Resolution: exactly 800x800 pixels
Duration: 10 seconds maximum
File size: 2 MB maximum
Audio: none (a track present causes silent rejection)

The resolution requirement is the tricky part. Videos are rarely square. A portrait selfie might be 1080x1920. You need to crop to 1:1 before scaling, not stretch it.

ffmpeg Does the Heavy Lifting

I wrote a wrapper around ffmpeg to handle the conversion. The command crops to the largest centered square, scales to 800x800, normalizes the pixel format, transcodes to H.264, cuts at 10 seconds, and strips audio.

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

What each flag does:

crop='min(iw,ih)':'min(iw,ih)' takes the largest centered square crop. No x/y offset means it centers automatically.
scale=800:800 scales to exactly 800x800 after cropping.
format=yuv420p sets the pixel format Telegram expects.
-c:v libx264 forces H.264 output regardless of what the input codec is.
-crf 28 trades a bit of quality for a smaller file. Good enough for 10s at 800x800.
-t 10 hard-cuts at 10 seconds.
-an strips audio tracks entirely.
-movflags +faststart puts the moov atom at the start of the file. Some Telegram clients need this.

For HEVC input, ffmpeg decodes it transparently and -c:v libx264 re-encodes to H.264. That's the core fix.

The aiogram 3 Handler

I built this as a Telegram bot using aiogram 3. The handler receives a video file, runs ffmpeg, and sends back the converted file.

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

router = Router()

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

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

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

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

        cmd = [
            "ffmpeg", "-i", input_path,
            "-vf", "crop='min(iw,ih)':'min(iw,ih)',scale=800:800,format=yuv420p",
            "-c:v", "libx264", "-preset", "fast",
            "-crf", "28", "-t", "10", "-an",
            "-movflags", "+faststart",
            output_path
        ]

        proc = await asyncio.create_subprocess_exec(
            *cmd,
            stdout=subprocess.DEVNULL,
            stderr=subprocess.DEVNULL
        )
        await proc.wait()

        if proc.returncode != 0 or not os.path.exists(output_path):
            await status.edit_text("Conversion failed. Try a different file.")
            return

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

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

        await message.answer_video(
            BufferedInputFile(data, "avatar.mp4"),
            caption="Set this as your Telegram video avatar."
        )
        await status.delete()

The 2 MB check after conversion matters because CRF 28 doesn't guarantee a size. Dense footage like screen recordings can still exceed 2 MB at 10 seconds. I retry at CRF 32 if the first pass is too large.

BufferedInputFile holds the whole file in memory. For light traffic this is fine. If you're running at scale, write to disk and use FSInputFile instead.

Running It as @liveavabot

I wrapped the converter into a live bot at https://t.me/LiveAvaBot?start=devto_article_20261023. It handles video, document, and GIF (animation) inputs, rate limits by user, and has a Telegram Stars payment gate for heavy usage.

473 users have tried it so far. The HEVC-to-H.264 path is the most common conversion, triggered by basically any iPhone video. The success rate is around 97%. Failures are mostly corrupt inputs or files over Telegram's 20 MB bot download limit.

The infra is a single VPS with a systemd service. SQLite for state. No external services.

Edge Cases Worth Knowing

Silent rejection without an error. Telegram returns 200 OK when you upload an incompatible avatar. The avatar just doesn't update. I spent a few days thinking the bot was broken before verifying what Telegram actually does with HEVC files on the backend.

Portrait crops cut off faces. My first version took the top-left square of the frame. The crop='min(iw,ih)':'min(iw,ih)' expression without an x/y offset defaults to center, which is much better for portrait selfies.

2 MB failures at CRF 28. This happens with high-motion clips. A retry at CRF 32 or 34 covers most cases. A two-pass encode with a hard size target would be cleaner but CRF retry is simpler and works.

GIF inputs. Animated GIFs sent through Telegram arrive as animation objects, not video. The handler needs to check all three message types. The ffmpeg command works on GIF inputs unchanged.

Built by me: @liveavabot on Telegram, https://t.me/LiveAvaBot?start=devto_article_20261023.

Why iPhone Videos Silently Fail as Telegram Avatars

liveavabot — Tue, 20 Oct 2026 19:09:53 +0000

Telegram lets you set a short looping video as your profile avatar. It's a neat feature. But if you try uploading a video from a recent iPhone, nothing happens. No error, no feedback, just silence.

I ran into this while building a helper bot. Spent two hours debugging before realizing the problem: iPhone records in HEVC (H.265), and Telegram's video avatar pipeline quietly rejects anything that isn't H.264. No warning, no rejection message in the UI.

What Telegram Actually Enforces

After digging through the API docs and doing manual tests, the constraints are:

Codec: H.264, yuv420p pixel format
Shape: square, 800x800 pixels
Duration: 10 seconds maximum
File size: 2MB maximum
Audio track: must be absent

None of this is documented clearly in one place. The Telegram mobile clients handle it automatically when you record in-app. Everything else is on you.

The HEVC problem hits iPhone users hardest because iOS 11+ defaults to HEVC for main camera recordings. Most Telegram users on iPhone have never successfully set a video avatar from their camera roll, because the app silently drops the clip.

The ffmpeg Pipeline

The good news: ffmpeg handles all of it. The tricky parts are cropping to square without knowing the source aspect ratio upfront, re-encoding HEVC to H.264 with the correct pixel format, and hitting the 2MB cap without a slow two-pass encode.

Here's the command I use:

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

Breaking it down:

cropdetect=24:2:0 scans the first frames for black borders and prints crop parameters to stderr. You parse that output and feed it back as a crop filter. For a quick shortcut, crop=ih:ih does a center square crop using the shorter dimension (height for portrait video, width for landscape).

scale=800:800:flags=lanczos resizes to the required 800x800. Lanczos produces cleaner edges than bilinear when downscaling.

format=yuv420p must be explicit. libx264 sometimes outputs yuv444p for certain source files, and Telegram rejects that without any explanation.

-crf 26 hits under 2MB for most clips at 800x800 and up to 10s. Dense motion content like screen recordings or gaming clips can still bust the cap. For those I retry with -b:v 1200k.

-an strips the audio track. Required.

-movflags +faststart relocates the moov atom to the front of the file. Without it, some videos upload successfully but never actually set as the avatar.

Real Numbers

Raw input from iPhone 14: ProRes.mov, 1080x1920, HEVC, 4.1s, 47MB. Output after this pipeline: output.mp4, 800x800, H.264 yuv420p, 4.1s, 0.9MB. Telegram accepts it immediately.

The aiogram 3 Handler

I wrapped the pipeline in a Telegram bot using aiogram 3. The handler receives a video, document, or animation, downloads it, runs ffmpeg in a subprocess, and sends the result back.

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

router = Router()

async def run_ffmpeg(src: str, dst: str) -> bool:
    proc = await asyncio.create_subprocess_exec(
        'ffmpeg', '-y', '-i', src,
        '-vf', 'crop=ih:ih,scale=800:800:flags=lanczos,format=yuv420p',
        '-c:v', 'libx264', '-preset', 'fast', '-crf', '26',
        '-t', '10', '-an', '-movflags', '+faststart', dst,
        stdout=asyncio.subprocess.DEVNULL,
        stderr=asyncio.subprocess.PIPE,
    )
    await proc.communicate()
    return proc.returncode == 0 and os.path.getsize(dst) <= 2 * 1024 * 1024

@router.message(F.video | F.document | F.animation)
async def handle_video(message: Message):
    file = message.video or message.document or message.animation
    with tempfile.TemporaryDirectory() as tmp:
        src = os.path.join(tmp, 'input')
        dst = os.path.join(tmp, 'output.mp4')
        await message.bot.download(file.file_id, destination=src)
        if not await run_ffmpeg(src, dst):
            await message.reply('Conversion failed. Try a shorter clip.')
            return
        with open(dst, 'rb') as f:
            await message.reply_video(
                BufferedInputFile(f.read(), filename='avatar.mp4'),
                caption='Set this as your Telegram video avatar.',
            )

The handler registers F.video | F.document | F.animation because Telegram delivers GIFs as animation messages (MP4 internally, not a real animation type). Skip that check and GIFs never get processed.

run_ffmpeg returns False on both non-zero exit code and output files over 2MB. The caller gets a clean boolean and sends the user a plain error message.

What I Shipped as @liveavabot

The bot is live at https://t.me/LiveAvaBot?start=devto_article_20261020. Send it a video, a GIF, or a document with a video file inside, and it returns a ready-to-set 800x800 MP4.

Current numbers: 467 total users. The typical path is someone who tried to set an iPhone clip as their avatar, got no response from Telegram, searched for a solution, and landed on the bot.

A few edge cases that showed up after launch:

Rotation metadata. Some Android phones write rotation as container metadata instead of physically rotating frames. ffmpeg applies auto-rotation by default, which is usually correct, but it can invert the portrait crop logic. -noautorotate disables it when needed.

Very short clips. Sub-second videos encode fine but occasionally produce a black preview thumbnail in Telegram. Not a hard failure, just a display quirk that disappears after the avatar loops once.

20MB Bot API download limit. The Bot API won't let bots fetch files over 20MB. I reject those upfront with a plain message. The local Bot API server removes this cap, but that adds infrastructure I haven't prioritized yet.

Lessons and What's Next

The pipeline is solid for typical phone videos. Two gaps remain.

Dense motion footage still hits the 2MB cap at CRF 26. A proper two-pass VBR encode would be more reliable but doubles processing time. I'm currently testing single-pass with -maxrate 1500k -bufsize 3000k as a middle ground.

4K source files are blocked by the 20MB API limit before ffmpeg even runs. The local Bot API server would fix it.

The bot doesn't handle 4K yet, and ffmpeg is doing the actual heavy lifting here. I wrote the wrapper around it. If you're building something similar, the cropdetect plus -movflags +faststart combination is the part that took the most trial and error to get right.

Built by me. @LiveAvaBot.

Why iPhone HEVC Videos Fail as Telegram Video Avatars

liveavabot — Sun, 18 Oct 2026 18:05:32 +0000

The Problem No One Documents

I was building a Telegram bot and hit a specific wall: users sending iPhone videos couldn't set them as video avatars. Telegram accepted the upload fine but silently rejected the avatar. No error message. No indication of what went wrong.

The culprit: iPhone records in HEVC (H.265) by default since the iPhone 12. Telegram's video avatar feature requires H.264. There's no error because Telegram doesn't surface one. It just doesn't apply the avatar.

This happens silently on every iPhone that hasn't manually set the camera to "Most Compatible" in Settings. That's a lot of users.

What Telegram Actually Requires

The video avatar spec isn't documented in one place. I pieced it together through trial, error, and reading client source code:

Codec: H.264 (libx264), yuv420p color space
Resolution: exactly 800x800 pixels
Duration: 10 seconds maximum
File size: 2MB maximum
Audio: must be stripped completely
Container: MP4 with faststart flag (MOOV atom at file start)

Every constraint applies simultaneously. A 1920x1080 H.264 video fails on resolution. A square 4K HEVC clip fails on both codec and resolution. The spec is strict and Telegram enforces all of it without telling the user which part failed.

The yuv420p requirement catches people too. Some encoders default to yuv444p or yuv422p. Telegram rejects those silently as well.

The ffmpeg Pipeline

The conversion needs to: detect and crop black bars, scale to 800x800, transcode to H.264, strip audio, enforce the 10-second cap, and stay under 2MB. I split this into two passes to get clean crops on non-square source material.

Pass 1: Crop Detection

Many videos have black bars from aspect ratio mismatches. Scale without cropping and the 800x800 avatar has bars on two sides. ffmpeg's cropdetect filter analyzes the first few seconds and returns the actual content bounds:

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

Output looks like: crop=1080:1080:0:0. Parse that string and pass it to the encode step. The three parameters to cropdetect are: luminance threshold (24), rounding (16), and skip frames at start (0). Default values work well for most content.

Pass 2: Encode

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

crop=1080:1080:0:0 uses the detected content bounds from pass 1. scale=800:800:flags=lanczos resizes to the exact target using Lanczos resampling. fps=30 normalizes inconsistent frame rates. -t 10 hard caps duration at 10 seconds.

-c:v libx264 -preset fast -crf 28 encodes H.264 at quality level 28. Lower CRF (23-25) gives higher quality and is safe for short clips. Higher CRF (32) compresses more aggressively when you need to hit the 2MB ceiling. -pix_fmt yuv420p is required for cross-device compatibility. -an strips all audio tracks. -movflags +faststart moves the MOOV atom to the file start so Telegram can stream it correctly.

CRF 28 keeps most 10-second clips under 2MB. Dense motion content sometimes pushes over. In that case I retry at CRF 32.

The aiogram 3 Handler

I used aiogram 3 for the bot. The handler accepts video files, GIFs (sent as animations), and raw documents in one route.

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

router = Router()

async def convert_to_avatar(input_path: str, output_path: str) -> bool:
    probe = await asyncio.create_subprocess_exec(
        'ffmpeg', '-ss', '0', '-t', '3', '-i', input_path,
        '-vf', 'cropdetect=24:16:0', '-f', 'null', '-',
        stderr=asyncio.subprocess.PIPE
    )
    _, stderr = await probe.communicate()

    crop = 'iw:ih:0:0'
    matches = re.findall(r'crop=(\d+:\d+:\d+:\d+)', stderr.decode())
    if matches:
        crop = matches[-1]

    proc = await asyncio.create_subprocess_exec(
        'ffmpeg', '-i', input_path,
        '-vf', f'crop={crop},scale=800:800:flags=lanczos,fps=30',
        '-t', '10',
        '-c:v', 'libx264', '-preset', 'fast', '-crf', '28',
        '-pix_fmt', 'yuv420p', '-an',
        '-movflags', '+faststart',
        '-y', output_path,
        stderr=asyncio.subprocess.PIPE
    )
    await proc.communicate()

    if not os.path.exists(output_path):
        return False
    if os.path.getsize(output_path) > 2 * 1024 * 1024:
        return False
    return True


@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 tmp:
        input_path = os.path.join(tmp, 'input.mp4')
        output_path = os.path.join(tmp, 'avatar.mp4')

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

        ok = await convert_to_avatar(input_path, output_path)
        if not ok:
            await message.reply('Conversion failed. Try a shorter or smaller file.')
            return

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

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

The two-pass approach adds 1-2 seconds to processing but avoids black bars on non-square sources. asyncio handles concurrent requests without blocking on I/O.

@liveavabot: The Hosted Version

I packaged this pipeline as https://t.me/LiveAvaBot?start=devto_article_20261018. Send it any video or GIF and it returns an 800x800 H.264 MP4 ready to set as a Telegram video avatar.

It handles iPhone HEVC recordings, landscape and portrait sources, animated GIFs, and anything else ffmpeg can decode. Most conversions finish in 3-8 seconds. The bot runs on a VPS with ffmpeg installed system-wide and asyncio handles concurrent requests.

Built by me: @LiveAvaBot.

Edge Cases Worth Knowing

File size over 2MB. Short clips at CRF 28 are usually fine. Dense motion content at 10 seconds sometimes pushes over. I retry at CRF 32 if the first pass is oversized. If CRF 32 still fails, the source is probably very long or very high resolution and the user should trim it first.

Animated GIFs. ffmpeg treats them as video, so the pipeline works unchanged. GIFs often have inconsistent frame rates (5-15 fps). The fps=30 filter normalizes this without artifacts.

Portrait vs landscape. The cropdetect pass handles both orientations correctly. A 9:16 portrait phone recording crops to a square and scales to 800x800 without distortion.

Corrupt or truncated files. ffmpeg exits non-zero and the bot replies with an error. No retry since there's nothing to fix server-side.

4K source videos. Processing takes 10-15 seconds, noticeably longer than 1080p. I'm considering a fast scale-down pre-pass for anything over 1080p before running cropdetect.

The ffmpeg pipeline is the hard part. Once that's working and tested, the aiogram handler is straightforward plumbing around it. The two-pass crop approach is the thing I'd add earlier if I was doing this again.

Fixing iPhone HEVC for Telegram Video Avatars with ffmpeg

liveavabot — Wed, 14 Oct 2026 16:03:24 +0000

The Problem

I wanted to set a short video clip as my Telegram profile avatar. Telegram lets you do that. Upload an MP4, it trims to 10 seconds, done.

Except it doesn't always work. Drag in a clip recorded on an iPhone and Telegram just silently does nothing. No error, no feedback. The avatar doesn't change.

The issue is HEVC (H.265). iPhones have been shooting HEVC by default since iOS 11. Telegram's video avatar processor only accepts H.264. It rejects HEVC files without telling you why.

So I built a bot to handle it: @LiveAvaBot. Send it any video or GIF, get back a ready-to-upload avatar file.

Here's what I learned building it.

What Telegram Actually Requires

The official docs are thin on details. After testing, here's the full spec that actually works:

Codec: H.264 (libx264)
Pixel format: yuv420p (some decoders reject other formats)
Resolution: 800x800 exactly
Max duration: 10 seconds
Max file size: 2 MB
Audio: not allowed (strip it or the upload fails)
Container: MP4 with faststart flag (moov atom at the front)

The resolution requirement is the tricky one. Most videos aren't square. You can't just scale to 800x800 and call it done, you'll stretch faces. You need to crop first, then scale.

Squaring with ffmpeg

The full encode pipeline I use:

ffmpeg -i input.mov \
  -vf "crop=ih:ih:(iw-ih)/2:0,scale=800:800,format=yuv420p" \
  -c:v libx264 \
  -preset slow \
  -crf 23 \
  -t 10 \
  -an \
  -movflags +faststart \
  output.mp4

What each part does:

crop=ih:ih:(iw-ih)/2:0 crops a centered square. ih is input height, so this takes a square with side equal to the shorter dimension, centered horizontally. For portrait video where width is shorter, I swap the crop expression.

scale=800:800 scales to the required resolution.

format=yuv420p forces the pixel format. Without this, libx264 sometimes picks yuv444p, which Telegram's decoder rejects silently.

-t 10 hard-stops at 10 seconds.

-an strips audio. Required by Telegram's avatar spec.

-movflags +faststart moves the moov atom to the front of the file. Telegram needs this.

Handling iPhone HEVC and Rotation

iPhones record HEVC in a .mov container with a rotation metadata tag. Without special handling, ffmpeg sometimes produces rotated output because it reads the display rotation from metadata and applies it differently depending on the codec.

The fix: read the rotation tag with ffprobe first, then build the filter graph explicitly.

import subprocess, json

def get_rotation(path: str) -> int:
    result = subprocess.run(
        [
            "ffprobe", "-v", "quiet",
            "-select_streams", "v:0",
            "-show_entries", "stream_tags=rotate",
            "-of", "json",
            path,
        ],
        capture_output=True, text=True,
    )
    data = json.loads(result.stdout)
    tags = data.get("streams", [{}])[0].get("tags", {})
    return int(tags.get("rotate", 0))


def build_vf(path: str) -> str:
    rot = get_rotation(path)
    transpose_map = {90: "transpose=1,", 180: "hflip,vflip,", 270: "transpose=2,"}
    pre = transpose_map.get(rot, "")
    return f"{pre}crop=ih:ih:(iw-ih)/2:0,scale=800:800,format=yuv420p"

Pass -noautorotate to ffmpeg alongside the generated -vf string. This gives consistent output across iPhone portrait, landscape, and selfie-mode clips.

The aiogram 3 Handler

The bot is built with aiogram 3. The core handler:

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

router = Router()

@router.message(F.video | F.document | F.animation)
async def handle_media(message: types.Message) -> None:
    media = message.video or message.document or message.animation
    if media is None:
        return

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

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

        ok = encode_avatar(src, dst)
        if not ok:
            await message.answer("Could not convert this file.")
            return

        size = os.path.getsize(dst)
        if size > 2 * 1024 * 1024:
            await message.answer(f"Output is {size // 1024} KB, over the 2 MB limit.")
            return

        await message.answer_video(
            FSInputFile(dst),
            caption="Save this, then set as your Telegram video avatar.",
        )

F.document catches videos sent as files, which happens when you forward from a camera roll without compression. F.animation catches GIFs (Telegram stores them as MP4 internally). Both go through the same pipeline.

The 2 MB check after encoding is a safety valve. CRF 23 at 800x800 for 10 seconds is usually under 1 MB, but very noisy source footage can push past the limit.

Packaging as @liveavabot

The bot is live at https://t.me/LiveAvaBot?start=devto_article_20261014. Send it any video, GIF, or file. No account, no signup required.

Built with aiogram 3, ffmpeg 6, running on a small Hetzner VPS. Currently at 458 registered users. Conversion is synchronous for now (the ffmpeg call blocks the handler). That's fine at this scale.

One thing I didn't anticipate: people sending 4K footage. ffmpeg handles it, but download plus encode takes a few seconds. I added send_chat_action(action="upload_video") before the ffmpeg call so the bot shows "Uploading video..." while it processes. Without that, the bot looks unresponsive.

Edge Cases and What's Next

A few things that bit me:

GIFs with transparency. Some animated GIFs have transparent frames. yuv420p doesn't support transparency, so ffmpeg fills those areas with black. Usually fine, occasionally ugly.

Square input. If the source is already 1:1 aspect ratio, crop=ih:ih:(iw-ih)/2:0 is a no-op (zero pixels cropped). ffmpeg handles it without a special case.

Very short clips. A 0.3-second clip produces a valid output but barely moves as an avatar. I added a warning for clips under 2 seconds but still process them.

File size spikes. A 10-second clip of fast-moving screen content at CRF 23 can hit 3-4 MB. I drop CRF to 28 on retry if the first encode comes out over 2 MB. That usually brings it under.

What's next: a web version with drag-and-drop conversion. The bot is convenient on mobile, but desktop users sometimes prefer not to open Telegram for file conversion.

Built by me. @LiveAvaBot

How I Built a Telegram Video Avatar Bot That Handles iPhone HEVC

liveavabot — Mon, 12 Oct 2026 15:03:04 +0000

Why Your iPhone Video Breaks as a Telegram Avatar

I wanted to set a video avatar on Telegram. Dropped my iPhone clip in. Nothing. Telegram just ignored it with no error, no feedback, just silent rejection.

Turns out Telegram has a strict spec for video avatars, and iPhone recordings don't meet it by default. This is what I built to fix that, and here's exactly how it works.

What Telegram Actually Requires

The Telegram API spec for video profile photos is specific:

Codec: H.264 (not HEVC/H.265)
Resolution: 800x800 pixels, square crop
Duration: 10 seconds max
File size: 2 MB max
Audio: none (must be stripped)

iPhone 12 and newer shoot in HEVC (H.265) by default. It's smaller, looks better at the same bitrate, but Telegram's video avatar parser doesn't accept it. No warning, just silent failure. Same issue with GIFs and some Android clips shot in non-square resolutions.

The fix is transcoding through ffmpeg.

The ffmpeg Pipeline

I spent a few hours iterating on the ffmpeg command. The tricky part is the crop: videos aren't always square, so you can't just scale blindly. You need to detect the relevant content area first, then crop and scale.

First pass gets the crop parameters:

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

Then encode with the detected crop values:

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,format=yuv420p" \
  -c:v libx264 -profile:v baseline -level 3.0 \
  -crf 28 -preset fast \
  -t 9.9 \
  -an \
  -movflags +faststart \
  output.mp4

Breaking that down:

crop=... uses cropdetect values to cut letterboxing or pillarboxing
scale=800:800 with force_original_aspect_ratio=decrease avoids stretching
pad=800:800 centers it on a black square canvas
setsar=1 fixes the sample aspect ratio so players don't misinterpret it
format=yuv420p ensures H.264 baseline compatibility (some encoders default to yuv444p)
-profile:v baseline -level 3.0 keeps it within Telegram's decoder constraints
-an strips audio
-movflags +faststart moves the moov atom to the front
-t 9.9 not 10.0: Telegram counts frames, and a 10.0s clip at 30fps can have 301 frames which gets rejected

In practice I run both passes via Python's asyncio.create_subprocess_exec, parse the crop= line from stderr, and feed those values into the encode command.

The Aiogram 3 Handler

The bot is built with aiogram 3. The handler accepts video and GIF messages, downloads the file, runs the ffmpeg pipeline, and sends back the result.

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

router = Router()

async def transcode_for_tg_avatar(input_path: str, output_path: str) -> bool:
    # Pass 1: cropdetect
    proc = await asyncio.create_subprocess_exec(
        "ffmpeg", "-i", input_path,
        "-vf", "cropdetect=24:2:0",
        "-frames:v", "30", "-f", "null", "-",
        stderr=asyncio.subprocess.PIPE,
    )
    _, stderr = await proc.communicate()
    crops = re.findall(r"crop=(\d+:\d+:\d+:\d+)", stderr.decode())
    crop = crops[-1] if crops else None

    vf_parts = []
    if crop:
        vf_parts.append(f"crop={crop}")
    vf_parts += [
        "scale=800:800:force_original_aspect_ratio=decrease",
        "pad=800:800:(ow-iw)/2:(oh-ih)/2",
        "setsar=1",
        "format=yuv420p",
    ]

    # Pass 2: encode
    proc2 = await asyncio.create_subprocess_exec(
        "ffmpeg", "-i", input_path,
        "-vf", ",".join(vf_parts),
        "-c:v", "libx264", "-profile:v", "baseline", "-level", "3.0",
        "-crf", "28", "-preset", "fast",
        "-t", "9.9", "-an", "-movflags", "+faststart",
        "-y", output_path,
        stderr=asyncio.subprocess.PIPE,
    )
    await proc2.communicate()
    return os.path.exists(output_path) and os.path.getsize(output_path) < 2_000_000

@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 tmpdir:
        input_path = f"{tmpdir}/input"
        output_path = f"{tmpdir}/output.mp4"
        await message.bot.download(file, destination=input_path)
        ok = await transcode_for_tg_avatar(input_path, output_path)
        if ok:
            await message.answer_video(
                FSInputFile(output_path),
                caption="Set this as your video avatar in Profile settings.",
            )
        else:
            await message.answer("Couldn't process that file. Try a shorter clip under 30s.")

A few things worth noting: the animation type in Telegram covers GIFs that Telegram auto-converts to mp4. You get those the same way as video. Documents can also be video files (when sent uncompressed), so I handle all three types.

If the output is still over 2 MB after the first encode pass (long clips at high resolution), I bump CRF to 32 and re-encode. That covers most cases without needing to trim the user's clip.

Packaging It as @liveavabot

Once the core ffmpeg logic worked locally, I wrapped it in a proper bot and deployed to a VPS. It's live at https://t.me/LiveAvaBot?start=devto_article_20261012.

The flow is simple: send a video or GIF, get back a ready-to-use mp4. No settings, no signup. After receiving the file, you go to Telegram Profile > Set Video Avatar and upload it.

I added HEVC detection via ffprobe to give a specific success message ("Your iPhone HEVC video was re-encoded to H.264") rather than generic output. People appreciate knowing why their file needed processing.

Currently 456 users have tried it. Most common input is iPhone 14/15 videos in HEVC and square GIFs that just need re-encoding to meet the spec.

Edge Cases I Hit

Rotation metadata. Some iPhone videos have rotate=90 in the container metadata but pixel data stored landscape. ffmpeg's -vf pipeline doesn't auto-rotate by default. I added -autorotate 1 as an input flag, which handles it on ffmpeg 4.3+.

Variable framerate. Some screen recordings come in VFR. H.264 baseline prefers CFR. Adding -vsync cfr before the output fixed duration mismatches I was seeing on certain clips.

The 9.9s cut. I mentioned this above but it bit me in testing. Cutting at exactly 10.0s at 30fps gives 300 or 301 frames depending on rounding, and Telegram's avatar upload rejects the latter. 9.9s is a cheap fix.

Next: I want to test sending the output back as a document (uncompressed) instead of as a video message, to prevent Telegram's client from re-compressing it during the avatar upload step. Still validating whether that compression step actually degrades quality enough to matter.

Built by me: LiveAvaBot on Telegram.

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

liveavabot — Sat, 10 Oct 2026 13:07:21 +0000

The Problem No One Warns You About

When Telegram introduced video avatars, the spec seems simple: a square video, under 10 seconds, under 2MB. Send any short clip from your phone and done.

Except it's not. iPhone users send HEVC .mov clips, Telegram silently rejects them, and the bot returns a generic error. No useful message, no codec name, nothing. The user assumes the bot is broken.

I ran into this building @liveavabot. About a third of early test files were HEVC from iPhones shooting in the default "High Efficiency" mode. None of them worked until I understood what Telegram actually requires.

What Telegram Actually Requires

The video avatar spec is documented only in fragments across Telegram's API docs and forum posts. Here's what I confirmed through testing:

Codec: H.264 (AVC), not HEVC (H.265)
Container: MP4 with faststart flag (moov atom at the front)
Pixel format: yuv420p
Resolution: exactly 800x800
Duration: 10 seconds max
File size: 2MB max
Audio: must be absent (Telegram strips it anyway, but presence sometimes triggers a rejection)

HEVC fails at the first checkpoint. iPhone 12 and later shoot HEVC by default. The .mov container adds more friction. And if your source video has odd dimensions (most phone footage is 16:9 or 4:3), naive scaling to 800x800 squishes it.

The FFmpeg Pipeline

The approach I settled on: cropdetect to find the largest square crop, then scale and encode in one pass.

First, a quick pass to get crop parameters:

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

That outputs a line like crop=1080:1080:0:60. Feed those values into the encode pass:

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

Key flags worth understanding:

-c:v libx264 forces H.264, overriding whatever the input codec was
-crf 26 balances quality vs file size (lower = better quality, bigger file)
-movflags +faststart moves the moov atom before the mdat, which Telegram requires for streaming
-an strips the audio track entirely
-t 10 hard-caps duration at 10 seconds

In practice I run cropdetect in a subprocess, parse the last crop= line with a regex, then inject those values into the encode command. For videos that are already roughly square, cropdetect returns the full frame dimensions, so no quality is lost.

The 2MB constraint is the hardest part. -crf 26 gets most 10-second clips under 2MB, but dense motion (confetti, fast panning) can push it over. My fallback bumps -crf to 30, then 34. If it's still over 2MB I truncate to 8 seconds. Hasn't failed yet across a few hundred test files.

The Aiogram 3 Handler

The bot itself is a thin wrapper around the ffmpeg pipeline. Here's the core video handler:

@router.message(F.video | F.animation | F.document)
async def handle_video(message: Message, bot: Bot) -> None:
    file_id = None
    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.startswith("video/"):
        file_id = message.document.file_id

    if not file_id:
        await message.reply("Send a video file or GIF.")
        return

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

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

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

        success = await asyncio.to_thread(convert_to_avatar, input_path, output_path)

        if not success:
            await status.edit_text("Conversion failed. Is this a valid video file?")
            return

        await bot.send_video_note(
            chat_id=message.chat.id,
            video_note=FSInputFile(output_path),
            reply_to_message_id=message.message_id,
        )
        await status.delete()

convert_to_avatar is the synchronous ffmpeg wrapper. Running it in asyncio.to_thread keeps the event loop unblocked during encoding.

One thing that tripped me up: Telegram's bot API doesn't let you directly set another user's avatar programmatically. You can set your own bot's profile photo, or you use the client API (TDLib or Telethon) for user accounts. For @liveavabot the use case is simpler: the user downloads the converted clip and sets it themselves. So I send back the video note and a download button.

How I Packaged This as @liveavabot

The bot went live after about a weekend of work. It has 453 users so far. Most sessions are under a minute: send video, get back 800x800 H.264 clip, done.

A few things that surprised me during testing:

GIFs from Telegram's own GIF keyboard come in as .mp4 animations, not .gif. Aiogram's F.animation filter catches them correctly without any extra handling.
Some Android phones send VP9-encoded .webm files. FFmpeg handles these without complaint, but I had to add webm to the accepted MIME type list.
The biggest user drop-off point was people sending photos instead of videos. A one-line handler that replies "that's a photo, not a video" cut the confusion noticeably.

The bot runs on a small VPS, processes files in a temp directory that gets wiped after each request, and logs nothing but request counts. No user data stored.

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

Built by me (@liveavabot).

What's Next

4K source handling. For true 4K sources, pre-scaling before cropdetect would be faster. Currently ffmpeg downsamples during the encode pass, which works but takes longer on a low-end VPS.

Better error messages. When ffmpeg fails, I return a generic message. Parsing ffmpeg's stderr would let me return the actual reason: "input is 47s, please trim to under 10s" is a lot more useful than "conversion failed".

Direct avatar setting. Right now the user sets the avatar manually after downloading. A proper implementation using the Telegram client API could set it in one tap. That's a bigger change but it's on the list.

The whole thing is straightforward Python: aiogram 3 for the bot layer, subprocess calls to ffmpeg for the conversion, nothing exotic. If you're building something similar, the cropdetect pipeline is worth borrowing.