Troubleshooting & FAQ

The problems authors actually hit, what's really going on, and how to fix each one, followed by quick answers to the most common questions.

Connection

My Mac doesn't appear in the headset's session list. Work down this list:

  1. Same network, same subnet. Both devices must be on the same Wi-Fi network — and the same subnet of it. Guest networks, VPNs, and networks with "client isolation" often block device-to-device discovery even when both devices show full Wi-Fi bars.

  2. Check the server is running. In Chapter Studio on the Mac, look for the green-dot Live menu in the status bar. Click it to confirm the service name and port. No green dot means the server isn't up; a project needs to be open.

  3. Check the Mac's firewall. In System Settings → Network → Firewall, allow the app to accept incoming connections. A firewall that silently drops incoming traffic is the most common cause of a Mac that advertises itself but can't be reached.

  4. Verify with a browser. From any device on the network, open http://<mac-name>.local:<port>/ (the Live menu shows the port). If the status page loads, the server is fine and the issue is discovery; if it doesn't, it's network or firewall.

The session dropped. Reconnecting is stateless: just tap the Mac in the session list again. The headset refetches the document and picks up where the Mac is. Any edits or media imports made while disconnected are re-asserted automatically on reconnect.

Playback

A video's first play seems to hang for a beat, or I expected it earlier. That's deliberate. The player holds a cold video invisible until its audio and picture are both fully ready (the file is cued to its in-point, buffered, and prerolled), and only then reveals and starts it, so sound and image begin together. The alternative is the classic black-panel-with- audio glitch. Once a video has played warm, subsequent plays start immediately.

A trimmed or looping video plays the wrong part. Loops and playback honor the clip's source window: playback starts at the in-point, ends (or loops back to the in-point) at the out-point. If a video plays footage you thought you'd trimmed away, check the clip's Trim values. A Retime drag moves when the clip plays, not which part of the file plays. See the spatial timeline for the difference.

Editing

I can't drag a chip out of a menu or button. On visionOS, controls that respond to a press (menus, buttons) own the pinch, so a drag never starts from them. Drag from the plain rows and chips instead: the Actions tab's chips and the Assets tab's rows are all built to be picked up directly.

Snapping fights me on fine adjustments. Toggle snap off in the timeline for freehand placement, then back on when you want boundaries and the 1/24s frame grid again. The cyan guide shows exactly where a snapped drag will land.

I'm worried auto-key will scatter keyframes everywhere. It won't. Auto-key only writes keys on channels that are already animated. Moving a never-animated prop with record on just moves it. The only way to start a new animation is an explicit pose key. See keyframes & auto-key.

Media

An import says "cached locally" and never syncs. That's the offline state, not an error: uploads queue while no Mac is connected and flush automatically the moment one appears. The file is fully usable in your scene the entire time. If a row shows Failed after a Mac was reachable, tap its retry button.

How do I know both devices have the same file? You don't have to check — every asset carries a content hash, and a file only counts as synced when the Mac's copy matches the headset's hash exactly. Mismatches resolve themselves: the newer side re-sends. Details in importing media on-device.

Undo

Undo on the Mac reverted a whole burst of headset edits at once. By design: a batch of edits arriving from a connected headset lands as one undo entry in Chapter Studio, so one ⌘Z cleanly reverses one remote gesture instead of leaving it half-applied.

Undo in the headset feels different from the Mac. Chapter Vision's undo is snapshot-based: each step restores a full document state. Solo mode restores locally and instantly; in a tethered session the restore is proposed to the Mac and rebroadcast, so both devices agree on history.

FAQ

Can I author without a Mac? Yes. Solo mode is full authoring on the headset: create, edit, and save .chapterscript bundles entirely on-device.

Can two people edit at once? Yes. Edits are revision-checked: the Mac arbitrates, stale changes are rejected and retried against fresh state, and every applied edit broadcasts to all connected peers. Two editors can't silently overwrite each other.

Is my project locked into Chapter Vision? No. A project is an open ChapterScript bundle: pretty-printed JSON plus your untouched media files. Read it, diff it, version it, or write your own tools against it.

Do video trims re-encode my footage? No. Trims are stored as in/out metadata on the document; masters are never modified. The one exception is the explicit Consolidate — Overwrite Master File… command, which trims a master down to its used range.

What plays a finished chapter? The player on Vision Pro, the same runtime that renders your scene while you edit, so playback is identical to what you authored.

Does live sync need the internet? No, it's entirely local-network. Nothing leaves your LAN, and no account is required. See live sync.

What do I need to run it? Chapter Studio runs on Apple silicon Macs on a current macOS; Chapter Vision runs on Apple Vision Pro on a current visionOS. For tethered sessions, both on the same Wi-Fi. See install & setup.

Will old projects open in new versions? Yes. Documents are upgraded on open, and unknown newer fields are ignored by older versions. Your file on disk only changes when you save.