Format / sheet spec 3
What is on a sheet, and where.
A Reeltiles sheet is a plain JPEG or PNG plus an optional JSON sidecar. Nothing about it is proprietary. This page describes the layout precisely enough to rebuild one, or to read one from a script.
Layout
A sheet has three bands: a header, the tile grid and a footer. The background is #0b0c0d unless you pass --paper, which flips the sheet to off-white for printing.
- Header — 92 px. Title (the file name without extension unless
--titleis given), then one line with source name, duration, frame rate, tile count and sampling interval. - Grid — tiles of equal size, 8 px apart, 24 px from the sheet edge. Default tile width is 320 px; height follows the display aspect ratio of the source.
- Tile labels — timecode on a dark plate bottom-left, two-digit tile index top-right. Both are drawn in a 5 × 7 bitmap face at 2× so they survive JPEG compression and a bad office printer.
- Footer — 40 px. Reel name, start timecode, source resolution and codec.
Sheet width is therefore 48 + cols × tile + (cols − 1) × 8. The Low Water sample is 6 columns of 320 px: 2008 px wide.
Sampling
There are three ways to choose frames. They are mutually exclusive; the last one on the command line wins.
--every Ntakes a frame everyNframes (12f) or seconds (2s,0.5s). The first sample sits half an interval in, so a sheet never opens on a slate or a black frame.--count Nspreads exactlyNsamples evenly across the file. Useful when the grid is fixed by a template.--shotsruns cut detection and takes one frame per shot, a third of the way into it. Dissolves count as a cut at their midpoint. Shots shorter than--min-shot(default 8 frames) are merged into the previous one.
Accuracy. Frames are decoded, not seeked to the nearest keyframe. On long-GOP sources this is slower, about 40 ms per tile for 1080p H.264, but the timecode on the tile is the timecode of the picture you see.
Timecode
Start timecode is read, in order, from: the tmcd track of a QuickTime file, the material package of an MXF, a timecode tag in the container metadata, then --tc-start. If none is present the sheet starts at 00:00:00:00 and the footer says so.
- Non-drop sources are written
HH:MM:SS:FF; drop-frame sources use a semicolon before the frames,HH:MM:SS;FF. - 23.976 and 29.97 are handled as rationals (24000/1001, 30000/1001). Since 2.4.1 the frame count is never derived from seconds.
--tc offremoves the plates;--tc framesprints absolute frame numbers instead.
JSON sidecar
Written next to the sheet as NAME.sheet.json unless --no-json is passed. Rectangles are in sheet pixels, origin top-left. This is the sidecar of the Low Water sample, shortened to three tiles:
{
"reeltiles": "2.4.1",
"spec": 3,
"source": {
"file": "LOW_WATER_R02.mov",
"width": 1280, "height": 720,
"fps": "25/1",
"frames": 300,
"tc_start": "01:00:00:00",
"drop_frame": false,
"transfer": "bt709"
},
"sheet": {
"file": "LOW_WATER_R02.sheet.jpg",
"width": 2008, "height": 876,
"cols": 6, "rows": 4,
"sampling": { "mode": "every", "frames": 12 }
},
"tiles": [
{ "n": 1, "frame": 6, "tc": "01:00:00:06", "rect": [24, 92, 320, 180] },
{ "n": 2, "frame": 18, "tc": "01:00:00:18", "rect": [352, 92, 320, 180] },
{ "n": 3, "frame": 30, "tc": "01:00:01:05", "rect": [680, 92, 320, 180] }
]
}
With --shots, each tile also carries "shot": {"in": …, "out": …} in frames. Unknown keys must be ignored by readers; we only add fields within a spec number, never rename them.
Options
| Flag | Default | What it does |
|---|---|---|
| --every N | auto | Sample every N frames (12f) or seconds (2s). |
| --count N | — | Exactly N tiles, spread evenly. |
| --shots | off | One tile per detected shot. |
| --min-shot N | 8f | Shortest shot that gets its own tile. |
| --cols N | 6 | Number of columns. Rows follow from the tile count. |
| --tile PX | 320 | Tile width in pixels. |
| --strip | off | Single row; overrides --cols. |
| --tc MODE | burn | burn, frames or off. |
| --tc-start TC | from file | Override the start timecode. |
| --title TEXT | file name | Header title. ASCII only in the bitmap face. |
| --paper | off | Light background for print. |
| --format EXT | jpg | jpg (quality 90) or png. |
| --no-json | off | Skip the sidecar. |
| -o PATH | next to source | Output file or directory. |
With no sampling flag at all, Reeltiles aims for 24 tiles and rounds the interval to a whole number of frames.
File naming
Output is written next to the source and never overwrites it: CLIP.mov becomes CLIP.sheet.jpg and CLIP.sheet.json. Pass a directory to -o to collect sheets from a batch:
$ reeltiles dailies/*.mxf --shots -o sheets/ A014_C003.mxf 18 shots sheets/A014_C003.sheet.jpg A014_C004.mxf 6 shots sheets/A014_C004.sheet.jpg A014_C007.mxf 1 shot sheets/A014_C007.sheet.jpg 3 sheets in 4.1 s
Questions about the format, or a file it gets wrong? Send the clip’s ffprobe output to hello@reeltiles.com.