Troubleshooting

Lagging can show up in two different places, and each one has a different cause. Check where you are seeing it before changing anything.

1. The video lags inside the Apple Vision Pro

Some Apple Immersive Video (.aivu) files are encoded at a bitrate the M-series processor in the headset cannot sustain, so playback freezes or stutters during an exhibition. Apple suggests keeping the bitrate at 150 Mb/s.

1. Check the bitrate of the file you are playing.
2. Play the same file with Apple’s native immersive player on the Apple Vision Pro. Spatial Companion uses that same native player, so the result tells you where the problem is.
3. If it lags in the native player too, the file is the cause - re-encode it at a lower bitrate and try again.

2. The video lags in Live View, but plays fine in the headset

Live View can run on an older Mac, iPhone, or iPad. The preview you see there is decoded by that device, not by the Apple Vision Pro, and a slower processor may not keep up with a high-bitrate file. When that happens, a banner warns you:

“Video bitrate (XXX Mbps) is too high for this device. Playback may freeze or lag.”

That warning is about the device showing Live View - not about the headset. Playback inside the Apple Vision Pro stays smooth and your audience sees no problem; only your own preview stutters. If you want a smooth preview as well, run Live View on a more recent Mac, iPhone, or iPad, or share a file with a lower bitrate.

If the image jitters or stutters during playback, other apps left open on the Apple Vision Pro are usually competing for resources. Make sure Spatial Companion is the only app running before starting an exhibition.

Close every other app:

1. Press and hold the Digital Crown and the top button at the same time until the Force Quit Applications window appears.
2. Select each app in the list and close it, leaving only Spatial Companion open.
3. Start the playback again.

If your Apple Vision Pro is paired to the correct account and both apps are open but the headset still shows as offline, the Wi-Fi network is the most likely cause.

Pairing and account status travel over the internet, while the app finds your Apple Vision Pro on the local network. A firewall can block that local traffic and leave the internet connection untouched. The headset stays paired, but the app never sees it.

Quick test:

1. Start a personal hotspot on a phone.
2. Connect the Apple Vision Pro and your Mac, iPhone, or iPad to that hotspot.
3. Open both apps and check whether the headset appears.

If it appears on the hotspot, a firewall on your usual Wi-Fi network is blocking the connection. Ask whoever manages that network to allow local network communication between devices.

If your Apple Vision Pro isn't being recognised, check two things - one on your Mac, iPhone, or iPad, and the other on the Apple Vision Pro.

On Mac:

1. Open System Settings.
2. Go to Privacy & Security.
3. Select Local Network.
4. Check that the toggle for “Spatial Companion” is on.

On Apple Vision Pro:

1. Open Settings.
2. Go to Apps.
3. Select Spatial Companion.
4. Check that the toggle for “Local Network” is on.

If the issue persists, try logging out and back in.