/

API Basics

API Basics, to get you started


(for full API, see Red5 Pro Stream Manager API)

For the POST calls, we recommend using a tool like Postman.

Verify Stream Manager is Using the Correct Controller

GET call:

https://<streammanager_URL>/streammanager/api/4.0/admin/debug/cloudcontroller?accessToken=<rest.administratorToken>

should return: Google Compute

Create a Scale Policy (post)

  • Make sure to include a role section for each node type you want to include (origin, edge, relay, transcoder):

POST call:

https://<streammanager_URL>/streammanager/api/4.0/admin/configurations/scalepolicy?accessToken=<rest.administratorToken>

Data (make sure to select JSON as the body type):

   {
  "policy": {
          "name": "<policy-name>",
          "description": "<policy-description>>",
          "type": "<policy-type>",
          "version": "<policy-version>",
          "targets": {
              "region": [
                  {
                      "name": "default",
                      "target": [
        {
          "role": "<role>",
          "minLimit": "<min-node-count>",
          "maxLimit": "<max-node-count>",
          "scaleAdjustment": "<node-scale-adjustment>"
        }
      ]
    }
    }}

Create a Launch Policy (post)

For ease of administration, we recommend naming the policy something easily identifiable and descriptive, such as <imagename>-<nodetypes> (e.g., red5pro6.4.0-allnodetypes)

POST call:

https://<streammanager_URL>/streammanager/api/4.0/admin/configurations/launchconfig?accessToken=<rest.administratorToken>

Data (make sure to select JSON as the body type):

   {
    "launchconfig": {
      "name": "<configuration-name>",
      "description": "<configuration-descrption>",
      "image": "<red5pro-image>",
      "version": "0.0.3",

    "targets": {
        "target": [
      {
        "role": "<role>",
        "instanceType": "<instance-type>",
        "connectionCapacity": "<instance-capacity>"
      }
      ]
      },

      "properties": {
        "property": [
          {
            "name": "<property-name>",
            "value": "<property-value>"
          }
        ]
      },
      "metadata": {
        "meta": [
          {
            "key": "<meta-name>",
            "value": "<meta-value>"
          }
        ]
      }
    }}

Create a New Node Group (post)

POST call:

https://<streammanager_URL>/streammanager/api/4.0/admin/nodegroup?accessToken=<rest.administratorToken>

Data (make sure to select JSON as the body type):

{
 "regions": [
   "<region, eg: us-west2>"
 ],
 "launchConfig": "<launchconfig-created-above>",
 "scalePolicy": "<scaleconfig-created-above>"
}

Note the cluster “name” that is returned by the above call. It will be used to create a new Origin server.

Launch New Origin (post)

After you create a node group, create the origin server. Creating an origin server will also generate at least one edge, per scaling policy min limit.

https://<streammanager_URL>/streammanager/api/4.0/admin/nodegroup/<cluster-name>/node/origin?accessToken=<rest.administratorToken from red5-web.properties file>

NOTE: If you wish to launch more than one origin, you can repeat the call. The maximum origins allowed will depend on the maxLimit attribute of the 'origin' object described in scale policy. If 'origin' is omitted from the scale policy then the default value for maximum origins is 1.

Set Alarm Threshold (POST)

By default, the alarm threshold (the capacity percentage at which the cluster will scale up any given node type) is set to 60%. To modify this, POST the following:

FOR EDGE:

FOR ORIGIN:

https://<streammanager_URL>/streammanager/api/4.0/admin/alarm/scaleout/default?type=origin&threshold=<threshold>&accessToken=<rest.administratorToken>

FOR RELAY:

https://<streammanager_URL>/streammanager/api/4.0/admin/alarm/scaleout/default?type=relay&threshold=<threshold>&accessToken=<rest.administratorToken>

FOR TRANSCODER:

https://<streammanager_URL>/streammanager/api/4.0/admin/alarm/scaleout/default?type=transcoder&threshold=<threshold>&accessToken=<rest.administratorToken>

LIST GROUPS (get)

https://<streammanager_URL>/streammanager/api/4.0/admin/nodegroup?accessToken=<rest.administratorToken from red5-web.properties file>

Stream Manager Publish and Subscribe Examples

Stream Manager Proxy Publish and Subscribe Examples

With the latest release, the live webapp includes two examples: proxy-publisher.html and proxy-subscriber.html. These examples will take the following query parameters:

NameDescriptionDefault Value
hosthostname or IPwindow.location.hostname
protocolprotocol which Stream Manager is served over (http or https)window.location.protocol
portport number that Stream Maager is served onwindow.location.port
appwebapp name to stream to on the serverlive
streamNameThe unique stream name to broadcast with or subscribe toNone. Required
verboseFlag to enable verbose logging in Dev ConsoleNone. optional
viewTarget broadcast tech (rtc, rtmp or hls)None. Optional

Example URI:

https://streammanager.test.com/live/proxy-publisher.html?streamName=stream1&verbose=1

Red5 Pro HTML5 SDK Examples:

Stream Manager examples

Note: the streaming-html5 examples testbed is included with the Red5 Pro server distribution, and can be accessed via your stream manager at https://your.server.url/webrtcexamples/.

Red5 Pro iOS SDK Examples:

Publish - Stream Manager

Subscribe - Stream Manager

Red5 Pro Android SDK Examples:

Publish - Stream Manager

Subscribe - Stream Manager

Compute VM Startup Scripts for Automation

Google compute allows the provisioning of shell scripts that can be executed on a VM as soon as it is initialized. This can be very useful in automating configuration tasks for dynamically scaled compute instances.

Sample Use Cases:

  • Use a shell script to update the cloudwatch url property in the autoscale.xml during instance launch.
  • Use a shell script to configure the various Red5 Pro attributes on the fly dynamically as the instance is being started.
  • Install NFS, mount your file share and set access permissions on an autoscaled node.

While these are just samples of use cases, you can have your shell script do almost any kind of changes on the instance.

Providing Startup Script to Autoscaled Nodes

Since its the Stream Manager which is responsible for launching Red5 Pro instances on the GCP, we need to configure Stream Manager to initialize Startup Script on nodes.

The way this is done is by using the launch configuration schema. The launch configuration allows us to specify a list of MetaData items. These items are added to the instance as a part of its metadata. Google cloud compute, uses special metadata by name startup-script-url to attach a shell script to the VM.

The URL points to a publically accessible shell script resource. During the VM startup, the script will be downloaded from the location and run on the instance. A common usage pattern is to place the script in your Google storage bucket by your project ID. Example: gs://" + PROJECT_ID + "/vm-startup.sh.

For more information on startup scripts checkout the official GCP documentation.