Package com.caplin.streamlink

Class StreamLinkFactory

java.lang.Object
com.caplin.streamlink.StreamLinkFactory
public class StreamLinkFactory extends Object

Factory that creates StreamLink instances.

You create and configure the StreamLink instance by calling one of the create() methods on this factory. The configuration settings are supplied in one of two ways, depending on which particular create() method is called:

  • Pass in a StreamLinkConfiguration object.
  • Pass in a JSON format configuration string. This facility is provided for compatibility with StreamLinkJS and StreamLink iOS.

The configuration format is JSON, which can contain the following attributes:

Attribute name Type Default Optional Description
liberator_urls string, [string], [[string]] None No The Liberator URL groups to connect to (see below).
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.
keymaster_url string None (KeyMaster not used) Yes URL of KeyMaster for secure authentication of Liberator login requests. In order to satisfy any HTTP requests you will need to implement the standard Java Authenticator interface. Details of how to do this can be found on the Oracle WebSite.
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 600000 milliseconds
(10 minutes)		 Yes Interval in milliseconds at which StreamLink will poll KeyMaster (on keymaster_poll_url) to keep the KeyMaster session open.
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).
clock_offset_interval number 10000 milliseconds
(10 seconds)		 Yes StreamLink calculates a new clock offset value every clock_offset_interval millseconds. 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.
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.
inactivity_timeout number -1 (disabled) Yes 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.
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.
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.
reconnect_delay number 1000 milliseconds
(1 second)		 Yes Delay in milliseconds before retrying, after failing to connect.
reconnect_attempts number 0 Yes Sets the number of times that Streamlink should retry a connection attempt for each connection type (eg. ws, https, poll etc.) Defaults to 0 i.e. only one connection attempt is made per connection type.
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
application_id string None Yes Application identifier. This is useful for tracing purposes and managing licensing requirements.
custom_attributes map None Yes A set of custom attributes provided in JSON object format (key-value pairs). These are used to annotate connections made using this StreamLink instance with any other useful identifying information. The attributes are recorded in the Liberator's RTTP request and traffic logs when the connection is established.
json_handler object None Yes Sets a JsonHandler that will be used to parse and patch Java objects.

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, tcp, tcps.

  • 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.

{
     "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": [
       ["rttp://liberator1:8080", "rttp://liberator2:8080"],
       ["rttp://liberator3:8080", "rttp://liberator4:8080"]
     ],
    "username": "test@example.com",
    "password": "my password"
 }

  • Method Details

    • create

      public static StreamLink create(String configuration)

      Creates a new StreamLink instance from the supplied JSON configuration.

      Parameters:
      configuration - A JSON configuration string.
      Returns:
      A new StreamLink instance.
      Throws:
      IllegalArgumentException - The configuration is invalid.

    • create

      public static StreamLink create(String configuration, KeymasterPollResponseListener listener)

      Creates a new StreamLink instance from the supplied JSON configuration.

      Parameters:
      configuration - A JSON configuration string.
      listener - The listener that receives the result of KeyMaster poll requests.
      Returns:
      A new StreamLink instance.
      Throws:
      IllegalArgumentException - The configuration is invalid.

    • create

      public static StreamLink create(String configuration, String username, String password)

      Creates a new StreamLink instance from the supplied configuration and username/password credentials.

      The configuration argument to this method can take the following forms:

      • A URI of the form protocol://liberator:port where protocol can be one of: tcp, tcps, ws, wss, http, https, rttp, rttps
      • A JSON array of failover Liberator addresses: [ [ "protocol://host1", "protocol://host2" ], ["protocol://host3", "protocol://host4" ] ]
      • A JSON configuration object, for example: { "liberator_urls" : [ [ "protocol://host1", "protocol://host2" ], ["protocol://host3", "protocol://host4" ] ] }. If you supply a configuration object, it can contain any of the configuration attributes defined in the table above, in addition to the failover configuration.
      Parameters:
      configuration - A Liberator connection URI, or Liberator connection and failover information in JSON format, or a JSON configuration object.
      username - The username to log in as.
      password - The password associated with the username.
      Returns:
      A new StreamLink instance.
      Throws:
      IllegalArgumentException - The configuration is invalid.

    • create

      public static StreamLink create(String configuration, CredentialsProvider credentialsProvider)

      Creates a new StreamLink instance from the supplied configuration and CredentialsProvider.

      The configuration argument to this method can take the following forms:

      • A URI of the form protocol://liberator:port where protocol can be one of: tcp, tcps, ws, wss, http, https, rttp, rttps
      • A JSON array of failover Liberator addresses: [ [ "protocol://host1", "protocol://host2" ], ["protocol://host3", "protocol://host4" ] ]
      • A JSON configuration object, for example: { "liberator_urls" : [ [ "protocol://host1", "protocol://host2" ], ["protocol://host3", "protocol://host4" ] ] }. If you supply a configuration object, it can contain any of the configuration attributes defined in the table above, in addition to the failover configuration.
      Parameters:
      configuration - A Liberator connection URI, or Liberator connection and failover information in JSON format, or a JSON configuration object.
      credentialsProvider - Your custom implementation of the CredentialsProvider interface.
      Returns:
      A new StreamLink instance.
      Throws:
      IllegalArgumentException - The configuration is invalid.

    • create

      public static StreamLink create(StreamLinkConfiguration configuration)

      Creates a new StreamLink instance with the supplied StreamLinkConfiguration object.

      Parameters:
      configuration - Configuration for this StreamLink instance.
      Returns:
      A new StreamLink instance.

    • create

      public static StreamLink create(StreamLinkConfiguration configuration, CredentialsProvider credentialsProvider)

      Creates a new StreamLink instance with the supplied StreamLinkConfiguration object and CredentialsProvider.

      Parameters:
      configuration - Configuration for this StreamLink instance.
      credentialsProvider - Your implementation of the CredentialsProvider interface.
      Returns:
      A new StreamLink instance.

    • createConfiguration

      public static StreamLinkConfiguration createConfiguration()

      Creates a new StreamLinkConfiguration object that can be used to configure StreamLink.

      Returns:
      A new StreamLinkConfiguration instance.

    • createConfiguration

      public static StreamLinkConfiguration createConfiguration(String configuration)

      Creates a new StreamLinkConfiguration object that can be used to configure StreamLink. It will be populated with the values obtained from the supplied configuration string.

      The configuration argument to this method can take the following forms:

      • A URI of the form protocol://liberator:port where protocol can be one of: tcp, tcps, ws, wss, http, https, rttp, rttps
      • A JSON array of failover Liberator addresses: [ [ "protocol://host1", "protocol://host2" ], ["protocol://host3", "protocol://host4" ] ]
      • A JSON configuration object, for example: { "liberator_urls" : [ [ "protocol://host1", "protocol://host2" ], ["protocol://host3", "protocol://host4" ] ] }. If you supply a configuration object, it can contain any of the configuration attributes defined in the table above, in addition to the failover configuration.
      Parameters:
      configuration - A Liberator connection URI, or Liberator connection and failover information in JSON format, or a JSON configuration object.
      Returns:
      A new StreamLinkConfiguration instance with values populated from the supplied configuration string.