Skip to content

Instantly share code, notes, and snippets.

@KhaosT
Last active February 24, 2025 14:25
Show Gist options
  • Save KhaosT/e9b60fc0fb99b9f4512759b953cbf38c to your computer and use it in GitHub Desktop.
Save KhaosT/e9b60fc0fb99b9f4512759b953cbf38c to your computer and use it in GitHub Desktop.
Guide for using Apple Vision Pro as HDMI display

Displaying HDMI sources on Apple Vision Pro

While it's possible to stream most content to Apple Vision Pro directly over the internet, having the ability to use Apple Vision Pro as an HDMI display can still be useful.

Since Apple Vision Pro does not support connecting to an HDMI input directly or using an HDMI capture card, we have to be a little creative to make this work. NDI provides the ability to stream HDMI content over a local network with really low latency, and it works great with Apple Vision Pro.

This page shows the setup I’m using.

What’s needed

  • HDMI NDI Encoder
    • Personally, I recommend the Kiloview N40, as it supports streaming up to 4K60 while being fan-less, and can use USB-C as a power input.
    • Kiloview N60 comes with more features, but it’s larger and has a fan.
  • Vxio app
    • I made this one, you can also use other NDI monitor apps as well.
    • Separately, Finn made Castaway that makes it possible to use a USB Capture Card + Mac/iPad instead of an NDI encoder. It's a more cost effective option for most people I imagine.

Things to consider

  • To ensure high video quality, an NDI stream typically consumes significantly more bandwidth than a typical H.264/H.265 stream. Before purchasing the encoder, make sure your network can support data transfers at that speed.
    • For 4K60 stream, the bandwidth required is typically around 250~300mbps. If you're having issue to stream smoothly, try go to the encoder's settings page and reduce the streaming quality.
    • You can test this with some free software NDI encoders.
  • Since this setup requires encode and decode the video content, it is not latency free. From my experience, I typically see 3~4 frames (~50ms, same as moonlight based on my measurement) of delay from the content source.

Setup

Setting up an NDI encoder is pretty straightforward. Just connect the device to your local network via Ethernet, supply power, and connect the HDMI input to the encoder.

If the visionOS shows the Local Network permission dialog, and after granting the permission the app still shows searching, you may need to force close the app, and reopen it.

After that, you should be able to see the encoder show up as a source in the Vxio app. Select the source, and you'll get your HDMI display 🎉

Screenshot

Misc

Adjusting audio queue size

Depending on the NDI encoder, the default audio queue size might be too small for some devices. In that situation, try increasing the audio queue size so that the audio no longer experiences abrupt stops between samples.

Disable Multi-TCP

If your Wi-Fi channel is congested, you can try force N40 to use UDP instead of Multi-TCP. In my experience, UDP performs a lot better in those network condition. You can do so from the N40's configuration UI, select NDI Connection -> Multi-TCP Disallowed.

UDP

Portable setup

I was able to make this setup portable by getting one of those mini router (GL.iNet Beryl AX) with a LAN port.

IMG_3978 IMG_3979

#AppleVisionPro #visionOS

@Jefe533
Copy link

Jefe533 commented Dec 5, 2024

@KhaosT thank you thank you thank you for color space override! I'm glad to see it was already helpful in a non-VR context :)

As @lightsailvr said, yeah, the HDR unfortunately doesn't carry over to the immersive view. I think you're right that this is a limitation of RealityKit. Might be necessary to somehow create the immersive viewing environment in Unity.

One more thing...could we actually bug you to add P3-D65 PQ (ST2084) as an option for the override? This is actually the mastering spec for Apple Immersive Video. I'm sitting in my grading suite now, looking at a video we graded to P3-D65 on my reference HDR monitor. When I look at that video in VXIO via NDI having chosen 2100 PQ as the override, all the colors look too saturated and cartoonish. This is expected behaviour of viewing something mastered in a smaller color space in a larger color space (aka, viewing P3-D65 in 2020).

Amazing, and again, thank you.

@KhaosT
Copy link
Author

KhaosT commented Dec 6, 2024

@lnguyen I think the one they released is technically newer, but didn't include the fix they made ad-hoc to set the correct color transfer function.

@KhaosT
Copy link
Author

KhaosT commented Dec 6, 2024

@Jefe533 For P3-D65, is that the color primaries or the YCbCr matrix? I assume the former?

@Jefe533
Copy link

Jefe533 commented Dec 6, 2024

P3-D65 is the color primaries.

@KhaosT
Copy link
Author

KhaosT commented Dec 6, 2024

@Jefe533 Can you give v1.1.7 a try? It added this option but since I don't have this workflow configured, I wasn't able to test it.

@Jefe533
Copy link

Jefe533 commented Dec 6, 2024

It works! Amazing. By selecting P3 in color override in VXIO now I get a proper saturation match. By the way, out of curiosity, for your HDR implementation...were you able to specify the target nits of the general output transform? If I have an HDR video file, and watch it in "Files" in the AVP, the bright light sources are quite bright. If I stream that same PQ video via NDI 6 to VXIO with these new metadata improvements, I have a close match but the brights are ever so slightly duller in VXIO. In any case, THANK you for these options!

@KhaosT
Copy link
Author

KhaosT commented Dec 6, 2024

Yeah there are some information I can attach to specify those. Currently it's just using the OS default value since NDI didn't provide those information as part of the stream.

Do you want these to be configurable, or is there a set of values I can just set for typical HDR content?

"master_display": {
    "red": {"x": 0.708, "y": 0.292},
    "green": {"x": 0.17, "y": 0.797},
    "blue": {"x": 0.131, "y": 0.046},
    "white_point": {"x": 0.31273,"y": 0.329},
    "luminance": {"max": 1000,"min": 0.0001}
},
"max_content_light_level": 1000,
"max_frame_average_light_level": 180

@smillin920
Copy link

would kilowview U40 be sufficient in this application? Its just an encoder, vs N40 encoder/decoder

@Jefe533
Copy link

Jefe533 commented Dec 7, 2024

The only parameters in the code you pasted that are catching my eye are "luminance max" and "max content light level." Both are currently 1,000. Presumably that means 1,000 Nits. That is a good value for a standard HDR display, like a high-end TV, a Flanders reference monitor, or an iPad. But the Vision Pro we are learning is only about 300 nits. So it's kind of a wimpy HDR, but it can still look effective since its so close to our eyes, and the black levels are quite nice (very dark). So part of me wonders - what if you changed one or both of those values to 300? Could that actually improve specular highlight detail or weirdly boost the luminance? If you were willing to make luminance min/max and max content light level / max frame average light level indeed configurable, I'd be happy to play around with the values and see if the image improves.
image
Sending an image from how these parameters are labeled in a grading application. Lum. Min, Lum. Max, MaxCLL, and MaxFALL. I think labeleing the code like that would be helpful.

@KhaosT
Copy link
Author

KhaosT commented Dec 7, 2024

@Jefe533 v1.1.8 now added support to load custom HDR metadata. After updating to the version, you can load custom HDR metadata by opening a JSON file with extension vxiohdrmetadata in Vxio from Files app. If everything is correct, you should get a prompt about import being successful. The custom metadata will be applied to all NDI streams that's using PQ transfer function and can be removed from the settings if later you don't want it.

Here is an example of the file you can use as a starting point.

Let me know if it makes any difference for you :)

@alechemy
Copy link

Would it be possible to add functionality to persist the selected Color Override profile, similar to how you can save the selected Audio Queue Size?

@KhaosT
Copy link
Author

KhaosT commented Dec 25, 2024

@alechemy This is added with v1.1.9. iOS update is already approved, visionOS one is currently still waiting for review.

@lightsailvr
Copy link

I captured a bunch of Spatial Video recently with the new Canon 7.8mm dual lens. Pretty rad stuff. I've been editing in FCPX inside the Apple Vision Pro and using VXIO as the program monitor. One bump I encountered is that the side by side mode is locked to a 16x9 aspect ratio, but the Spatial Video that Canon's software produces is a 1:1 aspect. Is there a way to modify this aspect ratio inside VXIO?

@KhaosT
Copy link
Author

KhaosT commented Dec 26, 2024

@lightsailvr The side by side mode adopts the aspect ratio of the underlying video source. If you want the 1:1 ratio, try adjust the encoding side so the width and height are equal.

@LowRiderXR
Copy link

@KhaosT When I use the suggested solution for the latest N60 firmware HDR issue, the color override does fix the greyish colors, but the image gets very blurry, when using the color override. Is there a way to fix this?

@haseebrabbani
Copy link

+1 on @LowRiderXR's comment above (I have also observed a slight blurriness when applying the color override)

@haseebrabbani
Copy link

@KhaosT also a feature request to support Apple Vision Pro environments in the AVP app 🙏 would be awesome to play PS5 games reflecting on a lake

@KhaosT
Copy link
Author

KhaosT commented Dec 30, 2024

but the image gets very blurry, when using the color override

I believe visionOS 2.2 broke the HDR video display for content shown using AVSampleBufferDisplayLayer since the same code works fine on iPadOS, Apple needs to fix that.

a feature request to support Apple Vision Pro environments in the AVP app

Currently Apple only provided API to let app do this for normal video content playback using AVPlayerViewController, which only works with HLS content over internet. There is no way for the app to do it using the display layer.

@LowRiderXR
Copy link

So the greyish tone of the HDR is not a kiloview firmware issue, but rather a visionOS bug? Is it possible to report the bug to apple?

@KhaosT
Copy link
Author

KhaosT commented Dec 30, 2024

So the greyish tone of the HDR is not a kiloview firmware issue, but rather a visionOS bug?
No, there are two things.

  1. N60 firmware isn't sending the NDI HDR metadata correctly right now. The color override fixes that.
  2. visionOS 2.2 displays HDR content incorrectly (blurry) when using AVSampleBufferDisplayLayer. If you take out the color override, the content should be pretty sharp since HDR is not triggered.

@haseebrabbani
Copy link

Is there a conversation with Kiloview to get the HDR metadata set correctly? I've found them to be pretty responsive at [email protected], but I myself probably don't have the know-how to explain/verify the issue

@KhaosT
Copy link
Author

KhaosT commented Dec 31, 2024

@haseebrabbani yeah the Kiloview thing they are aware of that since end of November. They actually sent out a test firmware that have the correct metadata so initially I didn't add the color override feature. I was a little surprised that the final released version didn't include their fix, not sure what happened.

@haseebrabbani
Copy link

anyway you could provide a link to the test firmware? 😁

@KhaosT
Copy link
Author

KhaosT commented Dec 31, 2024

@haseebrabbani Unfortunately no. It's not much different from the release version, only the HDR metadata thing which you can correct with the color override thing. The visionOS 2.2 issue happens regardless whether it's showing the HDR content based on the accurate metadata, or from the override.

@haseebrabbani
Copy link

got it. so is there a conversation/ticket with Apple to fix this? if not, I can help with that. I'll just go ahead and file that in their Feedback app anyway so theres more voices

@KhaosT
Copy link
Author

KhaosT commented Dec 31, 2024

I didn't file a radar since they never fix my radars from the past and it seems like a waste of time 🙃 My hope is just some high profile company also running into the issue and then Apple will fix the problem for them 😛

@haseebrabbani
Copy link

no worries, just filed in their Feedback app.

also, can we get a tvOS app as well? would be nice to have for my setup

@LowRiderXR
Copy link

@KhaosT
I‘ve written to the kiloview support. They claim that the ndi HB meta data is correct, but there seems to be an anomaly in the ndi HX metadata, which they still try to fix.

Can I use the ndi HX mode with the vxio app or only the the HB mode? When I use the HX mode, I get the sound, but only a black screen.

@KhaosT
Copy link
Author

KhaosT commented Jan 3, 2025

I think when HX mode only works if you set the N60 to only do HX. At least for me, when both HX and HB mode is enabled, I also get a blank screen for HX.

@LowRiderXR
Copy link

Thank you, I tried it yesterday. HX mode does work, HX3 seems not to work. I will wait for the visionOS fix.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment