HTML Overlay Installation Guide

https //archbee doc uploads s3 us east 1 amazonaws com/mzxttqevcnidungf2kuwj/d0sol7w3pplfjbmisprpf 20260320 171924 zip?x amz algorithm=aws4 hmac sha256\&x amz content sha256=unsigned payload\&x amz credential=akiayqnqcixnp4etosxw%2f20260320%2fus east 1%2fs3%2faws4 request\&x amz date=20260320t172228z\&x amz expires=86400\&x amz signature=c8bce5b4bd600746dd57835c78eb3ec07858251150a61a8e93ff0de91ddcfaf6\&x amz signedheaders=host\&response content disposition=attachment%3b%20filename%3d%22scripts for html overly setup zip%22\&x amz checksum mode=enabled\&x id=getobject overview zixi broadcaster’s html overlay feature overlays a dynamic html page on the video stream during the transcoding process as part of this process, the images from the html page are “burned” into the video the process uses chromium embedded framework (cef) to render the html page and then the image is passed on to the transcoder to overlay on top of the raw video frame, which is then encoded the overlay process occurs at the configured frame rate in the transcoder, assuming the cpu that is used for the cef process can keep up animations on the html page can be rendered on the video stream however, currently audio on the html page is not introduced into the transcoded stream there are two processes that are handled by the zixi broadcaster cef (html rendering) cef uses the cpu to render the html page at the designated frame rate during transcoding transcoding the transcoding process may use either nvidia gpu or a cpu the transcoding includes the following processes video decoding process, the page overlay insertion, and the video re encoding it is expected that cpu usage will be significantly higher when using the html overlay feature versus a normal transcode because of the cef rendering process and the handling of raw video frames deployment options to deploy the html overlay feature, select one of the following options pre packaged ami this option includes a pre configured broadcaster with html overlay enabled customers with an aws account have the option to directly install the ami on an instance in their account to obtain an pre packaged ami, contact your zixi account manager after obtaining the ami, you can either load a saved broadcaster configuration or they update it using ssh manual installation in this option, you will need to install the cef plugin and the xserver components on the zixi broadcaster machine this document describes the process of installing these components on an existing zixi broadcaster to install a new zixi broadcaster, follow the instructions in the zixi broadcaster installation guide the setup has two phases install a gnome desktop + tigervnc server — provides the virtual display that cef renders into install the cef plugin and reconfigure broadcaster — extracts the plugin, patches the broadcaster launcher, and installs a systemd service that ties everything together supported platforms scripts are provided for four environments use the folder that matches your deployment platform folder default user amazon linux 2023 (ec2) amazon linux2023/ ec2 user almalinux 9 on aws (ec2) aws alma linux/ ec2 user almalinux 9 on azure azure alma linux/ azureuser almalinux 9 on protectli appliance protectli alma 9/ root (vnc) / zixi (broadcaster) note all scripts must be run as root (or via sudo) prerequisites before beginning zixi broadcaster is already installed at /zixi broadcaster linux64/ for the platform user the cef plugin archive ( zixi cef plugin tar ) is present in the home directory of the platform user all scripts from the appropriate platform folder have been transferred to the server and are executable ( chmod +x sh ) the server has internet access or the required packages are available via a local repository for the gpu option for transcoding, make sure the latest nvidia drives have been installed phase 1 install gnome desktop and tigervnc this phase installs the graphical environment that cef needs to render html content see the link at the top of the page to download all scripts referenced below script platform script to run amazon linux 2023 al3 setup vnc gnome sh all almalinux variants setup vnc gnome sh what the script does installs the gnome desktop group and tigervnc server via dnf sets the system default to boot into graphical mode (graphical target) prompts you to set a vnc password for the platform user creates the vnc user to display mapping in /etc/tigervnc/vncserver users (display 1 → platform user) configures the gnome session in / vnc/config creates/patches the vncsession stop helper script at /usr/libexec/vncsession stop creates the vncsession\@ service systemd unit if it doesn't already exist enables and starts the vnc service on display 1 (almalinux only) opens tcp port 5901 in the firewall for external vnc access how to run sudo bash setup vnc gnome sh # almalinux variants sudo bash al3 setup vnc gnome sh # amazon linux 2023 when prompted, enter and confirm a vnc password for the platform user this password is used to connect to the desktop remotely verify after the script completes, confirm the vnc service is running systemctl status vncsession@ 1 you should see active (running) to connect from a remote machine, use any vnc client pointed at \<server ip> 5901 phase 2 install the cef plugin and configure broadcaster this phase installs the cef plugin, patches the broadcaster startup sequence, and installs a systemd service important this phase requires the vnc session from phase 1 to already be running the broadcaster service is bound to vncsession@ 1 files used in this phase file purpose zixi html overlay startup sh main installation script — run this one modify runnerbc sh patches the broadcaster runnerbc launcher (called automatically) startup broadcaster sh x display initialization script (called at broadcaster startup) zixibc service systemd service unit for broadcaster what zixi html overlay startup sh does stops the zixibc service if it is currently running extracts the zixi cef plugin tar archive into the broadcaster installation directory ( /zixi broadcaster linux64/) runs modify runnerbc sh to patch the runnerbc launcher (see below) copies zixibc service to /etc/systemd/system/ reloads systemd starts the zixibc service prints service status notifies you to wait approximately 30 seconds for broadcaster to fully initialize how to run navigate to the home directory of the platform user, then run the script cd /home/ec2 user # adjust to your platform user's home sudo bash zixi html overlay startup sh verify systemctl status zixibc you should see active (running) broadcaster's web ui should be accessible after about 30 seconds you should also see the dynamic overlay url in the broadcaster ui for adding/editing an input stream how the components work together startup broadcaster sh — x display initialization this script runs once at broadcaster startup (injected into runnerbc by modify runnerbc sh) it sets the display environment variable to 1 0 disables dpms (display power management / screen blanking) via xset so the virtual display stays active grants the root user access to the x display via xhost, which is required for broadcaster to connect to it modify runnerbc sh — patching the launcher the broadcaster package ships a shell script called runnerbc that starts the broadcaster binary this script inserts two lines into runnerbc immediately before its main loop a 20 second sleep — gives the vnc/gnome session time to fully initialize before broadcaster tries to connect to the display a call to startup broadcaster sh — runs the x display initialization described above, as the platform user zixibc service — systemd service unit this service unit ties everything together at the os level requires vncsession@ 1 service — broadcaster will not start unless the vnc display is already running sets display= 1 in the service environment so broadcaster and cef know which display to use starts broadcaster via runnerbc, which in turn runs the patched startup sequence restarts automatically on failure (2 second delay between retries) installs under graphical target so it starts with the desktop environment platform specific differences user account each platform variant uses a different default user the scripts are pre configured for platform user broadcaster install path amazon linux 2023 ec2 user /home/ec2 user/zixi broadcaster linux64/ aws almalinux ec2 user /home/ec2 user/zixi broadcaster linux64/ azure almalinux azureuser /home/azureuser/zixi broadcaster linux64/ protectli almalinux 9 zixi (broadcaster) / root (vnc) /home/zixi/zixi broadcaster linux64/ package group name the gnome installation command differs between distributions almalinux / rhel based dnf groupinstall "server with gui" amazon linux 2023 dnf groupinstall "desktop" firewall almalinux variants the vnc setup script actively opens port 5901 via firewall cmd amazon linux 2023 the firewall commands are present but commented out — port access should be managed via aws security groups service management reference action command start broadcaster systemctl start zixibc stop broadcaster systemctl stop zixibc restart broadcaster systemctl restart zixibc check broadcaster status systemctl status zixibc enable broadcaster at boot systemctl enable zixibc check vnc session status systemctl status vncsession@ 1 view broadcaster logs journalctl u zixibc f troubleshooting broadcaster fails to start / cef errors confirm the vnc session is running systemctl status vncsession@ 1 if the vnc session is not active, broadcaster will not start because zixibc service requires it check logs journalctl u zixibc n 50 vnc session fails to start verify the vnc password was set ls / vnc/passwd (as the platform user) if missing, re run vncpasswd as the platform user and restart the service systemctl restart vncsession@ 1 startup broadcaster sh errors (xset/xhost) these errors indicate the x display is not ready the 20 second sleep in runnerbc is usually sufficient, but on slower machines it may need to be increased by manually editing runnerbc check that display= 1 is set correctly in the environment cef plugin not found after extraction confirm the zixi cef plugin tar file is present in the platform user's home directory before running zixi html overlay startup sh verify the archive extracted into the correct directory ls /zixi broadcaster linux64/ should include cef related files port 5901 not accessible (almalinux) check the firewall firewall cmd list ports if not listed, re run the firewall commands from setup vnc gnome sh manually also check cloud security group / network acl rules file reference html overlay setup/ ├── amazon linux2023/ # amazon linux 2023 (ec2 / ec2 user) │ ├── al3 setup vnc gnome sh # phase 1 install gnome + vnc │ ├── zixi html overlay startup sh # phase 2 install cef plugin │ ├── modify runnerbc sh # patches runnerbc launcher │ ├── startup broadcaster sh # x display init (runs at startup) │ └── zixibc service # systemd unit for broadcaster │ ├── aws alma linux/ # almalinux 9 on aws ec2 (ec2 user) │ ├── setup vnc gnome sh │ ├── zixi html overlay startup sh │ ├── modify runnerbc sh │ ├── startup broadcaster sh │ └── zixibc service │ ├── azure alma linux/ # almalinux 9 on azure (azureuser) │ ├── setup vnc gnome sh │ ├── zixi html overlay startup sh │ ├── modify runnerbc sh │ ├── startup broadcaster sh │ └── zixibc service │ └── protectli alma 9/ # almalinux 9 on protectli hardware (root/zixi) ├── setup vnc gnome sh ├── zixi html overlay startup sh ├── modify runnerbc sh ├── startup broadcaster sh └── zixibc service