Debugging Tools
Updated: Feb 26, 2025
During a debugging session, interacting with the headset without wearing it can come very handy. Meta Quest Developer Hub (MQDH) offers tools to accelerate debugging and iteration by letting you capture screenshots, record videos, cast your headset to computer, and launch browser in headset, all from MQDH.
Capture monoscopic or stereoscopic screenshots of the live display of your headset with a single click, which avoids typing long commands or pressing combination of keys.
- Connect your headset with MQDH.
- Run your app on the connected headset.
- On Device Manager, under Device Actions, click Capture or press CTRL + Shift + S keyboard shortcut to capture the screenshot.
- To change the setting between stereoscopic and monoscopic, click the gear icon next to Capture, and in the Screenshot Type list, select Single Eye for monoscopic screenshot or Both Eyes for stereoscopic screenshot. By default, MQDH captures monoscopic screenshot.
MQDH opens the screenshot in a new window, from where you can copy the screenshot to the clipboard as well as take another screenshot. All screenshot images are stored locally on your computer in the /Users/janedoe/AppData/Roaming/odh/captures folder.
Record a monoscopic or stereoscopic MP4 video from your headset for a maximum of three minutes and use it for debugging or in marketing collaterals. Audio is not recorded with the video.
- Connect your headset with MQDH.
- Run your app on the connected headset.
- On Device Manager, under Device Actions, click Record or press CTRL + Shift + R keyboard shortcut to start and stop the recording.
- To change the settings for the recording, such as switching between stereoscopic and monoscopic, click the gear icon next to Record.
- In the Video Record Settings window that opens:
- Under Eye View, select Single Eye, Stereo Audio for monoscopic recording or Both Eyes, No Audio for stereoscopic recording. By default, MQDH records monoscopic video.
- Under Resolution, select the resolution and frames per second (fps), for example, 1024p @ 36fps (1:1) (default), 1080p @ 36fps (16:9), and so on.
- Under Bitrate, choose the bitrate, which ranges from 5 Mbps (very low quality) (default) to 40 Mbps (very high quality).
- Click Save.
MQDH opens the recording in a video player, from where you can play the video or share it externally. All recordings are stored locally on your computer in the /Users/janedoe/AppData/Roaming/odh/captures folder. You can also disable auto-opening the video player in Video Record Settings by unchecking the checkbox.
Cast provides a reliable and high-quality Quest-to-Desktop casting experience, enabling you to easily stream and record VR gameplay footage with others.
- Connect your headset with MQDH.
- Navigate to the Device Manager. Under the Device Actions section, select Cast to start casting.
- Once the casting window appears, use the menu bar at the top. This tool offers several options to customize your casting experience.
- To stop casting, either close the casting window or click the stop icon next to Cast Device.
Note: While casting, MQDH turns off the proximity sensor automatically. Once you stop casting, MQDH reactivates the proximity sensor to prevent unexpected battery drainage.
You have the option to switch between different aspect ratios while casting and recording. To do so, select the dropdown menu that shows Original (1:1).
- Original (1:1) - This is the uncropped image from the compositor which is roughly square (per eye).
- Cropped (16:9) - This is a widescreen view created by vertically center-cropping the top and bottom of the source image.
- Cinematic (16:9) - This is a widescreen view created by increasing the horizontally rendered FOV by around 30 degrees.
- Selecting this aspect ratio requires restarting any active immersive applications.
- The perceived horizontal resolution inside the headset will decrease slightly.
- This may impact in-game performance due to rendering additional geometry.
Enjoy the convenience of wireless casting and stream the headset display directly to your computer.
- Ensure your headset and desktop are connected to the same Wi-Fi network.
- On Device Manager, under Device Actions, toggle on ADB over Wi-Fi to enable wireless casting.
- When ADB over Wi-Fi is turned on, casting sessions will automatically use a wireless connection when possible.
- To stop casting wirelessly, simply toggle off ADB over Wi-Fi and start a new casting session.
While casting, capture uncompressed, full-resolution screenshots of your headset with a single click.
- Start a casting session.
- In the casting window, click the camera button to capture a screenshot.
- Screenshots are stored on your headset and you can access them by navigating to File Manager > On Device > Images.
Cast allows you to cast and record high quality videos simultaneously for debugging or marketing purposes. Footage captured using the method below is encoded at the source resolution. This results in a noticeably higher bitrate and smoother frame pacing, as opposed to capturing the screen of the casting window, for instance, using OBS.
- Start a casting session.
- If you want both system and gameplay audio included in your recording, make sure the speaker icon does not display it’s muted. Do this by ensuring there’s no line through the icon.
- Note: Microphone audio is not yet supported.
- In the casting window, click the camcorder button to start recording and click again to end recording.
- Videos are stored on your headset and you can access them by navigating to File Manager > On Device > Videos.
To control your headset in a casting session with the precision of your mouse and keyboard, you can forward input from your computer keyboard.
- Start a casting session in MQDH.
- Click the headset icon to enable input forwarding.
Click the keyboard icon to start forwarding text input.
You can now control your headset with the following key bindings:
| Action | Key Binding |
|---|
Look Around | Mouse2 Drag |
Move Forward | W, ↑ |
Move Right | D |
Move Backward | S, ↓ |
Move Left | A |
Turn Right | → |
Turn Left | ← |
Fly Upward | Q, Space |
Fly Downward | E, Ctrl |
Sprint | Shift |
Gaze Click | Mouse1
Note: to use Gaze Click, you must disable hand tracking and disconnect the controllers. |
Menu | Esc |
To disable input forwarding, click the headset icon again.
To configure your casting and recording experience, click the gear icon located in the menu bar at the top. The streaming settings you choose will impact the quality of the casted image:
- Target Bitrate controls the overall quality of the streams. A higher bitrate will reduce visual artifacts, but it might also increase latency. Cast by default, adaptively uses the highest bitrate that doesn’t impact latency.
- Maximum Resolution caps the maximum allowed stream resolution. Lowering the resolution could potentially improve performance. If the casting stream is lagging or significantly delayed, reduce the maximum resolution.
- Maximum Framerate sets the maximum frame rate of the stream. Higher frame rates will result in a smoother stream but could impact system performance.
- Adaptively Skip Frames decides whether the encoder should skip frames based on system performance. If you disable this setting, it might reduce stuttering but it could also increase the worst-case stream latency.
- Pause When Recording decides whether the stream should automatically pause while recording. Enabling this setting can improve the smoothness of captured videos.
The recording settings play a crucial role in determining the quality of captured videos. Here’s a closer look at these settings:
- Target Bitrate controls the overall quality of recorded videos. Higher bitrates will result in larger file sizes.
- When you set Capture Format to MAX, you can produce near-lossless video files optimized for post-production. A minute of VR footage is around 600 MB while a minute of MR footage is around 1.2 GB.
- Target Framerate sets a target variable frame rate for recorded videos. Higher frame rates may impact in-headset performance.
- Use the record video button in the menu bar - Capturing footage through the record video button ensures encoding at the source resolution. This method offers higher bitrate and smoother frame pacing compared to capturing the casting window, such as with OBS.
- Enable 60 FPS for recordings - Beyond merely setting 60 FPS as your target recording frame rate in Cast settings, you might need to enable the Pause When Recording setting. This is to maintain a consistent frame rate, depending on the game.
- Select the same eye as your dominant hand - If you’re right-handed, it’s best to use your right eye for casting and recording. This alignment ensures actions like peering down a scope are framed correctly.
- Delete video files after transfer - Video files recorded by Cast can be quite substantial, particularly when selecting MAX as the capture format. Verify that your device has ample storage space before initiating a recording. Remember to delete video files manually after moving them to your computer.
Instead of manually searching for screenshot images, video recordings, or recorded metrics files in the local folders on your computer or headset, you can use the Library.
- Connect your headset to MQDH.
- In the menu on the left, select File Manager.
- To see the list of screenshots, video recordings, and metric recordings saved on the headset, select On Device.
- To see the list of screenshots and video recordings captured directly from MQDH, click MQDH Local.
Launch a web page in the headset from MQDH without using the VR keyboard in headset. You can open any URL and is a great way to launch a WebXR application that you want to test or debug.
- Connect your headset to MQDH.
- On Device Manager, locate Browser under Device Actions. Type the URL and click Open.
- Put on your headset to view the web page.
You can launch and kill apps apps from the Device Manager.
Do the following to launch an app:
- Connect your headset with MQDH.
- On Device Manager, under Apps, find the desired app, and then click Launch App.
To kill an app, on Device Manager, under Apps, find the running app, and then click Stop App.
Multiplayer testing allows developers to seamlessly test multiplayer destination sessions from MQDH. It allows one or more devices to launch an activity with a group launch intent attached in order to debug and test launching into private and public lobbies within the app. The feature works for any app that has:
- At least one destination registered as group launch in the developer portal. When creating the destination, you must set the Group Launch Capacity Max to a value greater than 1.
- At least one build uploaded to a release channel.
To use multiplayer testing, on Device Manager, under Device Actions, click Join next to Multiplayer Testing. Fill in the following fields in the modal:
- Active Devices - This is populated with devices that MQDH knows about, and allows selecting any connected devices. At least one device must be selected.
- Org Name - Lists all of the Orgs associated with the signed-in user, and defaults to the selected Org from the App Distribution tab. Updating this value will reset App Name and Display Name, and populate App Name with all apps associated with the new Org. An Org must be selected.
- App Name - This is populated with all apps in the selected Org that contain a package name. Changing this value resets Display Name. An app must be selected.
- Destination Name - This is populated with the names provided when creating the destinations in the developer dashboard. This only includes destinations marked as group launch. A destination must be selected.
- Lobby Session ID - This is the session ID that will be passed along with the deep link intent. This field cannot be left blank.
You can optionally use the Close modal after launch check box.
Once everything has been filled in, click Launch to start the activity on the selected devices.
ADB command-line tool enables direct communication with your Meta Quest headset and provides a convenient way of setting system properties (
adb shell setprop). However, trying to remember the names and values of different system properties can be difficult. MQDH offers the
VrRuntime Debugging Tool that allows you to experiment with multiple vrruntime settings and rendering features, in a more user-friendly and less error-prone manner.
To use this tool, On Device Manager, under Device Actions, click the gear icon next to VrRuntime Debugging Tool.
This panel accepts three types of input: toggle switch, dropdown menu and text box. To adjust individual settings, you can toggle a switch, or select an item from the dropdown menu, or type in an numerical value in the text box and press Enter, based on the type of the interface provided.
More explanation for system properties can be found in the table below.
| Property Name | Description |
|---|
debug.oculus.textureWidth | Set eye buffer width (pixels) |
debug.oculus.textureHeight | Set eye buffer height (pixels) |
debug.oculus.cpuLevel | Set CPU to a recommended level |
debug.oculus.gpuLevel | Set GPU to a recommended level |
debug.oculus.eyeFovUp
debug.oculus.eyeFovDown
debug.oculus.eyeFovInward
debug.oculus.eyeFovOutward | Set device FOV angle for a specific direction |
debug.oculus.colorspace.overrideColorspace | Set display colorspace override |
debug.oculus.forceSpaceWarp | Set motion vector source for Application SpaceWarp |
debug.oculus.swapInterval | Set a specific swap interval value: "0", "1", "2", "3" |
debug.oculus.dynResScaler | Set dynamic resolution scale factor
Note: this only works for apps that have dynamic resolution enabled. |
debug.oculus.localDimming | Set local dimming mode on/off |
debug.oculus.gfr.mode | Set Gaze Foveated Rendering (GFR) mode on/off |
debug.oculus.foveation.dynamic | Set dynamic foveated rendering on/off |
debug.oculus.foveation.level | Set foveation level
Note: this property is only enabled when dynamic foveated rendering is off. |
debug.oculus.foveation.subsampled | Set subsampled layout on/off |
debug.oculus.layerFilter | Set layer filtering mode |
debug.oculus.layerFilter.foveate | Set sharpening radius for foveated rendering |
debug.oculus.pfr.autofilter | Set auto filter mode |
