Application Settings

Reading time ~12 minutes

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": "GER",
          "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": "Teletext",
              "RepositoryId": 1,
              "SubtitlePid": 4098,
              "SyncOffset": 0,
              "Magazine": 8,
              "Page": 2
            },
            {
              "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
          }
        }
      ]
    }
  ]
}

Caution

After editing the configuration file, the Cinegy Subtitling Service must be restarted for the changes to take effect.

Host Settings

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.

General Settings

Settings within these configuration blocks pertain to the overall operation of the entire Cinegy Subtitling Service.

Logging

This section provides the logging configuration and comprises the following categories: Default, Microsoft, and Microsoft.Hosting.Lifetime:

"Logging": {
    "LogLevel": {
      "Default": "Trace",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Warning"
    }
   },

The Default category is responsible for logging the Cinegy Subtitling Service, while the Microsoft and Microsoft.Hosting.Lifetime categories cover logging for the built-in HTTP server provided by Microsoft. The level of Microsoft-related logging is specified at the "Warning" level and should only be increased in cases of debugging.

The log level indicates the minimum severity of messages logged and ranges from "0" to "6", with lower numbers producing more detailed information in the resulting file. The available levels are:

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

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

Telemetry

The "Telemetry" section is reserved for cloud-based deep analysis and monitoring and is currently under development. At present, it only offers settings for log reporting.

  "Telemetry": {
    "Enabled": false,
    "OrgId": "sandpit",
    "Tags": "dev, testchannel",
    "TelemetryServer": "https://telemetry.cinegy.com"
  },

Globals

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

"Globals": {
    "LiveId": "LIVE"
    "SyncOffsetBase": 280
  },

The Cinegy Subtitling Service supports two types of subtitle sources: file-based (SRT and STL subtitle files) and stream-based (streams with Teletext transferred via Newfor protocol). In the "Globals" configuration block LiveId is responsible for switching subtitle source to stream-based type.

Once the Cinegy Subtitling Service receives an event from the Cinegy Event Manager for an item with Subtitle ID that corresponds to the LiveId value, the data from the stream will be transferred according to the channel configuration in the "LiveSource" block, while settings from the "FileSource" block will be ignored.

The SyncOffsetBase parameter determines the global offset of subtitles relative to the video for all encoders. Essentially, it shifts the initial frame, where the subtitle phrase should be inserted, by the specified value.

SubtitleChannels

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 hence all video streams within a subtitle channel have identical content. Each subtitle channel is configured individually within the "SubtitleChannels" section with the following parameters:

"SubtitleChannels": [
  {
    "Id": 1,
    "ClearInterval": 500,

The channel Id parameter serves to uniquely identify events generated by the Cinegy Playout engine for a specific subtitle channel. Therefore, the value assigned to the channel Id parameter should match the number used in the "Op1" field in the Subtitle events settings of the Cinegy Playout engine configuration:

If the "Op1" field in the "Subtitle events" settings is left empty, the events generated by this Cinegy Playout engine will be used for the subtitle channel with an Id=0.

To enable multichannel subtitle insertion, a separate channel configuration block should be created for each channel within the "SubtitleChannels" block, and each channel must have a unique Id number.

The ClearInterval parameter defines the time interval, in milliseconds, during which the Cinegy Subtitling Service sends the 'clear' command when a new item is started in the Cinegy Air playlist. This action aims to prevent the display of subtitles from the previous item. It is particularly relevant when an on-air item is interrupted by the manual starting of the next item in the playlist.

Subtitle Service Groups

Repositories

The "Repositories" block is responsible for configuring subtitle sources.

"Repositories": [
  {
    "Id": 0,
    "Language": "ENG",
    "FileSource": {
      "FileSearchPolicy": "Auto",
      "Directory": "D:\\Subtitles1"
    },
    "LiveSource": {
      "Enabled": true,
      "EndPoint": "127.0.0.1:50125",
      "VerbosityEnabled": false
    }

When subtitles need to be generated from various languages or of different Live sources, configuring multiple repositories is necessary.

General Settings

The Id parameter defines the unique repository ID. These repository IDs are used to link the encoders with respective repositories.

The value for the Language parameter is specified using an ISO 639-2/T language code (e.g., ENG, SPA, etc.). The Language parameter is used to create subtitle descriptors for both Teletext and DVB Bitmap, which then is transmitted in the transport stream. For Teletext, the corresponding Teletext character set is selected according to the required language to ensure proper character encoding. 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

FileSource

The "FileSource" configuration group is relevant for file-based scenarios, where the Cinegy Subtitling Service retrieves subtitle data from a subtitle file for further embedment into the output stream.

The FileSearchPolicy parameter defines the criteria for searching a subtitle file within a specified directory, corresponding to an item in the Cinegy Air playlist. This parameter can be assigned one of the following values:

"SubtitleId" – used when matching is based on the Subtitle ID of the playlist item.
"Name" – used when comparing with the Name of the playlist item.
"Auto" – used when the Name is considered first, followed by the Subtitle ID.

The Directory parameter defines the path to the directory containing subtitle files.

Note	We do not recommend using mapped drives as the directory for subtitles.

LiveSource

The "LiveSource" configuration is utilized when a stream is used as a source of subtitle data. The Cinegy Subtitling Service supports only the Teletext transferred via the NewFor protocol as a Live subtitle source.

The generation of stream-based subtitles can be enabled by setting the Enabled parameter to "true". In this scenario, when the Cinegy Subtitling Service receives an event from the Cinegy Event Manager for a playlist item with a Subtitle ID that corresponds to the LiveId value, the subtitle data source will be switched to the "LiveSource" for this item.

The EndPoint parameter defines IP_Address:Port to establish a TCP connection with the Newfor live subtitle stream generator. Setting the IP address to "127.0.0.1" limits connections to be accepted only from the local machine. To allow connections from external sources, specify the IP address "0.0.0.0", enabling access through any adapter. Alternatively, to restrict connections to a specific adapter, use its specific IP address. Also, you will need to specify the correct port, which will be listened to by the Cinegy Subtitling Service.

Note	The Cinegy Subtitling Service does not support NewsFor Message Type 1 (Set Subtitle Page) and Message Type 5 (Set Logical Channel), as these settings are configured at the Cinegy Subtitling service level.

The VerbosityEnabled parameter enables/disables verbose mode logging for debugging.

Streams

This section comprises a configuration of streams:

"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": 4096,

In this configuration block, the InputUrl parameter specifies the input stream URL for the subtitle channel. The URL will either correspond to the output stream, or will use the relevant SRT mode configuration to match, the master Cinegy Playout Engine. Please refer to our RTP/UDP/SRT URL Format article for additional information.

The InputAdapter defines the input network adapter to use for incoming RTP or UDP streams. It should be set to "0.0.0.0" to listen on all available adapters.

The InputSrtLatency parameter determines the latency, measured in milliseconds, for encoding the input SRT stream. If set to "-1", the default latency defined by the SRT library will be used. In InputSrtPassphrase you can optionally define the passphrase for input SRT stream encryption.

The OutputUrl parameter determines the output stream URL.

The OutputAdapter parameter defines the output network adapter and allows the user to use any adapter when set to "0.0.0.0".

The optional OutputBackupAdapter defines the output backup network adapter for RTP or UDP streams.

The OutputSrtPassphrase parameter can be used optionally to define the passphrase for output SRT stream encryption.

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

The FrameRate parameter defines the frame rate of the input stream.

The VideoPid parameter defines the video stream PID in the incoming transport stream. This parameter should be set the same as the output from the master Cinegy Playout Engine:

If the VideoPid is absent in the configuration file or its value is set to "0", the first elementary stream in the incoming transport stream will be used as a reference.

Encoders

Subtitle encoders are configured within the "Streams" section. In the example below, the configuration of three encoders is shown: two utilizing Teletext data and one using DVB Bitmap data.

"Encoders": [
   {
     "Type": "Teletext",
     "RepositoryId": 0,
     "SubtitlePid": 4098,
     "SyncOffset": 0,
     "Magazine": 8,
     "Page": 1
   },
   {
     "Type": "Teletext",
     "RepositoryId": 1,
     "SubtitlePid": 4098,
     "SyncOffset": 0,
     "Magazine": 8,
     "Page": 2
   },
   {
     "Type": "DVB",
     "RepositoryId": 1,
     "SubtitlePid": 4099,
     "SyncOffset": 0,
     "FrameSize": "1920x1080"
     "FontSize": "36",
     "FontName": "Times New Roman"
   }
 ],

The Cinegy Subtitling Service can embed DVB Bitmap and Teletext data into source IP streams. With the Type parameter, you can define whether "Teletext" or "DVB" subtitles will be generated.

In the RepositoryId you can define the subtitle repository ID used by the encoder.

Teletext Encoder

The SubtitlePid parameter defines the PID allocated to the subtitle stream.

The Magazine and Page parameters define the Teletext magazine and page numbers correspondingly.

In insertion mode, you can add up to 4 Teletext pages in one subtitle stream. If the number of pages exceeds 4, they should be split between several streams. The SubtitlePid parameter in this case should have identical values for all Teletext pages.

For overwrite mode, the SubtitlePid, Magazine, and Page parameters should be configured to match the setup of the master Cinegy Playout Engine that generates the video stream:

The SyncOffset parameter determines the offset of subtitles relative to the video for the respective encoder. The value is set in milliseconds. If SyncOffsetBase is specified in the "Globals" section was also specified, then the resulting offset will include the sum of both offsets.

DVB Encoder

The SubtitlePid parameter for the DVB encoder is configured in the same way as for Teletext in insertion mode.

The FrameSize parameter determines the frame size in pixels horizontally (width) and vertically (height) and should correspond to the incoming video stream.

The FontSize parameter determines the size of the font for encoding subtitles. The minimum font size is 5, and the maximum size is calculated as frame height / 6 (for example, for 1920х1080 video it is 1080/6=180, which means the maximum font size is 180).

The FontName parameter indicates the font used for encoding subtitles, supporting TrueType (.ttf) and OpenType (.otf) fonts. It must match exactly the name of the font installed on the server running the Cinegy Subtitling Service, including spelling, capitalization, and spacing. If the font is not specified in the settings file, the service defaults to "Helvetica Monospaced".

Also, on the Cinegy Playout Engine side, you should ensure that there is always enough space in the transport stream to add DVB subtitle data. Therefore, you have to increase the output transport rate by about 30% in comparison to the video bitrate. For example, if you configured a 35 Mbs video stream, you need to increase the "Transport rate" value in the Cinegy Playout configurator to about 50 Mbs:

Multiplexer

In this section, you can define how subtitle streams are muxed with video streams.

"Multiplexer": {
  "Type": "Video",
  "Mode": "Insert",
  "SyncDelayFrames": 7,
  "SyncToleranceFrames": 0
}

The Type parameter specifies the type of muxing that will occur. It can be either "Video" or "Subtitle".

Video Muxing

The video muxer 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.

The Mode parameter determines the video multiplexer mode to be used: "overwrite" or "insertion".

The SyncDelayFrames parameter specifies the number of frames used by the Cinegy Subtitling Service to buffer the incoming stream. Considering the unique requirements of processing various subtitle types, Teletext requires a minimum value of "3" for this parameter, with a recommended value of "7". Meanwhile, DVB subtitles require a buffer of "25" frames.

The SyncToleranceFrames parameter determines the number of frames before a certain video frame where the Cinegy Subtitling Service can embed subtitle data. Setting a large value is not recommended as it may affect decoder stability. The recommended values are 2-3 frames for Teletext and 15-20 frames for DVB.

Subtitle Muxing

With the "Subtitle" type of multiplexer defined, the Cinegy Subtitling Service produces a separate subtitles output stream that is not muxed with video and audio streams. The external muxer should be used to combine these streams.

"Multiplexer": {
  "Type": "Subtitle",
}