Skip to content
heic.fyi

Inspect

HEIC to JSON

Export a HEIC's metadata, tags, container structure and codec details as one JSON file, ready for scripts, catalogues and diffs.

Input

Drop HEIC or HEIF files here

or choose them from your device

HEIC or HEIF · up to 100 MB per file · processed on your device

At a glance

Output
Your file's name plus -metadata.json
Top-level keys
tool, generatedAt, file, image, metadata, tags, structure, health
Pixels decoded
No, so health.decodeTested is always false here
Scope
One file per export

What this tool does

One file in, one JSON document out, ready to parse, store or diff. The document has eight top-level keys. file holds the name, size, detected format, MIME type, brand, extension, whether the extension matches the contents, and the compatible brands. image is the summary: primary image size, image and thumbnail counts, codec, bit depth, channels, colour profile, rotation, mirror and has-flags for alpha, depth, HDR gain map, grid and so on. metadata carries hasExif, hasXmp, exifReadable, a tag count, the camera, capturedAt as an ISO time with offset, gps as latitude, longitude and altitude (null when there is none), a flat exif object and the raw xmp packet as a string (null when absent).

Two keys go beyond a summary. tags repeats the metadata viewer's rows grouped by directory, each with its tag ID, name, display value, meaning, storage type and hex bytes. structure is the container: top-level boxes, the primary item ID, an item list with each item's type, size, offset, storage method, roles and property types, the item references, any parse warnings, the codec configuration (HEVC profile, level, parameter sets), the grids layout and the auxiliary images with their type URNs. The last key, health, has an outcome, a title and decodeTested. The export never decodes the image, so that flag is always false and a good outcome means the container looks healthy, not that the picture decodes. For that verdict, run the Health Check.

The document is produced by the same inspection that powers the on-screen viewers, so it cannot disagree with them. Because it is complete, it also includes anything sensitive the file holds: GPS coordinates, serial numbers inside tags, and the entire XMP packet. It contains no image data. In our test, a photo carrying Exif, XMP and an Apple MakerNote produced a document of about 48 KB, largely because every tag carries its hex bytes. Treat the download with the same care as the photo. This page is the one to use when the goal is to keep or process the data. For reading it, the metadata viewer is easier.

How to use it

  1. 01

    Choose a HEIC or HEIF file

    The container and metadata are read without decoding any pixels. A file that is not a HEIC gets a notice saying what it really is, and no JSON is produced.

  2. 02

    Check the preview

    The JSON preview shows the first 6,000 characters, followed by an ellipsis if the document is longer. It is enough to confirm the shape. The download has the complete document.

  3. 03

    Download the file

    The Download button saves it as the original name plus -metadata.json. It is formatted with two-space indentation and a trailing newline.

  4. 04

    Query it with your own tools

    For example, jq '.metadata.gps' photo-metadata.json returns the coordinates or null, and jq -r '.structure.auxiliary[].kind' photo-metadata.json lists the depth, gain map and thumbnail entries.

  5. 05

    Check health.decodeTested before relying on health

    It is always false in this export. If you need to know that the image decodes, run the Health Check as well.

When to use it

Recording what a handful of files contained

Before you convert, migrate or publish a few photos, export each one and keep the documents. A null metadata.gps or metadata.hasXmp set to false is a quick, checkable audit result. There is no batch mode, so this suits small sets.

Diffing an original and an edited copy

Export both and compare. Apart from generatedAt, the name and the size, differences are real: a changed Software tag, a dropped GPS block, a re-encoded codec configuration or a different item list.

Reporting a HEIC bug without the photo

A library maintainer often wants the item table and codec configuration. The JSON gives them without any pixels, but it still contains GPS, serials and XMP, so delete metadata and tags or export from a cleaned copy before attaching it.

Feeding a script or catalogue

Stable key names make it easy to route files by file.detected.format, read image.codec or structure.itemCount, or load dimensions and capture times into a spreadsheet.

Good to know

  • 01No pixels are decoded. health.outcome can read healthy with the title "Container looks healthy" for a file whose image data is damaged. Only the Health Check tests decoding by default.
  • 02The shape is not a published schema and has no version field. The key names above are what the tool writes today, so inspect a sample export before building anything strict on top of it.
  • 03metadata.exif is a flat name-to-value object and can hold raw byte arrays, such as a MakerNote. tags is the fuller form, with groups, IDs and hex bytes (up to 256 per tag), and its values are display strings.
  • 04The document is sensitive. It includes location, device identifiers and the complete XMP block when the file has them.
  • 05One file per export and no zip. generatedAt is taken from your device clock and the document is a snapshot, not a live view of the file.

Technical notes

Privacy and limits

Your file stays on your device

This tool runs in your browser with WebAssembly. The file is read into the tab, processed there and discarded when you close it — there is no upload and no account. You can check this yourself in your browser's network panel, and the privacy page lists what analytics does and does not receive.

Limits and checks

Up to 100 MB and 100 megapixels per file; batches of up to 50 files and 500 MB. Files are treated as untrusted input and every output is re-opened and validated before it is offered — see how we handle untrusted files.

Frequently asked questions

Related tools and reading

HEIC Metadata ViewerRead the same rows interactively and export a filtered CSV.HEIF Structure ViewerSee the raw box tree behind the structure key.HEIC Health CheckGet the decode result that the export does not include.HEIC InspectorThe structure and auxiliary data as a readable report.

Further reading

Last updated: . Something wrong or out of date? Tell us — corrections are recorded in the changelog.