DEV Community: liveavabot

Converting iPhone HEVC Videos to Telegram Video Avatars with FFmpeg

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

The problem: iPhone videos that Telegram refuses

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

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

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

What Telegram actually requires

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

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

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

Cropdetect, scale, and format conversion in one pipe

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

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

Breaking it down:

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

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

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

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

The aiogram 3 handler

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

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

router = Router()

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

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

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

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

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

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

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

A few things worth noting:

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

Packaging it as @liveavabot

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

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

Edge cases I learned the hard way

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

What's next

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

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

Why iPhone Videos Silently Fail as Telegram Avatars (FFmpeg Fix)

liveavabot — Sun, 19 Jul 2026 23:05:15 +0000

My girlfriend tried to set a video avatar on her Telegram profile last month. Fresh clip from her iPhone 15, under ten seconds, looked great. Telegram accepted the upload, spun for a moment, then did nothing. No error message, no broken thumbnail. Nothing.

I pulled the file onto my laptop and ran ffprobe. Codec: hevc. That was the whole bug. iPhones have recorded HEVC (H.265) by default since iOS 11, and Telegram's video avatar pipeline only takes H.264. Instead of saying so, it silently drops the file.

One ffmpeg command fixed her avatar. Then I figured other people hit this every day, so I wrapped the command in a Telegram bot. This post is the build log: the spec Telegram actually enforces, the ffmpeg pipeline, and the aiogram 3 code that glues it together.

What Telegram actually accepts

There is no single doc page listing the video avatar requirements, so I collected them through testing and scattered API notes:

Codec: H.264. HEVC, VP9 and AV1 get dropped without a word.
Pixel format: yuv420p. Ten-bit HEVC from newer iPhones decodes to yuv420p10le, which also fails.
Square frame. 800x800 is what the official clients upload.
Duration: 10 seconds max.
No audio track. Muting is not enough, the stream has to be gone.
Size: under roughly 2 MB uploads reliably.
moov atom at the front (faststart), so the preview renders before the file finishes downloading.

Miss any one of these and the feedback is identical: nothing happens.

The ffmpeg pipeline

Two passes. First cropdetect, because screen recordings and vertical videos carry black bars that waste the 2 MB budget:

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

That prints something like crop=1080:1080:0:420. Feed it into the encode pass:

ffmpeg -y -i input.mov -t 9.5 \
  -vf "crop=1080:1080:0:420,scale=800:800,format=yuv420p" \
  -c:v libx264 -profile:v high -preset veryfast -crf 26 \
  -an -movflags +faststart \
  avatar.mp4

Notes on the flags:

-t 9.5 trims just under the 10 second cap. Cutting at exactly 10.0 sometimes lands on 10.03 after keyframe alignment and gets refused.
format=yuv420p fixes the 10-bit iPhone case in the same filter chain.
-an removes the audio stream entirely.
-crf 26 lands a 9.5 second 800x800 clip around 1.5 MB. If the output is over 2 MB I re-run with crf 28, then 30. Three tries have covered every file so far.
+faststart moves the moov atom to the front.

ffmpeg is doing the heavy lifting here. I just wrote the wrapper.

The aiogram 3 handler

The minimal bot side. A router catches videos and GIFs, downloads them, shells out to ffmpeg, sends the result back:

import asyncio
import tempfile
from pathlib import Path

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

router = Router()


@router.message(F.video | F.animation)
async def convert(message: Message, bot: Bot):
    media = message.video or message.animation
    if media.file_size and media.file_size > 50 * 1024 * 1024:
        await message.answer("Over 50 MB, send something smaller.")
        return

    with tempfile.TemporaryDirectory() as tmp:
        src = Path(tmp) / "src"
        dst = Path(tmp) / "avatar.mp4"
        await bot.download(media.file_id, destination=src)

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

        if proc.returncode != 0 or not dst.exists():
            await message.answer("ffmpeg choked on that file, try another one.")
            return

        await message.answer_video(FSInputFile(dst), width=800, height=800)

This lazy version skips cropdetect and uses force_original_aspect_ratio=increase plus a center crop. Good enough for most clips. The production bot runs the two-pass cropdetect flow and falls back to center crop when detection returns garbage.

One detail worth copying: asyncio.create_subprocess_exec instead of subprocess.run. The handler stays async, so one slow encode doesn't block updates from other users.

Turning it into @liveavabot

The wrapper became @LiveAvaBot. You send a video or GIF, it replies with a ready avatar file plus short instructions for setting it, since Telegram buries the video avatar option two menus deep.

Things I added on top of the core pipeline: a per-user queue so someone dumping ten videos doesn't starve everyone else, the crf retry loop for the 2 MB budget, and a duration probe before download, since there's no point pulling a 3 minute file to keep 9.5 seconds of it.

Current numbers, because build logs should have numbers: 234 users, 5 conversions in the last 24 hours. Not a rocket. But it fixes a real annoyance and runs mostly idle on a small VPS.

Disclosure: built by me. @liveavabot is my project and this article is part of building it in public.

Edge cases that bit me

Rotation metadata. iPhone clips are often stored sideways with a rotate tag. Modern ffmpeg autorotates, but one older distro build shipped sideways avatars until I noticed.
Odd dimensions. A GIF with a width like 479 makes libx264 refuse to encode, it wants even numbers. Scaling to 800x800 fixes that for free.
Alpha channels. Some webm files carry transparency and format=yuv420p flattens it to black. I now composite on white first.
Phantom audio. Some Android camera apps write an audio track with zero samples. -an kills it either way.

What's next

Hardware HEVC decode is the current experiment, since software decoding 4K60 iPhone footage is the slowest step in the pipeline. Animated WebP input is next on the list, people keep sending those.

If you've fought Telegram's other undocumented media specs (video sticker webm is a similar rabbit hole), I'd like to hear what you ran into.

Why iPhone Videos Silently Fail as Telegram Avatars (FFmpeg Fix)

liveavabot — Fri, 17 Jul 2026 22:03:21 +0000

Last month I tried to set a video avatar on Telegram using a clip from my iPhone. The upload ran, the progress bar filled, and then nothing. No error message. The old avatar just stayed there.

It took me an evening to figure out why. iPhones record HEVC (H.265) by default since iOS 11, and Telegram's video avatar pipeline only accepts H.264. Instead of telling you that, the client silently drops the file. This post is the build log of how I fixed it with ffmpeg and then wrapped the fix into a Telegram bot.

What Telegram Actually Requires

The video avatar spec is not written down in one place. I pieced it together from the Bot API docs, the Telegram Desktop source, and trial and error:

Video codec: H.264, pixel format yuv420p (8-bit, not 10-bit)
Container: MP4
Resolution: square, 800x800 works everywhere
Duration: 10 seconds max
File size: roughly 2 MB before clients start refusing
Audio: none. A file with an audio track gets rejected
moov atom at the front (faststart), or mobile clients stall

An iPhone clip breaks almost every line of that list. It's HEVC, it's 1080x1920 portrait, it's often 10-bit HDR (yuv420p10le), it has an audio track, and a 10 second clip weighs 20+ MB.

The FFmpeg Pipeline

There are two problems to solve: geometry (make it square) and encoding (make it H.264 under 2 MB).

For screen recordings and letterboxed clips I first run cropdetect to strip black bars, then center-crop to a square:

# pass 1: detect black bars on the first 3 seconds
ffmpeg -i input.mov -t 3 -vf cropdetect=24:16:0 -f null - 2>&1 \
  | grep -o 'crop=[0-9:]*' | tail -1

# pass 2: crop to square, scale, encode, strip audio
ffmpeg -i input.mov -t 10 \
  -vf "crop='min(iw,ih)':'min(iw,ih)',scale=800:800,format=yuv420p" \
  -c:v libx264 -profile:v high -preset medium -crf 26 \
  -an -movflags +faststart -y output.mp4

Notes on the flags, because each one earns its place:

crop='min(iw,ih)':'min(iw,ih)' center-crops to a square. When you omit the x and y arguments, ffmpeg centers the crop for you.
format=yuv420p is the fix for iPhone HDR clips. They come in as yuv420p10le, and 10-bit H.264 breaks Telegram playback.
-an drops the audio track. Without it the avatar upload fails.
-crf 26 lands a 10 second 800x800 clip at 1.2 to 1.8 MB most of the time. If the output is still over 2 MB, I retry with crf+4.
-movflags +faststart moves the moov atom to the front so the avatar starts playing before the whole file is fetched.

The Bot Handler in aiogram 3

The manual pipeline worked, but I didn't want to ssh into a box every time I change an avatar. So: Telegram bot. Here's a minimal aiogram 3 handler:

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

router = Router()

@router.message(F.video | F.animation)
async def convert(message: Message, bot: Bot):
    file = message.video or message.animation
    if file.file_size and file.file_size > 50 * 1024 * 1024:
        await message.answer("Over 50 MB, the Bot API won't let me download that.")
        return

    with tempfile.TemporaryDirectory() as tmp:
        src = pathlib.Path(tmp, "src.bin")
        dst = pathlib.Path(tmp, "avatar.mp4")
        await bot.download(file, destination=src)

        proc = await asyncio.create_subprocess_exec(
            "ffmpeg", "-i", str(src), "-t", "10",
            "-vf", "crop='min(iw,ih)':'min(iw,ih)',scale=800:800,format=yuv420p",
            "-c:v", "libx264", "-preset", "medium", "-crf", "26",
            "-an", "-movflags", "+faststart", "-y", str(dst),
        )
        await proc.wait()
        if proc.returncode != 0:
            await message.answer("ffmpeg choked on that file, try another one?")
            return

        await message.answer_video(FSInputFile(dst), width=800, height=800)

ffmpeg is doing the heavy lifting here, I just wrote the wrapper. Two details worth copying: run ffmpeg through create_subprocess_exec so the event loop doesn't block during encoding, and use a TemporaryDirectory so failed conversions don't pile up on disk.

Shipping It as @liveavabot

I cleaned this up and published it as @LiveAvaBot. You send it a video or a GIF, it replies with the converted file, and you set that as your avatar from Telegram settings. It also handles GIFs (Telegram stores them as silent mp4 already, so those mostly need a crop and a rescale) and documents with video mime types, since forwarded videos sometimes arrive that way.

It sits at 230 users now. Not a big number, and the usage pattern is funny: most people convert one file and disappear for a month. It's a tool, not an app, and I've stopped pretending otherwise.

Edge Cases That Bit Me

Rotation metadata. iPhones record portrait as landscape plus a rotate flag. Modern ffmpeg autorotates, but if you compute crop geometry from the raw stream width and height, you'll crop the wrong axis. Let the filter chain handle it.
10-bit HDR. Covered above, but it deserves repeating: if your output "looks fine in VLC but Telegram rejects it", check pix_fmt first.
The 2 MB budget. Grainy low-light clips blow past it even at crf 26. My retry loop bumps crf by 4 each attempt and caps at 34 before giving up.
The Bot API download cap. Files over 50 MB can't be downloaded through the standard Bot API at all. A self-hosted Bot API server lifts this. I haven't bothered yet.

Next on the list is a job queue: 4K 60fps input encodes slowly on my small VPS, and two simultaneous users can make each other wait.

Disclosure: I built @liveavabot myself, and it's free to use.

If you've fought the Telegram avatar spec and hit traps I missed, tell me in the comments.

Why Your iPhone Video Fails as a Telegram Avatar (and the Fix)

liveavabot — Wed, 15 Jul 2026 21:04:59 +0000

The Bug That Isn't a Bug

A friend sent me a screen recording of his problem. He picked a clip for his Telegram profile (the round animated avatar), the app showed a spinner, and then the avatar stayed a static photo. No error message, nothing in the UI at all. He tried three times and gave up.

I pulled the file apart. Recorded on an iPhone 13: .mov container, HEVC video, 10-bit color. That has been the default capture format since iOS 11. Telegram's video avatar pipeline wants H.264, and when the codec doesn't match, the client silently drops the upload instead of telling you why.

That silent failure annoyed me enough to build a fix. This post walks through the ffmpeg pipeline and the aiogram 3 handler behind it.

What Telegram Actually Wants

The docs are thin on video avatars, so most of these numbers came from testing against real clients:

Container: MP4
Codec: H.264 with yuv420p pixel format
Resolution: square, 800x800 works everywhere
Duration: 10 seconds max
Audio: none, strip the track entirely
Size: around 2 MB or under

The two killers are codec and pixel format. iPhone HEVC is usually yuv420p10le, meaning 10-bit. Even if you transcode to H.264 but keep 10-bit, some clients still refuse to animate it. format=yuv420p is not optional.

Audio surprises people too. A video avatar has no sound by design, and Telegram is stricter about a leftover audio track than you'd expect. -an is the reliable answer.

The FFmpeg Pipeline

The pipeline has three jobs: find the actual picture area, cut a square from it, and land on the codec spec.

For the picture area I run cropdetect on the first two seconds. It catches letterboxed videos and screen recordings with black bars:

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

Then I compute the largest centered square inside that region and do a single encode pass:

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

Flag by flag: -t 10 hard-caps duration. The crop values come straight from the cropdetect output. scale=800:800:flags=lanczos downscales sharper than the default bilinear. format=yuv420p forces 8-bit 4:2:0 and fixes the 10-bit HEVC case. -an drops audio. -movflags +faststart moves the moov atom to the front so playback starts before the file finishes downloading.

For the 2 MB cap I skip the bitrate math. I encode at CRF 26 and check the output size. Over the limit? Retry at 28, then 31. Two retries have covered every real file users have thrown at it. A 10-second 800x800 clip at CRF 26 usually lands between 1.2 and 1.8 MB.

Wiring It Into aiogram 3

The bot side is short. Download the incoming file, run the encode, reply with the result:

import asyncio
import tempfile
from pathlib import Path

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

router = Router()

VF = "crop='min(iw,ih)':'min(iw,ih)',scale=800:800:flags=lanczos,format=yuv420p"

@router.message(F.video | F.animation | F.document)
async def convert(message: Message, bot: Bot):
    media = message.video or message.animation or message.document
    if media.file_size and media.file_size > 50 * 1024 * 1024:
        await message.reply("Over 50 MB, the Bot API refuses the download.")
        return

    with tempfile.TemporaryDirectory() as tmp:
        src = Path(tmp) / "input.bin"
        dst = Path(tmp) / "avatar.mp4"
        await bot.download(media, destination=src)

        proc = await asyncio.create_subprocess_exec(
            "ffmpeg", "-y", "-i", str(src), "-t", "10",
            "-vf", VF,
            "-c:v", "libx264", "-preset", "veryfast", "-crf", "26",
            "-an", "-movflags", "+faststart", str(dst),
            stdout=asyncio.subprocess.DEVNULL,
            stderr=asyncio.subprocess.DEVNULL,
        )
        await proc.wait()

        if proc.returncode != 0 or not dst.exists():
            await message.reply("Conversion failed on this one. Mind sending the original as a file?")
            return

        await message.reply_video(FSInputFile(dst), width=800, height=800)

Three notes on the snippet. The inline min(iw,ih) crop is the lazy version, production runs cropdetect first as shown above. create_subprocess_exec means user filenames never touch a shell. And F.document matters more than it looks: sending a video "as file" is exactly how iPhone HEVC .mov files arrive, so skipping documents means missing the users who need this most. You'd want a mime type check inside the handler, I cut it here for length.

The 50 MB guard is a Bot API limit, getFile refuses anything larger, so failing early with a clear message beats a mysterious timeout.

Shipping It as @liveavabot

I wrapped the whole thing into @LiveAvaBot. You send it a video or GIF, it replies with a converted clip, and you set that clip from Telegram's profile settings. 223 people have used it so far, and most of them arrive after hitting the exact silent failure from the intro.

It runs on a small VPS. ffmpeg is doing the heavy lifting, my code is mostly plumbing, rate limits, and cleanup. With the veryfast preset a typical iPhone clip converts in under four seconds, so I haven't needed a job queue yet.

Edge Cases That Bit Me

Rotation metadata was the worst one. iPhones store portrait video as landscape plus a rotation flag in a display matrix. Modern ffmpeg autorotates on decode, but if you compute your crop square from raw stream dimensions you'll cut along the wrong axis. Probe the rotation, or measure dimensions after decode, not from container metadata.

Real .gif uploads (not Telegram's MP4 animations) can carry bizarre frame timing. Adding fps=30 to the filter chain normalizes them.

Some screen recorders write files where ffprobe reports duration as N/A. I fall back to decoding and counting frames before deciding whether the 10-second cap even applies.

And 10-bit HEVC deserves a second mention. It accounts for most of the "why doesn't my avatar animate" reports I get, which is why format=yuv420p sits permanently in the filter chain.

Next on the list: 4K sources are slow on the current box, so a queue with a progress message is probably coming. I also want a loop point picker so avatars don't visibly jump when they repeat.

Disclosure: built by me, @liveavabot.

If you've reverse engineered other undocumented Telegram media specs (voice message waveforms, anyone?), tell me how you did it, I collect these.

Why iPhone Videos Fail as Telegram Video Avatars (and the Fix)

liveavabot — Mon, 13 Jul 2026 20:03:46 +0000

Telegram lets you use a short looping video as your profile picture. On the phone app this mostly just works, because the client converts whatever you pick. Everywhere else you need a file that already matches the spec. And if your source clip came off an iPhone, there is a good chance Telegram will refuse it without showing a single error.

I hit this while helping a friend set a video avatar from a clip shot on her iPhone. The upload looked fine, then her old photo just stayed there. No toast, no "unsupported format", nothing. That silent failure annoyed me enough to dig into what Telegram actually accepts, and the digging turned into a small bot.

What Telegram Actually Wants

There is no single docs page that spells this out, so I assembled it from the Telegram Desktop source and a pile of test uploads. A video avatar needs:

MP4 container with H.264 video
square aspect, 800x800 is the target
10 seconds or less
no audio stream at all (not muted, removed)
yuv420p pixel format
a small file, under 2MB uploads reliably

Miss any of these and the client either rejects the file outright or accepts the upload and quietly ignores it. The second case is the maddening one.

Why iPhone Footage Fails Every Check

Since iOS 11, iPhones record HEVC (H.265) by default, the "High Efficiency" camera setting. Newer models add 10-bit HDR on top, so the pixel format is yuv420p10le instead of yuv420p. The clip is 1920x1080 or 4K, nowhere near square. There is an AAC audio track. And rotation is often stored as a display matrix in metadata instead of baked into the pixels, which some tools honor and some ignore.

So a stock iPhone clip has the wrong codec, the wrong bit depth, the wrong shape, an audio track it shouldn't have, and it might be sideways. Telegram transcodes none of that outside its official mobile clients. It just says no, silently.

The ffmpeg Pipeline That Fixes It

ffmpeg does all the real work here. I run two passes: cropdetect first to find the actual content box (GIFs and screen recordings often ship with letterboxing), then a crop, scale and encode pass.

# pass 1: sample the first seconds, let cropdetect find the content box
ffmpeg -i input.mov -t 3 -vf "cropdetect=24:16:0" -f null - 2>&1 \
  | grep -o 'crop=[0-9:]*' | tail -1

# pass 2: centered square crop, scale, transcode, strip audio
ffmpeg -y -i input.mov -t 10 \
  -vf "crop='min(iw,ih)':'min(iw,ih)',scale=800:800,format=yuv420p" \
  -c:v libx264 -profile:v high -preset slow -crf 26 \
  -an -movflags +faststart \
  avatar.mp4

The flags that matter:

format=yuv420p downconverts 10-bit HDR footage. Without it, libx264 happily produces 10-bit output that Telegram then rejects.
-an removes the audio stream entirely. Muting is not enough, the track has to be gone.
-t 10 hard caps the duration.
-movflags +faststart moves the moov atom to the front so the loop starts without buffering.
-crf 26 usually lands a 10 second 800x800 clip around 1.2 to 1.8MB. If the output comes out over 2MB, I re-run with crf bumped by 2 until it fits. Two retries cover almost every real input.

Wiring It Into an aiogram 3 Bot

I wanted a "send video, get avatar back" flow, so aiogram 3 with a single router:

import asyncio
import tempfile
from pathlib import Path

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

router = Router()

VF = "crop='min(iw,ih)':'min(iw,ih)',scale=800:800,format=yuv420p"

@router.message(F.video | F.animation | (F.document & F.document.mime_type.startswith("video/")))
async def convert(message: Message, bot: Bot):
    media = message.video or message.animation or message.document
    with tempfile.TemporaryDirectory() as tmp:
        src, dst = Path(tmp) / "in", Path(tmp) / "avatar.mp4"
        await bot.download(media, destination=src)

        proc = await asyncio.create_subprocess_exec(
            "ffmpeg", "-y", "-i", str(src), "-t", "10",
            "-vf", VF,
            "-c:v", "libx264", "-preset", "veryfast", "-crf", "26",
            "-an", "-movflags", "+faststart", str(dst),
            stdout=asyncio.subprocess.DEVNULL,
            stderr=asyncio.subprocess.DEVNULL,
        )
        await proc.wait()

        if proc.returncode != 0 or not dst.exists():
            await message.answer("Couldn't convert that one. Is it actually a video file?")
            return

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

A few notes. The Bot API caps downloads at 20MB unless you run a local Bot API server, so big 4K clips need a size check before download. asyncio.create_subprocess_exec keeps the event loop free while ffmpeg runs, so one user's 4K video doesn't block everyone else. The temp directory cleans up both files even when conversion dies halfway.

Shipping It as @liveavabot

I packaged this as @LiveAvaBot. Send it any video or GIF and it replies with an 800x800 H.264 clip that Telegram accepts as a profile video. It runs on a small VPS. ffmpeg is doing the heavy lifting, I mostly wrote plumbing, queueing and retry logic.

219 people have used it so far. Not a huge number, but conversions come through every day, and each one is someone who would otherwise be staring at an upload that fails with no explanation. HEVC off an iPhone is still the most common input I see.

Disclosure: built by me, @liveavabot.

Edge Cases and What's Next

Things that broke in production, in order of discovery:

10-bit HDR. The first version skipped format=yuv420p. Every HDR clip from an iPhone 12 or newer produced output Telegram rejected. It took a while to spot because the files played fine everywhere else.
Rotation metadata. Modern ffmpeg autorotates on decode, but if you compute a crop from the raw coded dimensions you can crop the wrong axis. Trust ffprobe display dimensions.
Odd dimensions. A 481x361 GIF makes libx264 unhappy. Cropping to min(iw,ih) and scaling to a fixed 800x800 sidesteps the whole class of problems.
Variable frame rate. iOS screen recordings sometimes came out longer than 10 seconds after trimming because of VFR weirdness. Putting -t 10 after the input, as an output option, fixed it.

Next up: faster handling of 4K sources (about 20 seconds on my VPS right now) and a way to pick the crop position, because a centered square crop cuts heads off some vertical videos.

If you've fought Telegram's media specs from a bot before, I'd like to hear which one bit you.

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

liveavabot — Sat, 11 Jul 2026 19:04:02 +0000

Last month a friend tried to set a video from her iPhone as her Telegram profile video. Telegram accepted the upload, spun for a second, then quietly did nothing. No error message. The video just never appeared.

The cause is boring: iPhones have recorded HEVC (H.265) by default since iOS 11, and Telegram's video avatar pipeline only accepts H.264. Telegram never tells you this. It fails silently, and you're left assuming your video is somehow broken.

I spent an evening figuring out the exact requirements, wrote an ffmpeg wrapper around them, and ended up shipping the whole thing as a Telegram bot. This is the build log.

What Telegram Actually Requires

The docs describe video avatars only vaguely, so most of this came from testing uploads until they stuck:

Container: MP4
Video codec: H.264, pixel format yuv420p (8-bit, this matters)
Aspect: square, 800x800 works well since avatars render inside a circle
Duration: 10 seconds max
File size: around 2 MB, stay under it to be safe
Audio: none, a file with an audio track gets rejected

The killer combination for iPhone footage is codec plus pixel format. Modern iPhones shoot HEVC in yuv420p10le (10-bit) when HDR is on. Even after transcoding to H.264, keeping 10-bit color makes some clients render green garbage instead of video. You need both libx264 and an explicit format=yuv420p.

The ffmpeg Pipeline

The conversion is a center crop to square, a scale to 800x800, a pixel format fix, and an H.264 encode with the audio stripped. I also run cropdetect first, because screen recordings and downloaded clips often arrive letterboxed, and black bars look terrible inside a circular avatar.

# pass 1: detect black bars (sample the first 3 seconds)
ffmpeg -i input.mov -t 3 -vf "cropdetect=24:16:0" -f null - 2>&1 \
  | grep -o "crop=[0-9:]*" | tail -1

# pass 2: center-crop to square, scale, force 8-bit H.264, drop audio
ffmpeg -i input.mov -t 10 \
  -vf "crop='min(iw,ih)':'min(iw,ih)',scale=800:800,fps=30,format=yuv420p" \
  -c:v libx264 -profile:v main -preset slow -crf 26 \
  -movflags +faststart -an -y output.mp4

The crop expression takes the largest centered square regardless of orientation. format=yuv420p downgrades 10-bit HDR to 8-bit, which every Telegram client can decode. -an removes the audio track, which is mandatory for avatars. -movflags +faststart moves the moov atom to the front of the file so playback starts without a full download.

-crf 26 with -preset slow usually lands a 10 second clip around 1.2 to 1.6 MB. For the 2 MB cap I don't do bitrate math. I check the output size and re-encode with CRF bumped by 3 if it's over. Two retries have covered everything users have thrown at the bot so far.

The aiogram 3 Handler

The bot side is small. aiogram 3 magic filters let one handler catch videos, GIFs (Telegram converts those to silent MP4 "animations" on upload), and video files sent as documents:

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

router = Router()

VF = "crop='min(iw,ih)':'min(iw,ih)',scale=800:800,fps=30,format=yuv420p"

@router.message(F.video | F.animation | F.document.mime_type.startswith("video/"))
async def convert(message: Message, bot: Bot):
    src_file = message.video or message.animation or message.document
    if src_file.file_size > 20 * 1024 * 1024:
        await message.answer("Over 20 MB, Bot API won't let me download that.")
        return

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

        proc = await asyncio.create_subprocess_exec(
            "ffmpeg", "-i", src, "-t", "10", "-vf", VF,
            "-c:v", "libx264", "-profile:v", "main",
            "-preset", "slow", "-crf", "26",
            "-movflags", "+faststart", "-an", "-y", dst,
        )
        await proc.wait()
        if proc.returncode != 0:
            await message.answer("ffmpeg choked on that file, try another one.")
            return

        await message.answer_video(
            FSInputFile(dst),
            caption="Done. Settings > Edit profile > Set new photo > pick this video.",
        )

Two boring details that matter. Standard Bot API servers cap downloads at 20 MB, so I reject bigger files up front instead of failing halfway through. And the subprocess uses create_subprocess_exec, not shell=True, so filenames never touch a shell. In production I also wrap proc.wait() in asyncio.wait_for with a 120 second timeout, because a corrupt file can make ffmpeg hang forever.

Shipping It as a Bot

I packaged this as @LiveAvaBot. You send a video or GIF, it replies with a ready avatar file in 10 to 20 seconds, and Telegram accepts the result as a profile video. It runs on a small VPS under systemd, nothing exotic.

Numbers so far: 215 users, about 7 conversions a day this week. Tiny, but people come back with a second video after the first one works, which tells me the pain is real. The most common input is exactly the case that started this whole thing: HEVC clips straight off an iPhone.

Edge Cases That Bit Me

Rotation metadata. Phones store rotation as a display matrix instead of rotating pixels. Modern ffmpeg autorotates on decode, but if you write filter logic that compares iw and ih yourself, do it after autorotation or portrait videos come out sideways.

10-bit HDR. Worth repeating because the failure mode is nasty: the file uploads fine, then renders green or black frames on some clients. format=yuv420p, always.

GIFs are not GIFs. Telegram converts uploaded GIFs to silent MP4s, so those are already halfway to spec. Real .gif files sent as documents still work, ffmpeg decodes them fine.

Very short clips. A 0.8 second video makes a jarring avatar loop. I don't pad these yet, I just warn the user.

Next up: 4K 60fps input is slow with -preset slow on a 2 vCPU box, sometimes 90 seconds per file. I'll probably drop long inputs to -preset medium and add a job queue instead of converting inline.

Disclosure: built by me, @liveavabot is my own project and free to use. If you've hit the silent avatar rejection, send the bot your weirdest iPhone clip and tell me if it survives.

Why iPhone Videos Silently Fail as Telegram Video Avatars

liveavabot — Thu, 09 Jul 2026 18:03:36 +0000

Telegram added video avatars back in 2020. You upload a short clip and it loops on your profile instead of a static photo. Fun feature. Except if you recorded that clip on an iPhone, there's a good chance Telegram does nothing with it. No error message. No rejection. The upload finishes and your profile still shows the old photo.

I hit this myself, then watched two friends hit the same wall. So I dug into why, and ended up shipping a bot around the fix. This is the write-up.

Why iPhone Videos Fail

Since iOS 11, iPhones record video in HEVC (H.265) by default. Better codec, roughly half the bitrate of H.264 at the same quality. The problem: Telegram's video avatar pipeline only accepts H.264. When it gets HEVC, the client doesn't transcode and doesn't warn you. It silently drops the upload.

The failure is invisible because regular video messages do get transcoded. Send the same .mov in a chat and it plays fine. Only the avatar path is strict, and that mismatch is exactly what makes people think their app is broken.

What the Spec Actually Requires

Telegram never published a formal document for video avatars, so this is reverse-engineered from what the official clients produce and what the API accepts:

MP4 container, H.264 video
yuv420p pixel format (10-bit HDR sources fail without conversion)
square, up to 800x800
10 seconds maximum
no audio track at all, not just muted
under roughly 2MB to be reliable

Miss any of these and you get the same silent nothing. The audio rule is the sneaky one: a video with a muted audio track still counts as having audio.

The FFmpeg Pipeline

ffmpeg does all the real work. For a center crop to square, the whole conversion is one command:

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

What each piece does:

crop='min(iw,ih)':'min(iw,ih)' takes the largest centered square, works for portrait and landscape
scale=800:800 downsizes to the avatar resolution
format=yuv420p converts 10-bit HDR footage to 8-bit; without it libx264 produces output Telegram rejects
-an strips the audio track completely
-movflags +faststart moves the moov atom to the front so the preview loads instantly
-t 10 hard-caps duration

For letterboxed input (screen recordings, clips with black bars) a center crop keeps the bars. cropdetect fixes that. Run a short analysis pass first:

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

It prints something like crop=1080:1080:0:420, which you drop into the filter chain of the encode pass in place of the min() expression.

The 2MB cap needs one more trick. CRF encoding doesn't target a file size, so I encode at crf 26 first, and if the output lands over 2MB I bump CRF by 3 and retry. Two retries cover every 10 second clip I've seen.

The aiogram 3 Handler

The bot side is small. Download the file, shell out to ffmpeg, send the result back:

import asyncio
import tempfile
from pathlib import Path

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

router = Router()

SQUARE = "crop='min(iw,ih)':'min(iw,ih)',scale=800:800,format=yuv420p"

@router.message(F.video | F.animation)
async def convert(message: Message, bot: Bot):
    src_file = message.video or message.animation

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

        proc = await asyncio.create_subprocess_exec(
            "ffmpeg", "-y", "-i", str(src), "-t", "10",
            "-vf", SQUARE,
            "-c:v", "libx264", "-preset", "slow", "-crf", "26",
            "-movflags", "+faststart", "-an", str(dst),
        )
        await proc.wait()

        await message.answer_video(
            FSInputFile(dst),
            caption="Done. Settings > Edit profile > set as video avatar",
        )

Details that matter:

create_subprocess_exec instead of subprocess.run, so one heavy encode doesn't block the event loop for every other user
F.animation catches GIFs, which Telegram already stores as silent MP4s, so the same pipeline handles them for free
Bot API caps downloads at 20MB, so check file_size before downloading and tell the user instead of failing mid-encode

Packaging It as a Bot

I wrapped this into @LiveAvaBot. The production version adds the CRF retry loop for the 2MB cap, cropdetect for letterboxed sources, and a small queue so parallel encodes don't flatten the VPS. 207 people have used it so far, most of them arriving right after Telegram silently ate their upload. That's the whole funnel: the app fails without explanation, people go looking, some land on the bot.

The stack is boring on purpose. One VPS, aiogram 3, ffmpeg from apt, SQLite for state. A typical 1080p iPhone clip encodes in 2 to 6 seconds at preset slow.

Edge Cases and Lessons

HDR colors go flat. format=yuv420p makes HDR footage valid but skips tone mapping, so colors wash out slightly. Proper tone mapping with zscale needs an ffmpeg build with zimg and costs real encode time. For a 10 second avatar nobody has complained yet.

Rotation metadata. iPhones store orientation as metadata instead of rotating pixels. Modern ffmpeg autorotates by default. If your output comes out sideways, your ffmpeg is old.

Muted is not silent. Early on I copied the audio stream when users had muted it in the iOS editor. The track was still present and Telegram rejected the file. Always -an.

Portrait crops cut heads. A centered square crop of a portrait video chops foreheads. I shift the crop window up for portrait input and the complaints stopped.

Next on the list: proper HDR tone mapping and letting users pick which part of the frame survives the crop.

Disclosure: I built @liveavabot, and the code above is a trimmed version of what runs in production.

If you've hit other undocumented corners of Telegram's media pipeline, tell me in the comments. I collect these.

Fixing iPhone HEVC Videos That Telegram Silently Rejects

liveavabot — Tue, 07 Jul 2026 17:02:36 +0000

The Avatar That Never Shows Up

You record a short clip on your iPhone, open Telegram, tap "Set profile video", pick the file. The upload spinner runs, finishes, and then nothing happens. No error message, no failed toast, no avatar. You try again and get the same nothing.

I hit this last year and burned a solid hour thinking my client was broken. It wasn't. iPhones have recorded in HEVC (H.265) by default since iOS 11, and Telegram's video avatar pipeline only accepts H.264. Instead of telling you that, the client silently drops the file. Same story with 10-bit HDR clips and anything in the wrong pixel format.

I ended up writing an ffmpeg wrapper, then a Telegram bot around the wrapper. This post is the build log.

What Telegram Actually Wants

The video avatar spec isn't written down in one place. I pieced it together from the Bot API docs, client behavior, and a lot of failed uploads. Here is what works reliably:

Video codec: H.264 with pixel format yuv420p. HEVC fails. 10-bit anything fails.
Resolution: square, 800x800 is the sweet spot. Non-square gets rejected.
Duration: 10 seconds max.
File size: roughly 2 MB in practice.
Audio: none. The avatar player has no sound, and files with an audio track get dropped.
Container: MP4 with the moov atom at the front (faststart), so playback starts instantly.

A stock iPhone clip fails on at least three of those. It's HEVC, it's 16:9 or 9:16, and it has an audio track. HDR clips add a fourth problem with 10-bit color.

The ffmpeg Pipeline

Two passes. First, cropdetect finds black bars (common when people screen-record or convert from other apps). Second, crop to square, scale down, convert the pixel format, encode H.264, strip audio, trim to 10 seconds.

# pass 1: find the active picture area (first 2 seconds is enough)
ffmpeg -i input.mov -vf "cropdetect=24:16:0" -t 2 -f null - 2>&1 \
  | grep -o 'crop=[0-9:]*' | tail -1

# pass 2: crop to square, scale to 800x800, encode, strip audio
ffmpeg -i input.mov \
  -vf "crop=1080:1080:0:420,scale=800:800,format=yuv420p" \
  -c:v libx264 -profile:v baseline -level 3.1 \
  -b:v 1200k -maxrate 1500k -bufsize 2000k \
  -t 10 -an -movflags +faststart \
  -y output.mp4

Notes on the flags:

format=yuv420p is the fix for HDR and 10-bit sources. Without it libx264 happily encodes yuv420p10le and Telegram drops the file.
-an strips audio. Forgetting this was my most common failure early on.
-movflags +faststart moves the moov atom to the front. Telegram sometimes accepts files without it, but playback stutters.
The bitrate ladder (1200k target, 1500k max) lands a 10-second 800x800 clip around 1.6 MB. If the output still exceeds 2 MB, I re-encode at 900k. Two attempts have covered every file I've seen so far.

If you don't care about black bars you can skip cropdetect and center-crop with crop='min(iw,ih)':'min(iw,ih)', which takes the largest centered square. That's the fallback my bot uses when cropdetect returns nothing useful.

Wiring It Into aiogram 3

The bot side is small. Accept a video, animation, or document, download it, run ffmpeg in a subprocess, send back the result.

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

router = Router()

@router.message(F.video | F.animation | F.document)
async def convert(msg: Message):
    file = msg.video or msg.animation or msg.document
    if file.file_size and file.file_size > 50 * 1024 * 1024:
        await msg.answer("50 MB limit, sorry.")
        return

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

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

        if proc.returncode != 0 or not os.path.exists(dst):
            await msg.answer("Conversion failed. Is the file actually a video?")
            return

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

Two things worth calling out. create_subprocess_exec takes an argument list, not a shell string, so weird filenames can't inject anything. And the whole job runs inside a TemporaryDirectory, so a crashed conversion doesn't leave junk on disk.

Shipping It as @liveavabot

I packaged this as @LiveAvaBot. You send it any video or GIF, it replies with an avatar-ready MP4, you save that file and set it as your profile video. No separate app, no upload site.

Current numbers, since this is a build log: 201 users, around 10 conversions a day. Small, but every one of those is someone who would otherwise be staring at that silent upload spinner.

The production version does a bit more than the snippet above: cropdetect with the center-crop fallback, the bitrate retry when output exceeds 2 MB, and GIF handling. Telegram delivers GIFs as MP4 "animations" already, but often in mpeg4 codec, so they still need re-encoding.

Edge Cases That Bit Me

Rotation metadata. iPhone stores orientation as a display matrix instead of rotating pixels. Modern ffmpeg autorotates on decode; the ffmpeg 4.x build on my first server did not, so portrait videos came out sideways. Check your ffmpeg version.
Variable frame rate. iPhone clips are VFR and some players choke after a re-encode. Adding -r 30 normalizes it and costs almost nothing.
HDR tone mapping. format=yuv420p makes 10-bit files encode, but HDR clips come out washed out without a tonemap filter. I currently accept the washed-out look. Proper tonemapping is on the list.
Zero-duration "videos". Some apps export files where the container claims 0 seconds. Run ffprobe first and reject early, it saves you a confusing ffmpeg error.

Next up is smarter handling of 4K sources (right now they just take longer than I'd like) and maybe animated emoji stickers, which use a related but stricter format.

If you've fought with Telegram's media formats and found other undocumented rules, I'd like to hear about them in the comments.

Built by me: @liveavabot.

Why iPhone HEVC Videos Silently Fail as Telegram Avatars

liveavabot — Sun, 05 Jul 2026 16:01:59 +0000

My girlfriend sent me a 4 second clip from her iPhone and asked me to set it as her Telegram profile video. Telegram accepted the upload, showed a spinner, then quietly kept the old static photo. No error message, nothing to google. The upload just evaporated.

The clip was HEVC (H.265), 1080x1920, 10-bit, straight from default iOS camera settings. Telegram's video avatar pipeline wants something very different, and when it doesn't get it, it fails without telling you what went wrong. I spent an evening figuring out the actual requirements, wrote an ffmpeg wrapper, and ended up shipping it as a bot. This post is the write-up.

What Telegram actually requires

The official docs on video avatars are thin. Most of this came from reading TDLib sources and brute-force testing:

Container: MP4
Video codec: H.264. HEVC gets rejected, even though Telegram plays HEVC fine in regular messages.
Resolution: square. 800x800 is what the official clients produce.
Duration: 10 seconds max.
File size: 2 MB max. Not 20. Two.
Audio: stripped entirely. A muted track is not enough, the stream has to be gone.
Pixel format: yuv420p. Modern iPhones record 10-bit HDR (yuv420p10le) and that fails.
moov atom at the front of the file (faststart), otherwise some mobile clients choke.

The 2 MB cap is the one that actually hurts. Ten seconds of 800x800 video in 2 MB gives you a total budget of about 1600 kbps. A default iPhone clip runs 15 to 50 Mbps. You are throwing away 95%+ of the original bitrate, so every encoding decision matters.

The ffmpeg pipeline

I run it in two passes. The first pass is cropdetect over the first 3 seconds, because letterboxed clips and screen recordings carry black bars that waste the tiny bitrate budget:

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

That prints something like crop=1080:1440:0:240. Then the real encode: apply the crop, scale so the short side hits 800, center-crop to a square, normalize to 30 fps and 8-bit yuv420p, cut at 10 seconds, strip audio:

ffmpeg -i input.mov -t 10 \
  -vf "crop=1080:1440:0:240,scale=-2:800,crop=800:800,fps=30,format=yuv420p" \
  -c:v libx264 -profile:v high -preset slow \
  -b:v 1400k -maxrate 1600k -bufsize 2000k \
  -an -movflags +faststart \
  output.mp4

Flag notes. -an removes the audio stream completely. -b:v 1400k with a 1600k maxrate leaves headroom so a full 10 second clip lands under 2 MB. format=yuv420p downconverts 10-bit HDR sources. -movflags +faststart relocates the moov atom to the front. -preset slow buys real quality at these starved bitrates, and on an 800x800 clip it costs only a few extra seconds of CPU.

If the output still overshoots 2 MB (busy footage with lots of motion does this), I retry once with the bitrate scaled down: new_bitrate = old_bitrate * (2_000_000 / actual_size) * 0.95. One retry has been enough for every real-world file I've seen.

Wiring it into aiogram 3

The bot side is small. Videos, GIFs (animations) and video files sent as documents all funnel into one handler:

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

router = Router()

@router.message(F.video | F.animation | F.document)
async def handle_media(message: Message):
    media = message.video or message.animation or message.document
    if media.file_size and media.file_size > 100 * 1024 * 1024:
        await message.answer("File too big, 100 MB max.")
        return

    status = await message.answer("Converting...")
    src = await download_file(message.bot, media.file_id)
    result = await convert_to_avatar(src)  # the ffmpeg pipeline above

    await message.answer_video(
        FSInputFile(result.path),
        caption=(
            f"{result.size_kb} KB, {result.duration:.1f}s. "
            "Save the file, then set it as your profile video "
            "in Settings > Edit Profile."
        ),
    )
    await status.delete()

convert_to_avatar runs ffmpeg through asyncio.create_subprocess_exec, so the event loop stays free while a 60 MB clip gets chewed through. One gotcha: Bot API file downloads cap at 20 MB unless you run a local Bot API server, which I do, because iPhone clips blow past 20 MB constantly.

Shipping it as @liveavabot

I packaged the pipeline as @LiveAvaBot. Send it any video or GIF, it replies with a ready file plus instructions. 193 people have used it so far, and iPhone HEVC clips are still the most common input, which matches the original itch.

The whole thing is one Python process: aiogram 3 plus ffmpeg plus a small queue so parallel conversions don't stack up on the VPS it runs on. ffmpeg is doing the heavy lifting, I just wrote the wrapper and the retry logic around it.

Edge cases that cost me time

Rotation metadata. iPhones record sensor-native and set a display matrix instead of rotating pixels. Modern ffmpeg autorotates before the filter chain, but if you build filters assuming the raw stream width and height, you'll compute crops for a sideways frame. I read dimensions after autorotation, not from the raw stream info.

GIF inputs. Palette GIFs with odd frame delays produce stuttery output unless you normalize with fps=30. Also, a "GIF" coming from Telegram is usually already an MP4 animation, so the extension means nothing.

10-bit HDR. Without format=yuv420p, some uploads got accepted and then rendered as green garbage on certain Android clients. Silent success turned out to be worse than silent failure.

Sub-second clips. Telegram accepts a 0.4 second avatar but the loop looks broken. The bot warns instead of refusing, people's call.

Next on the list is a trim picker, choosing which 10 seconds of a longer video to keep. Right now the bot takes the first 10, which is the wrong 10 about half the time.

Built by me: @liveavabot. Free to use, no signup, and the core of the ffmpeg pipeline is basically the two commands above.

Why iPhone Videos Silently Fail as Telegram Video Avatars

liveavabot — Fri, 03 Jul 2026 15:03:30 +0000

Last week someone sent me an iPhone clip and asked why Telegram wouldn't take it as a video avatar. The upload went through, the spinner finished, and then nothing. No error, no avatar, old photo still there. That silent failure is the whole reason this article exists.

The Silent Failure

iPhones have recorded in HEVC (H.265) by default since iOS 11. It saves storage, and it breaks in a lot of places that still expect H.264. Telegram's video avatar feature is one of them. Most clients accept the upload, show progress, and then quietly keep your old avatar. There's no toast and no log entry telling you the codec was the problem.

I lost an hour on this before I pulled the file into ffprobe and saw hev1 in the stream info. Once you know what Telegram actually wants, the fix is one ffmpeg command. Getting to that command took some digging, so here's all of it.

What Telegram Actually Requires

The spec is scattered across docs and client source code, so here it is in one place. A video avatar must be:

H.264 video in yuv420p pixel format (HEVC and 10-bit formats get dropped)
square, up to 800x800
10 seconds or shorter
no audio track at all (not muted, the stream has to be removed)
roughly 2MB or less, bigger files start failing on some clients

Miss any one of these and you get the silent rejection. A fresh iPhone clip fails the first check. A 16:9 clip fails the second. A clip with sound fails the fourth even if everything else is right. Most real-world files fail three of the five at once.

Cropping and Encoding with FFmpeg

Two problems to solve: get a square frame without squashing the subject, and re-encode to spec. I run cropdetect first because GIFs and re-uploaded clips often carry letterbox bars, then take the largest centered square.

# pass 1: detect letterbox bars (common on GIFs and re-encoded clips)
ffmpeg -i input.mov -vf cropdetect=24:16:0 -t 3 -f null - 2>&1 \
  | grep -o 'crop=[0-9:]*' | tail -1

# pass 2: center-square crop, scale, encode to spec
ffmpeg -i input.mov -t 9.5 \
  -vf "crop='min(iw,ih)':'min(iw,ih)',scale=800:800,format=yuv420p" \
  -c:v libx264 -profile:v baseline -preset veryfast -b:v 1200k \
  -movflags +faststart -an output.mp4

What each piece is doing:

crop='min(iw,ih)':'min(iw,ih)' takes the largest centered square from any aspect ratio. If pass 1 found bars, apply that crop first, then the square crop.
scale=800:800,format=yuv420p hits the resolution and pixel format requirements in one filter chain.
-an removes the audio stream entirely. Muting is not enough, the track has to be gone.
-movflags +faststart moves the moov atom to the front of the file so clients can play it while downloading.
-t 9.5 trims under the 10 second cap with a little margin. Exactly 10.0 is risky because container duration rounding can push it over.
Bitrate math: 2MB over 10 seconds is about 1600 kbps total budget. 1200k video leaves headroom for container overhead.

The Bot Handler in aiogram 3

Running this by hand gets old fast, so I wrapped it in a bot. Minimal aiogram 3 handler:

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

router = Router()

async def convert(src: str, dst: str) -> bool:
    vf = "crop='min(iw,ih)':'min(iw,ih)',scale=800:800,format=yuv420p"
    proc = await asyncio.create_subprocess_exec(
        "ffmpeg", "-y", "-i", src, "-t", "9.5",
        "-vf", vf, "-c:v", "libx264", "-profile:v", "baseline",
        "-b:v", "1200k", "-movflags", "+faststart", "-an", dst,
        stdout=asyncio.subprocess.DEVNULL,
        stderr=asyncio.subprocess.DEVNULL,
    )
    await proc.wait()
    return proc.returncode == 0 and os.path.getsize(dst) > 0

@router.message(F.video | F.animation)
async def handle_media(msg: Message):
    media = msg.video or msg.animation
    if media.file_size and media.file_size > 50 * 1024 * 1024:
        await msg.answer("50MB max, sorry.")
        return
    with tempfile.TemporaryDirectory() as tmp:
        src = os.path.join(tmp, "in")
        dst = os.path.join(tmp, "out.mp4")
        await msg.bot.download(media, destination=src)
        if not await convert(src, dst):
            await msg.answer("Conversion failed. Is this a valid video?")
            return
        await msg.answer_video(FSInputFile(dst))

Two details that matter. create_subprocess_exec keeps ffmpeg off the event loop, so the bot stays responsive while a conversion runs. And F.animation catches GIFs, which Telegram wraps as mp4 animations internally, so the same pipeline handles both.

Shipping It as @liveavabot

I packaged this as @LiveAvaBot. Send it any video or GIF, it returns the compliant mp4, and you set that file as your profile video from Telegram settings. 186 people have used it so far, and the most common input is exactly the case that started this: HEVC straight off an iPhone camera roll.

Edge Cases I Hit Along the Way

iPhone rotation. Portrait clips carry a display matrix instead of rotated pixels. ffmpeg 5+ autorotates on decode, older builds need an explicit transpose filter or your output comes out sideways.
GIFs with odd frame rates. Adding fps=30 to the filter chain keeps durations from drifting after encode.
The 2MB budget. Long busy clips blow past it at 1200k, so I retry at 900k, then 700k, before giving up.
HDR clips come out washed out after the yuv420p conversion. I don't tone map yet, it's on the list.
Animated stickers and WEBP are a different pipeline entirely. Not handled, probably never will be.

ffmpeg is doing the heavy lifting here, I just wrote the wrapper and the retry logic. Disclosure: built by me, @liveavabot.

If you've fought Telegram's other undocumented media specs (sticker WEBM requirements, anyone?), I'd like to hear how you figured out what the client actually accepts.

Why iPhone Videos Silently Fail as Telegram Video Avatars (and How to Fix It With ffmpeg)

liveavabot — Wed, 01 Jul 2026 14:03:48 +0000

I run a small Telegram bot called @liveavabot. It takes any video or GIF you send it and turns it into a Telegram video avatar. Sounds trivial. It's not, because Telegram's video-avatar format is picky in ways that aren't obvious until you fail three times in a row.

This post is the build log: what the spec actually requires, why iPhone videos silently fail, and the ffmpeg pipeline I settled on.

The spec Telegram never really documents

If you dig through the Bot API and the mobile client source, the constraints for a video avatar are:

Container: MP4 with faststart (moov atom at the front).
Video codec: H.264 (AVC). Baseline or main profile is safest.
Pixel format: yuv420p. Not yuv420p10le, not HDR.
Resolution: square, 800x800 works everywhere. Some clients accept 640x640.
Duration: at most 10 seconds.
File size: at most about 2 MB. Big files get rejected or heavily re-compressed.
Audio: must be stripped. Not muted, stripped.
Frame rate: 30 fps is fine. 60 fps sometimes trips older clients.

Send anything that misses one of these and the Telegram client will accept the upload, spin for a second, and then silently show the old avatar. No error toast. No log line you can see from your side.

Why iPhone videos in particular fail

Since iOS 11, the iPhone camera records in HEVC (H.265) inside a .mov container, with yuv420p10le pixel format for HDR captures. When a user shares that clip to the bot, Telegram forwards it as-is. Telegram's server then tries to remux it into an avatar. HEVC is not on the accepted list, so the client falls back to a still frame or drops the update entirely.

The user thinks they sent a video. The bot thinks it processed it. Telegram just quietly ignored it. This is the single most common bug report I got in the first month.

The fix is to re-encode every upload to H.264 + yuv420p before handing it back to Telegram, even if the input looks like an MP4 already. Trust nothing, transcode everything.

The ffmpeg pipeline

Here is the actual command the bot runs. Two passes: first cropdetect to find the tight bounding box, then encode.

# Pass 1: detect the crop box on a 2-second sample
ffmpeg -ss 0 -t 2 -i input.mov \
  -vf cropdetect=24:16:0 -f null - 2>&1 \
  | grep -oE 'crop=[0-9:]+' | tail -1
# -> crop=1080:1080:0:420

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

A few notes on the flags that matter:

-t 10 caps the output at 10 seconds. Users send 30-second clips all the time and I'd rather truncate than reject.
format=yuv420p in the filter chain, plus -pix_fmt yuv420p on the encoder, is belt-and-suspenders. HDR sources need both to actually get downconverted.
-an drops audio. Not -c:a copy, not -af volume=0. Strip it.
-movflags +faststart moves the moov atom to the start of the file so Telegram can begin decoding before the download finishes. Without this, the avatar often shows as a black square.
-crf 26 is my sweet spot. 23 blows past the 2 MB budget on busy scenes. 28 looks mushy.

The aiogram 3 handler

Wiring it into a bot is boring in a good way. Here's the minimal handler:

import asyncio
import tempfile
from pathlib import Path

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

router = Router()

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

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

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

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

        if proc.returncode != 0 or not dst.exists():
            await message.reply("couldn't convert this one, sorry")
            return

        await message.reply_video(FSInputFile(dst), caption="upload this via Settings, Edit profile, camera icon")

I dropped the two-pass cropdetect here and used scale + crop in one filter for simplicity. It handles portrait and landscape inputs by scaling the short side to 800 and center-cropping the long side. Good enough for 90 percent of uploads.

Packaging this as @liveavabot

The bot lives at https://t.me/LiveAvaBot?start=devto_article_20260701. Send it any video or GIF. It replies with a converted MP4 you can set as your Telegram video avatar. That's the whole product. No accounts, no menus, no upsell.

Infra is boring by design: a single 4 GB VPS, systemd unit for the aiogram process, ffmpeg from the Ubuntu repos. No queue, no worker pool. Each conversion is under a second for typical 5-second clips, so I just run them inline in the handler.

Edge cases I've hit

Live Photos on iPhone: they arrive as a still image plus a .mov. Handle the .mov, ignore the still.
Vertical videos: center-crop is fine for faces, terrible for full-body. I'm considering face-detection crop but it's not worth the dependency yet.
Animated WebP: .webp from stickers. ffmpeg handles it if you have libwebp built in. Ubuntu's package does.
10-bit HDR: covered by format=yuv420p in the filter chain. Without it, the encoder chokes with "pixel format not supported."
Files larger than 20 MB: Telegram's Bot API refuses the download. I catch this and ask the user to trim first.

What's next: batch mode (send a photo, get a 3-second Ken Burns pan as an avatar), and better handling of GIFs with palettes that go muddy after H.264 re-encode.

Built by me, @liveavabot. If you have a weird clip that breaks it, send it. That's how I find bugs.

Building a Telegram Video Avatar Converter with FFmpeg and Aiogram 3

liveavabot — Mon, 29 Jun 2026 13:03:39 +0000

The bug that ate my afternoon

I record a quick clip on my iPhone, open Telegram, tap the camera icon next to my profile, pick the video, hit set as avatar. Telegram thinks for a second, then shows the old avatar like nothing happened. No error, no toast, no log. The file is fine. It plays in Photos. It uploads to other chats. But as a video avatar, it gets silently rejected.

The culprit: iPhone shoots in HEVC (H.265) by default since iOS 11. Telegram's video avatar slot accepts only H.264 in an MP4 container, plus a stack of other constraints that are not documented in any user-facing place. The mobile app does not tell you why the upload was rejected, it just discards it.

I built @LiveAvaBot to fix that one specific paper cut. You send any video or GIF, the bot returns a Telegram-ready video avatar. Here is how the pipeline works.

What Telegram actually wants

The official Bot API docs are vague, but reverse-engineering the desktop client plus a lot of trial and error gives you the real spec for video avatars:

Container: MP4 with faststart (moov atom at the front)
Video codec: H.264 (libx264), yuv420p pixel format
Resolution: exactly 800x800, square
Duration: at most 10 seconds
File size: at most 2 MB
Audio: must be stripped entirely (no silent audio track, just no track at all)
Framerate: anything up to 30 fps is safe, I default to 25

Miss any one of these and the upload gets silently dropped. The 2 MB cap is the meanest one because it forces you to compromise between duration, resolution detail, and bitrate.

The ffmpeg recipe

The conversion is two passes. First, I run cropdetect to find the largest square inside the input. Most videos are 16:9 or 9:16, so naive center-crop loses important content. Cropdetect catches letterboxes and lets me crop a tighter square around the actual subject.

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

That spits out something like crop=1080:1080:420:0. I parse the four numbers, pick a square region, then run the real encode:

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

Key flags worth calling out:

-t 10 clamps duration to 10 seconds. Telegram rejects anything longer.
crop=W:H:X:Y then scale=800:800:flags=lanczos gives a clean 800x800 with decent downscaling.
format=yuv420p is non-negotiable. yuv444 or yuv422 will be silently rejected even though the file plays fine elsewhere.
-crf 28 -preset slow hits the 2 MB target for most 10 second clips. For longer or busier scenes I drop crf to 30 and re-encode.
-movflags +faststart puts the moov atom at the start of the file, otherwise Telegram clients hang on the first frame.
-an strips audio. Even a silent AAC track will cause rejection.

If the encoded file overshoots 2 MB I bump crf in steps of 2 and retry, up to crf 36. Past that I shorten duration. So far the loop terminates in at most three retries on real inputs.

The aiogram 3 handler

The bot is a single file in spirit, though I split it for testability. Here is the trimmed video handler:

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

router = Router()

@router.message(F.video | F.video_note | F.animation | F.document)
async def handle_video(message: Message) -> None:
    file_id = (
        message.video.file_id if message.video
        else message.video_note.file_id if message.video_note
        else message.animation.file_id if message.animation
        else message.document.file_id
    )

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

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

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

        await message.answer_video(
            FSInputFile(dst),
            width=800,
            height=800,
            caption="Set this as your Telegram video avatar in Settings > Edit profile.",
        )

async def convert_to_avatar(src: Path, dst: Path) -> bool:
    crop = await detect_crop(src)
    crf = 28
    while crf <= 36:
        await run_ffmpeg(src, dst, crop, crf)
        if dst.stat().st_size <= 2 * 1024 * 1024:
            return True
        crf += 2
    return False

detect_crop shells out to the cropdetect command from earlier and parses the last crop= line. run_ffmpeg is a thin asyncio.create_subprocess_exec wrapper around the encode command. Nothing exotic, just gluing ffmpeg to aiogram.

The handler accepts video, video_note, animation, and document because users send videos as any of those four types depending on the client. The document branch covers people who attached the .mov file directly to bypass Telegram's compression.

Shipping it as @liveavabot

The pipeline runs on a small Hetzner VPS. ffmpeg is doing the heavy lifting, I just wrote the wrapper. Total Python is maybe 400 lines including error handling and a sqlite log of conversions.

A few production-only things I learned the hard way:

Always use a tempdir per request. I started with a shared workdir and got mysterious failures under concurrent uploads.
aiogram 3's FSInputFile is the right primitive for sending the result back. BufferedInputFile works too but doubles memory for no reason.
Telegram's send_video has width and height arguments. If you do not pass them the desktop client picks a weird thumbnail. Pass 800, 800.
Keep ffmpeg stderr in a buffer and log it on non-zero exit. cropdetect failures are usually a malformed input rather than a bug in your pipeline.

You can try it at https://t.me/LiveAvaBot?start=devto_article_20260629. Send a video or a GIF, get back a Telegram-ready avatar in a few seconds.

What is next

The current pipeline does not handle 4K input gracefully, it just downscales and hopes for the best. I want to add a smart pre-scale step for anything above 1080p so cropdetect runs faster on the source. I also want to expose a mode where you can nudge the crop interactively instead of trusting cropdetect blindly.

The cropdetect threshold (24 in the command above) is also tuned for typical phone footage. Screen recordings with dark UI elements sometimes confuse it. If your input is mostly UI, drop the threshold to 16 or it will crop too aggressively.

Built by me, @LiveAvaBot is the Telegram side.