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"
            }
          ],
          "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 Air 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 Air 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

    English

    ENG

    German

    GER/DEU

    Swedish

    SVE

    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.

      Note
      The folder name must contain a number.
      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 Air 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 Air 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 Air Engine.
    • Page – defines the Teletext page number.

      Note
      In Overwrite mode, this should be set the same as for the master Cinegy Air Engine.
    • FrameSize – the frame size in pixels horizontally (width) and vertically (height).

      Note
      This parameter is 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.

Typical Configurations

This section provides various scenarios of the Cinegy Subtitling Service configuration.

One Channel: Two Subtitle Encoders, No Video Muxer

This scenario uses one channel with two subtitle encoders and does not use a video muxer:

scenario1

The following licenses are required for this scenario:

licenses1

One Channel: Two Subtitle Encoders, One Video Muxer

This scenario uses one channel with two subtitle encoders and one video muxer:

scenario1

The following licenses are required for this scenario:

licenses2

One Channel: Two Subtitle Streams, Two Subtitle Encoders, Two Video Muxers

This scenario uses one channel with two subtitle streams, two subtitle encoders and two video muxers:

scenario1

The following licenses are required for this scenario:

licenses2

Two Channels: Each One Has Two Subtitle Encoders, One Video Muxer

This scenario uses two channels and each one has two subtitle encoders and one video muxer:

scenario1

The following licenses are required for this scenario:

licenses2