Administration tool (ViveEngineAdm)

ViveEngineAdm is the command-line tool for installing, configuring, and debugging ViveEngine.

Index:

Global options
Installation
- status
- install
- uninstall
License management
Plugin management
Report management
- create_report
Low-level control
Low-level diagnostic

Global options

These options can be used with any command:

Flag	Description
`-v, --verbose`	Force verbose logging
`--version`	Print version and exit
`--help`	Show help message

Installation

`status`

Prints engine status.

Tip

Use this command to check if the engine is up and running.

Flags

None.

Example

ViveEngineAdm status

Output

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

`install`

Use this command to install the engine manually instead of using the installer. If you're using the installer, this command is invoked automatically.

You need to unpack engine distribution into desired installation directory (usually under C:\Program Files on Windows and /Applications on macOS). Then run ViveEngineAdm from that location.

The command registers engine components, starts services, and loads the driver. It performs only system-wide setup. Per-user setup happens automatically on first access from a user.

Note

This command requires administrator privileges.
After installing engine, a reboot is required to complete registration.

Danger

Don't relocate or remove the bundle until it's explicitly uninstalled. Run ViveEngineAdm install after unpacking engine distribution into desired installation path. The command registers absolute paths to the bundle in the operating system.

Installation sequence:

Unregister any previously installed components
Register components from the bundle in OS
Start background services
Attach driver to audio devices

Flags

None.

Example

ViveEngineAdm install

`uninstall`

Use this command to uninstall the engine manually instead of using the uninstaller. If you're using the uninstaller, this command is invoked automatically.

The command unloads the driver, stops services, and unregisters components. It performs both system-wide and per-user cleanup, for all users on the machine.

Note

This command requires administrator privileges.
After uninstalling engine, a reboot is required to complete de-registration. Also, on Windows you may not be able to fully remove the bundle until you reboot.

Danger

Don't remove the bundle until it's explicitly uninstalled. Run ViveEngineAdm uninstall and reboot before removing the bundle.

Uninstallation sequence:

Detach driver from all audio devices
Deactivate license (if activated)
Stop background services
Unregister all components from OS
Remove runtime data like logs, settings, etc.

Flags

Flag	Default	Description
`--no-wipe`	false	Don't remove runtime data after uninstallation

Example

# Uninstall and remove all data
ViveEngineAdm uninstall

# Uninstall but keep data
ViveEngineAdm uninstall --no-wipe

License management

`license_info`

Prints license status of currently logged in user.

Flags

None.

Example

ViveEngineAdm license_info

Output

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

`activate_license`

Activates license of currently logged in user to use the engine.

Needs to be done once for every OS user that needs access to the engine. Each user has its own activation and is treated as a separate seat.

Note

License activation requires an internet connection to validate and register your license.

Tip

You can (de)activate license via RPC or CLI, whatever is more convenient.

Available activation methods depend on your engine edition: --key (activate with a license key), --email (authenticate with email and password), and --trial (start a machine-locked trial).

When using --key or --email, the license key or password is prompted from stdin unless --file is provided.

Flags

Flag	Default	Description
`--trial`	false	Activate trial on this machine
`-k, --key`	false	Activate with license key
`-e, --email=EMAIL`	-	Activate with user email and password
`-f, --file=FILE`	-	Read license key or user password from file instead of stdin

Examples

# Start trial
ViveEngineAdm activate_license --trial

# Activate with license key (prompted for key)
ViveEngineAdm activate_license --key

# Activate with license key from file
ViveEngineAdm activate_license --key --file=/path/to/key.txt

# Activate with email (prompted for password)
ViveEngineAdm activate_license --email=user@example.com

# Activate with email and password from file
ViveEngineAdm activate_license --email=user@example.com --file=/path/to/password.txt

`deactivate_license`

Deactivates license of currently logged in user. Use when you need to free up the license seat for reuse or activate another license.

Note

License deactivation requires an internet connection to free up the seat.

Tip

You can (de)activate license via RPC or CLI, whatever is more convenient.

Flags

None.

Example

ViveEngineAdm deactivate_license

Plugin management

`load_plugin`

Load a plugin into the engine. The plugin stays loaded until you unload it or the engine restarts.

The engine loads the binary from the given filesystem location and makes it available for creating instances.

Flags

Flag	Description
`-t, --type=TYPE`	Plugin type: `native`, `golang`, or `dotnet`
`-l, --location=PATH`	Plugin binary location on the filesystem

Example

ViveEngineAdm load_plugin --type native --location "/Library/Application Support/ExampleProduct/ExamplePlugin.so"

`list_plugins`

List plugins currently loaded into the engine, along with how many instances of each are running.

Flags

None.

Example

ViveEngineAdm list_plugins

Output

Plugin:
    PluginID:        pn:4e8b2:91f6a:c03d7:bb42e
    Type:            native
    Location:        /Library/Application Support/ExampleProduct/ExamplePlugin.so
    Instance Count:  0

Total 1 plugin(s) loaded with 0 instance(s)

`unload_plugin`

Unload a plugin from the engine. Use the PluginID reported by list_plugins.

Flags

Flag	Description
`-p, --plugin-id=ID`	Plugin ID

Example

ViveEngineAdm unload_plugin --plugin-id pn:4e8b2:91f6a:c03d7:bb42e

Report management

`create_report`

Create a diagnostic report archive. You can send it to ViveSound support for troubleshooting.

Report includes engine logs, configuration files, registry settings, and system information. It is packaged as a .tar.gz archive on macOS or a .zip archive on Windows.

Note

Everything inside report is plain text for easy inspection.

Flags

Flag	Description
`-d, --directory=DIR`	Directory to save the report archive. If not specified, saves to user's desktop

Example

# Create report on desktop (default)
ViveEngineAdm create_report

# Create report in specific directory
ViveEngineAdm create_report --directory=/path/to/reports

Low-level control

Warning

Commands in this section provide direct control over internal engine components, so please use with care. They are not needed for normal operation and are intended for debugging and troubleshooting.

`register_orchestrator`

Register orchestrator service for current user.

Note

On Windows, this command requires administrator privileges.

Flags

None.

Example

ViveEngineAdm register_orchestrator

`unregister_orchestrator`

Unregister orchestrator service from current user.

By default, unregisters the orchestrator for the current user only. Use --all-users to unregister for all users on the machine.

Note

On Windows, this command requires administrator privileges. On macOS/Linux, administrator privileges are only required when using the --all-users flag.

Flags

Flag	Default	Description
`--all-users`	false	Unregister orchestrator for all users instead of current user only

Examples

# Unregister for current user
ViveEngineAdm unregister_orchestrator

# Unregister for all users (requires admin)
ViveEngineAdm unregister_orchestrator --all-users

`start_orchestrator`

Start orchestrator service of current user.

Note

On Windows, this command requires administrator privileges.

Flags

None.

Example

ViveEngineAdm start_orchestrator

`stop_orchestrator`

Stop orchestrator service of current user.

Note

On Windows, this command requires administrator privileges.

Flags

None.

Example

ViveEngineAdm stop_orchestrator

`register_gateway`

Register gateway system-wide service.

Note

This command requires administrator privileges.

Flags

None.

Example

ViveEngineAdm register_gateway

`unregister_gateway`

Unregister gateway system-wide service.

Note

This command requires administrator privileges.

Flags

None.

Example

ViveEngineAdm unregister_gateway

`start_gateway`

Start gateway service.

Note

This command requires administrator privileges.

Flags

None.

Example

ViveEngineAdm start_gateway

`stop_gateway`

Stop gateway service.

Note

This command requires administrator privileges.

Flags

None.

Example

ViveEngineAdm stop_gateway

`register_driver`

Register device driver in the system.

Note

This command requires administrator privileges.

On Windows, the driver is registered as an Audio Processing Object (APO). The command also enables loading of unsigned APOs.

On macOS, the driver bundle is copied into the system drivers directory.

Flags

None.

Example

ViveEngineAdm register_driver

`unregister_driver`

Unregister device driver from the system.

Note

This command requires administrator privileges.

On Windows, the driver is unregistered as an Audio Processing Object (APO).

On macOS, the driver bundle is removed from the system drivers directory.

Flags

None.

Example

ViveEngineAdm unregister_driver

`dock_driver`

Attach device driver to audio devices.

Note

This command requires running orchestrator and gateway.

This command connects the driver to audio devices, enabling ViveEngine to intercept and process audio streams.

Flags

None.

Example

ViveEngineAdm dock_driver

`undock_driver`

Detach device driver from audio devices.

Note

This command requires running orchestrator and gateway.

This command disconnects the driver from audio devices, disabling ViveEngine's audio processing.

Flags

None.

Example

ViveEngineAdm undock_driver

`wipe_data`

Remove runtime data created by service and driver.

Note

This command requires administrator privileges.

This command removes all runtime data (logs, caches, configs, registry keys) for all users on the machine. It cleans up both user-specific directories and system-wide directories. It doesn't remove the engine bundle.

Danger

This is a destructive operation that resets state for all users. Normally it is called as the final step of uninstallation.

Flags

None.

Example

ViveEngineAdm wipe_data

`wipe_license`

Remove local licensing data of currently logged in user.

This command removes all license-related data of the user, including trial activations and license keys. Unlike deactivate_license, this command does not contact the license server and does not free up a license seat.

Danger

Use deactivate_license to properly release a license seat. This command is only useful to reset corrupted activation data.

Flags

None.

Example

ViveEngineAdm wipe_license

Low-level diagnostic

Note

Commands in this section allow to collect various low-level info related to engine operation. They are intended for debugging and troubleshooting.

`engine_logs`

Capture engine logs in real-time.

This command connects to ViveEngine and continuously streams log messages to the terminal. This includes logs from all services and driver.

Flags

Flag	Default	Description
`-m, --method=METHOD`	`rpc`	Capture logs via RPC interface or native os_log/eventlog interface. Options: `rpc`, `syslog`
`-l, --level=LEVEL`	-	Filter log messages by level. Use short name (`A`, `E`, `W`, `I`, `D`, `T`, `N`) or long name (`Alert`, `Error`, `Warn`, `Info`, `Debug`, `Trace`, `Noise`)
`-s, --source=SOURCES`	-	Filter log messages by source(s). Comma-separated list of sources (`ORC,GWT,DRV`)
`-p, --process=PROCESSES`	-	Filter log messages by process name(s) or glob(s). Comma-separated list. Only works with `--method=syslog`
`-f, --file=FILE`	-	Additionally save captured log entries to text file

Examples

# Capture logs via RPC (default method)
ViveEngineAdm engine_logs

# Capture logs from system log
ViveEngineAdm engine_logs --method=syslog

# Show only error messages
ViveEngineAdm engine_logs --level=Error

# Filter by specific sources
ViveEngineAdm engine_logs --source=DRV

# Filter by process name (syslog only)
ViveEngineAdm engine_logs --method=syslog --process="ViveOrchestrator*"

# Save logs to file while displaying them
ViveEngineAdm engine_logs --file=/tmp/engine.log

`engine_info`

Prints detailed info about engine installation and runtime state.

Flags

None.

Example

ViveEngineAdm engine_info

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
    HAL_UUID:       {79E2C3FF-CDAB-4736-9BBF-C28156C53EA7}
    APPID:          {1A07C5C0-D023-4959-9254-7E769499E6F8}
    CLSID:          {ED0C8C66-EF8F-4C7B-B2EC-CE48605434F1}

Install Info:
    BundleDir:    /Library/Application Support/ViveEngine (Shared)/ViveEngine.app
    DriversDir:   /Library/Audio/Plug-Ins/HAL
    RundataDir:   /Library/Application Support
    LockfileDir:  /Library/Application Support
    BootID:       1782031673

Orchestrator Info:
    State:        online
    Version:      1.3.0

Gateway Info:
    State:        online
    Version:      1.3.0

Driver Info:
    State:        online
    Version:      1.3.0

`sound_info`

Prints info about OS sound server (AudioSrv on Windows, coreaudiod on macOS) and related configuration.

Flags

None.

Example

sudo ViveEngineAdm sound_info

Output

Audio Server:
    Name:   coreaudiod
    PID:    443

Driver Sandbox:
    Name:   Core Audio Driver (ZoomAudioDevice.driver)
    PID:    548
    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/Preferences/Logging/.plist-cache.2TKdq0jt
        /Library/Audio/Plug-Ins/HAL/ZoomAudioDevice.driver/Contents/MacOS/ZoomAudioDevice
        /usr/lib/dyld

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/Preferences/Logging/.plist-cache.2TKdq0jt
        /private/var/db/timezone/tz/2026b.1.0/icutz/icutz44l.dat
        /usr/lib/dyld
        /Library/Audio/Plug-Ins/HAL/ViveEngine@Shared.driver/Contents/MacOS/ViveEngineDriver
        /usr/share/icu/icudt76l.dat

`list_services`

List background services registered in the system by ViveEngine.

Flags

None.

Example

sudo ViveEngineAdm list_services

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:        unavailable
    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

`list_drivers`

List audio drivers registered in the system, by both ViveEngine and third-party software.

This command prints Audio Processing Objects (APOs) on Windows, and Audio HAL Plugins on macOS.

Flags

None.

Example

sudo ViveEngineAdm list_drivers

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
    DriverUUID:
        {CAA1275F-6FE5-4D3D-9A4C-4DC8F8D6761C}

`list_devices`

List audio devices detected by engine and their properties.

On Windows, also shows which driver (APO) is currently attached to the device.

Flags

None.

Example

ViveEngineAdm list_devices

Output

Output Device:
    Device ID:        do:a5d32:de78e:2eb17:1323a
    System Name:      BuiltInSpeakerDevice
    Display Name:     MacBook Air Speakers (Built-in)
    Flags:            IsValid|IsBuiltin|HasMuteSwitch|HasMasterVolume
    Is Muted:         no
    Master Volume:    1.000
    Channel Volumes:  n/a

Input Device:
    Device ID:        di:bcef2:a30ae:79e1c:80bf8
    System Name:      BuiltInMicrophoneDevice
    Display Name:     MacBook Air Microphone (Built-in)
    Flags:            IsValid|IsBuiltin|HasMuteSwitch|HasMasterVolume
    Is Muted:         no
    Master Volume:    0.620
    Channel Volumes:  n/a