Video streaming API tutorial

The Video Streaming API supports full integration workflows, from creating streams and broadcasts through managing status transitions and receiving webhook notifications.

Integration overview

A typical integration exposes a streaming interface to end users. Each user action maps to a Video Streaming API request and a corresponding webhook notification. The following diagram shows the high-level sequence grouped into stages:

Before starting, confirm the following are in place. Each is required for the API calls and webhook delivery in the workflow:

• A Gcore account with an active Streaming subscription — the API endpoints are only accessible with an active subscription
• API authentication configured — all requests require a valid API key
• A webhook endpoint registered to receive event notifications — without it, stream and broadcast status transitions are not delivered to the integration

The Broadcasts API used in this tutorial is deprecated and will be replaced by the Multicamera API. Existing integrations continue to work, but the Multicamera API will eventually replace the broadcast object and the create, status-change, and deletion operations used in this workflow. New integrations should monitor Gcore announcements for the migration path before building on this workflow.

Basic operations

Stage 1. Setup

1. Create a stream

   The Create live stream endpoint (POST /streaming/streams) creates a stream object.

   • To prevent errors due to the quota for concurrent active sessions, set the active property to false.
   • Select the transcoding region based on the user’s location.

   {
       "stream": {
           "name": "test_stream",
           "pull": false,
           "uri": null,
           "active": false,
           "transcoding_region": "ix1",
           "auto_record": false,
           "webrtc": false,
           "dvr_enabled": false,
           "cdn_id": 53949,
           "projection": "regular"
       }
   }
   

   If successful, the endpoint returns information about the stream created. Save the returned id and other necessary data for later steps.

   {
       "id": 320423,
       "active": false
       ...
   }
   
2. Create a broadcast

   The Create broadcast endpoint (POST /streaming/broadcasts) creates a broadcast object.

   • Set the stream_ids property to the id returned from step 1 to bind the broadcast and stream together.
   • Set the status property to pending.

   {
       "broadcast": {
           "name": "test_broadcast",
           "status": "pending",
           "share_url": "",
           "custom_iframe_url": "",
           "show_dvr_after_finish": false,
           "pending_message": "Please wait ...",
           "ad_id": null,
           "stream_ids": [320423]
           ...
       }
   }
   

   If successful, the endpoint returns information about the broadcast created. Save the returned id and other necessary data for later steps.

   {
      "id": 192470,
      "status": "pending",
      "stream_ids": [320423],
      ...
   }
   
3. Enable the stream

   Once the stream and broadcast are created, the user can publish the stream. Setting active to true makes the stream ready to receive ingest from the encoder. The Change live stream endpoint (PATCH /streaming/streams/{id}) activates the stream.

   {
      "stream": {
         "active": true
      }
   }
   

   {
       "id": 320423,
       "active": true
       ...
   }
   
4. Receive a webhook: stream started

   The Video Streaming sends a webhook that contains "live": true to the subscribed endpoint.

   {
      "type": "stream",
      "message": {
         "stream": {
           "id": 320423,
           "live": true,
           "recording": false
         }
      }
   }
   

Stage 2. Test

The user tests the broadcast at this stage.

1. Change the broadcast status to live

   The Change broadcast endpoint (PATCH /streaming/broadcasts/{id}) updates the broadcast status to live.

   {
      "broadcast": {
         "status": "live"
      }
   }
   

   {
      "id": 192470,
      "status": "live"
      ...
   }
   
2. Receive a webhook: broadcast live

   The Video Streaming sends a webhook that contains "status": "live" to the subscribed endpoint.

   {
      "type": "broadcast",
      "message": {
         "broadcast": {
           "id": 192470,
           "status": "live"
         }
      }
   }
   

Stage 3. Live

The stream and broadcast are now live and visible to the audience. Start recording if the session should be saved as a video.

1. Start recording

   The Start recording endpoint (PUT /streaming/streams/{id}/start_recording) begins recording.

   If the returned HTTP status code is 204, the request is successful.

2. Receive a webhook: recording started

   The Video Streaming sends a webhook that contains "recording": true to the subscribed endpoint.

   {
      "type": "stream",
      "message": {
         "stream": {
           "id": 320423,
           "live": true,
           "recording": true
         }
      }
   }
   

Stage 4. Stop

The user stops streaming at this stage.

1. Stop recording

   The Stop recording endpoint (PUT /streaming/streams/{id}/stop_recording) stops recording.

   The response contains information about the recorded video.

   {
       "id": 803111,
       "name": "Stream Record: test_stream, 2022-06-03 13:25:16 +0000",
       "recording_started_at": "2022-06-03T13:24:29.000Z",
       "created_at": "2022-06-03T13:25:16.000Z",
       ...
   }
   
2. Receive a webhook: recording stopped

   The Video Streaming sends a webhook that contains "recording": false to the subscribed endpoint.

   {
      "type": "stream",
      "message": {
         "stream": {
           "id": 320423,
           "live": true,
           "recording": false
         }
      }
   }
   
3. Receive a webhook: video processing started

   The Video Streaming sends a webhook that contains "status": "pending" to the subscribed endpoint.

   {
     "type": "video",
     "message": {
       "video": {
         "id": 803111,
         "slug": "MTdaAbW7IzBsjgvy",
         "name": "Stream Record: test_stream, 2022-06-03 13:25:16 +0000",
         "duration": 48410,
         "status": "pending",
         ...
       }
     }
   }
   
4. Change broadcast status to finished

   The Change broadcast endpoint (PATCH /streaming/broadcasts/{id}) updates the broadcast status to finished.

   {
      "broadcast": {
         "status": "finished"
      }
   }
   

   {
      "id": 192470,
      "status": "finished"
      ...
   }
   
5. Receive a webhook: broadcast finished

   The Video Streaming sends a webhook that contains "status": "finished" to the subscribed endpoint.

   {
      "type": "broadcast",
      "message": {
         "broadcast": {
           "id": 192470,
           "status": "finished"
         }
      }
   }
   
6. Disable the stream

   The Change live stream endpoint (PATCH /streaming/streams/{id}) deactivates the stream.

   {
      "stream": {
         "active": false
      }
   }
   

   {
      "id": 320423,
      "live": true,
      "transcoded_qualities": ["360n", "480n", "720n"],
      "transcoding_speed": 1.0,
      "active": false,
      "rtmp_play_url": [
         "rtmp://pull-ix1.gvideo.co:1939/in/320423?4a5d279b6371c7bcc5ce47afb0f74637",
         "rtmp://pull-ix1.gvideo.co:1939/out/58725_320423_360n?4a5d279b6371c7bcc5ce47afb0f74637?vhost=out",
         "rtmp://pull-ix1.gvideo.co:1939/out/58725_320423_480n?4a5d279b6371c7bcc5ce47afb0f74637?vhost=out",
         "rtmp://pull-ix1.gvideo.co:1939/out/58725_320423_720n?4a5d279b6371c7bcc5ce47afb0f74637?vhost=out"
       ],
      "transcoding_enabled": true,
      ...
   }
   
7. Receive a webhook: stream ended

   The response may still show "live": true while the stream transitions to inactive. Wait for the subsequent webhook with "live": false to confirm that streaming has ended.

   The Video Streaming sends a webhook that contains "live": false to the subscribed endpoint.

   {
      "type": "stream",
      "message": {
         "stream": {
           "id": 320423,
           "live": false,
           "recording": false
         }
      }
   }
   
8. Delete the broadcast

   The Delete broadcast endpoint (DELETE /streaming/broadcasts/{id}) deletes the broadcast.

   If the returned HTTP status code is 204, the request is successful.

9. Receive a webhook: video partially processed

   One quality version of the recorded video is ready for viewers to watch. The Video Streaming sends a webhook that contains "status": "viewable" to the subscribed endpoint.

   {
     "type": "video",
     "message": {
       "video": {
         "id": 803111,
         "slug": "MTdaAbW7IzBsjgvy",
         "name": "Stream Record: test_stream, 2022-06-03 13:25:16 +0000",
         "duration": 48410,
         "status": "viewable",
         "converted_videos": [
           { "name": "vod720n", "status": "complete" },
           { "name": "vod480n", "status": "processing" },
           { "name": "vod360n", "status": "processing" },
           { "name": "vod240n", "status": "processing" }
         ]
       }
     }
   }
   
10. Receive a webhook: video fully processed

    All quality versions of the recorded video are ready for viewers to watch. The Video Streaming sends a webhook that contains "status": "ready" to the subscribed endpoint.

    {
       "type": "video",
       "message": {
          "video": {
            "id": 803111,
            "slug": "MTdaAbW7IzBsjgvy",
            "name": "Stream Record: test_stream, 2022-06-03 13:25:16 +0000",
            "duration": 48410,
            "status": "ready",
            "converted_videos": [
              { "name": "vod720n", "status": "complete" },
              { "name": "vod480n", "status": "complete" },
              { "name": "vod360n", "status": "complete" },
              { "name": "vod240n", "status": "complete" }
            ]
          }
       }
    }
    
11. Get video information

    The Get video endpoint (GET /streaming/videos/{id}) retrieves detailed information about the recorded video.

    {
        "id": 803111,
        "name": "Stream Record: test_stream, 2022-06-03 13:25:16 +0000",
        "client_id": 58725,
        "duration": 48410,
        "stream_id": 320423,
        "recording_started_at": "2022-06-03T13:24:29.000Z",
        "created_at": "2022-06-03T13:25:16.000Z",
        "sprite": "https://s-ed1.cloud.gcore.lu/videoplatform/sprites/58725/803111_803111.mp4_sprite.jpg",
        ...
    }
    

Special cases

Reuse of a stream

The same stream can be reused for multiple broadcasts — this avoids recreating push URLs and reconfiguring the encoder between sessions. Instead of creating a new stream, update the existing one with the Change live stream endpoint (PATCH /streaming/streams/{id}) to set the appropriate transcoding region.

{
   "stream": {
      "transcoding_region": "dt1"
   }
}

{
   "id": 320423,
   "live": false,
   "backup_live": false,
   "transcoded_qualities": ["360n", "480n", "720n"],
   "transcoding_speed": 1.0,
   "push_url": "rtmp://vp-push-dt1.gvideo.co/in/320423?6460e735eda6b61bd4c99e02abf0c8df",
   "backup_push_url": "rtmp://vp-push-ix1.gvideo.co/in/320423b?6460e735eda6b61bd4c99e02abf0c8df",
   "push_url_srt": "srt://vp-push-dt1-srt.gvideo.co:5001?streamid=320423#6460e735eda6b61bd4c99e02abf0c8df",
   "backup_push_url_srt": "srt://vp-push-ix2-srt.gvideo.co:5001?streamid=320423b#6460e735eda6b61bd4c99e02abf0c8df",
   ...
}

Interruption during streaming

• The Video Streaming sends a webhook when the stream is briefly interrupted.

{
   "type": "stream",
   "message": {
      "stream": {
        "id": 320423,
        "live": false,
        "recording": false
      }
   }
}

• The Get live stream endpoint (GET /streaming/streams/{id}) returns the current stream state. If the response contains "active": false and the stream was not manually interrupted, the Change broadcast endpoint (PATCH /streaming/broadcasts/{id}) transitions the broadcast to paused status.

{
   "broadcast": {
     "status": "paused"
  }
}

{
   "id": 192470,
   "status": "paused",
   ...
}

• Stop recording (PUT /streaming/streams/{id}/stop_recording) when an interruption occurs (even for a couple of minutes). After the stream resumes, the recording splits into two files: data recorded before the interruption and data recorded after the stream resumes.

The Video Streaming does not reconnect without interrupting the recording if the stream encounters a temporary disruption.

Recording deletion

Recorded videos associated with a deleted user account can be removed using the Delete video endpoint (DELETE /streaming/videos/{id}).

If the returned HTTP status code is 204, the request is successful.

Other API methods

The Streaming API reference documents additional methods for other use cases.