Creates a StreamLink object that has the supplied StreamLink configuration settings.
Description
The configuration format is JSON, which can contain the following attributes:
Attribute name
Type
Default
Optional
Description
liberator_urls
string or [string] or [[string]] or function() -> string
None
No
The Liberator URL groups to connect to (see below), or a function to return the next Liberator URL to try.
keymaster_url
string
None (KeyMaster not used)
Yes
URL of KeyMaster for secure authentication of Liberator login requests.
keymaster_poll_url
string
None (KeyMaster not used)
Yes
URL that StreamLink uses to check the connection to KeyMaster every
keymaster_poll_interval milliseconds.
keymaster_poll_interval
number
60000 milliseconds (1 minute)
Yes
Interval in milliseconds at which StreamLink will poll KeyMaster
(on keymaster_poll_url) to keep the KeyMaster session open.
keymaster_poll_response_listener
KeymasterResponseListener
None
Yes
The implementation of the KeymasterResponseListener interface.
This receives information about responses to keep-alive requests made to KeyMaster.
keymaster_token_transport_method
string
POST
Yes
WARNING: We strongly recommend that you do not set this attribute to GET for security concerns. This attribute sets the transport method that Keymaster will use to request the Keymaster token, can be set to either GET or POST.
keymaster_token_transport_method_poll
string
POST
Yes
WARNING: We strongly recommend that you do not set this attribute to GET for security concerns. This attribute sets the transport method that Keymaster will use to poll the Keymaster token, can be set to either GET or POST.
keymaster_cross_domain_authentication
boolean
false
Yes
Enable cross-site (CORS) XMLHttpRequest invocations for keymaster requests. The server must
be CORS enabled and include the Access-Control-Allow-Credentials: true http header.
credentials_provider
CredentialsProvider
None
Yes
The implementation of the CredentialsProvider interface.
This custom Credentials Provider that will be used to send credentials to log into Liberator.
username
string
None
Yes
Liberator login user-name to use if logins are not being managed by KeyMaster.
password
string
None
Yes
Liberator login password to use if logins are not being managed by KeyMaster.
application_id
string
None
Yes
Application identifier. This is used by the Caplin Platform to distinguish StreamLink requests from
different client applications. It is recorded in StreamLink log files, and is used by Liberator in monitoring
software licence compliance and by the Caplin Permissioning Service to restrict the applicability of
permissioning rules to specific applications.
poll_interval
number
1000 milliseconds (1 second)
Yes
Time interval in milliseconds between polls of the Liberator.
This only applies to HTTP polling type connections
(see 'RTTP connection types' in the document StreamLink Overview).
disable_polling
boolean
false
Yes
Set to true if you don't want to use polling connection when the rttp(s) protocol is specified.
disable_sse_connection
boolean
false
Yes
Set to true if you don't want to use server sent events connection when the rttp(s) protocol is specified.
forever_frame_reconnect_count
number
10000
Yes
After receiving this number of messages, a forever frame connection will perform a fast reconnect
to prevent memory leaks.
reconnect_delay
number
1000 milliseconds (1 second)
Yes
Delay in milliseconds before retrying, after failing to connect.
reconnect_cycle_delay
number
2000, 4000, 8000, 16000
Yes
Array of backoff delays in milliseconds before retrying, after failing to connect with all available connection options.
The entries are treated as a backoff where each entry is used once and the last entry is the delay that will
keep getting used forever
request_timeout
number
10000 milliseconds (10 seconds)
Yes
Time in milliseconds allowed for the response to each request before StreamLink reconnects to the Liberator.
http_timeout
number
3000 milliseconds (3 seconds)
Yes
Time in milliseconds allowed for an HTTP Request to finish successfully before StreamLink times out.
http_pad_length
number
4096 bytes
Yes
The amount of padding to use when establishing a streaming connection using the http(s):// connection type. Increasing
this value can help should there be a buffering network component between the client and the Liberator.
clock_offset_interval
number
10000 milliseconds (10 seconds)
Yes
StreamLink calculates a new clock offset value every clock_offset_interval milliseconds.
The clock offset is Liberator time minus StreamLink time; it is a measure of how much the Liberator
and client clocks differ and is used in the calculation of latency statistics, such as average latency
(see the latency_interval attribute). Also see StatisticsEvent.getClockOffset().
clock_offset_window
number
120000 milliseconds (2 minutes)
Yes
Time in milliseconds a calculated clock offset is valid for use in producing statistics. For the definition
of clock offset, see the clock_offset_interval attribute. You should not normally need to change
this attribute; if you think it needs to be changed, please contact Caplin Support for advice.
latency_interval
number
10000 milliseconds (10 seconds)
Yes
Time in milliseconds between successive calculations of average latency.
Latency is the time taken for a StreamLink heartbeat message to be sent from the Liberator to the client.
The shorter the latency_interval, the more accurate are the average latency statistics.
However, too small a value can adversely impact performance.
latency_window
number
120000 milliseconds (2 minutes)
Yes
Time in milliseconds for which a calculated latency value is valid for use in producing latency statistics.
The shorter the time, the faster changes in average latency will show up in the statistics. However, too small
a value can result in the average varying in a way that makes it hard to see trends.
log_window_log_level
LogLevel
LogLevel.FINE
Yes
When the debug log window is shown, (see log_window_visible), only messages
at or above the log level defined by log_window_log_level appear in the window.
log_window_visible
boolean
none
Yes
When true, the debug log window is shown when StreamLink first connects.
When false, the debug log window cannot be shown.
When left undefined the debug window can be shown if the page url contains a fragment of the form
?debug=[LogLevel name].
inactivity_timeout
number
-1 (disabled)
No
Set the duration (in milliseconds) that Liberator will use to disconnect this client should no
messages have been received from StreamLink
log_buffer_size
number
-1 (disabled)
Yes
Sets the number of log lines to be cached in the log buffer.
webworker_timer_url
string
None
Yes
Sets the url location of the webworker js code used to prevent throttling of background timers.
clientside_refiner_enable
boolean
false
Yes
Enables clientside Refiner for all sorted/filtered containers, to specify which containers are refined client/server use the
clientside_refiner_fn_use_for callback function.
clientside_refiner_fn_use_for
function
always refine on the client
Yes
If clientside_refiner_enable is true this function will be called to determine if a particular container subscription should be refined on
the client or server. The signature of the function is (subject :String, parameters: SubscriptionParameters) => boolean, returning true will refine on the client.
clientside_refiner_custom_sorts
object
none
Yes
A Javascript object containing a mapping between custom sort names and their functions. For example {tenorSort: tenorSortFunction} where
tenorSortFunction is a comparator function of the form (a,b) => number, number should be -1, 0, 1 for a<b, a==b, a>b
clientside_refiner_custom_filters
object
none
Yes
A Javascript object containing a mapping between custom filter names and their functions. For example {evennumbers: evenNumberFunction}.
The mapped functions can be of 2 forms, 1: a comparator like the custom sort functions in clientside_refiner_custom_sorts,
2: a simple function of the form (fieldProvider) => boolean, where fieldProvider is an object with a single method, getField(fieldName) for retrieving a field from
the record being filtered. If the filter expression is of the form where:customFilterName:<fieldname>:<operator>:<value> (e.g where:tenorFilter:FIELD1<1m) then
the filter is expected to be of type 1 (a comparator), if however the filter expression is of the form where:evennumbers then the filter is expected to be of type 2 (a simple filter).
fetch_credentials
string
None
Yes
Sets the credentials option on connections using an underlying Fetch request.
Possible values are: "omit", "same-origin", "include" (see: https://developer.mozilla.org/en-US/docs/Web/API/Request/credentials).
sse_with_credentials
boolean
None
Yes
If set to true will include the 'credentials: "include"' parameter on underlying server-sent events connection requests.
Failover configuration using liberator_urls.
The liberator_urls configuration attribute defines the Liberator URL groups to connect
to in failover situations. A URL group is selected at random and StreamLink tries to
connect to the URLs in the group sequentially. If StreamLink fails to connect to
any of the URLs in a group, the next group is tried, and so on.
For more information about how to configure a failover strategy for StreamLink,
see the "Resilience, failover, and load balancing" section of the StreamLink Overview.
Each URL specified must include the protocol; one of: rttp, rttps,
http, https, ws, wss, poll, polls.
The protocol rttp means use the best non-ssl supported protocols (in the order: ws, http, poll).
The protocol rttps means use the best ssl supported protocols (in the order: wss, https, polls).
Examples:
The following example shows the JSON configuration to connect to a single Liberator instance running on the
host liberator1 on port 8080. The credentials to login to the Liberator are
specified using the username and password attributes.
StreamLinkFactory.create({
"liberator_urls": "rttp://liberator1:8080",
"username": "test@example.com",
"password": "my password"
});
The following example shows the JSON configuration for failover between two
Liberator pairs. The credentials to login to the Liberator are
specified using the username and password attributes.
liberator_urls can alternatively return a function that will return the next Liberator URL to try connecting to, this can be
used to dynamically control the Liberator sequence:
var index = -1;
var fixedLiberators = ["rttp://liberator1:8080", "rttp://liberator2:8080"];
StreamLinkFactory.create({
"liberator_urls": function(){
index = (++index) % fixedLiberators.length;
return fixedLiberators[index];
},
"username": "test@example.com",
"password": "my password"
});
Creates a StreamLink object that has the supplied StreamLink configuration settings.
Description
The configuration format is JSON, which can contain the following attributes:
keymaster_poll_interval
milliseconds.(1 minute)
keymaster_poll_url
) to keep the KeyMaster session open.(1 second)
(1 second)
(10 seconds)
(3 seconds)
(10 seconds)
clock_offset_interval
milliseconds. The clock offset is Liberator time minus StreamLink time; it is a measure of how much the Liberator and client clocks differ and is used in the calculation of latency statistics, such as average latency (see the latency_interval attribute). Also seeStatisticsEvent.getClockOffset()
.(2 minutes)
clock_offset_interval
attribute. You should not normally need to change this attribute; if you think it needs to be changed, please contact Caplin Support for advice.(10 seconds)
latency_interval
, the more accurate are the average latency statistics. However, too small a value can adversely impact performance.(2 minutes)
When false, the debug log window cannot be shown.
When left undefined the debug window can be shown if the page url contains a fragment of the form
?debug=[LogLevel name]
.Failover configuration using liberator_urls.
The
liberator_urls
configuration attribute defines the Liberator URL groups to connect to in failover situations. A URL group is selected at random and StreamLink tries to connect to the URLs in the group sequentially. If StreamLink fails to connect to any of the URLs in a group, the next group is tried, and so on.For more information about how to configure a failover strategy for StreamLink, see the "Resilience, failover, and load balancing" section of the StreamLink Overview.
Each URL specified must include the protocol; one of: rttp, rttps, http, https, ws, wss, poll, polls.
Examples:
The following example shows the JSON configuration to connect to a single Liberator instance running on the host
liberator1
on port 8080. The credentials to login to the Liberator are specified using theusername
andpassword
attributes.The following example shows the JSON configuration for failover between two Liberator pairs. The credentials to login to the Liberator are specified using the
username
andpassword
attributes.liberator_urls can alternatively return a function that will return the next Liberator URL to try connecting to, this can be used to dynamically control the Liberator sequence:
Function