Configuration and command-line arguments

Configuration and command-line

Typically ew-hlsingest is run as a systemd service with command-line arguments specified in /usr/lib/systemd/system/ew-hlsingest.service.

In can also be started from the command-line.

Command-line arguments

ew-hlsingest -h
Usage of ew-hlsingest:
  -cfg string
    	Config file (default "/etc/edgeware/ew-hlsingest/config.json")
  -defaultConfig
    	Print default configuration
  -logFormat string
    	Format and type of log: [consolejson consolepretty journald discard] (default "consolepretty")
  -logLevel string
    	log level (default "trace")
  -version
    	Get version, date, and possible expiration date

Configuration parameters

The configuration file, in the location specified as above, controls the service.

Review note: generate JSON-schema

This is an example configuration with two channels:

{
  "outDir": "/tmp/ew-hlsingest",
  "startCatchup": 20,
  "logFormat": "journald",
  "logLevel": "info",
  "maxAdBreakDuration": 600,
  "channels": [
     {
           "name": "ch1",
           "url": "https://sometv.org/channel1",
           "configID": 0,
           "maxBandwidth": 100000000,
           "liveWindowS": 180,
           "logLevel": "info"
     },
     {
           "name": "ch2",
           "url": "https://othertv.org/channel1",
           "configID": 0,
           "maxBandwidth": 100000000,
           "liveWindowS": 180,
           "logLevel": "info"
     }
  ]
}

Some fields may need clarification:

maxAdBreakDuration Sometimes upstreams may fail to insert ad-break-end-markers (i.e. #EXT-X-CUE-IN) After the specified duration inside an ad-break ew-hlsingest will insert an end-marker.

maxBandwidth variants with bitrates above this threshold will be dropped from the output

configID allows the “downstream” CBM to distinguish between channel configurations. For example if maxBandwidth is modified the number output variants change, and configID must be incremented.

Review note: part of defaultconfig and internal struct, never referenced, remove! startCatchup

Review note: maxAdBreakDuration [etc] should have Sin its name to clarify unit

Configuration updates

Channels can be modified/added/removed without restarting the service. Any modification to the configuration file are automatically detected, and channels will be restarted/started/stopped accordingly. Changes not directly related to the service itself, such as logLevel, will not trigger a restart.

Integration with ew-cbm

ew-hlsingest acts as the input source for ew-cbm (Catchup Buffer Manager, a part of SW Live Ingest), and ew-cbm, in its turn, will be the backend of sw-repackager, from which the channels are streamed to CDN, and then, to end user.

To make ew-hlsingest channel visible with ew-cbm, outDir attribute in ew-hlsingest configuration have to be the same with the location that ew-cbm gets the input from. The service file of ew-cbm can be referred to get that location (specified by argument --live-ingest-path), it is usually /mnt/ramdisk.

cat /usr/lib/systemd/system/ew-cbm.service
...
ExecStart=/usr/bin/ew-cbm --live-ingest-path /mnt/ramdisk --socket-path /var/run/edgeware/ew-cbm/socket --with-accel-redirect --node-id=%m
...

The next step is configuring the channel for ew-cbm to work with ew-hlsingest buffer.

confcli services.liveIngest.channels. -w
Running wizard for resource 'Channels'
<A list of channels>

Hint: Hitting return will set a value to its default.
Enter '?' to receive the help string

Channels <A list of channels>: [
  Channel <Configuration for a single channel>: {
    Channel Name (default: default): hlsingest-channel
    Channel State (default: enabled): cbm-only
    Catchup Location (default: ): cb1
    Channel Name Alias (default: ): 
    Channel Template Name (default: default): 
    Config Id (default: 0): 
    Input Sources <A list of input sources>: [
      Input Source <Input source configuration>: {
        Backup IGMPv3 Source (default: ): 
        Error correction (default: off): 
        IGMPv3 Source (default: ): 
        Source (default: ): 
        Passphrase for SRT connection (default: ): 
        Tracks <A list of tracks from the channel template>: [
          Track <Configuration for a single track>: {
            Log Level (default: INHERIT): 
            Track Name (default: default): 
            Variant flags (default: -1): 
          }
          Add another 'track' element to array 'tracks'? [y/N]: 
        ]
        Use As SCTE-35 Source (default: False): 
      }
      Add another 'inputSource' element to array 'inputSources'? [y/N]: 
    ]
    Logging <Logging configuration>: {
      General Log Level (default: INHERIT): 
      Track Log Level (default: INHERIT): 
      Source Log Level (default: INHERIT): 
    }
    Nielsen Marker Tracking (default: off): 
    Segmentation Template Name (default: default): 
  }
  Add another 'channel' element to array 'channels'? [y/N]: 
]
Generated config:
{
  "channels": [
    {
      "name": "hlsingest-channel",
      "state": "cbm-only",
      "catchupLocation": "cb1",
      "alias": "",
      "channelTemplate": "default",
      "configId": 0,
      "inputSources": [
        {
          "backupIgmpV3Source": "",
          "errorCorrection": "off",
          "igmpV3Source": "",
          "source": "",
          "srtPassphrase": "",
          "tracks": [
            {
              "logLevel": "INHERIT",
              "name": "default",
              "variantFlags": -1
            }
          ],
          "useAsScte35Source": false
        }
      ],
      "logging": {
        "general": "INHERIT",
        "track": "INHERIT",
        "source": "INHERIT"
      },
      "nielsenMarkerTracking": "off",
      "segmentationTemplate": "default"
    }
  ]
}
Merge and apply the config? [y/n]:

Only three configurations should be cared about: Channel Name (name), Channel State (state), Catchup Location (catchupLocation), others are meaningful for ew-live-ingest, another part of SW Live Ingest, so they should be left as default:

  • Channel Name (name): have to be exactly the same with the channel name configured in ew-hlsingest, so that ew-cbm will know where to look for the input.
  • Channel State (state): cbm-only is a must.
  • Catchup Location (catchupLocation) (optional): is the location that ew-cbm will write the catch up buffer to, please refer to ew-cbm documentation to know how to configure it.

After done configuring, this command, ew-cb-media, can be used to check for the running channel. If the channel name appears in the output of that command and the duration of catchup buffer starts growing (repeat the command the see if the channel is growing, or just use watch ew-cb-media), then the live content can now be delivered through ew-cbm to repackager and beyond.