Live API: Static Entry Points

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 by default - if you wish to change the waiting time, you will need to contact Support. Automatic deactivation cannot be disabled.
  • If the event_length value is less than the reconnect_time, 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:

Active SEP Stream
Method PUT
Endpoint
https://api.bcovlive.io/v1/jobs/{jobID}/activate

No request body is required.

Deactivate SEP Live 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

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 cannot 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:

    1. Activate the stream at minimum 60 seconds in advance of starting the encoder.
    2. 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 APIs 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 per region. 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"
    }
  • If you attempt to activate more than 5 SEP jobs at once, you will receive an error like the following:
    {
      “message”:“Allocating additional streaming capacity to the region. Please retry your request.: no_streaming_capacity_in_region”,
      “statusCode”:500,
      “name”:“ApiError”,
      “isApiError”:true
    }

    You will need to wait until some jobs have finished activating before retrying the request.

Notes

Clipping SEP jobs after deactivation
Users can create clips up until the next activation of the stream, or for 7 days, 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?
When a SEP is activated that would be considered the start time.