Studio OVP Connectors

An Online Video Platform (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 then returns 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, stream key, playback URL). Web stream and 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 the responses from Studio:

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 from the OVP Service and the OVP Service returns a status of PASS indicating that the stream is up and running.
WARN	The stream is possibly in a degraded state.	Studio requests a stream health check from the OVP Service, the OVP Service returns a 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 check; the OVP Service is not configured to properly fulfill any requests. (Missing page, missing information that cannot be found on a recovery, OVP API Down, etc.)

OVP Broadcast Monitoring and Recovery 

Studio can be used to create and manage MILE broadcasts that last for multiple days or even weeks. 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. The Broadcast Monitoring and Recovery section is 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 in 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 stream key in the Genvid Settings page. If any of those are missing, Studio will automatically contact the service’s OVP Connector to populate the address, channel, and stream key before starting a new broadcast.

Activate OVP Autoconfigure: To activate the OVP Autoconfigure process, you must first enable (set to true) the Composition and Broadcast services from 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 settings page have been read and updated. This includes monitoring and 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 and 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.	Studio 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 will stop monitoring.
Recovery step: Status=done Step=Request recovery from OVP.	The 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.	The 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 https://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 