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.
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." |
1. 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.
Privacy
Same as VOD, you can find more details here.
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 thecustomizeobject.
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 will need to 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 list of the 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:
{
"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"
}
}
2. 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
3. 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
4. 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
5. End Livestream
You can use the following API to end a Livestream that is currently streaming.
POST /bv/cms/v1/lives/{id}:end
6. 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