Skip to content

Timezone model

Timezones are the hard part of organizing multi-camera trip media, and they are the reason media-ingest exists rather than a one-line rename script. This page explains the naming policy, why it is the way it is, and how the tool checks itself.

One timezone per trip

Every filename is expressed in the single trip timezone configured in ingest.toml. This is a deliberate policy, not an accident of whichever clock a device happened to hold.

The payoff is that sorting by filename gives strictly chronological order across every device, including travel days when different cameras held different clocks. A DJI clip, an iPhone photo, and a mic recording of the same moment all get the same normalized timestamp prefix, so they sort together.

The trade-off is that on a trip where local time genuinely changes, such as a ship crossing time zones, names reflect trip time rather than the wall clock you experienced in that moment. For a cruise or a multi-country trip, one consistent trip time is almost always what you want for editing, and it is what this policy gives you.

How each device is interpreted

Different devices record time in incompatible ways. media-ingest classifies every file by how its authoritative timestamp should be read, then converts all of them into the one trip timezone.

  • UTC devices (DJI Osmo and GoPro video metadata): the metadata timestamp is naive UTC. media-ingest applies the trip offset to get trip-local wall time.
  • Timezone-aware devices (iPhone video CreationDate, and photos that carry OffsetTimeOriginal): the timestamp already knows its own offset. Because iPhones switch zones automatically mid-trip, media-ingest converts these to the trip zone rather than taking them at their own wall time. This is what keeps a photo taken right after crossing a zone boundary in the correct order relative to a DJI clip.
  • Local devices (DJI Mic recordings, Osmo audio sidecars, screenshots, and photos with no offset tag): the timestamp is already local wall time and is used as-is.

Screenshots and photos without an offset tag fall back to their wall time, which is indistinguishable from trip time in the common case where you were in the trip zone when you took them.

The cross-check

The trip timezone you configure is a claim, and media-ingest verifies it against the cameras themselves.

DJI video is the key. A DJI filename embeds local wall time (DJI_20260316184422_0105_D.MP4 was captured at 18:44:22 local), while the same file's QuickTime metadata is UTC. The difference between the two is exactly the UTC offset the camera's clock was set to. media-ingest recovers that offset for every DJI clip, snaps it to the nearest quarter hour, and groups it per camera per day.

It then compares each inferred offset against the trip timezone in ingest.toml. Any day where they disagree produces a warning during plan:

warning [timezone] dji-action6 on 2026-03-16: camera clock implies UTC-5 but config says UTC-4

That message means the Action 6's clock was set to UTC-5 on the 16th, but you told media-ingest the trip was UTC-4. Either the config is wrong, or that camera's clock was off. The warning does not block apply; it is a prompt to look closer.

Confirming a warning by eye

When a timezone warning fires, or a clip just looks out of place in the report, cross-check it against iPhone media with align. iPhones set their clock and timezone automatically, so iPhone times are the trusted reference. align lists everything captured around a clip's corrected time with iPhone rows highlighted. If the neighboring iPhone photo shows a different scene than the clip, the offset applied to that clip is wrong.

The cross-check flags the suspicion automatically; align lets you confirm it.

Setting the timezone

Set the trip timezone with init, or by editing ingest.toml directly. It accepts either form:

  • an IANA name like America/New_York, which handles daylight-saving transitions within the trip correctly, or
  • a fixed UTC offset like -04:00, which is simplest when the whole trip sat at one offset.

For a trip that crosses a daylight-saving boundary, prefer the IANA name so the offset is computed per capture rather than fixed.

Device knowledge

These are the timestamp facts each device profile is built on, verified against real files:

  • DJI Osmo Pocket 3 and Action 6 MP4: filename is local wall time, QuickTime CreateDate/TrackCreateDate are UTC.
  • DJI Mic 3 internal WAV (32-bit float): DateTimeOriginal and filename are local time, because the mic syncs its clock to the camera when paired.
  • DJI Osmo audio backup sidecar WAV or AAC: only the filename carries a timestamp, in local time. Sidecars adopt their paired video's name so they sort adjacent.
  • iPhone video MOV: CreationDate is timezone-aware and authoritative.
  • iPhone photo HEIC or JPG: DateTimeOriginal is local wall time; OffsetTimeOriginal supplies the UTC offset on recent iOS. Screenshots (PNG) carry DateTimeOriginal but no offset.
  • Generic camera photos (for example theme-park photo services): DateTimeOriginal in local time.
  • GoPro HERO 10 through 19: metadata is UTC.