On This Page

Live API: Notifications

Product(s)

Live

Role(s)

API Developer

Topic(s)

Live Streaming

API(s)

Live API

Type

Support Doc

This topic show how to set up notifications for Live API jobs.

Introduction

The Brightcove Live system sends notifications of various events. You can set up listeners for notifications to trigger further actions. The listener(s) can be written in any server-side language you use, and they would look for incoming POST requests, parse the JSON request body, and then take whatever action you want. Below we will see how you can request notifications.

Requesting notifications

You can request notifications by including one or more notifications fields in the outputs your Create Job request.

The value of notifications is an array of notification destination objects. You can use a simple string with a url: "http://httpbin.org/post", or you can use an object with following options: {"url": "http://httpbin.org/post", "credentials": "reference_to_your_credentials"}. A notification will be sent to the destination you specify when the output changes its state. If you apply this parameter to a VOD output the notifications will only be related to that VOD job, not to the live job.

Events

Below are the events of a job lifecycle you can listen for. Note that the event scope is per job, so the event lifecycle for a live job would be separate from the lifecycle for a VOD clipping job based on the same live stream.

state_changed

first_segment_uploaded

output_finished

The state_changed will notify on the following states described in the table below

Live Job States

State

Description

JOB States (reported in notifications as state)

error

An error has occurred; the job will not be processed.

standby

(Only applicable to Static Entry Point [SEP] jobs.) The job is allocated and ready for activation.

waiting

The job has been assigned to a streaming worker and ready for the encoder to connect.

processing

The encoder is connected and the job is available for playback.

disconnected

The encoder has disconnected and the streaming worker is waiting for a reconnection.

cancelling

The job has been cancelled and the worker is stopping the job and will NOT process any pending VOD outputs.

finishing

The encoder has been disconnected for more than reconnect_time, and streaming worker is stopping the jobs and creating any associated VOD outputs.

cancelled

The job has been cancelled successfully.

finished

The job has finished successfully.

failed

The job has stopped as a result of a system error.

VOD JOB States (reported in notifications as jvod_state)

error

An error has occurred; the job will not be processed.

waiting

The job waiting for processing.

waiting_finish_live

The job waiting for the Live Job to finish (if the clip depends on that).

processing

The clip is being processed.

creating_asset

A VOD asset is being created.

cancelling

The job has been cancelled and the worker is stopping the job and will NOT process any pending VOD outputs.

cancelled

The job has been cancelled successfully.

finished

The job has finished successfully.

failed

The job has stopped as a result of a system error.

SSAI States (reported in notifications as ssai_state)

none

The job is not an SSAI job.

waiting_input

The streaming worker is waiting for the encoder to connect and provide the stream input information.

start_transcoding

The encoder has connected and the SSAI slate has been queued for transcoding based on the stream input data and outputs data.

transcoding

The slate is being transcoded.

error

The slate could not be downloaded or transcoded.

ready

The slate has been generated and the job is ready for SSAI playback.

SEP States (reported in notifications as sep_state)

none

The job is not an SEP job.

ready

The entry point has been activated and ready for the encoder to connect.

pending_activation

The entry point has been queued for streaming worker assignment.

activation_in_progress

The entry point is updating to route connections to the streaming worker.

pending_deactivation

The entry point has been queued for cleanup from the streaming worker.

deactivation_in_progress

The entry point is disconnecting from the streaming worker.

cancelled

The entry point has been cancelled.

finished

The entry point has completed successfully.

RTMP Output States (reported for rtmp_output_state_changed notifications as state)

starting

The stream is starting.

connected

The encoder has connected.

Disconnected

The encoder has disconnected.

error

The stream failed to connect.

pending_deactivation

The entry point has been queued for cleanup from the streaming worker.

deactivation_in_progress

The entry point is disconnecting from the streaming worker.

cancelled

The entry point has been cancelled.

finished

The entry point has completed successfully.

Sample notifications

Live stream notification

Here is a sample notification for a state_changed event for a live job: