# Quality and delivery choices

## Recommended pipeline

1. Read RAW metadata and extract lightweight, oriented JPEG previews for the local vision model. Keep a manifest mapping each preview back to its CR3 original.
2. Form time candidates, then visually audit every group and the largest internal gaps.
3. Split at true shutter pauses and flag one-to-four-frame fragments for review.
4. In Lightroom, develop only approved frames and export with unchanged basenames.
5. Render a ProRes editing master, then reframe and export H.264 delivery files from DaVinci.

This removes Lightroom export from the discovery/grouping stage while keeping Lightroom's RAW development and the user's look in the final media.

## CR3 and local vision models

Do not assume a local vision model or its image loader can decode CR3. Treat CR3 as the timing, identity, and final-render source. Extract `JpgFromRaw` from each CR3, fall back to `PreviewImage` when necessary, normalize orientation, and resize a proxy for vision:

```bash
python3 scripts/extract_cr3_previews.py \
  /path/to/cr3-root \
  /path/to/vision-preview-cache \
  --long-edge 1600
```

The generated manifest is the bridge between visual decisions and the untouched RAW originals. A vision model may approve or split groups using the JPEG proxies; final CR3 development must resolve membership through that manifest/basename mapping.

## Source export profiles

| Goal | Lightroom export | Video master |
|---|---|---|
| Highest practical editing quality | 16-bit TIFF, sRGB, full size, no output sharpening | ProRes 422 HQ, 10-bit |
| Strong quality with less storage | JPEG quality 95-100, sRGB, full size | ProRes 422 or 422 HQ |
| Quick preview | JPEG long edge 2048, sRGB | H.264 CRF 15-18 |

ProRes does not recreate detail or bit depth lost in a small 8-bit JPEG. Its advantage is smooth editing and avoiding repeated H.264 generation loss.

## Framing

Camera portrait frames in this workflow are 2:3, while Reels are 9:16. Preserve 2:3 in the editing master so DaVinci can choose the crop. A full-resolution vertical master of 2560x3840 leaves enough width for a 2160x3840 crop; final social delivery can be 1080x1920.

## Three-second delivery rule

Use source-frame count to decide whether a burst contains enough unique motion. Keep five or more frames by default. The finished deliverable—not the unique cycle—must last at least three seconds:

`cycle_seconds = (2 * unique_frames - 2) / fps`

`cycles = ceil(3 seconds / ((2 * unique_frames - 2) / fps))`

Keep one-to-four-frame fragments in a review pool. Never merge independent shutter bursts to reach three seconds; repeat whole forward/reverse cycles instead.

For editing triage, sort rather than merge: long/full-motion clips have at least 3.0 seconds in one natural forward/back cycle, medium clips have 1.5–2.99 seconds, and short bounce clips have less than 1.5 seconds. These are review tiers, not new grouping boundaries.

## Script examples

Plan candidates from RAW files or exported JPEGs without moving originals:

```bash
python3 scripts/plan_bursts.py /path/to/source --output /path/to/burst_plan.csv
```

Audit existing grouped folders for hidden shutter pauses, then build corrected symlink groups while preserving the originals:

```bash
python3 scripts/analyze_true_bursts.py \
  /path/to/grouped-jpegs \
  /path/to/raw-root \
  --gap 0.25 \
  --minimum-output 3 \
  --output /path/to/true_burst_plan.csv

python3 scripts/build_true_burst_groups.py \
  /path/to/true_burst_plan.csv \
  /path/to/grouped-jpegs \
  /path/to/corrected-groups \
  --minimum-frames 5
```

Extract embedded CR3 previews into a disposable cache for visual review:

```bash
python3 scripts/extract_cr3_previews.py \
  /path/to/cr3-root \
  /path/to/preview-cache \
  --long-edge 1600
```

Render approved grouped exports as H.264 previews:

```bash
python3 scripts/render_boomerangs.py --source /path/to/grouped-exports --codec h264
```

Render 2560x3840 ProRes 422 HQ editing masters:

```bash
python3 scripts/render_boomerangs.py --source /path/to/grouped-exports --codec prores --width 2560 --height 3840
```

Render matching CR3 files as 16-bit-developed ProRes 422 HQ masters while using grouped JPEG folders only as the membership plan:

```bash
python3 scripts/render_cr3_boomerangs.py \
  --groups /path/to/grouped-jpegs \
  --raw-root /path/to/cr3-files \
  --output /path/to/prores-masters \
  --raw-mode developed \
  --width 2560 --height 3840
```

Use `--raw-mode embedded` only for a much faster camera-rendered result. It extracts the full-resolution JPEG stored in each CR3; it is higher resolution than a small preview export but remains an 8-bit JPEG source.

Verify a ProRes master batch against its manifest and fully decode every frame:

```bash
python3 scripts/verify_video_batch.py /path/to/prores-masters \
  --codec prores \
  --profile HQ \
  --width 2560 \
  --height 3840 \
  --pix-fmt yuv422p10le \
  --minimum-duration 3
```