Tutorial: Using administration tool (ViveEngineAdm)
ViveEngineAdm is the administration tool included with ViveEngine. It is installed together with the engine by the installer.
Use it to manage the installation and perform low-level engine administration. Its primary purpose is to assist installation process and help developers verify status of individual components and collect diagnostic.
Command-line reference
For full command-line reference, see Administration tool reference (ViveEngineAdm).
Common uses:
- Check whether the RPC interface, orchestrator, gateway, and driver are online.
- Activate or inspect the current user's license.
- Install or uninstall engine components when doing manual setup.
- Load and unload plugins while testing integrations.
- View logs and create diagnostic reports for support.
Locate the tool
ViveEngineAdm lives in the engine installation directory.
For the Shared edition, the default installation directory is:
C:\Program Files\ViveEngine (Shared)\
The tool is available as a batch file:
ViveEngineAdm.bat
Open a terminal in that directory and run commands like this:
.\ViveEngineAdm.bat status
/Library/Application Support/ViveEngine (Shared)
The tool is available as a symlink:
ViveEngineAdm
Open a terminal in that directory and run commands like this:
./ViveEngineAdm status
Administrator privileges
Some ViveEngineAdm subcommands require Administrator privileges on Windows or sudo on macOS. The command reference usually calls this out, and the tool also reports when elevated privileges are required.
Health check
The first thing to do after installation is verify that the installed components are visible and running.
Check engine status
To check the engine status, run the status command from the installation directory.
./ViveEngineAdm status
A healthy fresh installation reports the RPC interface, orchestrator, gateway, and driver are all online.
ViveEngine status report
Profile: engine.shared/prod
Edition: ViveEngine (Shared) 1.3.0
RPC interface: online
RPC address: 127.0.0.1:49172
Orchestrator state: online
Gateway state online
Driver state: online
Now that the engine is running, the next step is to check the license for the user who will run the engine.
Activating license
Now check the license information. Immediately after installation, before activation, the license is not verified yet.
Activation is per-user
Licenses are activated per operating system user. Continue in the same terminal as the user who will use ViveEngine.
Check license status
To inspect the current user's license state, run license_info.
./ViveEngineAdm license_info
The output shows that no usable license is active for this user.
License info:
IsVerified: false
Mode: none
Type: none
Activation ID: n/a
Features: n/a
Key: n/a
Activations: n/a
IssueDate: n/a
ActivationDate: n/a
ExpirationDate: n/a
Activate the license
To activate the license with a license key, run activate_license --key. Other possible activation methods are --trial and --email + --password. Which methods are available depends on engine edition.
./ViveEngineAdm activate_license --key
The command will prompt you for the key.
Confirm license activation
To confirm that activation succeeded, run license_info again. This time, IsVerified should be true.
./ViveEngineAdm license_info
License info:
IsVerified: true
Mode: activation_key
Type: node_locked
Activation ID: 8f3b7c2a-4e91-4c6d-9a25-1d7e5b8f0c43
Features: voice_enhancements byoc_captioning
Key: VSND-2K9M-7Q4P-X8R3-N6T1
Activations: 7 / 100
IssueDate: 2026-06-15
ActivationDate: 2026-07-06
ExpirationDate: 2027-06-15
At this point, the installed engine is running and the current user has an active license. Setup is complete and the engine is ready for work.
Reporting bugs
If you need to report an issue, such as incorrect processing, a device not being detected, or a connection problem, create a diagnostic report archive. The archive collects information about the engine and the system so support can inspect the environment without asking you to copy many separate files and registry keys.
The report is a plain-text archive, ready for inspection. It has .zip format on Windows and .tar.gz on macOS.
| Information type | What it helps diagnose |
|---|---|
| Engine state and configuration | Whether the installed components are registered and configured as expected |
| Engine logs | What the orchestrator, gateway, driver, and related components were doing before the issue was reported |
| Operating system audio state | Whether the OS audio service and audio driver registration look correct |
| System details | Which OS version, user context, and environment the engine is running under |
Create a diagnostic report
To create the report in the default location, run create_report.
./ViveEngineAdm create_report
Report created: C:\Users\Alice\Desktop\viveengine-report-2026-07-11-143012.zip
Report created: /Users/alice/Desktop/viveengine-report-2026-07-11-143012.tar.gz
The tool prints the archive it created. By default it is placed on desktop.
Specify output directory
To choose where the archive is written, pass a directory:
.\ViveEngineAdm.bat create_report --directory=C:\Users\Public\Documents\ViveEngineReports
./ViveEngineAdm create_report --directory=/tmp/viveengine-reports
After the archive is created, you can send that archive by email or attach it to the support request. You do not need to extract it unless you want to inspect it by yourself.
Manual diagnostics
ViveEngineAdm provides several low-level commands that display different information about the engine and the system. They may be useful for debugging and troubleshooting.
Advanced usage
These commands are advanced diagnostics. They are generally not needed during normal operation and are intended for debugging.
Query engine components
To collect diagnostics about the engine itself, including component versions, installation paths, connection statuses, run engine_info.
./ViveEngineAdm engine_info
Example output:
Build Info:
Profile: engine.shared/prod
Edition: ViveEngine (Shared) 1.3.0
Revision: 27e3b53837
Orchestrator: com.vivesound.viveengine-shared.orchestrator
Launcher: com.vivesound.viveengine-shared.launcher
Gateway: com.vivesound.viveengine-shared.gateway
Driver: com.vivesound.viveengine-shared.driver
Install Info:
BundleDir: /Library/Application Support/ViveEngine (Shared)/ViveEngine.app
DriversDir: /Library/Audio/Plug-Ins/HAL
RundataDir: /Library/Application Support
Orchestrator Info:
State: online
Version: 1.3.0
Gateway Info:
State: online
Version: 1.3.0
Driver Info:
State: online
Version: 1.3.0
Capture engine logs
To capture engine logs and print them in real time to the console, run engine_logs. The logs can be filtered by various criterias.
./ViveEngineAdm engine_logs --level=Info
There are also two methods for capturing logs: rpc and syslog. The first one is the normal path, and the second is more an emergency channel. If some engine components lost connectivity, you can grab their logs via syslog to see what's happening there.
The log format undocumented and isn't stable, but generally it's self-explanatory and often can be useful for troubleshooting.
Inspect OS audio server and loaded extensions
To troubleshoot OS integration you may want to query operating system sound server (that is AudioSrv on Windows and coreaudiod on Mac).
The sound_info command prints information about the sound server process and the dynamic modules currently loaded into it. This way you can confirm that the ViveEngine driver was properly detected and loaded.
sudo ./ViveEngineAdm sound_info
Example output:
Audio Server:
Name: coreaudiod
PID: 443
Driver Sandbox:
Name: Core Audio Driver (ViveEngine@Shared.driver)
PID: 12837
Modules:
/System/Library/Frameworks/CoreAudio.framework/Versions/A/XPCServices/com.apple.audio.Core-Audio-Driver-Service.helper.xpc/Contents/MacOS/com.apple.audio.Core-Audio-Driver-Service.helper
/Library/Audio/Plug-Ins/HAL/ViveEngine@Shared.driver/Contents/MacOS/ViveEngineDriver
/usr/lib/dyld
Inspect service registration
To collect information about background services registered by the engine in the OS, use list_services. The command searches through all registered services, both system and per-user.
sudo ./ViveEngineAdm list_services
Example output:
Service Launcher:
BundlePath: /Library/Application Support/ViveEngine (Shared)/ViveEngine.app/Contents/Library/LoginItems/ViveEngineLauncher.app
BundleName: ViveEngineLauncher
BundleID: com.vivesound.vivetune.launcher
Executable: /Library/Application Support/ViveEngine (Shared)/ViveEngine.app/Contents/Library/LoginItems/ViveEngineLauncher.app/Contents/MacOS/ViveEngineLauncher
State: loaded
PID: 47446
Service:
BundlePath: /Library/Application Support/ViveEngine (Shared)/ViveEngine.app
BundleName: ViveEngine
BundleID: com.vivesound.vivetune.orchestrator
Executable: /Library/Application Support/ViveEngine (Shared)/ViveEngine.app/Contents/MacOS/ViveEngineOrchestrator
State: loaded
PID: 47455
Inspect driver registration
ViveEngine installs a driver for operating system sound server. On Windows, the engine registers Audio Processing Object (APO), and on Mac it installs Audio HAL Plug-In. Third-party drives may be present as well, depending on installed software and hardware.
To troubleshoot driver registration, use list_drivers command. It will search for all registered drivers and display various useful information. This is especially useful on Windows whete driver registration consists of many pieces scattered across the registry.
Loaded libraries vs. registered drivers
sound_info prints the libraries currently loaded by the audio server process. list_drivers prints the drivers logically registered in the operating system. When everything is working fine, the driver should appear in both outputs.
sudo ./ViveEngineAdm list_drivers
Example output:
HAL Driver:
BundlePath: /Library/Audio/Plug-Ins/HAL/ViveEngine@Shared.driver
BundleName: ViveEngine@Shared
BundleID: com.vivesound.viveengine-shared.driver
Version: 1.3.0
DriverUUID:
{79E2C3FF-CDAB-4736-9BBF-C28156C53EA7}
HAL Driver:
BundlePath: /Library/Audio/Plug-Ins/HAL/ZoomAudioDevice.driver
BundleName: ZoomAudioDevice
BundleID: zoom.us.ZoomAudioDevice
Version: 1.0