The Video Intelligence Framework has two parts. The Video Intelligence Controller (VIC) is a plugin that runs inside Wowza Streaming Engine. The Video Intelligence Service (VIS) is the GPU service that runs the AI models. Most deployments run VIS as a Docker container, but when Docker is not an option, you can install VIS natively with the standalone Linux installer.
The installer is self-contained. It bundles the service, its Python runtime, and all of its dependencies, including CUDA, cuDNN, and TensorRT, and it registers a wowza-vis systemd service. The install pulls nothing from package repositories.
This installer sets up the VIS service only. To complete VIF you also need the VIF plugin in your Wowza Streaming Engine (see Install the VIF module), and you point Engine at this service (see Connect Wowza Streaming Engine below).
The installer bundles the object detection and scene understanding models. VLM analysis and synthetic video detection run as separate containers, so those two detectors still need Docker even when the service is installed natively.
Requirements
- An x86_64 (amd64) or arm64/aarch64 host, with root rights. Match the package to your CPU.
- glibc 2.35 or newer. Ubuntu 22.04+/24.04, Debian 12+, and RHEL 10+ equivalents qualify. RHEL 9 ships glibc 2.34, which the installer rejects.
- systemd.
- An NVIDIA Turing-architecture GPU or newer with driver 570 or later (
nvidia-smimust work). Only the kernel driver is needed. CUDA, cuDNN, and TensorRT are bundled. - About 13 GB of disk for the installed service, plus about 5 GB for model checkpoints that download on first start. The extracted tarball takes the same again while installing, so delete it afterward.
install.shchecks free space before it copies anything. - No network is needed to install, because every runtime library ships in the package. The service downloads model checkpoints on first start. See Air-gapped installs to avoid even that.
Download
Download the installer from the Wowza customer portal. Sign in, go to My Account, open the Downloads tab, and select Wowza Video Intelligence Framework. Under Video Intelligence Service, choose the package for your CPU: Linux-X86_64 or Linux-Arm64. The file is named wowza-vis-<version>-linux-<arch>.tar.xz.
You also need a Video Intelligence Service license key, which is a base64 string. If you do not have one, contact Wowza support.
Install
-
Extract the package and run the installer as root:
tar xf wowza-vis-<version>-linux-<arch>.tar.xz cd wowza-vis-<version>-linux-<arch> sudo ./install.sh -
Answer the prompts:
- VIS_LICENSE is required. Paste your base64 license string. The installer checks its shape before installing, so a typo costs you nothing. The service checks the signature, expiry, and product at startup.
- VIS_API_KEY is required while Secure Mode is on. This is the key Engine uses to authenticate. To install without a key, leave it blank and confirm the prompt to set Secure Mode off instead.
- Port defaults to 5001. Press Enter to accept it, or type another.
- The installer also offers logging and threading options. Decline them to use the defaults.
-
Start the service:
sudo systemctl start wowza-vis
The default location is /usr/local/WowzaVideoIntelligenceService. To install elsewhere, pass --prefix. An existing install keeps its own location on upgrade. The path must be absolute and use only letters, digits, ., _, and -.
Secure Mode
Secure Mode is the fail-closed switch, and leaving it on is the recommended setting. With it on and no API key, the service refuses to start, so off is the only configuration in which an empty key works. With it on, a connection from another host must use wss. Configure TLS in VIS (see TLS and WSS) or put a TLS-terminating proxy in front, because an API key sent over plaintext ws is a key on the wire.
Scripted or graphical install
For an unattended install, run:
sudo ./install.sh --non-interactive --license "<base64>" --api-key "<key>" --port 5001
--license and --api-key put both secrets on the process command line, where any local user can read them from /proc for the minutes the install runs. Where that matters, pass them in the environment instead:
sudo VIS_INSTALL_LICENSE="<base64>" VIS_INSTALL_API_KEY="<key>" \
./install.sh --non-interactive --port 5001
Other options: --allow-no-auth installs with Secure Mode off instead of taking an API key, --no-enable registers the service without enabling it at boot, and --port is optional (an omitted port means 5001).
On a desktop, sudo -E ./install-gui.sh collects the same settings in one dialog and installs behind a progress window. On a headless server, or with --unattended, it hands over to install.sh.
Verify
curl http://localhost:5001/status
On first start, the service downloads about 5 GB of model checkpoints and builds GPU engines, so it can take several minutes before /status reports ready. It starts answering with ready:false well before that. If it does not come up, watch it with sudo journalctl -u wowza-vis -f.
Connect Wowza Streaming Engine
Point your Wowza Streaming Engine at this service in the VIF configuration (Stream Config Defaults, or conf.modules/vif/Default.json):
- Set the VIS URL to
ws://<this-host>:5001/ws/stream/, orwss://...once TLS is configured. - Set the VIS API Key to the key you set as
VIS_API_KEY, or store it as a secret and reference it by name.
See Configure VIF in Wowza Streaming Engine Manager. If Engine is on a different host and Secure Mode is on, configure TLS first.
Configure
All settings live in one file, outside the install directory:
/etc/wowza-vis/wowza-vis.env
To change any setting, edit the file and restart the service. Both steps need root, because the file holds your license and API key and is readable only by root and the service user:
sudo nano /etc/wowza-vis/wowza-vis.env
sudo systemctl restart wowza-vis
The format is KEY=VALUE, one per line. A # starts a comment, quotes around a value are optional and stripped, and there is no variable expansion. A variable already set in the environment wins over the file. Settings you add, such as SSL_KEYFILE, are preserved on upgrade, because once the file exists the installer leaves it alone. That is also why changing the license or port later means editing the file rather than re-installing. Clearing VIS_API_KEY by hand also requires SECURE_MODE=false in the same file.
TLS and WSS
VIS serves plaintext http and ws until you configure a certificate. With Secure Mode on, a remote Engine must connect over wss, so configure TLS in VIS or put a TLS-terminating proxy in front. Configure exactly one of the two sources below in the env file. Setting both, or a keystore without its password, stops the service at startup.
Reuse the keystore Engine already uses
If Engine on this host serves TLS, for example with a StreamLock certificate, point VIS at the same keystore. Use the values from VHost.xml (<KeyStorePath> and <KeyStorePassword>):
SSL_KEYSTORE_PATH=/usr/local/WowzaStreamingEngine/conf/example.streamlock.net.jks
SSL_KEYSTORE_PASSWORD=your-keystore-password
VIS reads JKS and PKCS12 keystores and detects the format from the file’s contents. The keystore must hold one private key with its issuers and nothing else, and the keystore password must open the key too. Make the file readable by the service user. Grant its group read access, or keep a copy for VIS:
sudo chgrp wowza-vis /usr/local/WowzaStreamingEngine/conf/example.streamlock.net.jks
sudo chmod 640 /usr/local/WowzaStreamingEngine/conf/example.streamlock.net.jks
Use a PEM key and certificate
SSL_KEYFILE=/etc/wowza-vis/vis-key.pem
SSL_CERTFILE=/etc/wowza-vis/vis-cert.pem
# Only when the private key is encrypted.
#SSL_KEYFILE_PASSWORD=
Both are required. Setting one alone stops the service at startup, and so does a path that does not exist. SSL_CERTFILE may hold the whole chain, leaf certificate first. Make both readable by the service user, and the key readable by nobody else:
sudo chown root:wowza-vis /etc/wowza-vis/vis-key.pem
sudo chmod 640 /etc/wowza-vis/vis-key.pem
Certificates and keystores are read at startup only, so restart the service after you renew one. The startup log names the certificate it loaded, its hostnames, and its expiry, and warns through the last 30 days of validity.
Engine must trust the certificate
Serving TLS is only half of wss. The Engine that connects also has to accept the certificate VIS serves. Engine judges it against its Java trust store, and the VIF plugin has no setting to relax that. Two things have to hold:
- The certificate chains to a CA the trust store knows. A public CA, such as StreamLock, already qualifies.
- The host in Engine’s VIS URL appears in the certificate. A certificate for
example.streamlock.netcovers neitherlocalhostnor an IP address, even when Engine and VIS share a host, so address VIS by the name on the certificate.
A self-signed certificate, or one from an internal CA, has to be imported into a copy of Engine’s trust store:
engine=/usr/local/WowzaStreamingEngine
sudo cp $engine/java/lib/security/cacerts $engine/conf/vis-truststore.jks
sudo $engine/java/bin/keytool -importcert -alias wowza-vis \
-file /etc/wowza-vis/vis-cert.pem \
-keystore $engine/conf/vis-truststore.jks -storepass changeit
Name the copy in <VMOptions> in Engine’s conf/Tune.xml, then restart Engine:
<VMOption>-Djavax.net.ssl.trustStore=/usr/local/WowzaStreamingEngine/conf/vis-truststore.jks</VMOption>
<VMOption>-Djavax.net.ssl.trustStorePassword=changeit</VMOption>
Kept under conf/, the store survives an Engine upgrade.
Update
The portal installer handles both a first install and an update. From a newer package, run update.sh. It stops the service, installs the new version while keeping your configuration and downloaded models, and restarts it:
tar xf wowza-vis-<new-version>-linux-<arch>.tar.xz
cd wowza-vis-<new-version>-linux-<arch>
sudo ./update.sh
Running install.sh over an existing install is also safe, and it does not re-ask for anything already configured.
Operate
The service is the systemd unit wowza-vis, enabled at boot. Start, stop, and restart need root. Status and logs do not. Restart after any change to the env file.
systemctl status wowza-vis
sudo systemctl restart wowza-vis
curl http://localhost:5001/status
sudo journalctl -u wowza-vis -f
Uninstall
sudo ./uninstall.sh # remove the service, keep models and config
sudo ./uninstall.sh --purge # remove everything
Keeping models lets a later re-install skip the 5 GB download, and keeping config reuses your settings and a file-based license.
Troubleshooting
A service that stops right after starting says why in the journal (sudo journalctl -u wowza-vis -n 50). A configuration error that the service rejects, such as an unreadable TLS certificate, is a single line that begins with Fatal error, the service is stopping and names what to correct. The service also writes /usr/local/WowzaVideoIntelligenceService/logs/videointelligenceservice.log. A port already in use (error while attempting to bind on address) is reported to the journal only.
If the service runs but Engine cannot use it, the evidence is on the Engine side. PKIX path building failed against VisService in Engine’s access log means Engine is refusing the certificate VIS serves. See Engine has to trust the certificate. Until you resolve it, the VIF pages read nothing from VIS: the Checkpoint Path list shows “No custom models available”, the class lists come up empty, and no stream connects.
Air-gapped installs
To skip the first-start checkpoint download, copy a populated models directory into the install directory (default /usr/local/WowzaVideoIntelligenceService/models) before you start the service. Checksums are validated on startup, and matching files are not re-downloaded. The install itself needs no network, because every runtime library ships in the package.
