Installation

Reading time ~6 minutes

Prerequisites

To use Cinegy Subtitling Service, the following Cinegy software components are required:

The subtitling component consists of two parts: Cinegy Subtitling Control and Cinegy Subtitling Service.

Cinegy Subtitling Control Plugin

Cinegy Subtitling Control is a subtitling secondary event plugin, installed along with Cinegy Event Manager. After installation it should be properly configured and activated.

Important
 Refer to the Cinegy Subtitling Control paragraph in the Cinegy Event Manager Manual for details on its configuration.

Cinegy Subtitling Service

The Cinegy Subtitling Service package is provided as a separate folder containing several files. Among them, the SubtitlingService.exe file can be run as a console utility used to process the incoming streams in accordance with the settings specified in the appsettings.json configuration file (also provided in the installation package). This file is placed in the same folder where Cinegy Subtitling Service is running, but after the first start it will be automatically copied into the Application Data folder.

Important
 Refer to the Application Settings paragraph for details on the configuration settings in the appsettings.json file.

Installation as the Windows Service

Cinegy Subtitling Service can be installed and run as a standard Windows service by using the delivered installation and configuration script. To do so, you should run the Configure-Services.bat file from your Cinegy Subtitling Service installation package using the "Run as administrator" command. The following management console window appears:

management console window

Here you can perform the following actions:

  • Install or Upgrade Subtitling Service – copies the SubtitlingService.exe file to the C:\Program Files\Cinegy\Cinegy Subtitling Service folder.

    Note
    		 If detected, the previous version of Cinegy Subtitling Service will be automatically replaced with the new one.

  • Create Subtitling Service – creates Cinegy Subtitling Service as a Windows service.

    Note
    		 This step requires the "Install or Upgrade Subtitling Service" action to be completed beforehand.

  • Start Subtitling Service – starts pre-created Cinegy Subtitling Service as a Windows service. At this stage, the appsettings.json configuration file is copied to the C:\ProgramData\Cinegy\SubtitlingService folder.

    Note
    		 This step requires the "Create Subtitling Service" action to be completed beforehand.

  • Stop Service – stops the pre-created Cinegy Subtitling Service started as a Windows service.

  • Remove Service – removes Cinegy Subtitling Service from Windows services list.

  • Exit – quits the management console.

Note
 After installation of the service, navigate to the C:\ProgramData\Cinegy\SubtitlingService folder and configure the appsettings.json file as described here or replace the existing file with a pre-configured one. At the service start the configuration will be applied automatically.

Application Settings

The appsettings.json configuration file is provided in the Cinegy Subtitling Service installation package. Below is the sample of the appsettings.json configuration file with the detailed description:

{
  "AllowedHosts": [
    "http://localhost:8080",
    "https://subs.qa.cinegy.com"
  ],
  "ApplicationUrls": [
    "http://0.0.0.0:8501"
  ],
  "Logging": {
    "LogLevel": {
      "Default": "Trace",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Warning"
    }
  },
  "Telemetry": {
    "Enabled": false,
    "OrgId": "sandpit",
    "Tags": "",
    "TelemetryServer": "https://telemetry.cinegy.com"
  },
  "Clocks": [
    {
      "ClockType": "ApiClock",
      "ClockId": 1
    },
	  {
      "ClockType": "ApiClock",
      "ClockId": 2
    },
	  {
      "ClockType": "PcClock",
      "ClockId": 1
    }
  ],
  "SubtitleChannels": [
    {
      "ClockId": 1,
      "ChannelId": 1,
      "ItemsDirectory": "D:/Subtitles",
      "ClearInterval": "500",
      "SubtitleEncoders": [
        {
          "EmbedMode": "Overwrite",
          "EncoderType": "teletext",
          "FrameRate": "25",

          "InputUrl": "rtp://@239.1.1.1:1234",
          "InputAdapter": "0.0.0.0",

          "OutputUrl": "udp://239.1.1.2:1234",
          "OutputTTL": "7",
          "OutputAdapter": "192.168.1.5",
          "OutputBackupAdapter": "192.168.1.10",

          "SyncDelayFrames": "7",
          "SyncToleranceFrames": "0",
          "SyncOffset": "0",

          "ProgramNumber": "0",
          "VideoPid": "0",

          "Language": "ENG",
          "MagazineNumber": "8",
          "PageNumber": "1",
          "TeletextPid": "2049"
        }
      ]
    },
  {
      "ClockId": 2,
      "ChannelId": 2,
      "ItemsDirectory": "D:/Subtitles",
      "ClearInterval": "500",
      "SubtitleEncoders": [
        {
          "EmbedMode": "Insert",
          "EncoderType": "teletext",
          "FrameRate": "25",

          "InputUrl": "rtp://@239.1.1.3:1234",
          "InputAdapter": "0.0.0.0",

          "OutputUrl": "udp://239.1.1.4:1234",
          "OutputTTL": "7",
          "OutputAdapter": "0.0.0.0",

          "SyncDelayFrames": "7",
          "SyncToleranceFrames": "0",
          "SyncOffset": "0",

          "ProgramNumber": "0",
          "VideoPid": "0",

          "Language": "RUS",
          "MagazineNumber": "8",
          "PageNumber": "88",
          "TeletextPid": "2049"
        }
      ]
    }
  ]
}

ApplicationUrls can be set as follows: http://<server_name>:8501, where <server_name> is the REST IP of the server where Cinegy Subtitling Service is running. Set it to 0.0.0.0 to use all the available IPv4 addresses on the local machine.

The SubtitleChannels section defines subtitle encoder engines. Further on, details of the options to that section parameters are described:

  • ChannelId – defines the channel ID that determines which Cinegy Air Engine channel should be associated with this subtitle channel.

    Note
    		 Setting this parameter is necessary only if you are building multi-channel subtitle insertion on one machine. Otherwise, its value should be set to "0".
    Note
    		 ApiClock in the Clocks section is a clock controlled by the timecode event of the channel. In multi-channel setup for each channel you should add ApiClock and set its ClockId accordingly, considering that the ClockId value should be the same as the ChannelId value. The rest of the parameters in this block should be configured similarly to ones defined for the channel set by default.

  • ItemsDirectory – defines the folder where subtitle SRT files are placed.

  • ClearInterval – defines the time interval for sending the 'clear' command when a new item is started, in milliseconds.

    Note
    		 Setting this parameter to "0" disables sending clear commands.

  • SubtitleEncoders – defines the set of Subtitle Encoders (engines) which may be associated with the various channel output streams (e.g. simulcast mode), where:

    • ProgramNumber – defines the source program number in the incoming stream.

      Note
      		 This parameter should be the same as set for master Air engine. If it is set to "0" or undefined, the first video program in the stream will be taken.

    • VideoPid – defines the video stream id in the incoming program.

      Note
      		 This parameter should be the same as set for master Air engine. If this parameter is absent in the configuration file or its value is set to "0", the first video stream in the program will be taken.

    • EmbedMode – defines the Cinegy Subtitling Service mode. This parameter can be set as "overwrite" or "insert").

    • EncoderType – defines the subtitle type.

      Note
      		 Currently only "teletext" is supported.

    • FrameRate – defines the stream frame rate.

    • InputUrl – defines the input stream URL.

      Note
      		 This parameter should be the same as set for master Air engine.

    • InputAdapter – defines the input network adapter.

      Note
      		 This parameter should be the same as set for <<products/air/21.9/playout/user-manual/playback-device-settings/output#network-settings,master Air engine>. Also it can be set to "0.0.0.0" to use all the adapters.

    • OutputUrl – defines the output stream URL.

    • OutputAdapter – defines the output network adapter.

      Note
      		 Set this parameter to "0.0.0.0" to use any adapter.

    • OutputBackupAdapter – defines the output backup network adapter.

      Note
      		 This parameter is optional.

    • OutputTTL – defines the TTL (Time To Live) interval for output.

    • SyncDelayFrames – defines the subtitling buffer size.

      Note
      		 The minimum value for this parameter is "3"; the recommended value is "7".

    • SyncToleranceFrames – defines the subtitling synchronization tolerance.

      Note
      		 The default value for this parameter is "0".

    • SyncOffset – defines the sync adjustment, in milliseconds.

    • Language – defines the teletext language.

      Note
      		 This parameter should be set as a three-letter abbreviation (ENG, RUS).

    • MagazineNumber – defines the teletext magazine number.

      Note
      		 This parameter should be the same as set for master Air engine.

    • PageNumber – defines the teletext page number.

      Note
      		 This parameter should be the same as set for master Air engine.

    • TeletextPid – defines the teletext PID.

      Note
      		 For overwrite mode, the TeletextPid value should be the same as the Teletext stream PID configured in the master Air engine.