Correct rotated thumbnails for videos uploaded as a Telegram document

[techeng322]

Summary

• Telegram's document.thumb for a video sent as a document is a raw frame grab that ignores the container's moov/trak/tkhd display-rotation matrix — a portrait-recorded video (landscape pixel data + rotation matrix, e.g. 1920x1080 + 90°) got a sideways/squished preview image. Confirmed against a real iPhone MOV: video track matrix a=0,b=1,c=-1,d=0 → 90°, matching the actual video's portrait content vs. the mis-oriented thumb
• Added readTkhdMatrix.ts + readMp4VideoRotationDegrees.ts (src/lib/media/) to read the video track's display matrix and compute the clockwise correction angle (atan2(b, a), normalized to 0/90/180/270)
• Added rotateImageBuffer.ts, a thin sharp().rotate() wrapper
• uploadVideoAttachment.ts now computes rotation from the already-downloaded video buffer and applies it to the Telegram-provided thumbnail before uploading to Supabase; unmodified when no rotation is detected (identity matrix or no video track found) — same fail-safe fallback policy as the existing EXIF/QuickTime capture-date path
• tkhd is a standard ISO-BMFF box (not Apple-specific), so this also corrects rotation on plain MP4 uploads (e.g. Android), unlike the capture-date feature which only works for Apple's com.apple.quicktime.* metadata
• Scope: thumbnail image only — the Mux-hosted playback video is untouched since Mux already respects the rotation matrix correctly

Stacked on #407 (base branch is that PR's branch, not main) since this branch was cut from its tip.

Test plan

• pnpm vitest run src/lib/media src/lib/telegram/chat — 326 tests passing, including new unit tests for the matrix parser (synthetic buffers matching real iPhone MOV byte values), rotation-degree calculation, and the real sharp rotation wrapper
• Cross-checked readMp4VideoRotationDegrees against the actual real-world MOV file bytes directly (not just synthetic fixtures) — returned 90°, matching the tkhd matrix read manually
• tsc --noEmit clean on touched files
• Manual: send a portrait iPhone video to the Telegram bot as a document and confirm the minted token's preview image is upright, not sideways

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
in-process-api	Ready	Preview	Jul 12, 2026 12:25pm

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 46ad0d7f-5f43-4b25-98eb-3e6e2f911480

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch techengme/myc-5018-videos-uploaded-to-telegram-bot-as-a-document-get-a-mis

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}