DEV Community: liveavabot

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.

Fixing Telegram Video Avatars: HEVC, ffmpeg, and aiogram 3

liveavabot — Thu, 08 Oct 2026 12:03:31 +0000

The Problem: iPhone Videos Silently Fail

Setting a video avatar in Telegram sounds trivial. Open the app, tap your profile, upload a short clip. But if you recorded that clip on an iPhone, there's a good chance Telegram will silently refuse it with no useful error message.

The reason is HEVC (H.265). iPhones have recorded in HEVC by default since iOS 11, and Telegram's video avatar pipeline doesn't support it. You don't get "wrong codec." You get nothing. The upload just fails.

I hit this myself while testing a channel. After about 20 minutes of confusion, I started digging into what Telegram actually requires.

What Telegram Actually Requires

Here are the hard constraints for a Telegram video avatar:

Codec: H.264 (not HEVC, not VP9, not AV1)
Resolution: 800x800 pixels, square
Duration: 10 seconds max
File size: 2 MB max
Audio: none (must be stripped or the upload fails)
Container: MP4 with the faststart flag for streaming

That last one trips people up. faststart moves the moov atom to the front of the MP4 file so Telegram can start processing before the full download completes. Without it, some uploads fail silently.

The codec constraint is the main issue. HEVC footage from iPhone needs to be re-encoded to H.264, and the resolution needs to be cropped to a square before scaling. A naive scale to 800x800 on portrait video produces letterboxing, which looks bad as an avatar.

How ffmpeg Handles It

ffmpeg's cropdetect filter finds the natural crop bounds of a video. You can chain it with scale and format conversion in a single pass.

Here's the command I settled on after testing with a batch of iPhone clips:

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

Walk-through of the key flags:

scale=800:800:force_original_aspect_ratio=increase scales the video so the shorter dimension reaches 800px, then crop=800:800 cuts it square.
libx264 re-encodes from HEVC to H.264.
yuv420p forces 4:2:0 chroma subsampling. Without this, H.264 output from some sources uses 4:4:4, which Telegram rejects silently.
-t 10 trims to 10 seconds max.
-an strips all audio tracks.
+faststart relocates the moov atom to the file header.

CRF 28 gives decent quality at small file size. For a 10-second 800x800 clip that's usually well under 2 MB. If the output goes over, I retry with CRF 30 or add a bitrate cap (-b:v 800k).

One edge case I didn't expect: vertical iPhone videos shot in 60fps HEVC. The first few frames have a partial black region from the auto-exposure ramp, which throws off cropdetect. I now skip the first 15 frames: cropdetect=24:2:15.

aiogram 3 Handler

Here's a minimal handler that accepts a video or GIF, converts it, and replies with the processed file:

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

router = Router()

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

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

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

        await message.bot.download_file(tg_file.file_path, input_path)

        cmd = [
            "ffmpeg", "-i", input_path,
            "-vf", "scale=800:800:force_original_aspect_ratio=increase,crop=800:800",
            "-c:v", "libx264", "-preset", "fast", "-crf", "28",
            "-pix_fmt", "yuv420p",
            "-t", "10", "-an", "-movflags", "+faststart",
            "-y", output_path
        ]
        result = subprocess.run(cmd, capture_output=True, timeout=60)

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

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

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

This is simplified. The real bot handles the 20 MB download cap (Telegram's limit for bots without the local API server), retries, and a two-pass cropdetect. But the structure is the same.

One migration note: aiogram 3 uses F.video | F.animation | F.document for content type filters. The old content_types= argument from aiogram 2 is gone. That's a common breakage point if you're upgrading.

How I Packaged This as @liveavabot

The bot has been running for a few months and now has around 450 users. It handles iPhone MOV files, Android MP4s, GIFs, and the occasional WebM someone drags in from a browser.

The pipeline per request:

Receive file via aiogram 3
Download to a temp directory
Run ffmpeg: cropdetect pass, then encode pass
Check output size, retry with lower CRF if over 2 MB
Send the MP4 back
Clean up temp files

You can try it at https://t.me/LiveAvaBot?start=devto_article_20261008.

Lessons and What's Next

A few things I'd do differently starting over:

Temp file handling. Initially I used tempfile.NamedTemporaryFile directly in handlers. Concurrent requests stepped on each other. tempfile.TemporaryDirectory() as a context manager is cleaner and cleans up even on exceptions.

ffmpeg timeout. Some clips have corrupt headers that make ffmpeg hang indefinitely. subprocess.run(..., timeout=60) is a must. Without it, the bot eventually wedges itself on a bad file.

The yuv420p flag. I missed this in the first version. Telegram rejected about 15% of outputs with no error message. Adding -pix_fmt yuv420p fixed all of them. It's worth adding even if you don't think you need it.

What's next: a preview step where the bot sends a 3-second thumbnail before converting the full clip. That would help users pick the right moment in longer videos without running the full encode.

ffmpeg is doing most of the heavy lifting here. The bot is just a thin wrapper that moves files around and calls the right flags in the right order. Built by me, @liveavabot is a personal side project and free to use.

Why iPhone Videos Silently Fail as Telegram Avatars

liveavabot — Mon, 05 Oct 2026 04:04:48 +0000

The problem nobody talks about

You record a short clip on your iPhone, open Telegram, tap "set video avatar", upload, and nothing happens. No error, no toast, just the old photo sitting there. I hit this once before I got curious.

The culprit is HEVC. Since iOS 11 the default camera codec is H.265 (HEVC), and Telegram's video avatar pipeline rejects HEVC without telling you. The upload "succeeds" because the file reaches the server, but the server side validator throws it out.

What Telegram actually wants

The video avatar spec is strict and not well documented. After some trial and error on what gets accepted, here is the shortlist:

Codec: H.264 (AVC), profile baseline or main
Pixel format: yuv420p, not yuv420p10le
Container: MP4 with faststart
Resolution: 800x800, square
Duration: 1 to 10 seconds
File size: under 2 MB
Audio: must be absent, not just muted

Miss any of these and the avatar silently reverts. The "under 2 MB" one is brutal: a 9 second 800x800 clip at reasonable bitrate often lands at 3 MB and gets dropped.

FFmpeg does the heavy lifting

The pipeline I settled on has two passes. First, cropdetect to find the content bounding box on vertical phone video so I can square crop without black bars. Second, scale and encode.

# Pass 1: detect crop box over 2 seconds
ffmpeg -hide_banner -ss 0 -t 2 -i input.mov \
  -vf "cropdetect=24:16:0" -f null - 2>&1 \
  | grep -o "crop=[0-9:]*" | tail -1
# -> crop=1080:1080:0:420

# Pass 2: encode to Telegram safe MP4
ffmpeg -y -i input.mov -t 9.5 \
  -vf "crop=1080:1080:0:420,scale=800:800:flags=lanczos,format=yuv420p" \
  -c:v libx264 -profile:v main -preset slow -crf 28 \
  -movflags +faststart -an output.mp4

A few things worth calling out:

-an strips audio entirely. Mute is not enough, the stream has to be gone.
-movflags +faststart moves the moov atom to the front so the server can validate without downloading the whole file.
-crf 28 sits in a sweet spot for 800x800 clips: visibly fine, usually under 2 MB for 8 to 10 second content. For longer clips drop to 30 or trim duration.
lanczos for scaling because bilinear on faces looks mushy.

If the output still exceeds 2 MB after this, I either shorten the clip or bump CRF to 30 or 32 and re-encode. That retry loop runs once in maybe 15 percent of uploads.

Aiogram 3 handler

Here is a minimal handler that catches an incoming video or document, pipes it through the ffmpeg converter, and sends the result back. Error handling trimmed for brevity.

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

router = Router()

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

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

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

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

        await message.answer_video(
            FSInputFile(dst),
            caption="Set this as your video avatar in Settings, Edit Profile.",
        )

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

The real bot does a bit more: size check retry loop, cropdetect fallback for very dark clips, user facing progress on long files. The skeleton above is what makes the thing work end to end.

Packaging it as a bot

I wrapped this into a Telegram bot and let it sit on a small VPS. Send any clip, get back a video avatar ready to upload. It handles HEVC from iPhones, portrait from Android, square clips, GIFs, even old DV footage from a mini-DV tape I digitized recently (that was fun).

Try it: @LiveAvaBot

If you just want the ffmpeg one liner for your own scripts, the two commands above are the whole product. The bot wrapper is convenience.

Lessons and edges

A few things I did not expect going in:

iPhone portrait video has a rotation flag, not a rotated raster. ffmpeg honors the flag by default on recent builds, older builds need -vf transpose=1 or the output is sideways. Pin a known ffmpeg version in your Docker image.
GIFs loop by default inside Telegram, so I keep looping behavior intact in the MP4 by not setting an audio track and letting the player decide.
Users sometimes send 4K ProRes from pro cameras. Those files are 400 MB. I reject anything over 50 MB before download instead of waiting through a slow upload to the bot.
Animated WebP from stickers is a trap. Treat it as an animation but convert the frame rate explicitly, otherwise you get a static frame.

Next thing I want to add is a face centered square crop for portrait clips where the subject sits in the bottom third. Current heuristic uses cropdetect only, which centers on content density, not faces. Probably mediapipe or a tiny ONNX model, still deciding.

Built by me, @liveavabot.

How I Converted iPhone HEVC Videos Into Telegram Video Avatars

liveavabot — Sat, 03 Oct 2026 03:04:33 +0000

The pain nobody mentions

I recorded a short clip on my iPhone, dragged it into the Telegram "set video avatar" dialog, and nothing happened. The app accepted the file, pretended to upload it, then quietly fell back to a still frame. No error message.

The problem turned out to be HEVC. iPhones record H.265 by default since iOS 11. Telegram's video avatar endpoint will not touch H.265. It expects H.264, square frame, under 10 seconds, under 2MB, no audio track. Nothing in the UI tells you this.

I lost two hours before I found the spec buried in a Telegram Core page. Then I spent a weekend building a bot that does the conversion in one tap. This post is the writeup.

What Telegram actually wants

The constraints for a Telegram video avatar are strict:

Codec: H.264, yuv420p pixel format.
Container: MP4 with faststart flag.
Resolution: square. Telegram officially supports 640x640, but 800x800 works fine and looks sharper.
Duration: 3 to 10 seconds.
Size: under 2MB.
Audio: must be removed entirely, not just muted.

If any one of these fails, Telegram silently reverts to the first frame as a static picture. No upload error. The video just does not play when someone taps your avatar.

Most phone-recorded clips fail on at least three of these: HEVC codec, non-square aspect ratio, audio present, size over 2MB.

FFmpeg does the heavy lifting

The conversion is a single ffmpeg pipeline. I run cropdetect first on a 2-second sample to pick a square crop centered on motion, then re-encode with a size target.

Here is the actual command the bot uses:

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

Breaking that down:

crop=min(iw,ih):min(iw,ih) makes the output square by taking the shortest side.
scale=800:800 resizes to 800x800.
fps=30 caps the framerate so a 60fps iPhone clip does not blow up the file size.
format=yuv420p is the pixel format Telegram wants. Without this, H.264 Main profile can still fail.
-c:v libx264 picks the right codec. HEVC input is transcoded here.
-preset veryfast -crf 28 is my size vs quality compromise. For a 10 second clip at 800x800, it lands around 1.5MB.
-an drops audio. Telegram requires this.
-movflags +faststart moves the moov atom to the front so Telegram can start playing before the whole file is downloaded.
-t 9.5 hard-caps duration to 9.5 seconds, under the 10s limit with a safety margin.

If the result is still over 2MB (long clips, lots of motion), I retry with -crf 32. Two retries at most, then I give up and tell the user to send a shorter clip.

The aiogram 3 handler

The bot runs on aiogram 3. The handler takes a video or document message, saves the file, runs ffmpeg, and sends the result back.

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

router = Router()

async def convert(src: Path, dst: Path, crf: int = 28) -> None:
    cmd = [
        "ffmpeg", "-y", "-i", str(src),
        "-vf",
        "crop=min(iw\\\\,ih):min(iw\\\\,ih),scale=800:800,"
        "fps=30,format=yuv420p",
        "-c:v", "libx264", "-preset", "veryfast", "-crf", str(crf),
        "-an", "-movflags", "+faststart", "-t", "9.5",
        str(dst),
    ]
    proc = await asyncio.create_subprocess_exec(
        *cmd,
        stdout=asyncio.subprocess.DEVNULL,
        stderr=asyncio.subprocess.PIPE,
    )
    _, err = await proc.communicate()
    if proc.returncode != 0:
        raise RuntimeError(err.decode()[-500:])

@router.message(F.video | F.animation | F.document)
async def handle_video(msg: Message) -> None:
    file = msg.video or msg.animation or msg.document
    if file.file_size and file.file_size > 50 * 1024 * 1024:
        await msg.reply("File is over 50MB, send a shorter clip.")
        return

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

        for crf in (28, 32):
            await convert(src, dst, crf=crf)
            if dst.stat().st_size <= 2 * 1024 * 1024:
                break
        else:
            await msg.reply("Could not get under 2MB. Try a shorter clip.")
            return

        await msg.answer_video(
            FSInputFile(dst),
            caption=(
                "Done. Open Telegram settings, tap your avatar, "
                "pick this video."
            ),
        )

A few notes:

F.video | F.animation | F.document catches all three ways users send videos. GIFs arrive as animation. Dragged files arrive as document.
The 50MB cap is bot-side. Telegram's bot API maxes at 20MB for direct downloads, 50MB with a workaround. For larger files I use the full file API.
Running ffmpeg as a subprocess with asyncio.create_subprocess_exec keeps the event loop responsive. One worker per message is fine for low traffic. For higher volumes I would put ffmpeg behind a work queue.

Packaging this as a bot

I ran this as a local script for a week, converting clips for myself. Then I turned it into a public bot: @LiveAvaBot.

Current numbers: 441 users, running on a single Hetzner box. ffmpeg eats CPU for about 2 seconds per clip, which is the main bottleneck. Storage cost is zero because files are deleted right after upload.

The bot is free and has no account step. Send a video, get a converted file back. If you want the result applied automatically, the Bot API cannot change your profile picture for you, so you still have to tap "Set" in Telegram settings yourself.

Edge cases and what is next

Things that broke in the first week:

Portrait clips with text at the bottom got cropped weird. I added a cropdetect pass that biases toward the face region if one is detected. Still not perfect.
Very dark clips at crf 28 looked grainy. I bumped the minimum to crf 26 for clips under 5 seconds.
Telegram's animation type for GIFs sometimes has no audio stream, which made ffmpeg log scary warnings. The warnings are safe to ignore, but I had to parse stderr more carefully to catch real errors.
Some HEVC clips with 10-bit color (yuv420p10le) needed an explicit -pix_fmt yuv420p on top of the vf filter chain. Without it, libx264 complained about input format.

What I want to add next: a scene-aware auto-trim that picks the most interesting 9.5-second window instead of just taking the first 9.5 seconds. ffmpeg has select='gt(scene,0.3)' for this. I just have not shipped it yet.

Built by me, @LiveAvaBot.

Converting iPhone HEVC Videos to Telegram Video Avatars with FFmpeg

liveavabot — Thu, 01 Oct 2026 02:03:28 +0000

The problem: iPhone videos fail silently as Telegram avatars

Telegram added video avatars a while back. You can set a short looping clip as your profile picture or channel icon. Nice feature. Except when I tried to upload a video shot on my iPhone, Telegram just rejected it without an error message. The file picker closed, nothing happened.

The culprit is HEVC (H.265). iPhones record in HEVC by default since iOS 11. Telegram's clients only accept H.264 for video avatars. There is no in-app transcoder, no "convert and try again" dialog. The upload just dies.

I built @LiveAvaBot to fix this. Send any video or GIF, get back a Telegram-compliant video avatar. Here is how the pipeline works.

What Telegram actually accepts for video avatars

The spec is strict and poorly documented. After reading BotAPI docs, Telegram Desktop source hints, and doing a lot of trial and error, this is what works:

Codec: H.264 (libx264), yuv420p pixel format.
Container: MP4 with faststart flag (moov atom at the front).
Resolution: exactly 800x800, square.
Duration: up to 10 seconds.
File size: up to 2 MB.
Audio: must be stripped. Telegram rejects clips with an audio stream even when the stream is silent.
Framerate: 25 to 30 fps works best. Higher pushes file size over 2 MB.

If you miss any of these, the upload fails. HEVC is the most common blocker, but I have also seen 1080p 60fps clips rejected because they were 3 MB.

Fixing it with ffmpeg: cropdetect, scale, re-encode

The core of the bot is an ffmpeg pipeline. Two passes. First pass runs cropdetect to find the center of the video, so a portrait clip gets cropped to a square around the subject, not around empty space. Second pass does the actual encode.

# Pass 1: find crop box
ffmpeg -ss 0 -t 3 -i input.mov \
  -vf "cropdetect=round=2" \
  -f null - 2>&1 | grep -oE 'crop=[0-9:]+' | tail -1

# Example output: crop=1080:1080:0:420
# That is width:height:x:y

Then feed that crop into the real encode:

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

Quick breakdown of the flags that matter:

crop=W:H:X:Y applies the box from cropdetect.
scale=800:800:flags=lanczos resizes to the exact square Telegram wants. Lanczos keeps edges sharp.
format=yuv420p forces 8-bit chroma subsampling. Without this, iPhone HEVC comes through as yuv420p10le and some decoders choke.
-c:v libx264 -preset veryfast -crf 28 is the sweet spot for file size vs quality on short clips. CRF 28 gets most clips under 2 MB.
-t 10 caps duration.
-movflags +faststart moves the moov atom to the front so Telegram can parse metadata before downloading the full file.
-an drops audio.

If the file still comes out over 2 MB after this (long high-detail clips sometimes do), the bot does a second pass with CRF 32. Rarely needed in practice.

Wiring it into an aiogram 3 handler

The bot is aiogram 3. Here is the trimmed-down handler:

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

router = Router()

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

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

        crop = await detect_crop(src)
        ok = await encode(src, dst, crop)
        if not ok:
            await message.answer("couldn't convert this one, sorry")
            return

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

async def encode(src: Path, dst: Path, crop: str) -> bool:
    cmd = [
        "ffmpeg", "-y", "-i", str(src),
        "-vf", f"{crop},scale=800:800:flags=lanczos,format=yuv420p",
        "-c:v", "libx264", "-preset", "veryfast", "-crf", "28",
        "-t", "10", "-r", "30",
        "-movflags", "+faststart", "-an",
        str(dst),
    ]
    proc = await asyncio.create_subprocess_exec(
        *cmd,
        stdout=asyncio.subprocess.DEVNULL,
        stderr=asyncio.subprocess.DEVNULL,
    )
    return (await proc.wait()) == 0

A few things worth noting.

The handler accepts F.video, F.animation (that is GIFs, which Telegram sends as MP4), and F.document (users often send videos as uncompressed files to preserve quality). All three paths go through the same pipeline.

detect_crop is a separate async function that runs the cropdetect pass and parses the last crop=... line from stderr. It falls back to a center crop when detection fails on blank or very dark clips.

The temp directory gets cleaned up automatically when the with block exits. Even if ffmpeg crashes.

Packaging as @liveavabot

I wrapped the pipeline in a small aiogram 3 bot, added a SQLite table for conversion counts, and shipped it on a cheap VPS. Running for a few months now, around 437 users, no incidents. ffmpeg is doing the heavy lifting here, I just wrote the glue and handled the edge cases.

If you want to try it on your own clips: https://t.me/LiveAvaBot?start=devto_article_20261001

The bot is free. No ads, no sign-up. Send a video, get back an MP4 you can set as your profile picture or channel avatar.

Edge cases and what is next

A few things I hit along the way.

GIFs with palette artifacts. Telegram sends animated GIFs as MP4, but some clients re-encode them with weird palettes. Adding format=yuv420p after scale fixes most of them.

Portrait vs landscape. Portrait clips need a vertical center crop around the subject. Cropdetect handles this if there are letterbox bars. If not, I default to a center square and accept that some content gets cut off.

Very short clips. Anything under 1 second loops weirdly as an avatar. I pad to 3 seconds by slowing playback with setpts=3*PTS for clips under that threshold.

4K source. Have not tackled this yet. The resize works, but encoding time blows past the handler's 60-second timeout on cheap VPS hardware. On the todo list.

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

Happy to answer questions in the comments if you are building something similar.

Converting iPhone HEVC Videos Into Telegram Video Avatars

liveavabot — Tue, 29 Sep 2026 01:07:33 +0000

The Problem Nobody Documents

Telegram video avatars loop silently on your profile when they work. But try uploading a video shot on an iPhone and Telegram silently ignores it. No error, nothing.

The culprit is HEVC (H.265). iPhone has defaulted to recording in HEVC since iOS 11. Telegram's video avatar endpoint only accepts H.264 with yuv420p colorspace, 800x800 resolution, no audio track, under 10 seconds, under 2 MB. Send anything else and the server accepts the upload but treats it as a regular file, not a video profile.

I ran into this while building @liveavabot. Users kept sending videos and asking why the bot wasn't working. Most of them were on iPhones.

What Telegram Actually Requires

The official TDLib docs are sparse, but testing against the actual endpoint reveals the constraints:

Codec: H.264 (libx264). Not H.265, VP9, or AV1.
Colorspace: yuv420p. Not yuv420p10le, not yuv444p.
Resolution: exactly 800x800 pixels.
Duration: 10 seconds maximum.
File size: 2 MB maximum.
Audio: none. Any audio track causes silent rejection.
Container: .mp4 with the faststart flag set.

The faststart flag trips people up. Without it, the moov atom sits at the end of the file. Telegram's server reads sequentially and gives up before it reaches the video metadata.

The ffmpeg Pipeline

Two passes: first detect crop bounds to remove letterboxing, then encode to spec.

Step 1: Detect crop bounds

ffmpeg -i input.mov -vf cropdetect=24:2:0 -t 5 -f null - 2>&1 | grep "crop="
# typical output: crop=1080:1080:0:0

This runs 5 seconds through cropdetect. The output gives width, height, x offset, y offset of the content area. iPhone portrait video is usually already square, but landscape videos from other sources often have black bars baked in.

Step 2: Encode to spec

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

scale with force_original_aspect_ratio=decrease shrinks without stretching non-square content. pad centers the result in an 800x800 canvas with black fill if needed. setsar=1 resets the sample aspect ratio so downstream players don't miscalculate dimensions.

-crf 28 with -preset fast gives a reasonable size/quality tradeoff. For clips close to the 10-second limit you may need -crf 34 to stay under 2 MB.

-pix_fmt yuv420p explicitly forces 8-bit 4:2:0. iPhone ProRes and some HEVC recordings use 10-bit colorspace. libx264 can encode 10-bit, but Telegram's parser rejects yuv420p10le.

The aiogram 3 Handler

Here's a minimal version. The real bot adds a two-pass crop detection step and a job queue, but this covers the core conversion logic:

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

router = Router()

async def to_avatar(in_path: str, out_path: str, crf: int = 28) -> bool:
    cmd = [
        "ffmpeg", "-y", "-i", in_path,
        "-vf", (
            "scale=800:800:force_original_aspect_ratio=decrease,"
            "pad=800:800:(ow-iw)/2:(oh-ih)/2,setsar=1"
        ),
        "-t", "10",
        "-c:v", "libx264", "-crf", str(crf), "-preset", "fast",
        "-pix_fmt", "yuv420p", "-an",
        "-movflags", "+faststart",
        out_path,
    ]
    proc = await asyncio.create_subprocess_exec(
        *cmd, stderr=asyncio.subprocess.PIPE
    )
    await proc.communicate()
    return proc.returncode == 0 and os.path.getsize(out_path) <= 2 * 1024 * 1024

@router.message(F.video | F.document | F.animation)
async def handle_video(message: Message):
    status = await message.answer("Converting...")
    media = message.video or message.document or message.animation
    file = await message.bot.get_file(media.file_id)

    with tempfile.NamedTemporaryFile(suffix=".mp4", delete=False) as tmp:
        in_path = tmp.name
    out_path = in_path.replace(".mp4", "_avatar.mp4")

    try:
        await message.bot.download_file(file.file_path, in_path)
        ok = await to_avatar(in_path, out_path)
        if not ok:
            ok = await to_avatar(in_path, out_path, crf=34)
        if ok:
            await message.answer_video(FSInputFile(out_path))
            await status.delete()
        else:
            await status.edit_text("Conversion failed or output too large.")
    finally:
        for p in (in_path, out_path):
            try: os.unlink(p)
            except FileNotFoundError: pass

F.animation handles GIFs. Telegram stores animated GIFs as MPEG4 internally, but if a GIF arrives as a file attachment rather than a native GIF send, it comes through as a Document type. Filtering on both document and animation covers most cases.

How @liveavabot Packages This

A few extra layers on top of the core conversion:

Queuing. ffmpeg is CPU-heavy. I use asyncio.Semaphore(3) to cap simultaneous conversions. Requests beyond that limit queue and wait.

Cooldown. A 60-second per-user cooldown prevents queue exhaustion. The bot runs on a single shared VPS.

Size retry. The handler above shows the crf fallback. The real implementation also tries tighter crop parameters before giving up on files that remain over 2 MB after crf 34.

Try it: https://t.me/LiveAvaBot?start=devto_article_20260929. Send any video or GIF and it returns an 800x800 H.264 file ready to set as a Telegram video avatar.

What I Learned

The biggest surprise was yuv420p10le. I spent an afternoon on a user report where output looked correct locally but Telegram rejected it. The video came from a ProRes recording. ffprobe showed pix_fmt=yuv420p in the output, but -pix_fmt yuv420p was silently falling back on some libx264 builds. Adding -vf format=yuv420p before the scale filter made the behavior consistent.

The crop detection pass was not in the original design. I added it after a batch of 16:9 landscape videos arrived with black bars baked into the sides. Without cropping first, the 800x800 output had black borders inside the frame.

GIFs are a minor ongoing edge case. Some large GIFs converted server-side by Telegram arrive as documents with mime_type=video/mp4 but without the animation flag properly set. The handler above covers most of these. The rest I log and review manually.

The bot has 433 users as of this writing. The most common use case, by far, is iPhone users who couldn't figure out why Telegram kept silently rejecting their video.

Built by me: @liveavabot

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

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

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

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

What Telegram Actually Requires

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

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

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

The ffmpeg Pipeline

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

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

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

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

Key flags:

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

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

aiogram 3 Handler

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

router = Router()

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

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


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

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

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

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

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

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

Packaging This as @liveavabot

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

A few things I added after the first 100 users:

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

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

Edge Cases and Loose Ends

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

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

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

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

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

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

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

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

The Problem Nobody Explains

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

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

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

What Telegram Actually Requires

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

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

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

ffmpeg Pipeline: Cropdetect, Scale, Encode

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

Detect crop parameters first:

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

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

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

A few decisions worth explaining:

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

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

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

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

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

The aiogram 3 Handler

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

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

router = Router()

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

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

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

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

        result = encode_for_avatar(src, dst)

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

    await status.delete()


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

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

    return {"ok": True}

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

Packaging It as @liveavabot

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

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

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

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

Built by me: @liveavabot

Edge Cases Worth Knowing

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

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

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

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

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

How to Convert iPhone HEVC Video to Telegram Video Avatar

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

The Bug I Didn't Expect

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

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

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

What Telegram Actually Requires

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

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

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

The ffmpeg Pipeline

The naive approach:

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

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

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

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

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

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

Key flags:

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

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

The aiogram 3 Handler

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

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

router = Router()


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

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

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


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

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

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

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

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

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

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

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

How I Packaged It as @liveavabot

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

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

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

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

Edge Cases Worth Knowing

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

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

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

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

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

Why iPhone Videos Silently Fail as Telegram Avatars

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

The Silent Failure

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

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

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

What Telegram Actually Requires

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

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

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

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

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

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

The ffmpeg Pipeline

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

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

A few things worth explaining:

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

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

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

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

A Minimal aiogram 3 Handler

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

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

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

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

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

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

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

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

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

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

Edge Cases Worth Knowing

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

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

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

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

What's Next

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

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

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

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