Configuration

Reading time ~9 minutes

Application Settings

The appsettings.json configuration file is provided in the Cinegy Subtitling Service installation package. Below is a version of the appsettings.json configuration file with some example values and a detailed description:

{
  "ApplicationUrls": [
    "http://localhost:8501"
  ],
  "Logging": {
    "LogLevel": {
      "Default": "Trace",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Warning"
    }
  },
  "Telemetry": {
    "Enabled": false,
    "OrgId": "sandpit",
    "Tags": "dev, testchannel",
    "TelemetryServer": "https://telemetry.cinegy.com"
  },
  "Globals": {
    "LiveId": "LIVE"
    "SyncOffsetBase": 280
  },
  "SubtitleChannels": [
    {
      "Id": 1,
      "ClearInterval": 500,
      "Repositories": [
        {
          "Id": 0,
          "Language": "ENG",
          "FileSource": {
            "FileSearchPolicy": "Auto",
            "Directory": "D:\\Subtitles1"
          },
          "LiveSource": {
            "Enabled": true,
            "EndPoint": "127.0.0.1:50125",
            "VerbosityEnabled": false
          }
        },
        {
          "Id": 1,
          "Language": "RUS",
          "FileSource": {
            "FileSearchPolicy": "SubtitleId",
            "Directory": "D:\\Subtitles2"
          },
          "LiveSource": {
            "Enabled": false,
            "EndPoint": "127.0.0.1:50125",
            "VerbosityEnabled": false
          }
        }
      ],
      "Streams": [
        {
          "InputUrl": "rtp://@239.1.1.2:1234",
          "InputAdapter": "0.0.0.0",
          "InputSrtLatency": -1,
          "InputSrtPassphrase": null,
          "OutputUrl": "rtp://@239.1.1.3:1234",
          "OutputAdapter": "0.0.0.0",
          "OutputBackupAdapter": null,
          "OutputSrtPassphrase": null,
          "OutputTTL": 1,
          "FrameRate": "25",
          "VideoPid": 0,
          "Encoders": [
            {
              "Type": "Teletext",
              "RepositoryId": 0,
              "SubtitlePid": 4098,
              "SyncOffset": 0,
              "Magazine": 8,
              "Page": 1
            },
            {
              "Type": "DVB",
              "RepositoryId": 1,
              "SubtitlePid": 4099,
              "SyncOffset": 0,
              "FrameSize": "1920x1080"
              "FontSize": "36",
              "FontName": "Times New Roman"
            }
          ],
          "Multiplexer": {
            "Type": "Video",
            "Mode": "Insert",
            "SyncDelayFrames": 7,
            "SyncToleranceFrames": 0
          }
        }
      ]
    }
  ]
}

ApplicationUrls is the address and port to which the application binds when running. This can be set as follows: http://<server_name>:8501, where <server_name> is the REST IP of the server where the Cinegy Subtitling Service is running.This can be set to 0.0.0.0 to use all the available IPv4 addresses on the local machine.

All logging configuration is provided in the Logging section.

In this example, the Default, Microsoft and Microsoft.Hosting.Lifetime categories are specified with associated log levels of Trace and Warning. The log level indicates the minimum severity of messages which are logged and ranges from 0 to 6 with lower numbers producing more information in the resultant file.

The available levels are:

Trace = 0, Debug = 1, Information = 2, Warning = 3, Error = 4, Critical = 5, and None = 6.

Note	The log files are stored in the following path: C:\ProgramData\Cinegy\SubtitlingService\logs.

The Telemetry section is used to enable and define the elements required to send information to an ElasticSearch cluster. This data can then be visualized using dashboards created in tools such as the Grafana. Cinegy provides a non-SLA backed ElasticSearch cluster with a Grafana frontend for customers. Please contact the Cinegy Sales Team if you wish to make use of this.

Enabled – turns the feature on or off.
OrgID – is unique to each customer and is used to secure your data from access by any other users.
Tags – can be used to identify and filter data when viewed in created dashboards.
TelemetryServer – defines where the data should be sent.

In the Globals section you can define the parameters that will be used globally:

LiveId – it should match the value used in the Subtitle Id field for Live items in the Cinegy Air playlist.

Note
Currently Live subtitling is only supported using the Newfor protocol.
SyncOffsetBase – defines the global sync value, in milliseconds.

A subtitle channel is a reflection of an upstream TV channel, which can contain one or more video streams (in the case of simulcast) based on the same Cinegy Air playlist, and therefore all video streams have the same content. Each subtitling channel is configured individually within the Subtitle Channels section with the following parameters:

Id – defines the channel ID that should match the number used in the Op1 field in the Cinegy Playout Engine channel configuration and therefore that it 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 can be set to "0" and there is no need to define the channel ID in the Cinegy Playout Engine configuration.

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

Note	To use multiple channels, you can duplicate the contents of the SubtitleChannels section and edit its parameters accordingly.

Each subtitle channel may have one or more subtitle encoders. The subtitle encoder is an engine generating subtitle data, based on its parameters, playlist data and reference video stream. Each encoder is linked to a subtitle repository, containing the required files. Each Repository has its own static settings, defining its content:

Id – defines the unique repository ID.

Language – defines the Teletext language descriptor using an ISO 639-2/T language code (e.g. ENG, SPA etc.). The list of currently supported languages is given in the following table:

Language ISO 639-2 code Language ISO 639-2 code Language ISO 639-2 code

Language	ISO 639-2 code	Language	ISO 639-2 code	Language	ISO 639-2 code
English	`ENG`	German	`GER/DEU`	Swedish	`SWE`
Finnish	`FIN`	Hungarian	`HUN`	Italian	`ITA`
French	`FRE/FRA`	Portuguese	`POR`	Spanish	`SPA`
Czech	`CZE/CES`	Slovak	`SLO/SLK`	Polish	`POL`
Turkish	`TUR`	Serbian	`SRP`	Croatian	`HRV`
Slovenian	`SLV`	Romanian	`RON/RUM`	Estonian	`EST`
Lettish	`LAV`	Lithuanian	`LIT`	Russian	`RUS`

English

ENG

German

GER/DEU

Swedish

SWE

Finnish

FIN

Hungarian

HUN

Italian

ITA

French

FRE/FRA

Portuguese

POR

Spanish

SPA

Czech

CZE/CES

Slovak

SLO/SLK

Polish

POL

Turkish

TUR

Serbian

SRP

Croatian

HRV

Slovenian

SLV

Romanian

RON/RUM

Estonian

EST

Lettish

LAV

Lithuanian

LIT

Russian

RUS

Note	For multilingual mode, you can use different languages in different subtitle encoders for one subtitle channel.

FileSource group defines the following parameters:
- FileSearchPolicy – defines the search policy used to determine if a playlist item has a matching subtitle file. Currently, the following search policies are supported: "SubtitleId" to search using the Subtitle Id of items in the Cinegy Air playlist and "Auto".
- Directory – defines the folder where subtitle files are placed.
  
  Important
  The use of mapped drives as a subtitles directory is not recommended.
LiveSource group defines the following parameters:
- Enabled – defines whether the live source will be enabled or disabled. If set to "True", it provides subtitle generation for live items using the Newfor protocol and requires a repository separate from that used by file items.
- EndPoint – defines the IP address and port of the machine providing the live source in the following format: IP_Address:port.
- VerbosityEnabled – enables/disables verbose mode logging for debugging.

The Streams section groups together an incoming and outgoing transport stream with the required subtitle encoders and muxer. Each subtitle encoder, defined in the channel, can be used in several subtitle streams, in any combination. Each subtitle stream uses one channel video stream as the reference.

Note	Only one license is required for each subtitle encoder, regardless of the number of subtitle streams created, since the same subtitle encoder data is used. Refer to the scenario using a configuration with one subtitle stream and two subtitle encoders.

InputUrl – defines the input stream URL for the subtitle channel, which will be the output stream from the master Cinegy Playout Engine.
InputAdapter – defines the input network adapter to use for incoming RTP or UDP streams.

Note
This parameter can be set to "0.0.0.0" to listen on all available adapters.
InputSrtLatency – the latency to be used for encoding the input SRT stream.
InputSrtPassphrase – define the passphrase for input SRT stream encryption.

Note
This parameter is optional.
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.
OutputSrtPassphrase – define the passphrase for output SRT stream encryption.

Note
This parameter is optional.
OutputTTL – defines the TTL (Time To Live) interval for output.
FrameRate – defines the stream frame rate.

VideoPid – defines the video stream PID in the incoming transport stream.

Note	This parameter should be set the same as the output from the master Cinegy Playout Engine. If this parameter is absent in the configuration file or its value is set to "0", the first video stream in the incoming transport stream will be used.

Encoders group allows the user to configure subtitle encoders with the following parameters:
- Type – defines the type of subtitles which will be generated.
  
  Note
  Currently the "Teletext" and "DVB" types are supported.
  
  Note
  Currently formatting for DVB subtitles is not supported.
- RepositoryId – defines the subtitle file repository ID used by the encoder.
- SubtitlePid – defines the PID allocated to the subtitle stream.
- SyncOffset – defines the encoder sync offset to be added to the SyncOffsetBase value, in milliseconds.
- Magazine – defines the Teletext magazine number.
  
  Note
  In Overwrite mode, this should be set the same as for the master Cinegy Playout Engine.
- Page – defines the Teletext page number.
  
  Note
  In Overwrite mode, this should be set the same as for the master Cinegy Playout Engine.
- FrameSize – the frame size in pixels horizontally (width) and vertically (height).
- FontSize – the size of the font for subtitles encoding.
- FontName – the name of the font for subtitles encoding.
  
  Note
  The frame size, font size and font name parameters are only topical for the DVB encoder.

The video muxer is an optional component, which can be applied to each subtitle stream in a channel to multiplex the generated subtitle stream with its reference video stream into a master output stream.

Multiplexer can be configured with the following parameters:

Type – defines what muxing will take place.

Note	Currently the "video" and "subtitle" types are supported. Video will produce an output combining the incoming video from the transport stream with the generated subtitle stream. Subtitle will only produce a stream which contains subtitle data to be added back to the reference video downstream.

Note	The subtitle multiplexer type has no further configuration.

Mode – defines video multiplexer mode.

Note
This parameter can be set as "overwrite" or "insert".
SyncDelayFrames – defines the subtitling buffer size.

Note
This parameter is only topical for the video multiplexer. The minimum value for this parameter is "3"; the recommended value is "7".
SyncToleranceFrames – defines the subtitling synchronization tolerance.

Note
This parameter is only topical for the video multiplexer. The default value for this parameter is "0".

Note
Please avoid using SyncToleranceFrames = 0. Increasing this parameter value to 2-3 frames will improve the stability of teletext muxing in the stream.