Skip to content

init

Write an ingest.toml template into a project directory.

media-ingest init [OPTIONS] [DIRECTORY]

init is the one command you run before there is any config. It creates ingest.toml at the project root, pre-filled with the trip timezone, the trip date range, and a best-guess list of the media directories to scan. It refuses to overwrite an existing ingest.toml, so it is safe to run into a directory you are not sure about.

Arguments

  • DIRECTORY is the project directory to initialize. It must already exist. Defaults to the current directory (.).

Options

  • --timezone, -t sets the trip timezone. Accepts an IANA name like America/New_York or a fixed UTC offset like -04:00. Defaults to America/New_York. See the timezone model for how this is used.
  • --start sets the trip start date (YYYY-MM-DD). Captures outside the trip range are flagged during plan.
  • --end sets the trip end date (YYYY-MM-DD).

If you omit --start or --end, they default to today's date, which you will almost certainly want to edit.

Example

cd "/Volumes/T7/PROJECTS/2026-03_my-trip"
media-ingest init --timezone -04:00 --start 2026-03-14 --end 2026-03-22

This writes ingest.toml and prints where it went. It then reminds you to edit the [scan] include list before scanning.

What it writes

The generated ingest.toml looks like this:

# media-ingest project configuration
[project]
# IANA name ("America/New_York") or fixed offset ("-04:00").
# Used to localize devices that record UTC (DJI and GoPro video metadata).
timezone = "-04:00"
# Expected trip date range; captures outside it are flagged for review.
start = 2026-03-14
end = 2026-03-22

[scan]
# Directories (relative to this file) containing raw, unrenamed media.
include = ["DCIM", "iphone-export", "mic"]

# Destination templates per device group (relative to this file).
# Available placeholders: {date}
[destinations]
action_cameras = "media/source/action_cameras/{date}"
iphones = "media/source/iphones/{date}"
photos = "media/source/photos/{date}"
mics = "audio/mics/{date}"

The include list

init populates [scan] include with the non-hidden subdirectories it finds, skipping a few conventional output folder names (media, audio, exports, graphics, and project) so it does not try to re-ingest already-organized material. This is only a guess. Open the file and make sure the list names only the folders that hold raw, unrenamed media, then run media-ingest scan.

Device labels

Every renamed file carries a device label, like OsmoPocket3 or iPhone 17 Pro. Two identical devices get the same label, which matters for the DJI Mic 3: its files carry no serial number, so recordings from two transmitters are indistinguishable once they leave the card. The TX00/TX01 prefix in DJI Mic filenames is not the transmitter. Both transmitters write both prefixes.

To keep them apart, offload each device into its own folder and give the folder a label in an optional [labels] table:

[labels]
"raw/mic3-a" = "DJI Mic 3 A"
"raw/mic3-b" = "DJI Mic 3 B"

Keys are folders relative to ingest.toml, and every file under a folder takes its label, with the deepest matching folder winning. The label replaces the detected one in the filename (2026-03-15T122218 - DJI Mic 3 A - TX00_MIC001.wav) and gives each mic its own lane in the timeline report. Labels are read at scan time, so re-run scan after changing them. The same table works for any pair of identical devices, like two iPhones of the same model.

Destination templates

Each device group renames into its own destination tree, with {date} expanded to the capture day (YYYY-MM-DD). The four groups are action_cameras (DJI Osmo and GoPro), iphones, photos (other cameras and screenshots), and mics (DJI Mic recordings). Edit the templates if you want a different layout. Any file whose group is not listed falls back to media/source/other/{date}.