Studio OVP Connectors

An Online Video Player (OVP) Connector is a service that transparently establishes communication and manages API calls and responses between Studio and an OVP. Studio makes API calls to the OVP Connector which then makes API calls to the OVP to then return the results to Studio. The OVP Connector changes the arguments passed, and handles or redirects operations as needed. This behavior is consistent for all OVPs.

We currently support the following OVP Connectors:

YouTube Connector
Twitch Connector

OVP Stream Health Status 

The stream health status is a core feature of the OVP Connector. Studio constantly monitors the stream’s health and determines which measures it will take to ensure the stream stays up and running for as long as needed, and that recovery is executed whenever it is necessary and technically feasible.

During a broadcast, Studio will constantly request the stream health status from the OVP Connector. If the stream is not healthy, Studio will call the OVP Connector to request a new stream, then update the stream’s Studio configuration (ingest address, the stream key, playback url). Web stream/overlay viewers will then be seamlessly switched to the new playback url.

Below are possible stream health status field values along with a description of Studio’s response:

Status	Definition	Example
PASS	Studio requests a health check from the OVP service and no issues are reported. The system continues its operation.	Studio requests a stream health check form the OVP Service, the OVP Service returns a status PASS indicating that it is up and running.
WARN	The stream is possibly in a degraded state.	Studio requests a stream health check form the OVP Service, the OVP Service returns the WARN because an issue has been detected on its end. Studio will then check again. If the stream’s health is not reestablished, Studio will initiate a recovery.
FAIL	The stream is not functioning, Studio must immediately stop the monitoring/recovery process.	Studio requests a stream health, the OVP Service is not configured to properly fulfill any requests (missing arn, missing page, missing information that cannot be found on a recovery, OVP API Down…)

OVP Broadcast Monitoring and Recovery 

Studio can be used to create and manage MILE broadcasts that last multiple days or even weeks. To do so it has features allowing it to monitor the current stream health and to restart streaming when necessary by creating a new stream.

Note

This Monitoring and Recovery feature is available for all supported Online Video Platforms (OVP).

To enable Broadcast Monitoring and Recovery, go to the Cluster-UI Genvid Settings page, there’s a section called Broadcast Monitoring and Recovery from where you can enable and configure broadcast monitoring frequency. Once Broadcast Monitoring and Recovery are enabled, you can:

Enable the Restarter: If the current stream reports an unhealthy status, Studio will restart the broadcast by creating a new stream.
Set the Restarter Error Threshold: To avoid infinite restart loops, you can set an Error Threshold to determine how many times Studio will try to automatically restart the stream.

Studio OVP Autoconfigure 

OVP Autoconfigure is a process that is automatically launched whenever Studio starts on a cluster. The OVP Autoconfigure process will read the Genvid Settings to determine which OVP service is selected. If the service is not set to standalone, Studio will verify the address, channel and key in the Genvid Settings page. If one of those is empty, Studio will automatically contact the service’s OVP Connector to populate the address, channel and stream key and then start a new broadcast.

Activate OVP Autoconfigure: To activate the OVP Autoconfigure process, you must first enable (set to true) the Composition and Broadcast services (through the Genvid Settings page).
OVP Autoconfigure in Studio Logs: In the Studio logs, you will see “Autoconfigure: Successful” if the process was triggered and executed properly. If the process fails, the log entry will read “Autoconfigure: Unsuccessful”.

Studio OVP Connector Logs 

This section describes the most common Studio log messages concerning OVP Connectors.

Message	Meaning
OVP name is now set to {name}	The broadcast settings will attempt to use the OVP service identified by {name}.
Broadcast Monitoring and Recovery have been updated	Broadcast Monitoring and Recovery on the setting page have been read and updated. This includes monitoring/recovery activation as well as check interval and error threshold settings.
Monitor Routine Status: Broadcast On Air=false In a Recovery Routine=false OVP Service Reachable=false	Indicates the status of the monitoring/recovery routine.
OVP Stream Health: Stream is not ready yet	Studio is waiting for the OVP to initially be healthy before starting the check/recovery pipeline.
OVP Stream Health: Health Status=PASS(WARN, FAIL) OVP Name={ovp_name} message={message}	OVP Stream Status. Refer to the Stream Health Status section of this document.
OVP Stream Health: Health Status=WARN OVP Name=ivs message=Stream degraded, we will proceed with the next step of the pipeline.	will check the encoding or decide to recover immediately based on the options specified in the restarter.
Encoding Stream Health: Service=gvencode message=Continuing monitoring,no action will be taken for now. status=PASS	Encoding Stream Status. Refer to the Stream Health Status section of this document.
Encoding Stream Health: Service=gvencode message=Initiate a recovery… status=WARN	Encoding is not healthy, Studio will initiate the recovery process.
Recovery step: Step=Pause monitoring	Recovery process has started, Studio stops monitoring.
Recovery step: Status=done Step=Request recover from OVP	Recovery process is in progress, Studio requests recovery status from the OVP Service.
Recovery step: Status=done Step=Update broadcast settings with new config	Studio has updated the broadcast settings with the new stream configuration.
Recovery: component checked done, back to monitoring.	Studio checks the initial start of the stream after a recovery and reverts back to monitoring.
Recovery not enabled, back to monitoring	Recovery option has not been enabled, Studio will continue to monitor.

OVP Connector Setup 

Twitch Connector

Twitch Connector is a service that transparently establishes communication and manages API calls and responses between Studio and Twitch to then return the results to Studio. The Twitch Connector changes the arguments passed, and handles or redirects operations as needed.

Requirements

Genvid SDK and Toolbox installed
Twitch Developer Account to setup an application and get credentials

Authentication

The service uses an Oauth 2.0 flow. When the service runs, you can authenticate by accessing the link named “Twitch” in the cluster Jobs page.

If you already have a valid access token with a refresh token, you can enter your token in the “secrets” section of the hcl file:

 secrets {
    twitch_token {
        AccessToken = "YOUR_ACCESS_TOKEN",
        Expiry = "EXPIRY_TIME_OF_TOKEN",
        OvpID = "twitch",
        RefreshToken = "YOUR_REFRESH_TOKEN"
    }
}

Configuration

Create a new environment variable called [TWITCHPROJECTDIR] that points to the root folder where the Twitch OVP Connector folder is, by default GENVID_SDK_FOLDER/ovp-connectors/twitch. For example, in PowerShell, the command would be similar to this:
```
$env:TWITCHPROJECTDIR = {GENVID_SDK_FOLDER}/ovp-connectors/twitch.
```
Open the file GENVID_SDK_FOLDER/ovp-connectors/twitch/config/twitch.hcl.
Fill the fields CLIENT_ID, CLIENT_SECRET with the ones created from your Twitch application.
Fill the field REDIRECT_URL with the URL where the authentication process must return. The REDIRECT_URL must match the following route http{s}://{LOCALHOST or DNS_NAME_TO_YOUR_OVP_CONNECTOR}:{OVP_CONNECTOR_PORT}/auth. This is the route where we will redirect the auth code obtained from the Oauth servers. As a default, the Twitch OVP Connector service will be accessible via the bastion proxy see Cluster API.
When deploying a cluster in the cloud using either basic_cluster_alb_ssl or minimal_cluster_alb_ssl module, make sure to update your twitch.hcl file for proper load balancing and SSL termination configuration:
```
settings {
  leaf {
      port = 30001
  }
}
config {
    embed_ssl {
      enabled = true
  }
}
```

Deployment

Local Cluster

Load your configuration by executing the following command:

genvid-sdk load-config --with-consul-template [TWITCHPROJECTDIR]\config\twitch.hcl --job-template-dir [TWITCHPROJECTDIR]\templates\local\

Start your service.

Cloud Cluster

Upload the ovp-connector docker image to the cluster by executing the following command:
```
genvid-sdk -c {cluster_id} upload-images -u
```

Load your configuration by executing the following command:

genvid-sdk load-config -c {cluster_id} --with-consul-template [TWITCHPROJECTDIR]\config\twitch.hcl --job-template-dir [TWITCHPROJECTDIR]\templates\cloud\

Start your service.

Useful resources

YouTube Connector

YouTube Connector is a service that transparently establishes communication and manages API calls and responses between Studio and YouTube to then return the results to Studio. The YouTube Connector changes the arguments passed, and handles or redirects operations as needed.

Requirements

Genvid SDK and Toolbox installed
Youtube Cloud Console access
YouTube Data API v3 enabled
Valid Client ID and Client Secret to access Youtube Data API v3

Authentication

This service uses an Oauth 2.0 flow. When the service runs, you can authenticate by accessing the link named “YouTube” in the cluster Jobs page.

If you already have a valid access token with a refresh token, you can enter your token in the “secrets” section of the hcl file:

secrets {
   youtube_token {
       AccessToken = "YOUR_ACCESS_TOKEN",
       Expiry = "EXPIRY_TIME_OF_TOKEN",
       OvpID = "youtube",
       RefreshToken = "YOUR_REFRESH_TOKEN"
   }
}

Configuration

Create a new environment variable called [YOUTUBEPROJECTDIR] that points to the root folder where the YouTube OVP Connector folder is, by default GENVID_SDK_FOLDER/ovp-connectors/youtube. For example, in PowerShell, the command would be similar to this:
```
$env:YOUTUBEPROJECTDIR = {GENVID_SDK_FOLDER}/ovp-connectors/youtube.
```
Open the file GENVID_SDK_FOLDER/ovp-connectors/youtube/config/youtube.hcl.
Fill the fields CLIENT_ID, CLIENT_SECRET with the ones created from your YouTube application.
Fill the field REDIRECT_URL with the URL where the authentication process must return. The REDIRECT_URL must match the following route http{s}://{LOCALHOST or DNS_NAME_TO_YOUR_OVP_CONNECTOR}:{OVP_CONNECTOR_PORT}/auth. This is the route where we will redirect the auth code obtained from the Oauth servers. As a default, the YouTube OVP Connector service will be accessible via the bastion proxy see Cluster API.
When deploying a cluster in the cloud using either basic_cluster_alb_ssl or minimal_cluster_alb_ssl module, make sure to update your youtube.hcl file for proper load balancing and SSL termination configuration:
```
settings {
  leaf {
      port = 30001
  }
}
config {
    embed_ssl {
      enabled = true
  }
}
```

Deployment

Local Cluster

Load your configuration by executing the following command:

genvid-sdk load-config --with-consul-template [YOUTUBEPROJECTDIR]\config\youtube.hcl --job-template-dir [YOUTUBEPROJECTDIR]\templates\local\

Start your service.

Cloud Cluster

Upload the ovp-connector docker image to the cluster by executing the following command:
```
genvid-sdk -c {cluster_id} upload-images -u
```

Load your configuration by executing the following command:

genvid-sdk load-config -c {cluster_id} --with-consul-template [YOUTUBEPROJECTDIR]\config\youtube.hcl --job-template-dir [YOUTUBEPROJECTDIR]\templates\cloud\

Start your service.

Useful resources

OVP Logs

OVP logs provide more detailed information concerning any issues with the OVP Connector service or the communication between the OVP API (misconfiguration, authentication errors, api not available, etc.). If an issue is reported by the Studio OVP Connector logs, consult the specific OVP’s logs for more details about the cause of the issue.

Studio OVP Connectors

OVP Stream Health Status

OVP Broadcast Monitoring and Recovery

Studio OVP Autoconfigure

Studio OVP Connector Logs

OVP Connector Setup

Twitch Connector

Requirements

Authentication

Configuration

Deployment

Useful resources

YouTube Connector

Requirements

Authentication

Configuration

Deployment

Useful resources

OVP Logs

OVP Stream Health Status 

OVP Broadcast Monitoring and Recovery 

Studio OVP Autoconfigure 

Studio OVP Connector Logs 

OVP Connector Setup 