Basics about FAB Subtitle Database REST API
FAB Subtitle Database offers a REST API for reading and writing data from and into the subtitle database. The REST API as described below is available starting with FAB Subtitle Database Version 7.05.
FAB Subtitle Database stores a list of records for every configured channel in the database. Every channel is identified by the name of the channel.
Every record is identified by “InternalID” which is assigned to every new record directly by FAB Subtitle Database Server. It is guaranteed that no two records in the database will have the same “InternalID”.
Every record may also have a “UniqueID”. The “UniqueID” is an external ID which can be imported when importing database records from an XML file or when writing the record into the database through a REST API call. The UniqueID must also be guaranteed to be unique. This means that no two records in the database must have the same “UniqueID”.
When using REST API functions to read/write/delete database records it is possible to use both the “InternalID” and the “UniqueID”.
Configuration
In order to be able to use the REST API there are two configuration settings which have to be configured correctly after starting the “Database Config” program.
List of possible subtitle file types and languages
The “subtitle type” defines whether the subtitle file is “hoh / hard of hearing” or “ows / original sound with subtitle in local language”. You may define different subtitle types than the ones in the picture.
The “subtitle language” defines the language of every subtitle file stored in a database record.
The subtitle file is identified by specifying the “subtitle type” and “subtitle language” combination. It is not possible to store two subtitle files with the same combination of “subtitle type” and “subtitle language” into one database record.
When defining the “subtitle type” list and “subtitle language” list for the first time, all existing subtitle files in the subtitle database will automatically be assigned to the first value in the list.
Web server settings
-
Enable Web server, optionally configure SSL and optionally configure users
-
To enable REST API to write into the database make sure to select the checkbox “Allow writing into database”
REST API Functions for Reading Subtitle Record List
GET /api/list
HTTP GET ip:port/api/list?channels=ch1,ch2&start=20230116T000000&end=20230116T030000
HTTP GET ip:port/api/list?channels=ch1,ch2&start=-080000&end=*080000
Above requests return the list of all database records for channels with the name ch1 and ch2. The first one returns the list for the time interval between 20230116T000000 and 20230116T030000. The second one returns the list between now-8h and now+8h.
It is possible to add &description=sometext which will only return records which contain the text “sometext” in the description field.
Reply Body
{
"@version": "3",
"Playlist": [
{
"@network": "ch1",
"@start": "2023-01-16T00:00:00.000",
"@end": "2023-01-16T03:00:00.999",
"Item": [
{
"@itemversion": "40",
"PlaylistID": "214171",
"DateTime": "2023-01-16T00:33:29",
"AutomationID": "F0310693",
"UniqueID": "65597B77-6C50-4D25-87DE-109DBCD1FCEC",
"InternalID": "123456781",
"Description": "Inspector Barnaby",
"Duration": "01:27:58",
"Created": {
"Time": "2022-12-07T09:20:12",
"User": "admin"
},
"Modified": {
"Time": "2023-07-10T10:46:10",
"User": "admin"
},
"Deleted": "0",
"SubtitleFiles": {
"File": [
{
"@fileversion": "12",
"@lang": "deu",
"@type": "hoh",
"Text": "F0310693_deut_Inspector_Barnaby_Die_Voegel_180115.stl"
}]
}
},{
"@itemversion": "17",
"PlaylistID": "214172",
"DateTime": "2023-01-16T02:02:22",
"AutomationID": "F1022057",
"UniqueID": "36567BD9-A42D-4E1D-9627-109DBCD0B3BB",
"InternalID": "123456782",
"Description": "Hanna Svensson - Blutsbande (3)",
"Duration": "00:57:59",
"Created": {
"Time": "2022-12-07T09:20:12",
"User": "admin"
},
"Modified": {
"Time": "2023-07-10T10:46:10",
"User": "admin"
},
"Deleted": "0",
"SubtitleFiles": {
"File": [
{
"@fileversion": "5",
"@lang": "deu",
"@type": "hoh",
"Text": "103_hoh_deu_Hanna Svensson.stl"
}]
}
}]
},{
"@network": "ch2",
"@start": "2023-01-16T00:00:00.000",
"@end": "2023-01-16T03:00:00.999",
"Item": [
{
"@itemversion": "191",
"PlaylistID": "214580",
"DateTime": "2023-01-16T00:31:22",
"AutomationID": "F1032106",
"UniqueID": "13160DBE-4EDF-4896-AC2D-1305C7594F6F",
"InternalID": "123456783",
"Description": "Große Mythen aufgedeckt: Das Nibelungenlied",
"Duration": "00:43:33",
"Created": {
"Time": "2022-12-13T14:17:09",
"User": "admin"
},
"Modified": {
"Time": "2023-07-10T10:46:19",
"User": "admin"
},
"Deleted": "0",
"SubtitleFiles": {
"File": [
{
"@fileversion": "24",
"@lang": "deu",
"@type": "hoh",
"Text": "F1032106_hoh_deu_Terra_X_Das_Nibelungenlied_12122021.stl"
}]
}
},{
"@itemversion": "174",
"PlaylistID": "214581",
"DateTime": "2023-01-16T01:16:05",
"AutomationID": "F1032637",
"UniqueID": "871E2D16-3B76-4E78-BBC5-1305C7A361C6",
"InternalID": "123456784",
"Description": "Große Mythen aufgedeckt: Das Rätsel um König Artus",
"Duration": "00:43:33",
"Created": {
"Time": "2022-12-13T14:17:09",
"User": "admin"
},
"Modified": {
"Time": "2023-07-10T10:46:19",
"User": "admin"
},
"Deleted": "0",
"SubtitleFiles": {
"File": [
{
"@fileversion": "22",
"@lang": "deu",
"@type": "hoh",
"Text": "F1032637_hoh_deu_Terra_X_Das_Raetsel_um_Koenig_Artus_191221.stl"
}]
}
},{
"@itemversion": "212",
"PlaylistID": "214582",
"DateTime": "2023-01-16T01:59:58",
"AutomationID": "F1021834",
"UniqueID": "A7470A07-7403-4EA7-8FAD-13123EF36A57",
"InternalID": "123456785",
"Description": "Mythos Burg (1/2)",
"Duration": "00:43:29",
"Created": {
"Time": "2022-12-13T14:17:10",
"User": "admin"
},
"Modified": {
"Time": "2023-07-10T10:46:19",
"User": "admin"
},
"Deleted": "0",
"SubtitleFiles": {
"File": [
{
"@fileversion": "41",
"@lang": "deu",
"@type": "hoh",
"Text": "F1021834_hoh_deu_TerraX_Mythos_Burg_180819.stl"
}]
}
},{
"@itemversion": "124",
"PlaylistID": "214583",
"DateTime": "2023-01-16T02:43:47",
"AutomationID": "F1021835",
"UniqueID": "444AD890-362B-4C3F-8B40-13123EF39E9F",
"InternalID": "123456786",
"Description": "Mythos Burg (2/2)",
"Duration": "00:43:35",
"Created": {
"Time": "2022-12-13T14:17:10",
"User": "admin"
},
"Modified": {
"Time": "2023-07-10T10:46:19",
"User": "admin"
},
"Deleted": "0",
"SubtitleFiles": {
"File": [
{
"@fileversion": "40",
"@lang": "deu",
"@type": "hoh",
"Text": "F1021835_hoh_deu_TerraX_Mythos_Burg_Bollwerk_der_Macht_250819.stl"
}]
}
}]
}]
}
REST API Functions for Reading/Writing Subtitle Records
GET /api/record
HTTP GET ip:port/api/record?internalid=123456781
HTTP GET ip:port/api/record?uniqueid=E00D985B-304E-4211-B8DA-1382829B4591
The above requests return the content of the subtitle database record with the specified InternalID or UniqueID. Every database record is identified by an InternalID and optionally Unique ID so that it is guaranteed that only one record will be returned, if it exists.
Reply Body
{
"@version": "3",
"Item": {
"@itemversion": "47",
"Network": "ZDF",
"PlaylistID": "267647",
"DateTime": "2024-07-04T16:13:23",
"AutomationID": "F1020665",
"UniqueID": "E00D985B-304E-4211-B8DA-1382829B4591",
"InternalID": "123456781",
"AnmeldungsID": "DE157FC7-E85E-4503-8598-17389078CE12",
"Description": "Die Rosenheim-Cops",
"Duration": "00:25:01",
"Created": {
"Time": "2024-05-24T04:21:29",
"User": "admin"
},
"Modified": {
"Time": "2025-02-13T10:39:39",
"User": ""
},
"Deleted": "0",
"SubtitleFiles": {
"File": []
}
}
}
POST /api/record
HTTP POST ip:port/api/record?internalid=123456781
HTTP POST ip:port/api/record?uniqueid=E00D985B-304E-4211-B8DA-1382829B4591
The above request stores the content provided in the Body as displayed below into the pre-existing subtitle database record with the specified InternalID or UniqueID.
When ?internalid= and ?uniqueid= is not specified, the record is added into the database and the database generates a new InternalID which is returned in the Return Body. The UniqueID can be provided in the Request Body.
Note that the list of subtitle files is not included in the record in the request body. Subtitle files can not and must not be included in the request body. If the record exists, all subtitle files are preserved. To add/replace/delete subtitle files use the functions for reading/writing subtitle files as described below.
Request Body
{
"@version": "3",
"Item": {
"Network": "ch1",
"DateTime": "2024-07-04T16:13:23",
"AutomationID": "F1020665",
"UniqueID": "E00D985B-304E-4211-B8DA-1382829B4591",
"InternalID": "123456781",
"Description": "Die Rosenheim-Cops",
"Duration": "00:25:01",
"Deleted": "0"
}
}
Reply Body
The reply body is the same as in GET /api/record.
DELETE /api/record
HTTP DELETE ip:port/api/record?internalid=123456781
HTTP DELETE ip:port/api/record?uniqueid=0B3F14DD-E653-4916-AE84-0A5CAF4F6F42
The above request deletes the database record with the Unique ID E00D985B-304E-4211-B8DA-1382829B4591 if it exists.
REST API Functions for Reading/Writing Subtitle Files
GET /api/subtitlefile
HTTP GET ip:port/api/subtitlefile?internalid=123456781&lang=eng&type=hoh
HTTP GET ip:port/api/subtitlefile?uniqueid=0852468C-A058-4984-AFA2-0CAD848B8C31&lang=eng&type=hoh
The above request reads the content of the subtitle file with lang=eng and type=hoh from the record with the specified InternalID or UniqueID.
Reply Body
The reply body will be of Content-Type: application/octet-stream and will contain the subtitle file that is stored in the database record. When the file is in STL file format the start of the content will be similar to:
850STL25.0120008 61B1F790 161012161013 1835 327 1 40231000000000959550011DEU
POST /api/subtitlefile
HTTP POST ip:port/api/subtitlefile?internalid=123456781&lang=eng&type=hoh
HTTP POST ip:port/api/subtitlefile?uniqueid=0852468C-A058-4984-AFA2-0CAD848B8C31&lang=eng&type=hoh
The above request writes the content of the subtitle file provided in the Request Body into the record with the specified InternalID or UniqueID and the file will be stored with lang=eng and type=hoh. If the file with lang=eng and type=hoh exists, it will be overwritten.
Request Body
The request body must be of Content-Type: application/octet-stream and must contain the subtitle file that will be stored in the database record.
To get a sample of the request body the easiest is to analyze the reply body of GET /api/subtitlefile.
DELETE /api/subtitlefile
HTTP DELETE ip:port/api/subtitlefile?internalid=123456781&lang=eng&type=hoh
HTTP DELETE ip:port/api/subtitlefile?uniqueid=0852468C-A058-4984-AFA2-0CAD848B8C31&lang=eng&type=hoh
The above request deletes the subtitle file with lang=eng and type=hoh from the record with the specified InternalID or UniqueID.
This page was last updated on 2025-02-21