AnalyzeMedia
Get an API key

image/scene

A scene file describes a view of something: a photograph, a painting, or a render. It shows a place, a person, or an object from a viewpoint, with light and depth. Whether a camera captured the image or a hand or a program made it is a descriptor, not the type. No field carries a time.

envelope the same fields in every typemeasured computed from the file's bytes; the same value every timeobserved what a model saw or heard; never a recommendationmixed some parts measured and some observed; the description says whichderived computed from other fields; the writer regenerates it and never edits itNo time marks: an image has no time at any level. Positions are fractions of the frame, measured from the top left: x, y for a point and x, y, w, h for a box.
DSC_0412.HEIC.analyzemediaone JSON object next to the original

From top to bottom: the envelope with the camera's facts, what the image is, who and what is in it with boxes, and how the frame is built.

The envelopealways present, in this order
format
"analyzemedia"
Always this string.
version
"0.1"
Within a major version, changes only add fields.
type
"image/scene"
The writer declares the type. Readers don't second-guess it.
generatedmeasured
{ at, by, models }
When the writer made the file, which writer, and which models it used. Nothing per item.
sourcethe file, the camera, and, when the file carries them, where and when
name, bytes, sha256, quickHashmeasured
The hashes bind the sidecar to the file.
imagemeasured
{ format, width, height, orientation, colorSpace, bitDepth, hdr, alpha }
Width and height apply after orientation, so they match what a viewer shows.
camera · exposuremeasured
{ make, model, lens, software } · { iso, shutter, aperture, focalLength, focalLength35, exposureBias, flash, whiteBalance }
From EXIF, when the file carries it. The shutter is in seconds, the aperture is the f-number, and the focal lengths are in millimeters.
recordedmeasured
{ utc, local, offset, zoneSource, timeOfDay { … } }
Present when the file carries a capture time. The time of day requires a location.
locationmixed
{ lat, lon, altitude, accuracy, address, nearby [], venue | null }
Every field is measured except venue. A model picks venue from nearby as the place that the picture shows.
What it is
summaryobserved
string
What the image shows, in one paragraph. You can use it as alt text.
kindobserved
string
What sort of scene image this is: photograph, painting, drawing, illustration, render, or frame (a still from a video).
formobserved
{ size, angle, lens, depthOfField, lightKey, lightQuality, lightSource, timeOfDay, interior, setting }
The picture as a cinematographer would name it, with the same vocabulary as footage. An editor picks and places images by these values.
picturemeasured
{ aspectRatio, orientation, palette [hex], warmth, saturation, tonalRange, luma, contrast, sharpness, clippedHighlights, crushedBlacks }
The measured color and tone of the pixels. This is the same block as a footage frame.
quality[]observed
[ string ]
Conditions that are visible in the image: blurry, dark, overexposed, subject cut off, obstructed, noisy, compressed, watermarked, cropped, or low resolution. This isn't a grade.
Who and what is in iteach item has a box, because you look at a still image long enough to point at things
people[]observed
[ { label, description, box, eyeline, expression } ]
The subjects, lettered from left to right. description says who they look like and what they wear. eyeline is camera, left, right, down, up, or away. expression says what the face shows, in plain words. You read the size and position from the box.
objects[]observed
[ { text, box } ]
Things worth naming, each with a box. Brands and models are included when they are legible.
text[]observed
[ { text, kind, box } ]
Everything written in the picture, read as it appears. kind is scene text, sign, label, caption, handwriting, or watermark.
surroundingsobserved
string
Everything that isn't a subject, in one paragraph: what is behind the subjects, who else is there, and the small things that a viewer would miss at a glance.
compositionhow the frame is built
textobserved
string
The paragraph that a photographer would write: where the subject sits, what leads the eye, what balances what, and where the horizon and the empty space are.
devices[]observed
[ string ]
The framing devices in use: thirds, centered, symmetry, leading lines, diagonal, frame within a frame, pattern, fill the frame, negative space, layering, reflection, or silhouette.
subjectobserved
string | null
The main subject, named by its label in people[] or its text in objects[]. Its box lives there and isn't repeated. The value is null when the picture has no subject, such as a texture or a sky.
The example photograph, with its boxes drawn
Aobjects[0]
people[A].box { x: .61, y: .42, w: .09, h: .34 }, objects[0].box { x: .40, y: .31, w: .02, h: .02 }, composition.subject: "A", devices: thirds, leading lines, reflection, negative spacesurroundings: "Wet sand in the foreground doubles her in reflection; flat sea and a low sun to the left; footprints lead from the bottom left corner to where she stands."

The photograph shows a woman in a yellow raincoat at the water's edge during golden hour. The dashed grid marks the thirds device. The blue boxes mark person A and the sailboat. The subject is "A", which points at her box. The horizon, the reflection, and the footprints appear in the sentences, not in fields.

A scene file answers the question "what does this picture show, and how is it built". You can use summary as alt text. The boxes let software point at things. form and composition let an editor pick and place the image. A scene file never holds time, camera motion, or layout. A photo of a screen is a scene, and its objects hold the screen.

Rules you can rely on