On This Page

Live API: Static Entry Points

Product(s)

Live

Role(s)

API Developer

Topic(s)

Live Streaming

API(s)

Live API

This topic explains static entry points and how to implement them using the Live API.

Introduction

The Static Entry Points (SEP) feature allows for a long-running live job that can be activated and deactivated while keeping the entry point URLs and playback URLs static and re-usable. This feature allows for customers to configure their encoder in their facilities or the field and allows the customer to create their own scheduling logic for live channels or programs.

DVR and SEP

DVR capability is available for static entry points, but only while the SEP is activated.

Creating a static entry point

The standard Create Job operation will is used, but for the addition of Static Entry Points a property will need to be added to the job request:

"static": true

The responding RTMP URL from this job will be static and can then be reused by activating/deactivating the job with the operations described in the sections below. Please read and understand the limitations listed at the end of this document.

Maximum waiting time

After an SEP job is activated, it will automatically deactivate after some time if the encoder is not started. The rules are as follows:

If the event_length value is greater than 30 minutes, the job will automatically terminate in 30 minutes.

If the event_length value is less than 30 minutes, the job will terminate in the time set for event_length.

Activate SEP Live Stream

To activate a static entry point live stream, send the following request to the Live API:

To be able to ingest to a Static Entry Point, you must make the activate API request.

Active SEP Stream

Method

PUT

Endpoint

https://api.bcovlive.io/v1/jobs/{jobID}/activate

No request body is required.

Deactivate SEP Live Stream

Note: always stop the encoder before deactivating the stream.

To deactivate a static entry point live stream, send the following request to the Live API:

Active SEP Stream

Method

PUT

Endpoint

https://api.bcovlive.io/v1/jobs/{jobID}/deactivate

Note that when you deactivate a static entry point, the last few seconds of the stream remain playable.

No request body is required.

Cancel an SEP job

To permanently stop a static entry point job, you can cancel the job just as you would any live job, by sending a PUT request the endpoint /jobs/{job_id}/cancel. See the API reference for full details.

Limitations

Live to VOD can not be set to archive the stream on completion.

Alternatives:

Use clipping to archive the full live event as a VOD. The window for clipping will be available for the standard duration after an event or until the next activation of the SEP (whichever is shorter).

Job settings can not be modified. They are currently tied to the settings that initially created the SEP.

Activating the stream can take up to 60 seconds for the entrypoint to be available.

Best practice:

Implement notifications from the Live platform for job state changes to get real-time updates for when a SEP job is actually ready.

Alternatives:

Activate the stream at minimum 60 seconds in advance of starting the encoder.

If the encoder has built-in retry (Wirecast, Elemental, etc.), the stream can be connected immediately (though there may be some errors) and the encoders will reconnect as soon as the entry point is available.

Reconnect_time is still applicable for SEP jobs on encoder disconnects. If the reconnect time is reached, the SEP job will be placed back to a deactivated state.

Best practice:

Always deactivate a stream via the API’s when a job completes and set the reconnect time to an acceptable window of time to wait in the event of a disconnect (input hour costs are accrued during this wait period).

Each account will only be allocated 3 available SEP jobs. If you hit the limit, you will need to cancel one of your SEP jobs before you can create a new one.

If you have reached the maximum number of SEP jobs and attempt to create another one, the following error will be returned:

{
"error": "You've reached the number of static entry points jobs you can create for your account"
}

Notes

Clipping SEP jobs after deactivation

Users can create clips up until the next activation of the stream, or for 24 hours, whichever is shorter. When the stream is re-activated, previous recording sessions are removed from the server and can no longer be clipped.

What is the timing for the stream_start_time field when a SEP is used?