# Mobile vertical aspect QA and repair

Use this when a short/reel/Telegram preview appears with black bars at top/bottom, wrong aspect ratio, or the visible image looks vertically compressed even though the source clip was intended as 9:16.

## Durable lesson

Do not rely on nominal source dimensions alone. A clip can be near-vertical, but still display badly on mobile platforms if the export lacks explicit square-pixel and display-aspect metadata, or if an assembly step has letterboxed instead of producing a true vertical canvas.

## Required checks

Probe every final-near MP4 before delivery:

```bash
ffprobe -v error -select_streams v:0 \
  -show_entries stream=width,height,sample_aspect_ratio,display_aspect_ratio \
  -show_entries format=duration \
  -of json path/to/video.mp4
```

Expected mobile-safe target for Shorts/Reels/TikTok review exports:

- `width=1080`
- `height=1920`
- `sample_aspect_ratio=1:1`
- `display_aspect_ratio=9:16`
- no visible black bars in extracted QA frames

Extract a frame for visual QA:

```bash
ffmpeg -y -hide_banner -loglevel error -i path/to/video.mp4 \
  -vf "select=eq(n\,10)" -frames:v 1 /tmp/frame.png
```

Inspect the frame for top/bottom black bars and obvious squeezing before sending to the user.

## Repair command

For source clips that should fill a vertical mobile canvas, create a post-render normalized export:

```bash
ffmpeg -y -hide_banner -loglevel error -i input.mp4 \
  -vf "scale=1080:1920:force_original_aspect_ratio=increase,crop=1080:1920,setsar=1,setdar=9/16,format=yuv420p" \
  -c:v libx264 -preset veryfast -crf 18 -movflags +faststart -an \
  output_1080x1920_sar1.mp4
```

Use `increase,crop` for full-bleed visual proofs where black bars are unacceptable. Use `decrease,pad` only when preserving every pixel is more important than full-screen mobile presentation, and label it as letterboxed.

## Workflow rule

If the user reports black bars or squeezed height, treat it as a blocking export QA issue:

1. Probe the delivered MP4 metadata.
2. Extract at least one representative frame.
3. Inspect the extracted frame itself before changing the image geometry.
4. If metadata is wrong, re-export with explicit 1080x1920, `setsar=1`, `setdar=9/16`.
5. If the extracted frame contains baked-in top/bottom bars, only then use a full-bleed crop/scale repair and label it as geometry-changing.
6. If metadata is correct and extracted frames are vertical/full-frame, suspect the Telegram/mobile player UI first. Re-deliver the verified original instead of stretching/cropping.
7. Probe the final file and report the verified SAR/DAR.
8. Deliver the corrected or verified media, not a theory lecture.

## Telegram/player false-positive pattern

A Telegram player can show apparent top/bottom bars or a square-looking preview even when the underlying MP4 is valid 9:16. Before destructive repair, compare:

- `ffprobe` metadata: `width=1080 height=1920 SAR=1:1 DAR=9:16`
- extracted frame dimensions: `1080x1920`
- visual QA of the extracted frame, not just Telegram's inline player

If all three pass, do **not** crop/stretch. Tell the user the player is the likely cause and keep the unwarped file as canonical. Crop/stretch variants are review experiments only and should be discarded if the player diagnosis is confirmed.

## Pitfalls

- Do not say “the source is 9:16 enough” based on dimensions like `416x736` alone. Platform players can still expose metadata or canvas mistakes. Verify the final delivered artifact.
- Do not overcorrect by stretching a valid 9:16 video just because Telegram preview looks wrong. Destructive geometry repair can make the real asset worse.