Download the PHP package ronanlenouvel/raw-preview-extractor without Composer

Raw Preview Extractor

Extract the JPEG preview embedded in camera RAW files — pure PHP, no external binaries.

Status: feature-complete and validated against real camera files (see Tested cameras). The public API is settled, but a released version is a semver commitment, and more cameras are worth testing first.

Why

Displaying a thumbnail for a RAW file normally means decoding it, which requires libraw or Imagick — unavailable on shared hosting without root access.

Almost every modern camera already embeds a full JPEG preview inside its RAW files. This library locates and extracts that JPEG by reading the container structure. No demosaicing, no sensor data, no dependencies: just byte reading.

Supported formats

Detection reads the file's binary signature, never its extension: a .cr2 renamed to .jpg is still detected as a CR2, and a .cr2 that isn't one is rejected.

RAF (Fuji) and ORF (Olympus) are planned for v2.

Requirements

PHP >= 8.2. That's it — the require section depends on nothing else.

The optional Symfony bundle supports 6.4 (LTS), 7.x and 8.x. Composer picks whichever matches your application; the library itself never depends on Symfony.

Installation

Usage

Orientation

A preview is stored exactly as the sensor captured it: a shot taken in portrait comes out lying on its side. The camera records the rotation rather than applying it.

This library does not rotate the image — that would need GD, the very dependency it exists to avoid. It tells you what the file says:

In a browser, fixing it costs nothing:

Server-side, if you do have GD — note it rotates counter-clockwise:

Check support before extracting:

Processing a directory — the whole library in one loop:

Extraction is O(1) in file size: a 30 MB RAW takes the same ~2 ms as a 7 MB one, because the file is never loaded — only its container structure is read, then the JPEG block is seeked to directly.

Metadata

Alongside the preview, the extractor reads the shooting settings from the RAW's EXIF — what a photographer wants next to the image: when it was taken, and how.

Every field is nullable, and so is $preview->metadata itself: a tag may be absent, an old body says less than a recent one, and a partial read is never a failure. RawMetadata::isEmpty() tells a caller nothing usable was found, in one call:

Values are exposed exactly as the file encodes them — no rounding, no locale: the shutter speed keeps its fraction ("1/250" reads better than 0.004), the aperture stays a plain number. Metadata is read from the same container walk as the preview, so it costs nothing extra.

Coverage follows the TIFF-based formats (CR2, NEF, ARW, DNG), which carry EXIF in a standard IFD. For CR3 (ISO-BMFF) the preview is returned but metadata is currently null.

Exceptions

All of them implement RawPreviewExtractorException:

Symfony integration (optional)

The package ships a thin, optional bundle. The core library itself knows nothing about Symfony and works in any PHP project.

RawPreviewExtractorInterface then becomes autowirable.

Tested cameras

Verified against real files from raw.pixls.us (CC0):

All five formats are verified against real camera files:

Four generations of the same Canon 5D line — 2005 to 2016, 12 to 30 megapixels — are covered deliberately: RAW layout drifts between generations, and that drift is where format parsers break.

Wider audit

Beyond the table above, the library is audited against the raw.pixls.us catalogue — 400+ camera models, CC0 files:

Each file is downloaded, extracted, verified with imagecreatefromstring(), then deleted. Latest run — 72 models across the four brands in scope:

Every failure was verified by hand, and every one is correct: those files contain no JPEG preview at all (zero FFD8 bytes in the entire file). A Nikon D1H from 2001 carries an uncompressed 160×120 RGB thumbnail; CHDK-generated compact DNGs do the same; legacy .CRW files predate CR2 and are out of scope. PreviewNotFoundException is the right answer, so the real success rate on files that have a preview is 100 %.

The full list is at the bottom of this page.

Every preview above is checked with imagecreatefromstring() — not just decoded headers, but actually opened. Extraction takes 1–9 ms on files up to 62 MB: the file is never loaded into memory, only the container structure is read before seeking to the JPEG block.

RAW layout varies between camera generations, and CR3 has no public specification. If your camera is not listed, the library may well work — it just has not been verified. You can check in one command: see Trying it on your own RAW files.

Contributing

See CONTRIBUTING.md for conventions, the TDD workflow, and the binary parsing rules. In short:

The suite runs on a clean machine with no RAW file whatsoever: tests build byte sequences in memory. No camera files are committed to this repository — a RAW carries EXIF data (serial number, sometimes GPS), and a committed binary stays in git history forever.

Trying it on your own RAW files

Synthetic tests prove the parsing is correct; they cannot prove your camera lays out its IFDs the way this library expects. To check for yourself:

Extracted previews are written to tests/Fixtures/local/output/ — open them. A JPEG that decodes is not necessarily the right JPEG: this library once returned a valid 160×120 thumbnail where a 1620×1080 preview was expected, and every test was green.

Neither the RAW files nor the extracted previews are committed. The script itself lives in bin/, excluded from the published archive by .gitattributes.

Free CC0 sample files for most cameras: raw.pixls.us.

License

MIT — see LICENSE.

exiftool and libraw were used as behavioural references only. No code was copied from either project.

Appendix: models verified against real files

Every model below had a real file downloaded, its preview extracted, and the result opened with imagecreatefromstring(). Sources: raw.pixls.us (CC0).

Canon — CR2 & CR3

Nikon — NEF

Sony — ARW

Apple — DNG (including ProRAW)

Known to have no preview

These models throw PreviewNotFoundException — and that is the correct answer. Their files contain no JPEG whatsoever, which is verifiable in one command:

Two reasons, neither of them a parser bug. The oldest bodies predate the convention: a D1H from 2001 stores a raw RGB thumbnail because embedding a JPEG preview was not yet standard practice. The compacts never had a RAW mode: their DNGs come from CHDK, an alternative firmware that writes sensor data with a minimal thumbnail.

There is nothing to extract in those files, so throwing is right — returning something would mean fabricating it.

Success rate on files that actually contain a preview: 100 %.