Skip to content

Troubleshooting

Jump to bottom
Tom edited this page Sep 30, 2025 · 1 revision

Troubleshooting Guide

Common issues and solutions for the Quest WebRTC AI Video Processing System.

🛠️ Camera Issues

"Passthrough Camera not supported"

Symptoms:

  • Error message on startup
  • Black camera preview
  • No local video feed

Solutions:

  1. Verify Device Compatibility

    • ✅ Quest 3 or Quest 3S only
    • ❌ Quest 2, Quest Pro not supported

  2. Check Horizon OS Version

    • Required: v74 or higher
    • Update via Quest Settings → System → Software Update

  3. Validate Camera Support

    // Check in PassthroughCameraUtils.cs
if (!PassthroughCameraUtils.IsSupported) {
    Debug.LogError("Passthrough camera not supported on this device");
}

"Permission denied"

Symptoms:

  • Camera preview shows permission error
  • Application crashes on camera access
  • Camera initialization fails

Solutions:

  1. Grant Permissions Manually

    • Quest Settings → Apps → Unknown Sources
    • Find your app → Permissions
    • Enable both Camera and Microphone

  2. Required Permissions Check

    android.permission.CAMERA (Standard Android)
horizonos.permission.HEADSET_CAMERA (Quest-specific)

  3. Restart Application

    • Close app completely
    • Restart after granting permissions
    • Permissions require app restart to take effect

"Black camera preview"

Symptoms:

  • Camera permission granted but no video
  • Local preview shows black screen
  • Camera seems initialized but no image

Solutions:

  1. Check Lighting Conditions

    • Ensure adequate room lighting
    • Quest cameras need minimum light levels
    • Try different location or add lighting

  2. Clean Camera Lenses

    • Gently clean Quest passthrough cameras
    • Remove dust, fingerprints, or obstructions
    • Use microfiber cloth

  3. Wait for Initialization

    // In WebCamTextureManager.cs, proper initialization:
yield return null;
yield return new WaitForSeconds(1); // Critical delay
webCamTexture.Play();

  4. Check Camera Selection

    • Try switching between Left/Right eye cameras
    • Some devices may have one camera with better performance

🌐 WebRTC Connection Issues

"Connection failed" / "WebSocket error"

Symptoms:

  • No AI processing
  • Connection timeout messages
  • WebSocket connection drops

Solutions:

  1. Verify Internet Bandwidth

    # Test connection speed (8+ Mbps required)
speedtest-cli  # Or use web-based speed test
    • Required: 8+ Mbps bidirectional
    • Recommended: 16+ Mbps for optimal quality

  2. Check WebSocket URL

    // Verify in WebRTCConnection component
string serverUrl = "wss://bouncer.mirage.decart.ai/ws?model=decart-v2v-v2.0-704p";

  3. Test Different Networks

    • Try mobile hotspot
    • Switch to 5GHz WiFi
    • Avoid congested networks

  4. Firewall/Network Restrictions

    • Ensure WebSocket (WSS) traffic allowed
    • Check corporate firewall settings
    • Try from different network location

"No processed video" / "AI not responding"

Symptoms:

  • Local camera works fine
  • WebSocket connection successful
  • No AI-processed video appears

Solutions:

  1. Wait for Initial Processing

    • First AI response takes 5-10 seconds
    • Allow warmup time for AI model
    • Check for processing indicators in UI

  2. Verify Video Receiver Setup

    // In WebRTCController.cs, check:
if (receivedVideoImage != null && receivedVideoImage.texture != null) {
    // Video receiver properly configured
}

  3. Check ICE Connection State

    // Monitor WebRTC connection state
Debug.Log($"ICE Connection State: {pc.IceConnectionState}");
// Should show "Connected" for successful peer connection

  4. AI Service Status

    • Decart AI service may be temporarily unavailable
    • Check service status or try again later
    • Monitor debug logs for specific error messages

"High latency" / "Slow response"

Symptoms:

  • Long delay between actions and AI response
  • Video stuttering or freezing
  • Poor real-time performance

Solutions:

  1. Optimize Network Connection

    • Use 5GHz WiFi (not 2.4GHz)
    • Position Quest closer to router
    • Minimize WiFi interference

  2. Close Background Applications

    • Quest: Close unused apps
    • PC: Close bandwidth-intensive programs
    • Router: Limit other devices' usage

  3. Adjust Video Quality

    // In WebRTCConnection.cs, reduce resolution/bitrate:
VideoResolution = new Vector2Int(960, 540);  // Lower resolution
maxBitrate = 2000000UL;  // 2Mbps instead of 4Mbps

  4. Check Thermal Throttling

    • Quest may reduce performance when overheating
    • Allow device to cool down
    • Ensure good ventilation during use

🎭 Performance Issues

"Stuttering video" / "Frame drops"

Symptoms:

  • Jerky video playback
  • Inconsistent frame rates
  • Visual stuttering

Solutions:

  1. Reduce Video Resolution

    // Balanced settings for performance
Resolution: 960x540 or 1280x720
Frame Rate: 16fps (matches AI processing)
Bitrate: 2Mbps sustained

  2. Unity Performance Optimization

    • Use Unity Profiler to identify bottlenecks
    • Monitor CPU, GPU, and memory usage
    • Check for memory leaks in WebCamTexture handling

  3. Device Cooling

    • Ensure Quest isn't overheating
    • Take breaks to allow cooling
    • Use in well-ventilated environment

"App crashes" / "Out of memory"

Symptoms:

  • Application closes unexpectedly
  • Unity out of memory errors
  • System becomes unresponsive

Solutions:

  1. Check Memory Leaks

    // Proper cleanup in OnDisable/OnDestroy
void OnDestroy() {
    if (webCamTexture != null) {
        webCamTexture.Stop();
        webCamTexture = null;
    }
}

  2. Unity Profiler Analysis

    • Monitor memory allocation patterns
    • Check for texture memory leaks
    • Verify proper WebRTC cleanup

  3. Device Resources

    • Close all other Quest applications
    • Restart Quest if needed
    • Ensure sufficient storage space

🎮 Quest-Specific Issues

"Controllers not responding" / "Input issues"

Symptoms:

  • A/B buttons don't change styles
  • No response to controller input
  • Voice commands not working

Solutions:

  1. Controller Calibration

    • Quest Settings → Device → Controllers
    • Recalibrate or reset controllers
    • Check battery levels

  2. Input System Configuration

    // Verify in WebRTCController.cs
OVRInput.GetDown(OVRInput.Button.One);  // A button
OVRInput.GetDown(OVRInput.Button.Two);  // B button

  3. Voice Command Setup

    • Check Meta Voice SDK configuration
    • Verify Wit.ai app settings
    • Ensure microphone permissions granted

"Unity Scene Issues"

Symptoms:

  • Scene fails to load properly
  • Missing UI elements
  • Components not initialized

Solutions:

  1. Scene Configuration Check

    MainCanvas should be active
├─ receivedVideoImage (RawImage)
├─ promptNameText (TextMeshPro)
└─ ReceivingRawImagesParent

  2. Inspector References

    • Verify all component references assigned
    • Check for missing script references
    • Ensure proper GameObject hierarchy

  3. Asset Reimport

    • Right-click project folder → Reimport All
    • Clear Unity cache if needed
    • Restart Unity editor

🔍 Advanced Debugging

Enable Debug Logging

  1. WebRTC Debug Logs

    SimpleWebRTCLogger.Log("Debug message");

  2. Unity Console Monitoring

    • Filter logs by WebRTC, Camera, Unity tags
    • Monitor for specific error patterns

  3. Quest Device Logs

    adb logcat -s Unity:* WebRTC:* Camera:*

Performance Monitoring

  1. Unity Profiler

    • Profile on actual Quest hardware
    • Monitor CPU, GPU, Memory, Network
    • Identify performance bottlenecks

  2. Quest Developer Hub

    • Real-time performance metrics
    • Thermal monitoring
    • Network usage analysis

Network Diagnostics

  1. Connection Testing

    # Test WebSocket connection
wscat -c wss://bouncer.mirage.decart.ai/ws?model=decart-v2v-v2.0-704p

  2. Latency Measurement

    • Monitor round-trip times
    • Check for packet loss
    • Analyze network congestion

📞 Getting Additional Help

Before Asking for Help

  1. Check Known Issues: Review current limitations
  2. Search Issues: Check GitHub issues for similar problems
  3. Provide Details: Include device info, Unity version, exact error messages
  4. Include Logs: Unity console output and device logs

Support Channels

  • GitHub Issues: Technical problems and bug reports
  • Email: tom@decart.ai for research collaboration
  • Documentation: Check API Reference and FAQ sections

Information to Include

When reporting issues, always include:

  • Quest device model and Horizon OS version
  • Unity version and platform settings
  • Network speed and connection type
  • Exact steps to reproduce the issue
  • Unity console logs and Quest device logs
  • Screenshots or recordings if applicable

Quick Reference Links:

Clone this wiki locally