Engine discovery

To talk to the engine over gRPC, you first need to discover its address. If you use a client library, this happens automatically. With a generated gRPC client, you read the address yourself.

Metadata file

The Control API listens on 127.0.0.1 on a dynamic port, chosen at startup, and the engine writes its address to a metadata file that any client can read.

The file lives in a system directory and is named after the engine's edition identifier, in reverse-DNS form:

Platform	File
Windows	C:\ProgramData\ViveSound\com.vivesound.viveengine-shared.metadata.json
macOS	/Library/Application Support/com.vivesound.viveengine-shared.metadata.json

If you use a non-shared edition, such as an enterprise dedicated edition, you need to replace viveengine-shared in the file name with your edition identifier.

The file is JSON with the engine's address and a few details:

{
  "edition": "ViveEngine (Shared)",
  "version": "1.1.92",
  "rpc_address": "127.0.0.1:52731"
}

The rpc_address is what you feed to your gRPC client. The rest is informational.

The address can change

The port is assigned at startup, and changes if engine restarts. Don't cache the address — re-read the metadata each time you reconnect.

Client libraries

If you use an SDK client library, such as C# or Go, it discovers the shared engine's address automatically — you don't read the metadata file yourself.

To connect to a different edition, you can query the available editions and their addresses, or pass an address explicitly.

Command-line tool

You can also read the metadata with the vive-ctl command-line tool:

$ vive-ctl engine list
EDITION              VERSION  ADDRESS          IDENTIFIER
ViveEngine (Shared)  1.1.92   127.0.0.1:52731  com.vivesound.viveengine-shared

Add --json for machine-readable output:

$ vive-ctl engine list --json
[
  {
    "edition": "ViveEngine (Shared)",
    "identifier": "com.vivesound.viveengine-shared",
    "version": "1.1.92",
    "rpc_address": "127.0.0.1:52731"
  }
]

To check the default engine and whether it's currently reachable, use engine status:

$ vive-ctl engine status
Edition:     ViveEngine (Shared)
Identifier:  com.vivesound.viveengine-shared
Version:     1.1.92
Address:     127.0.0.1:52731
Status:      online