This guide provides information about setting up and configuring iCap Alta. It also describes a basic input/output test using the Alta configuration website.
Applicability
iCap Alta Virtual Encoder products come in two versions:
- Alta TS: for use as the input and output format for MPEG transport streams.
- Alta 2110: for use with the SMPTE 2110 suite of standards.
These instructions apply to both versions except where otherwise stated. The setup instructions for individual channel instances vary considerably and are covered separately.
Notes
The iCap Alta software is packaged on a 64-bit Debian 8 Linux virtual machine (VM) for placement inside a customer video facility.
- Customers can host the VM on VirtualBox, Cisco, or Microsoft HyperV controllers.
- The default distribution format is a .ova file, though Ai-Media also provides disk images on request.
- Once the iCap Alta virtual machine is running and reachable on a local network, users interact with the software over HTTP, as a web service or in a browser.
Virtual Machine Controller Settings
Follow these steps in this section to install and configure the EEG virtual machine in Oracle VM VirtualBox version 5, with a Microsoft Windows 7 host operating system. Other host operating systems and virtual machine controllers have similar options.
Importing the EEG Virtual Machine
Import the EEG virtual machine .ova or other file into your VM controller software:
- In VirtualBox, navigate to File > Import Appliance.
- If the guest machine settings aren’t automatically detected:
- Select 64-bit architecture.
- Select Linux or Debian as your operating system.
We recommend you provide the guest virtual machine with permission to use at least 1 core of CPU and 1 GB of RAM per simultaneous video I/O channel. Your actual results could vary depending on the bandwidth of the streams and the speed of the processor cores. <-- Do we need to give instructions for this? (SL)
Networking
Seems like this whole section needs instructions (SL)
Configure the networking in your VM controller to have the number of interfaces for the Alta system that your environment needs. For simple installations, one network interface may be enough. A common use for more than one network interface is a management network, which controls the Alta software, and one or more data networks that send and receive media.
For a split management/data configuration, you should tie the first interface to the “management” network – this will make the controller website and other non-media features accessible through this interface. Later, when you launch actual Alta jobs, each job can specify the IP address of a second (or third, etc) interface where the media streams should be published and received.
If you are starting multiple VMs on the same subnet, also make sure to randomize the virtual MAC addresses to avoid duplication.
Example network settings in VirtualBox are pictured below. The most common setting for an iCap Alta instance will be “bridged” adaptor mode. This mode will cause the guest VM to appear as a peer on the network that the host machine is on. Generally, other machines that can access the host machine would also be able to access the guest machine. The host and guest will have different IP addresses, but be on the same subnet.
The IP address, gateway, DNS, and other settings specific to each network interface are configured in the Guest OS (Alta) once it is booted in the VM hypervisor.
In VirtualBox, the alternative to “bridged” mode is “NAT” mode. In this case, the guest machine will be on a private network that operates inside the host machine. The guest machine is generally not accessible in this mode by any other machines on the host’s network. You can consult the documentation on VirtualBox or your VM controller for more information.
Additional VM Controller Tips for Alta 2110
SMPTE 2110 specifies the use of PTP to synchronize the generated media timestamps for each transmitter with an external grandmaster clock. However, some VM controllers, including VirtualBox, will sync the system time of the Guest OS (Alta) directly to the time on the Host OS, which will interfere with Alta’s ability to control its own clock through PTP synchronization.
So for 2110 mode, you should always disable time syncing from the host OS to Alta in your VM controller. In VirtualBox, you must use the command line VBoxManage tool bundled with the VirtualBox software to achieve this; the command is as shown below, where [VMname] needs to be replaced with the name of the Alta VM on your local system:
vboxmanage setextradata [VMname] "VBoxInternal/Devices/VMMDev/0/Config/GetHostTimeDisabled" "1"
Once you have checked the settings in the VM controller, boot the iCap Alta Virtual Machine.
Guest Machine (iCap Alta) Setup
For this section, we assume you have successfully set up your VM controller and have been able to boot the Alta VM and see the initial login screen.
For your initial login, use username “eeg-user” and password “eeg-user”. If you need the root password to set up networking, it will be set to “eeg-admin”. These passwords can be changed for your use with standard Linux desktop or command-line tools.
You will need to configure your desired network settings on the iCap Alta guest machine. The simplest way to get to the network settings on the guest machine is to click the Ethernet cable icon in the top right of the top toolbar, select one of the networks, click
“Edit” on the pop-out window, and go to the “IPv4” settings tab.
For a fixed IP address, select “Manual”, and provide the appropriate address, along with any needed gateway and DNS settings. You may need to switch the adaptor Off and On using the slider at the top of the page for your setting to take.
If you would like more information on the GNOME NetworkManager tool bundled with Alta, please see: https://access.redhat.com/documentation/en- us/red_hat_enterprise_linux/7/html/networking_guide/sec- using_networkmanager_with_the_gnome_graphical_user_interface
Network Settings Troubleshooting
We strongly recommend performing a networking sanity check BEFORE trying to use the Alta software, since nearly all of the functions of the software rely on the network interfaces to be set up correctly for proper use.
If you expect to be able to reach the internet from the Alta machine, try opening the web browser on the Guest OS and reaching a popular site like google.com.
In some environments with closed networking, this may not be expected to work. However, if you intend to use iCap with your Alta installation, you will have to whitelist iCap servers as described in the EEG Application Note for iCap firewall settings. You may also have to whitelist EEG API servers for floating licensing.
You should at least be able to access any local resources on the same subnet as your primary / “management” network interface.
If you are using multiple network interfaces, be sure that the correct number of cables are plugged into the physical host’s network card, that the correct number of virtual interfaces are configured in your hypervisor software, and in a matching order to the expected one on the host network card, and that each of these has a valid static IP address or DHCP setting in the Guest OS.
Using the Browser Interface
Whenever the iCap Alta guest virtual machine is running, you should be able to connect to its internal web server for configuration either from the guest machine desktop (using “localhost” or “127.0.0.1” as the IP address in your browser bar), or from the host or other machines on the same network using the guest machine IP address.
For example, enter: http://127.0.0.1/alta on the guest machine browser (“Activities” | “IceWeasel”) to view the main documentation page. This page is mostly useful if you will interact with the Alta instance controller through the back-end REST API. Click “Home” from the top bar to interact with Alta through a GUI form.
Alta Instance Licensing
The first step to running your Alta product is entering your unique license key into the “License Key” tab at the top of the web controller.
Your licensing key is typically a string like “lic_xxxxxxxxxxxx”. Enter the key you were provided by support and click “Save”.
Your license key is a “floating” license, meaning you can use it across multiple VMs to run up to your allocated number of Alta channels in any combination, as long as each VM is phoning home to EEG APIs licensing server to report whether the license is checked back in.
If you have multiple channels licensed and you would prefer separate keys for each VM, please contact EEG Support and the licenses can be split up as you prefer.
If you find in the next section that your Alta channels are not able to acquire licenses, you may need to see if firewall restrictions or networking problems are preventing the Alta VM from accessing the license server. The license requests are HTTP protocol to the
address “licensing.eegapis.com”, originating from the first network interface on your VM.
For further information, please see the following documents on our support page: https://eegent.com/support/resources/FAQs/Installing%20your%20License%20Key%20o n%20iCap%20Alta%20Virtual%20Machine
https://eegent.com/support/resources/Appnotes/Network%20Activated%20Licensing%20 Requirements
Setting up and Activating a Test Stream
To set up a running stream manually using the web browser interface, click “Home” on the top bar or go to http://127.0.0.1/alta/gui/alta_instances.
Each independent video I/O stream running on your Alta VM is called an “instance” on the page. You can set up any number of instances, and save unique settings configurations to each one. Turning the instance ON activates it.
Your license controls the number of instances that can be active or turned on simultaneously on this VM and any other copies of the VM which have the same license key installed. Turning on a new instance that exceeds your license limit will fail and the instance will moved to the “Stopped” state.
Click “Add New Instance”, and a dialog will come up providing all of the settings options on your version of Alta. The settings are described in detail in the next section. When you have finished modifying settings, press “Save” to return to the instance listing screen.
From the listing screen, you can Edit the settings on any previously created Instance that is not currently running, or you can use the Power button on the interface to toggle individual instances between the active and inactive states.
Activate your instance, and then click on its name to proceed to the running log and status specific to that instance.
The available settings are described below, as well as on the page itself. Once you have reviewed all the settings, click “Start Instance” and you will be switched to a logs stream for the new instance.
Instance Settings (Alta Transport Stream)
Stream Settings Submenu
Name
This is the name that will display in the instance list for this channel of settings.
Primary
This parameter provides the source for the IP video input stream. The setting can take the following forms:
- “3000” - listen for RTP unicast on port 3000. The sending device will need to send to the virtual machine IP address on port 3000.
- “udp://0.0.0.0:7000” – listen for UDP unicasts on port 7000, from any source, headed to the VM interface.
- “udp://239.120.200.101:5000” – listen for UDP multicast on multicast address 239.120.200.101, on port 5000. The multicast request will be registered with your router, which will then forward multicasts on this address to the VM interface.
Generally, you MUST specify a primary IP video parameter or your instance will not start. The only exception to this is if you are using a separate iCap Reference video stream, in the iCap-to-telnet bridging mode.
Source
This parameter is optional and permits an additional input stream which will be used for caption bridging (in caption bridging, caption data from the “Source” stream will be
transferred to the “Primary” stream). The same address formats permitted for the Primary stream are permitted for the Source stream.
Output
This parameter sets the destination address and port for the output video stream. The destination can be either unicast or multicast. All output data is sent in RTP format.
iCap Reference
This parameter is optional and permits an additional input stream which will be used as the audio source to a remote transcriber connecting through iCap. The stream may be audio-only, or may also contain a video elementary stream which will be used to send reduced frame-rate picture reference data. The same address formats permitted for the Primary stream are permitted for the iCap Reference stream.
Multicast Interface
This parameter is optional, and is recommended only for setups where the virtual machine is connected to multiple NIC interfaces and networks, and where IP multicast is used for the input/output streams. In these cases, the Multicast Interface parameter should be given the IP address of one of the interfaces which sits on the network where all multicast input and output traffic will be directed. (It is not currently possible with the Alta VM to subscribe to different multicasts on multiple interfaces within the same instance).
iCap Settings Submenu
iCap Company, Username, and Password
iCap account information will be provided to you by EEG with your purchase or demo, or accessible from your company’s admin account at https://www.eegicap.com . Each iCap account has a company namespace, a username, and a password. This account will be used to uniquely identify your stream by your contracted real time captioner over iCap, so you must use a different user name for each simultaneously operating Alta encoder instance.
You do not need an iCap account to perform certain non-cloud functions such as caption bridging between input sources or SCTE-35 cue insertion.
iCap Reference PIDs
When connected to iCap, the Alta instance will send an audio reference signal for transcription to authorized captioners connected across iCap. Separate audio programs can be transmitted for up to 6 languages of transcription simultaneously.
The Audio PID field can be used to list PIDs from the input stream to be sent over iCap. If you list multiple PIDs, they will be associated with numbered language services on iCap in the order they are specified.
If this field is left blank, the Alta instance will send audio only for one language, and will auto-detect the first audio listed audio PID in your transport stream.
Each Alta instance can send only one video reference program to captioners. If more than one video PID is present in your stream, you can use the Video PID field to specify which one is the source of the feedback.
SCTE-35 Settings Submenu
SCTE-104 Command Listen Address
This parameter is optional and can be used to open a local port on the VM to accept SCTE-104 commands from an external automation controller, which will be used to generate SCTE-35 splicing and segmentation data in this instance’s output stream.
The parameter can be a port number only in a VM with a single network interface, or should include a local IP address and a port number in a multi-homed configuration.
The default port specified for communication in the SCTE-104 standard is 5167, however please note that if you are running multiple Alta instances on a single VM, you must have a different IP address/port number combination for each instance that accepts SCTE-104 commands.
When this parameter is specified, SCTE-35 data will be announced in the output stream PMT on a default PID of 0x1f2. Splices will be injected based on the SCTE-104 commands received from the Automation System over the specified port. SCTE-104 command receipt will be logged in the system log as well.
SCTE-35 PIDs
Up to eight PIDs may be allocated for SCTE-35 data from the Alta instance. If multiple PIDs are specified, the SCTE-104 controller uses the DPI_PID_index field in the incoming SCTE-104 messages to direct Alta which PID each message is for.
Do not specify a PID for SCTE-35 service that may already contain upstream data of any type.
Telnet Settings Submenu
The Telnet Settings menu provides functionality to clone “CTRL+A” style caption data from the iCap connection over to a legacy SDI closed captioning encoder or other similar device/system. The IP address and port number to the receiving device must be provided, and if the receiving device requires a username and password to open a connection, these fill in these fields as well.
This is the sole output mode of the “Alta Bridge” license option.
Other Settings Submenu
warnlevel
This parameter sets the verbosity of logging for the Alta instance. We recommend the “0” setting when troubleshooting, and to leave the parameter blank otherwise.
Once each setting is configured and the Alta instance has started up, you should begin to see an output stream arriving at the destination that matches the “primary” input stream.
Caption Output Format
This setting controls the format used to write captioning data into the output transport stream. Alta supports ATSC CEA-708 in MPEG-2 or H264, SMPTE RDD-11 CEA-708, DVB Text (teletext) or DVB Subtitles (bitmap).
Note that the ASTC user data setting is not compatible with the Alta “low latency mode”, and requires a processing delay of approximately one complete video GOP.
DVB Text Config
Use only with the DVB Text Caption Output format. Specifies how many languages of DVB Text data to output, and provides a language identifier and Teletext magazine and page for each.
DVB Bitmap Config
Use only with the DVB Bitmap Caption Output format. Specifies how many languages of DVB Subtitle data to output, and provides a language identifier and page identifier for each.
Transport Rate
This parameter is optional and can be used to constrain a fixed transport rate on the output stream. If the parameter is not specified or set to 0, the input transport rate will be auto-detected from the stream’s PCR data and bitrate, and will be replicated on the output. If a known transport rate is desired, it is often preferable to use this setting to avoid the possibility that temporary data loss/corruption on the input could lead to changing transport rate on the output as well.
This feature can also be used to increase the output transport rate above the input rate to accommodate additional data insertion by Alta. This could be necessary if the input
transport stream has insufficient null packets to replace with timely insertion of captions, subtitles, or SCTE-35 trigger data.
A fixed transport rate separate from the input rate cannot be used in “Low Latency Mode”.
Low Latency Mode
This checkbox can be used to disable detailed de-multiplexing of the transport stream passing from the master input to the master output.
Certain Alta product features such as ATSC format captioning in user data or SEI require data insertion in video picture display order, and therefore an additional buffer delay of approximately one Group of Pictures (GoP) is introduced.
In low latency mode, this additional delay passing through Alta is not incurred. SCTE-35 injection can still be used, along with captioning in formats that do not embed in the video elementary stream, such as SMPTE-2038 or DVB Subtitles.
For full control of input-to-output latency in Low Latency mode, also see “UDP Buffer Size” in “Other Settings”.
UDP Buffer Size
This parameter is optional and allows finer control over the output buffer size used between Alta’s internal transport stream processing and the network output buffer.
Higher values provide greater resistance to output hits when the underlying computer or network is busy. Lower values reduce the input-to-output delay of the stream passing through the Alta system.
It is also may be necessary to use higher values to maintain low output jitter when a stream is being used in the standard re-multiplex mode (not Low Latency Mode) that has significant variation in the size in bytes of successive GoPs.
Test Captions
This option begins outputting a stream of scrolling test captions on Language 1 whenever the Alta instance is started. The stream of test captions will continue until a live iCap captioner first sends to data to the encoder. After this occurs, the test captions will not resume again unless the instances is stopped and restarted.
Instance Settings (Alta 2110)
The SMPTE 2110 version of the Alta VM contains a number of additional Global settings, as well as some differences in the per-instance settings.
PTP Global Menu
The PTP menu provides settings and status for using PTP to synchronize the Alta VM and the media timestamps for all streams to an external PTP master clock. PTP synchronization is a requirement for correct SMPTE-2110 reception and transmission.
PTP Doman ID
Set this value to the PTP Domain ID programmed in the master clock that Alta should take its timing synchronization from.
Current PTP Status
The status table refreshes every several seconds with details on whether the Alta VM is locked to a master clock, what the offset appears to be between Alta and the master clock, and whether a valid SMPTE 2059 TLV is being received from the master.
Remember that to allow full synchronization using PTP and receive regular 2110 media timestamps, it may be necessary to disable host-to-guest time synchronization on your VM hypervisor.
NMOS Global Menu
The NMOS menu provides control and status for how the Alta VM presents itself as a “Node” on NMOS IS-04 and IS-05 management systems.
Note that to re-register to a new Registry present on the network or to change the Node Description, it may be necessary to toggle and reset the “Enable Node Registration” check box, or in cases where mDNS needs to be refreshed, to restart the Alta VM to see the new settings.
Node Description
Sets the Node description that this Alta VM uses to identify itself to the NMOS Registry Server.
Node Status
The status table will show whether the Alta VM has been able to use mDNS to find an NMOS Registry, and what the IP address of that registry is. HTML links are also provided to browse the local IS-04 and IS-05 resource structures on the Alta VM.
You should expect to see a single “Node” corresponding to the Alta VM itself. Under the Node will be a separate “Device” for each Alta instances that has been activated on the VM. The devices each have an audio receiver and an upstream ancillary receiver, and an ancillary transmitter as the output. The multicast parameters for any of these transmitters and receivers can be modified through IS-05 endpoint commands.
Stream Settings Submenu (2110)
Device Label
The name to be used for this instance within the Alta interface, and as a device label in NMOS registration.
Use NMOS IS-05?
Check to make this device responsive to changes in the input and output parameters made by NMOS IS-05 HTTP requests.
ANC Multicast Destination
A UDP unicast or multicast address and port to be used for the 2110-40 output transmissions. This parameter may be changed from its initial value by NMOS IS-05 once the device is active.
Audio Multicast Source
A UDP listen port or multicast address and port to receive a 2110-30 audio stream for iCap reference. This parameter may be changed from its initial value by NMOS IS-05 once the device is active.
Audio Sample Frequency, Sample Size, and Number of Channels
Required information (as from an SDP file) on the sample rate and number of channels expected from the Audio Input stream. These parameters may be changed from its initial value by NMOS IS-05 once the device is active.
ANC Multicast Source
A UDP listen port or multicast address and port to receive a 2110-40 ancillary stream as a source of upstream captioning. Upstream captioning from this stream will be multiplexed with any new captioning being locally inserted according to priority rules as documented in EEG Smart Encoder protocol documentation. This parameter may be changed from its initial value by NMOS IS-05 once the device is active.
Media Network Interface
If multiple NICs are available on the Alta VM, specify one of the NIC IP addresses in this field to control which interface is used to send and listen for media multicasts associated with this instance.
Other Settings Submenu (2110)
Warnlevel
This value can be set from 0-5 to control how much information is sent to the logs for this instance. Lower number settings may be more useful when debugging a problem but can make logs harder to read and increase resource usage per stream.
Caption Output Format
Choose between SMPTE 334 CEA-708 VANC packets (DID/SDID 6101) and OP 47 EBU Teletext packets (DID/SDID 4302).
DVB Text Config
If using OP 47 Teletext output, specify how many languages to include by listing the language code and Teletext magazine and page number desired for each service. Up to 6 language services are supported.
Video Frame Rate
This option allows you to force selection of a specific frame rate for the interpretation of input and output 2110-40 ancillary streams.
The default option relies on data from the SMPTE 2059 TLV transmitted by the current PTP grandmaster to obtain this information.
Send VITC
Select this option to add VITC packets in DID/SDID 6060 into the output 2110-40 stream. The VITC time code is derived from the PTP grandmaster’s signals as described in SMPTE 2059.
Test Captions
Select this option to have a looping test message of single language scrolling captions created on the 2110-40 output beginning when the instance is activated, and ending when a live captioner begins sending data to the instance. After a live captioner connects, the test caption message will not resume unless the instance is stopped and then re-started.
Viewing Alta Logs
When an Alta instance is successfully activated, the most recent log entries will appear in the instance status page. You can get to this page by clicking on the instance name in the list of instances.
To see logs for the entire life of the instance, browse to (or download): http://{alta- IP}/alta/alta_instances/{instance-ID}/logs. The “instance-ID” is the string that begins “EEG_BR_”, followed by a number, that uniquely identifies a particular Alta instance that is running and can be found from the top of the “Home” screen that shows active running instances.
In some browsers the log file will not display in the browser but will download automatically to your Downloads folder on the browsing computer. Please open the file in Wordpad or another test file.
To control the amount of material that is logged, see the “warnlevel” setting in “Other Settings” when launching Alta instances.
Using iCap to Caption into the Alta stream
Once the iCap Alta encoder instance is launched, it will be accessible to captioners using the iCap software in the same way as other common devices like SDI caption encoders. Full documentation on this procedure is available in iCap documents, but a brief overview of the system is provided here.
The encoder user name needs to be assigned to one or more iCap “Access Codes” using the iCap Admin web site or API. Startup access codes may also be provided on shipping/licensing of a new account from EEG. If you are working with an external caption vendor, the access codes also need to be “shared” with that company’s iCap account (this makes the access code visible to the vendor and gives them permission to monitor and write data to it). The sharing process is managed through the iCap Admin web site or API, and again may be administered on the customer’s behalf by EEG Support as part of the setup process.
An internal user on your company’s account, or an external captioning vendor, can connect to your Alta instance by entering the access code into their iCap PC Captioner software, at which point audio from your stream should be heard over iCap. At this point, the user is in “standby” or “read-only” mode. To enter the “On Air” mode, press the “Start” button on the iCap PC software. A real-time writer can then begin to send caption commands over the connection using their standard captioning software package.
If you are testing without a real-time writer, a simple test caption can be inserted by going to “Tools | Send Test Caption” in the iCap PC software. More complex tests are possible by licensing the iCap VC add-on, which allows timed sending of text files or arbitrary live keyboard or speech-to-text input.