# Media Ingest

Source: https://www.potatoannotator.com/docs/vision-spatial/media-ingest

**Files a browser cannot display produce a blank canvas and no error, so the annotator concludes the tool is broken.** Potato transcodes them on first request, caches the result, and when it genuinely cannot, says so with the command to run instead.

## Requesting a transcoded file

Reference the file through `/media/proxy/` instead of `/media/`:

```json
{"id": "scan_001", "image_url": "/media/proxy/scan_001.tif"}
```

Files browsers already display (`.jpg`, `.png`, `.webp`, `.mp4`, `.webm`) pass straight through un-re-encoded, so a mixed corpus needs no special handling. Point everything at the proxy.

Results are cached under `<output_annotation_dir>/.media_cache/`. The cache key includes the source's size and modification time, so editing a source file produces a new entry rather than a stale hit.

## What it handles

| Source | Converted to | Notes |
|---|---|---|
| TIFF | WebP | Multi-page and 16-bit, with percentile windowing |
| [HEIC](https://en.wikipedia.org/wiki/High_Efficiency_Image_File_Format) | WebP | The default iPhone photo format |
| Camera RAW | WebP | Through `rawpy` |
| ProRes, MKV, MOV, HEVC | MP4 | ffmpeg proxy transcode, with an extracted-frames fallback |

ffmpeg and Pillow-SIMD stay optional. Their absence produces a message naming the missing tool rather than a blank panel.

## 16-bit windowing is the substantive part

Scientific TIFF is usually 16-bit, and its content usually occupies a narrow band of the available range. Casting that to 8 bits naively is not a small loss: a scan whose content sits between 1200 and 1800 renders with **4 grey levels of separation out of 255**. Under a percentile window it renders with **254**.

The same windowing logic drives [depth maps](/docs/vision-spatial/depth-maps), where getting it wrong is likewise invisible rather than obvious.

## Related

- [Deep zoom](/docs/vision-spatial/deep-zoom) — for images too large to transcode whole
- [CV formats](/docs/vision-spatial/cv-formats)
- [Source documentation](https://github.com/davidjurgens/potato/blob/main/docs/annotation-types/multimedia/media_ingest.md)