Control a Livestream

Livestream control of live streaming is managed as a state machine. The following diagram illustrates the state transitions of a Livestream driven by control operations. The rectangles represent the states a Livestream may reside in. The arrows indicate the possible transitions between states that occur when certain events or conditions are met, such as the start of a scheduled event, the completion of server setup, or the initiation of a Livestream.

Figure: The state diagram of a Livestream

Here is the explanation of each state:

State	Description
Scheduled	This is the initial state of an event when it is scheduled but not yet ready for streaming.
Preparing	When the scheduled event is less than 12 hours away, the status changes to "Preparing." At this point, the infrastructure is being set up for the event.
Wait for Preview	After the infrastructure is set up, the status changes to "Wait for Preview." The streaming server has been built-up but is still not open for pushing signals.
Preview	When the server is ready, the status changes to "Preview," indicating that the event can start sending signals and rehearsing.
Live	After the "Go Live" action is triggered, the event is live, and the status changes to "Live."
Encoding	Once the live event has ended, the content is transcoded to VOD by BlendVision encoding service, and the status changes to "Encoding."
VOD Ready	When the VOD is ready to be broadcast, the status changes to "VOD Ready," indicating it is waiting for the scheduled time.
VOD	Once the transcoding has been completed and the live event can be played as VOD content, the status changes to "VOD."
Live END	When the live-only event ends or the VOD of a Live to VOD event ends, the status changes to "Live END."
Closed	When the event is canceled or successfully ended, the status changes to "Closed," and the channel can be re-opened and recreated.
Archived	When the channel is archived, the status changes to "Archived."

Create Livestream

You can use the following API to create a Livestream with the desired request body.

POST /bv/cms/v1/lives

{
  "live":{
    "name":"string",
    "custom_id":"string",
    "type":"LIVE_TYPE_LIVE",
    "source":{
      "type":"LIVE_SOURCE_TYPE_LIBRARY",
      "library":{
        "id":"string"
      }
    },
    "broadcast_mode":"BROADCAST_MODE_TRADITIONAL_LIVE",
    "scheduled_at":"2019-08-24T14:15:22Z",
    "resolution":"LIVE_RESOLUTION_HD",
    "live_vod":{
      "source":"LIVE_VOD_SOURCE_UNSPECIFIED",
      "replace":{
        "id":"string"
      },
      "playback":{
        "id":"string"
      },
      "started_at":"2019-08-24T14:15:22Z",
      "ended_at":"2019-08-24T14:15:22Z"
    },
    "security":{
      "privacy":{
        "type":"SECURITY_PRIVACY_TYPE_PUBLIC",
        "token":{
          "device_limit":0
        }
      },
      "watermark":{
        "enabled":true,
        "type":"WATERMARK_TYPE_IMAGE",
        "position":"WATERMARK_POSITION_TOP_RIGHT",
        "image":{
          "library_id":"string"
        }
      },
      "domain_control":{
        "enabled":true,
        "domains":[
          "string"
        ]
      },
      "protection":{
        "type":"PROTECTION_TYPE_UNSPECIFIED"
      },
      "geo_control":[
        "string"
      ]
    },
    "ull_enabled":false,
    "cover_images":{
      "ready_to_start":{
        "type":"COVER_IMAGE_TYPE_UNSPECIFIED",
        "auto":{
          
        },
        "customize":{
          "library_id":"string"
        }
      },
      "preview":{
        "type":"COVER_IMAGE_TYPE_UNSPECIFIED",
        "auto":{
          
        },
        "customize":{
          "library_id":"string"
        }
      },
      "player_pause":{
        "type":"COVER_IMAGE_TYPE_UNSPECIFIED",
        "auto":{
          
        },
        "customize":{
          "library_id":"string"
        }
      },
      "signal_interruption":{
        "type":"COVER_IMAGE_TYPE_UNSPECIFIED",
        "auto":{
          
        },
        "customize":{
          "library_id":"string"
        }
      },
      "end":{
        "type":"COVER_IMAGE_TYPE_UNSPECIFIED",
        "auto":{
          
        },
        "customize":{
          "library_id":"string"
        }
      },
      "close":{
        "type":"COVER_IMAGE_TYPE_UNSPECIFIED",
        "auto":{
          
        },
        "customize":{
          "library_id":"string"
        }
      },
      "current":{
        "type":"COVER_IMAGE_TYPE_UNSPECIFIED",
        "auto":{
          
        },
        "customize":{
          "library_id":"string"
        }
      }
    },
    "metadata":{
      "short_description":"string",
      "long_description":"string"
    },
    "showroom":{
      "model":{
        
      },
      "libraries":[
        {
          "id":"string"
        }
      ]
    },
    "interaction":{
      "poll_enabled":false,
      "chatroom":{
        "live":{
          "enabled":false,
          "theme":"CHATROOM_THEME_UNSPECIFIED"
        },
        "vod":{
          "enabled":false,
          "theme":"CHATROOM_THEME_UNSPECIFIED"
        }
      }
    },
    "ingestion_types":"LIVE_STREAM_INGEST_TYPE_RTMP"
  }
}

The response will contain the details of the newly created event, including its id. The id field can be used to control the Livestream.

{
  "live":{
    "id":"string",
    "name":"string",
    ...
  }
}

The followings introduce each important attribute in more detail:

Type

BlendVision provides two options for Livestream: Live (LIVE_TYPE_LIVE) and Simulive (LIVE_TYPE_SIMULIVE). For Simulive, you can select an uploaded video as the streaming source. You can find more details here.

Broadcast mode

BlendVision offers three broadcast modes for Livestream:

1. Traditional Live

Only broadcasts the current live stream, with no progress bar for users to operate.

2. DVR (start-over)

Displays the start and latest stream on the progress bar, allowing users to drag it to watch live from the start.

3. Playback

Displays the start and end on the progress bar, enabling users to see the overall length and drag the progress bar to watch what they want.

These modes are only available on certain Livestream types:

Live: DVR (start-over) and Traditional Live
Simulive: DVR (start-over), Traditional Live, and Playback mode.

To specify the broadcast mode, you can set the broadcast_mode field to either BROADCAST_MODE_TRADITIONAL_LIVE, BROADCAST_MODE_PLAYBACK, or BROADCAST_MODE_DVR.

Resolution

To specify the resolution, you can set the resolution field to either LIVE_RESOLUTION_HD, LIVE_RESOLUTION_FHD, or LIVE_RESOLUTION_4K. Note the higher resolution options come at a higher cost.

Security

Privacy

Manage the visibility of your content by specifying the regions or audiences authorized to access it, ensuring compliance with licensing agreements and target audience restrictions. For more information about privacy, see The Visibility of Content.

Watermark

Overlay watermarks on your videos to claim copyright, deter piracy, and identify unauthorized usage, providing additional content protection. You can enable watermarking with a specified type and position. For more information about enabling a watermark, see Watermarks.

Domain Control

Limit content delivery to authorized domains, ensuring that your content is only accessible on approved websites and platforms, reducing the risk of unauthorized distribution. For more information about enabling domain control, see Domain Control.

Geo control

Restrict access to your content based on geographical regions, allowing you to target specific markets and comply with content distribution regulations. For more information about enabling geo control, see Geo Region Control.

DRM

By implementing DRM technologies such as FairPlay, PlayReady, and Widevine, you can encrypt your content and control its playback, preventing unauthorized copying and piracy. For more information about enabling DRM to protect your content, see Digital Rights Management.

Ultra-low latency

Ultra-low latency (ULL) is the ability to reduce the latency or delay between when a video is captured and when it is displayed to the viewer. With ULL enabled, the latency can be reduced to less than 3 seconds, giving the audience a more real-time and interactive viewing experience.

By setting uul_enabled to true, you can enable the ULL function to have a lower latency experience. Note you will be charged a higher fee if you enable ultra-low latency for your live stream.

scheduled_at

The Livestream will be launched instantly if the scheduled_at parameter is not set. The scheduled_at parameter is used to specify a specific date and time at which the Livestream should be launched. To set the scheduled_at parameter, you can use the ISO 8601 format to specify the date and time. Here is an example of scheduling a Livestream to launch on May 1, 2023, at 10:00 AM UTC:

"scheduled_at": "2019-08-24T14:15:22Z"

Cover images

You can specify a thumbnail image for each status of a Livestream, which can be displayed on the player.

Status	Description
Ready to start	when the Livestream has built up resources, and wait for 12 hours before the scheduled date and time.
Preview	The Livestream is in preview mode.
Player pause	The player is paused.
Signal interruption	The signal is interrupted, the event host has cut the signal, or other detectable accidents happen.
End	This Livestream has ended.
Close	This Livestream has closed.

For each status, you need to specify the type of cover image and the image itself. The available values for the type field are:

COVER_IMAGE_TYPE_AUTO: The system automatically generates the thumbnail image.
COVER_IMAGE_TYPE_CUSTOMIZE: You need to specify the library ID of the image in the customize object.

Interactions

You can enable the interaction features, including poll and chatroom, during Live phase.

The poll_enabled field is a boolean value that enables or disables the poll feature.

The chatroom field contains information related to the chatroom feature. If the enabled field is set to true, then the theme field is also required. The theme field specifies the theme or color scheme for the chatroom. There are two possible values for this field:

CHATROOM_THEME_LIGHT: The theme is a light color scheme.
CHATROOM_THEME_DARK: The theme is a dark color scheme.

Here's an example that specifies a chatroom with the dark theme enabled for a Livestream:

"interaction": {
  "poll_enabled": false,
  "chatroom": {
    "live": {
      "enabled": true,
      "theme": "CHATROOM_THEME_DARK"
    }
  }
}

Ingestion Types

Currently, we offer two methods to ingest live stream data.

LIVE_STREAM_INGEST_TYPE_RTMP: Real-Time Messaging Protocol
LIVE_STREAM_INGEST_TYPE_WHIP: WebRTC HTTP Ingest Protocol

By default, the ingestion method is RTMP, but you can specify the method in the ingest_types field.

Live to VOD

You may want to host a live event and provide playback to your viewers after the live has ended. You can do this using the Live to VOD feature. This feature allows you to use the catchup of live as the source of VOD, or replace the VOD with an edited version.

To use Live to VOD, you must select the source of the VOD and set the start and end times.

Source of Live to VOD

There are three options for the source of the VOD:

1. Live Catchup

You can use the catchup of the live as the source of VOD. You can broadcast the live part at the scheduled time, and viewers can browse and download it from the list of video assets.

2. Replace with an edited VOD

Download the Live source from the video library, edit it, and re-upload it to the Video Library as the source for VOD replacement. Then, you can choose the edited video from the Video Library once you enable the VOD replacement feature.

3. Playback

You can use the existing playback as the source of VOD. This option requires you to specify the playback object in the request body.

The values for the source field are:

LIVE_VOD_SOURCE_CATCHUP: Use the catchup of the live as the source of VOD
LIVE_VOD_SOURCE_REPLACE: Replace the VOD with an edited version
LIVE_VOD_SOURCE_PLAYBACK: Use the existing playback as the source of VOD

The replace object is required if the source is LIVE_VOD_SOURCE_REPLACE, and the playback object is required if the source is LIVE_VOD_SOURCE_PLAYBACK.

Start and End Time

You will need to set up the VOD available playback time, which is the period when the VOD is allowed to broadcast as an on-demand service with playback mode. Ensure that the source is prepared before the scheduled start time, and the VOD will go live automatically once the video source is ready. If the video is not provided or not ready, the VOD won’t display any content. You can adjust the end time during the live event. You can use the ISO 8601 format to specify the date and time for the started_at and ended_at parameters.

Here's an example of setting a Live to VOD:

{
  "live_vod":{
    "source":"LIVE_VOD_SOURCE_PLAYBACK",
    "playback":{
      "id":"your_vod_id_for_playback"
    },
    "started_at":"2023-04-11T12:00:00Z",
    "ended_at":"2023-04-11T13:00:00Z"
  }
}

Preview Livestream

The streaming server has been built but is still not open for pushing signals. Once it is less than 12 hours until the event starts, you can preview Livestream using the following API. Now, you can send your signal and start the rehearsal.

POST /bv/cms/v1/lives/{id}:preview

Start Livestream

You can use the following API to turn a Livestream from preview mode to live streaming mode.

POST /bv/cms/v1/lives/{id}:start

Cancel Livestream

You can cancel a Livestream when the state is scheduled, preview, or go live using the following API.

POST /bv/cms/v1/lives/{id}:cancel

End Livestream

You can use the following API to end a Livestream that is currently streaming.

POST /bv/cms/v1/lives/{id}:end

Archive Livestream

Once you don't want to reopen the Livestream, you can use the following API to archive an ended Livestream.

POST /bv/cms/v1/lives/{id}:archive

Updated August 22, 2023 03:09

Go Live