Fix iPhone HEVC Videos for Telegram Avatars

Resumen

Pixel shares a practical guide to fixing iPhone HEVC videos that Telegram rejects as video avatars. It explains Telegram’s requirements—H.264, 800×800 resolution, up to 10 seconds, under 2MB, and no audio—and provides an ffmpeg command to crop and convert clips.

DEV Community

How I Fixed iPhone HEVC Videos for Telegram Video Avatars

The Problem You record a video on your iPhone and try to set it as your Telegram video avatar. Telegram silently rejects it. No error, no dialog, just nothing happens. The culprit is HEVC (H.265). iPhones have recorded in HEVC by default since iOS 11. Telegram's video avatar feature only accepts H.264. It doesn't tell you that. I hit this myself, then saw it come up repeatedly in Telegram support threads. So I built a bot to handle the conversion. What Telegram Actually Requires After reading the docs and doing a lot of trial and error, the full spec for a Telegram video avatar is: Codec: H.264 (not HEVC, not VP9, not AV1) Pixel format: yuv420p Resolution: 800x800 pixels, square Duration: 10 seconds maximum File size: 2MB maximum Audio: none (video avatars are silent) That's six constraints. Miss any one and Telegram rejects the file, usually without explanation. The resolution is the awkward one. Phone videos are 16:9. You need a square crop centered on something useful. ffmpeg can handle all of this in a single pass. Solving It With ffmpeg The pipeline has two jobs: crop to square and encode to spec. ffmpeg -i input.mov \
- vf "fps=30,scale=800:800:force_original_aspect_ratio=increase,crop=800:800,format=yuv420p" \
- c:v libx264 \
- crf 28 \
- preset fast \
- movflags +faststart \
- an \
- t 10 \
output.mp4
What each part does: fps=30 normalizes frame rate before scaling scale=800:800:force_original_aspect_ratio=increase upscales to fill the 800x800 box without distortion crop=800:800 cuts the center square format=yuv420p ensures H.264 compatibility with all players -an strips audio -t 10 caps duration at 10 seconds -movflags +faststart moves the moov atom to the front so the file streams correctly The -crf 28 with -preset fast keeps a 5-10 second clip well under 2MB. For longer clips or high-motion content, -crf 32 or -crf 34 usually gets it under the limit. The Aiogram 3 Handler The bot accepts both video files and GIF documents. One thing to watch: Telegram converts GIFs to MP4 on upload, so they arrive as document with mime type video/mp4, not as animation. from aiogram import Router, F
from aiogram.types import Message, FSInputFile
import subprocess, tempfile, os

router = Router()

FFMPEG_ARGS = [
"ffmpeg", "-y", "-i", "{input}",
"-vf", "fps=30,scale=800:800:force_original_aspect_ratio=increase,crop=800:800,format=yuv420p",
"-c:v", "libx264", "-crf", "28", "-preset", "fast",
"-movflags", "+faststart", "-an", "-t", "10",
"{output}"
]

@router.message(F.video | (F.document & F.document.mime_type.startswith("video/")))
async def handle_video(message: Message):
file = message.video or message.document

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

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

    cmd = [p.format(input=src, output=dst) for p in FFMPEG_ARGS]
    result = subprocess.run(cmd, capture_output=True, timeout=60)

    if result.returncode != 0:
        await message.reply("Conversion failed. The file might be corrupted or in an unsupported format.")
        return

    if os.path.getsize(dst) > 2 * 1024 * 1024:
        await message.reply("Result is over 2MB. Try a shorter clip (under 8 seconds usually works).")
        return

    await message.reply_video(
        FSInputFile(dst),
        caption="Done. Go to Telegram Settings > Set Profile Photo > choose this video."
    )

The explicit size check after encoding matters. ffmpeg doesn't know about Telegram's 2MB limit, so it will happily produce a larger file. Better to give the user a clear message than let Telegram silently reject it again. Packaging It as @liveavabot I wrapped this into a hosted Telegram bot: @LiveAvaBot. Send it any video or GIF, it runs the ffmpeg pipeline on a VPS and sends back the converted file. Round-trip is usually 5-20 seconds depending on ...
Fix iPhone HEVC Videos for Telegram Avatars
Powered by Readybot.io

Lo último de Pixel

Incident Response: Look Beyond the Red Alert

Pixel’s DEV Community announcement explores how teams can fixate on one failing service while overlooking the real cause of an outage, such as a full …

Sach: AI Fact-Checks WhatsApp Forwards in India

Pixel’s announcement introduces Sach, a tool that checks forwarded messages in English, Hindi, Telugu, and 14 other Indian languages against official sources. It gives cited …

Java 25 Removes SecurityManager: What to Fix

Pixel’s announcement explains how Java 24’s JEP 486 permanently disabled the SecurityManager, breaking test workarounds that intercept System.exit. It recommends returning exit codes or throwing …