Agent Configuration
After you have downloaded and untarred the Zixi ESAM Agent files, you can configure the agent by editing the /zixi/esam-linux-x64/config.json or /zixi/esam-linux-arm64/config.json file.
The JSON configuration is made up of six arrays of key/value pairs, which are explained below. Also see: Appendix B: Example config.json file.
Agent configuration
agent array
This array contains startup information:
- port [integer] - The TCP port the Agent is listening on. This port will be used for unsolicited messages and SCTE-35 messages coming from the Broadcaster.
sds [Signal Decision Service]
There are two SDS services that can be used with ESAM:
- ESNI/SCTE-224 – Content switching
- POIS/SCTE-130 – SCTE-35 manipulation
(See SDS Terminology below for an explanation of terms used in this section.)
sds configuration array
- mode [string] - “esni” or “pois” indicating desired service. Multiple services can be configured by adding an additional SDS json array { } within the sds section.
- baseURL [string] - URL to send Signal Processing Event messages to. Note: if using both pois and esni it is not recommended to use the same endpoint as each service sends its own signal processing event.
- username [string] - if the SDS requires authentication
- password [string] - if the SDS requires authentication
- zoneIdentity – ID of output to be switched. Corresponds to Audience in SCTE-224.
- type [string] - generally “output”
- path [string] - Full JSONPath location of desired External ID key in output metadata. “user_data.zm_external_id” is default.
- acquistionPointIdentity – ID of an output or input to mark where the SCTE-35 messages were captured. Corresponds to source in SCTE-224.
- type [string] - options include [“output”,”input”]
- path [string] - Full JSONPath location of desired External ID in input/output metadata. “user_data.zm_external_id” is default.
- altContentIdentity [string] – ID of an input that the zoneIdentity will switch to. (destination input.) Generally, should match path of acquistionPointIdentity. Corresponds to content under viewingpolicy in SCTE-224.
- retryDelay [integer] - Wait time before retry after api timeout
- maxRetries [integer] - number of retries after timeout
broadcaster array
The ESAM agent gathers input and output info as well as triggers switches and inserts SCTE via the Broadcaster API. This section outlines communication preferences.
- port [integer] - TCP port hosting the broadcaster service
- username [string] - Broadcaster UI admin username
- password [string] - Broadcaster UI admin password
- retryDelay [integer] - Milliseconds the Agent should wait when interacting with the Broadcaster API.
- maxRetries [integer] - Number of attempts the Agent should make when interacting with the Broadcaster API.
- cachMs [integer] - How long the broadcaster input/output list is stored to optimize performance when conducting multiple switches at once.
redirect array
This array details switching options using the redirect_client.json api:
- abortOnTimeout [boolean] - Allow redirect_client API call to abort action if PTS detection time runs out.
- seamless [boolean] - Perform seamless switch if PTS detection times out.
- overwriteIfInProgress [boolean] - Cancel current API request in favor of new API request with same parameters. If False, multiple switches will be queued.
- ptsDetectionTimeoutMs [integer] - The amount of time in milliseconds the broadcaster should continue to search in real time for provided PTS.
logger array
There are three options to log—console, syslog, file. They can be used simultaneously. The library is the Winston library which has more config info found here.
- console – will post logs to stdout
- silent [boolean] - False will post logs to the stdout
- level [string] - Sets the log level that should be posted to the stdout. Options include: [“debug”, “info”, “warning”, “error”]
- file – will post logs to file
- level [string] - Sets the log level that should be posted to the file. Options include: [“debug”, “info”, “warning”, “error”]
- filename [string] - Format of filename %DATE% will use the value assigned to datePattern
- dirname [string] - Directory to write logs to. It’s recommended to match the file path with that of the Zixi broadcaster logs so they can be accessed in a single place via ZEN Master tunnel without SSH access.
- datePattern [string] - format of datetime string.
- maxSize [string] - Max size each file should reach
- maxFiles [string] - The number for files to keep before cycling.
- syslog - Will post logs to external syslog server. We passthrough parameters from the Winston syslog implementation: https://www.npmjs.com/package/winston-syslog.
- level [string] - log level [“debug”, “info”, “warning”, “error”]
- host [string] - host ip of syslog server
- port [integer] - syslog communication port
- protocol [string] - syslog communication protocol.
Log Message Reference: details of all log messages can be found in Appendix F: ESAM Agent Log Reference
zenmaster array
This array configures Agent to report to ZEN Master or other external system.
- baseUrl [string] – The URL where to post SCTE-35 messages and notifications of content switches. (If using ZEN Master, https://zen.zixi.com)
- apiKey [string] - Key used for authentication to external system. Added as value to “x-api-key" in request headers. (If using ZEN Master, Configuration > API Keys in your ZEN Master account)
- switchTargetPath [string] - URI where the notifications can be sent in the baseUrl. (If using ZEN Master, “api/scte224/targets”)
Input & Output configuration
Parameters
- Acquisition Point Identity – The ID associated with any SCTE 35 message sent to a decisioning service. Included in both SPEs and SPNs, this can correlate to a Zixi Broadcaster input or output depending on how the schedule is set up and will generally correspond to the <source> attribute in an ESNI media or mediapoint.
- Zone Identity – Part of the SPN for the switching component, this is the ID of the Zixi output or ESNI audience that will be switched.
- Alt Content Identity – Part of the SPN for the switching component, this is the ID of the input that will be switched to a Zixi output or Zone Identity and corresponds to the <content> in an ESNI schedule’s viewingPolicy.
Basic configuration using ZEN Master
ESNI
Mapping sources to schedule:
- In ZEN Master, create a failover source containing desired source, and in the Advanced section, enter an External ID that corresponds with Source or Content IDs in the external schedule. (failover source does not require two components. They are just used in this case as a variable element that is written to the broadcaster)
- Create a Passthrough channel for the source.
- In the ESAM Agent config file, set acquisitionPointIdentity and altContentIdentity types to input and paths to user_data.zm_external_id
Mapping targets to schedule:
- In ZEN Master, create a target and in the Advanced section, enter an External ID that corresponds to the Audience ID (or Zip/VIRD/etc) in the external schedule.
- In the ESAM Agent config, set zoneIdentity type to output and path to user_data.zm_external_id
POIS
In ZEN Master:
- Create a failover source containing desired sources, and in the “Advanced” section, enter an External ID (failover source does not require two components. In this case, it is just used as a variable element that is written to the Zixi Broadcaster).
- Create a Passthrough channel for the source.
- Create a target and in the “Advanced” section, choose an External ID and enter a POIS latency offset. This value can be zero, but it establishes that this output should receive POIS SCTE conditioning. If a value is entered, this will offset the POIS modification path to allow for api latency. Note that the External ID is only required if doing POIS modification on the inputs.
In the ESAM Agent config file, set acquisitionPointIdentity path to user_data.zm_external_id
- If acquisitionPointIdentity is on the input, all POIS-enabled targets connected to the channel with matching External ID will receive POIS conditioning.
- If acquisitionPointIdentity is on the output, only SCTE on targets with matching External ID will be conditioned.
Broadcaster only deployments (no ZEN Master)
The ESAM agent references input/output metadata to match unique identifiers. For the below instructions use the /edit_stream.json and /edit_output.json endpoints with parameter userdata= {“zm_external_id”:”desired-id”}. For more information on API, refer to Zixi Broadcaster API manual available on the Custom Portal.
acquisitionPointIdentity
- In the agent config.json, set type to either input or output depending on the external SDS set up.
- For path, we recommend the default, user_data.zm_external_id
This ID represents where the SCTE-35 messages were captured, or the output connected to the input that the SCTE-35 messages were captured on. This generally equates to the <SOURCE> attribute in a 224 Schedule. For POIS this would be that input/output that will receive manipulation
- Using the Broadcaster API, update the user_data.zm_external_id field to match the source IDs referenced by the SDS on desired inputs/outputs that should be referenced by the SDS.
ZoneIdentity
- zoneIdentity is often on the output. In the config, set type to output.
- For path, we recommend the default, user_data.zm_external_id
- Using the Broadcaster API, set the user_data.zm_external_id field to match output/audience ID’s referenced by the SDS.
altContentIdentity
- There is no ‘type’ for altContentIdentity as it will always be an input. In the config, set ‘path’ to use the same field as acquisitionPointIdentity.
- Using the Broadcaster API, update the user_data.zm_external_id field to match the content IDs referenced by the SDS on desired inputs or outputs that should be referenced by the SDS (if there are some sources that are not included in acquisitionPointIdentity list)
SDS Terminology
ESAM Terminology and how it relates to Zixi, scheduling and POIS
- Signal Processing Event (SPE) – this is the XML message that is sent to the decisioning service when triggered by a relevant SCTE message.
- Signal Processing Notification (SPN) – this is the XML message that is returned from a decisioning service outlining any stream switches or SCTE 35 manipulation that should occur.
- Unique components of the SPE/SPN:
- >Acquisition Point Identity – The ID associated with any SCTE 35 message sent to a decisioning service. Included in both SPEs and SPNs, this can correlate to a Zixi Broadcaster input or output depending on how the schedule is set up and will generally correspond to the <source> attribute in an ESNI media or mediapoint.
- Zone Identity – Part of the SPN for the switching component, this is the ID of the Zixi output or ESNI audience that will be switched.
- Alt Content Identity – Part of the SPN for the switching component, this is the ID of the input that will be switched to a Zixi output or Zone Identity and corresponds to the <content> in an ESNI schedule’s viewingPolicy.
Authentication
Authentication is handled in the config file as user and password parameters. The credentials are added to the SDS endpoint URL with Apache basic authentication.
Communication Methods
There are two ways the ESAM agent communicates with an external SDS:
Solicited – @matchSignal
The ESAM Agent requests a notification message from the SDS on what to do. When the ESAM Agent is provided a SCTE-35 message from the Broadcaster. The ESAM Agent will make an HTTP Post to the SDS (at the URL provided in the config file) and await a response within the same HTTP connection. In ESNI/SCTE-224, this is called matchSignal.
Unsolicited – @matchTime
The SDS reaches out to the ESAM Agent without prompting from the Agent. As part of the setup with the SDS, the IP of the Broadcaster, the port hosting the ESAM Agent, and a list of input and output id’s must be provided to the SDS to allow them to send messages. In ESNI/SCTE-224, this is called matchTime.
Special note: notifying SDS of ESAM enabled inputs and outputs
To facilitate interaction with an SDS, Zixi has added an External ID metadata field. In general, the External ID that is used to identify esam enabled inputs and outputs should match the source, content, and audience IDs used in the SDS. If the SDS partner is planning to send unsolicited messages it is important to notify them of all the available input and output external id’s that can be switched (or manipulated).