OSCQuery - vrchat-community/osc GitHub Wiki

Overview

VRChat implements the OSCQuery specification as of release 2023.3.1. This protocol enables OSC applications to more easily find each other, learn about each other's capabilities and automatically configure themselves so users don't have to mess around with IP addresses and Ports.

OSCQuery essentially adds two new features:

  • Advertising and Discovery of OSC and OSCQuery services on the link-local network through technology known as mDNS, Zeroconf and Bonjour. The service info here includes the IP address of the service and the receiving port it uses.
  • Serving information about the whole OSC address space and its current values over TCP so applications can describe their own features and discover the features of other applications.

:warning: VRChat running on Windows can only serve information about its OSC addresses and values to applications running on the same machine due to Windows security limitations in the HTTP library it uses. This still covers most use cases, especially since VRChat running on Android is not limited in this same way.

Scenarios

  • VRChat running in Windows can find OSCQuery applications running on the same machine which want to receive OSC messages for Avatars and the Tracking System, and send them data on the OSC port which they've bound to. It can also find OSCQuery applications running on mobile devices on the local network and do the same. Example: VRChat running on Windows, with an app that responds to avatar changes running on the same machine. VRChat finds this application automatically and sends the id of the changed avatar to this application when it happens (as well as all avatar parameters). This could also work if the application were running on an Android device on the local network, and if VRChat were running on Quest, sending to an application running elsewhere on the network.

  • VRChat running in Windows can be found by OSCQuery applications running on the same machine, and serve information about all the available OSC addresses as well as their values (for readable value endpoints). Example: a Text-To-Speech application running on your machine converts your voice to text and sends it to VRChat's /chatbox/input address to show the resulting text.

  • VRChat running on Android can to all of the above and ALSO serve information about all the available OSC addresses and their readable values to OSCQuery applications running anywhere else on the network.

Automatically Receiving OSC In Your Application

If a user passes arguments for an OSC Port at startup, then VRChat will still send all available OSC messages to that port. For users who don't set this, or users who use multiple OSC receiving apps, VRChat can now detect destinations and send OSC messages to multiple receivers.

To do this, your application should advertise its OSC and OSCQuery services, and the address tree it serves from OSCQuery should contain a path that matches something VRChat can send. Right now, that is:

  • /avatar - will receive /avatar/change as well as /avatar/parameter/* messages.
  • /tracking/vrsystem - will receive /tracking/vrsystem/head, /tracking/vrsystem/leftwrist, /tracking/vrsystem/rightwrist and /tracking/vrsystem/pose messages, after a user accepts an additional legal notice in VRChat.

When your program is recognized by VRChat, the user will see a HUD notification telling them that VRChat is going to send data to APPLICATION_NAME, including the name advertised by the service.