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.
NoteCurrently 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 configuration and therefore that it should be associated with this subtitle channel:
NoteSetting 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 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
NoteFor 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.
ImportantThe 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.
NoteThis 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.
NoteThis parameter is optional. -
OutputUrl – defines the output stream URL.
-
OutputAdapter – defines the output network adapter.
NoteSet this parameter to "0.0.0.0" to use any adapter. -
OutputBackupAdapter – defines the output backup network adapter.
NoteThis parameter is optional. -
OutputSrtPassphrase – define the passphrase for output SRT stream encryption.
NoteThis 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.
NoteThis 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.
NoteCurrently the "Teletext" and "DVB" types are supported. NoteCurrently 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.
NoteIn Overwrite mode, this should be set the same as for the master Cinegy Playout Engine. -
Page – defines the Teletext page number.
NoteIn 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.
NoteThe 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.
NoteCurrently 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. NoteThe subtitle multiplexer type has no further configuration. -
Mode – defines video multiplexer mode.
NoteThis parameter can be set as "overwrite" or "insert". -
SyncDelayFrames – defines the subtitling buffer size.
NoteThis 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.
NoteThis parameter is only topical for the video multiplexer. The default value for this parameter is "0". NotePlease 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:
The following licenses are required for this scenario:
One Channel: Two Subtitle Encoders, One Video Muxer
This scenario uses one channel with two subtitle encoders and one video muxer:
The following licenses are required for this scenario:
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:
The following licenses are required for this scenario:
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:
The following licenses are required for this scenario: