---
skill: process-360-video
requires: ffmpeg
input: equirectangular MP4
domain: geo.camera
profiles:
  - name: web-1920
    suffix: _web
    ext: .mp4
  - name: full-3840
    suffix: _3840
    ext: .mp4
  - name: hevc-3840
    suffix: _3840-crf22-hvc
    ext: .mp4
  - name: timelapse
    suffix: _timelapse_1920_scrub
    ext: .mp4
  - name: poster
    suffix: _poster
    ext: .png
see-also: https://acequia.org/docs/agent-skills.md
---

# Processing 360 Video for pano-view.html

Equirectangular 360 video from Ricoh Theta X → web playback via Pannellum.

## Input

Ricoh Theta X outputs equirectangular MP4 (H.264) at native resolution (typically 3840×1920 or similar). Raw files land in `guerin/cameras/ricoh-theta-x/`.

---

## ffmpeg Recipes

### Web-resolution H.264 (1920px wide)

Scale down for fast streaming. Good for previews and low-bandwidth playback.

```bash
ffmpeg -i INPUT.MP4 \
  -vf "scale=1920:-2" \
  -c:v libx264 -crf 23 -preset medium \
  -g 30 -keyint_min 30 \
  -c:a aac -b:a 128k \
  -movflags +faststart \
  OUTPUT_web.mp4
```

- `-crf 23` — visually transparent for most 360 content; lower = bigger/better
- `-g 30 -keyint_min 30` — keyframe every 30 frames (~1sec at 30fps); critical for responsive scrubbing in pannellum
- `-movflags +faststart` — moves moov atom to start of file for progressive web playback
- `-scale=1920:-2` — width 1920, height auto (divisible by 2)

### Full-resolution H.264 (3840px)

Keep native resolution, compress for streaming.

```bash
ffmpeg -i INPUT.MP4 \
  -c:v libx264 -crf 20 -preset slow \
  -g 30 -keyint_min 30 \
  -c:a aac -b:a 128k \
  -movflags +faststart \
  OUTPUT_3840.mp4
```

- `-crf 20` — higher quality for full-res; `-preset slow` for better compression ratio
- `-g 30 -keyint_min 30` — keyframe every ~1sec for scrubbing
- File size will be significantly larger than 1920 variant

### HEVC/H.265 compressed (3840px, smaller file)

Same resolution, ~40-50% smaller file size. Requires browser HEVC support.

```bash
ffmpeg -i INPUT.MP4 \
  -c:v libx265 -crf 22 -preset medium \
  -g 30 -keyint_min 30 \
  -tag:v hvc1 \
  -c:a aac -b:a 128k \
  -movflags +faststart \
  OUTPUT_3840-crf22-hvc.mp4
```

- `-tag:v hvc1` — required for Safari/Apple playback
- `-g 30 -keyint_min 30` — keyframe every ~1sec for scrubbing
- `-crf 22` — comparable visual quality to H.264 CRF 20 at smaller size
- Not all browsers support HEVC; provide H.264 fallback

### Timelapse from Theta X stills

Assemble sequential JPGs into a scrubable 360 video.

```bash
ffmpeg -framerate 10 -pattern_type glob -i 'R001*.JPG' \
  -vf "scale=1920:-2" \
  -c:v libx264 -crf 20 -preset slow \
  -pix_fmt yuv420p \
  -movflags +faststart \
  star_timelapse_1920_scrub.mp4
```

- `-framerate 10` — 10 fps; adjust for desired scrub speed
- `-pattern_type glob` — match file glob pattern (Unix); on Windows use `-i R001%04d.JPG` with sequential numbering
- `-pix_fmt yuv420p` — ensures compatibility with web players

### Extract poster frame

Pull a single frame for `pano-view.html` poster image.

```bash
ffmpeg -i INPUT.MP4 -frames:v 1 -q:v 2 poster.png
```

Or from a specific timestamp:

```bash
ffmpeg -ss 00:00:05 -i INPUT.MP4 -frames:v 1 -q:v 2 poster.png
```

---

## File Naming Convention

Match existing patterns in `guerin/cameras/ricoh-theta-x/`:

| Pattern | Example | Purpose |
|---|---|---|
| `R00NNNNN_web.mp4` | `R0010255_web.mp4` | Web-optimized single clip |
| `{name}-{resolution}.mp4` | `vis2476-review-1920.mp4` | Named project, resolution suffix |
| `{name}-{resolution}-crf{N}-hvc.mp4` | `vis2476-review-3840-crf22-hvc.mp4` | HEVC variant with CRF noted |
| `{name}_scrub.mp4` | `star_timelapse_1920_scrub.mp4` | Timelapse assembled from stills |

---

## Loading in pano-view.html

Default video is hardcoded. Override with `?src=` parameter:

```
https://geo.camera/guerin/pano-view.html?src=cameras/ricoh-theta-x/vis2476-review-1920.mp4
```

Or absolute URL:

```
https://geo.camera/guerin/pano-view.html?src=https://geo.camera/guerin/cameras/ricoh-theta-x/R0010255_web.mp4
```

Poster image is currently hardcoded in `pano-view.html` — edit the `poster` attribute to match your video.