Importing media on-device
Chapter Vision imports media local-first: pick a file from Photos or Files, and it's in your scene immediately. Getting the bytes to your Mac is the app's problem, not yours.
Where you can import from
The Media tab in the left rail offers two pickers:
- Photos: your photo library, including iCloud Photos and spatial videos shot on Vision Pro or iPhone. Spatial video imports are recognized and set up as immersive backdrops automatically.
- Files: anything reachable in the Files app, including iCloud Drive, other cloud providers, and On My Vision Pro. Video, audio, images, and USDZ models are all supported, including Apple Immersive Video files.
Usable the moment you pick it
When you pick a file, Chapter Vision copies it into an on-device media cache, fingerprints it with
a content hash, and probes its duration and dimensions. It then registers the file in your
document right away: the asset appears in the Media rail, videos get a ready-to-place panel in
the scene, and you can drop play actions for it on the timeline immediately.
Nothing about that first minute involves the network. The scene plays the file from the local cache — a multi-gigabyte spatial video is scrubbing in your timeline seconds after you pick it.
Tip. This is the fastest path for spatial video: shoot on-device, import from Photos, and place it in your chapter without ever routing the footage through a Mac first.
The background trip to your Mac
In a tethered session, a background uploader takes over after registration. It pushes the
file's bytes to the connected Chapter Studio, which writes them into the project
bundle's assets/ folder. The Media rail shows each file's journey:
| Status | Meaning |
|---|---|
| Caching | Copying and fingerprinting into the on-device cache. |
| Cached locally | Usable now; upload queued (or parked until a Mac connects). |
| Uploading | Bytes in flight, with progress. |
| Synced | The Mac has confirmed an identical copy. |
| Failed | All retry attempts exhausted; a retry button appears on the row. |
Uploads retry automatically with increasing backoff. If the connection drops mid-transfer, the upload simply parks; the next time a Mac connects, every pending file re-registers and resumes. Editing never waits on any of this: "cached locally" is a fully working state, not a limbo.
Hashes keep both sides honest
Every asset in a chapter carries a content hash in the document's manifest, computed the same way on the headset and the Mac. That single fingerprint does a lot of quiet work:
- Sync confirmation. A file counts as synced only when the Mac's manifest entry matches the local hash, not merely because an upload request returned.
- No redundant transfers. Re-importing a file the Mac already has is detected by hash and marked synced instantly, with zero bytes sent. The headset also avoids re-downloading a file it just uploaded.
- Conflict resolution. If the Mac later replaces a file, the changed hash tells the headset to fetch the new version; if the Mac never received a local file, the headset re-asserts it. Both sides always converge on exact, verified bytes.
Tethered and solo
Everything above describes a tethered session, where the Mac's project bundle is the
ultimate destination. In solo mode there's no Mac to sync
to. Imports stay in the local cache, and saving the project copies any imported media into the
bundle's assets/ folder so the .chapterscript bundle remains fully
self-contained. Nothing queues, nothing is pending; the bundle is its own truth.
Note. Files imported on-device while offline are safe across launches. The cache and the pending-upload queue persist, and live sync flushes them whenever a Mac next appears.