Pages in this section:

Ingestion Status Callbacks

When an item is ingested into yospaceCDS, it is acquired and encoded into a variety of formats managed automatically by yospaceCDS in order for it to be available to a wide range of connected devices.

yospaceCDS R2.6 introduced the ability for the MediaItem API to make status update callbacks allowing your software to determine when the item is ready for end users. This may be used in preference to polling the item status method repeatedly.

Furthermore, yospaceCDS will send callbacks for each interim stage of processing, although your software to estimate the timeframe in which it will be processed. These interim updates can be ignored, of course.

Overview

The callback method operates as follows:

MediaItem is created using the standard MediaItem Create method, but is supplied with the <stateChangeUrl> parameter to specify the callback URL.
This URL is called when on each stage of its processing by yospaceCDS is started and completed, within estimation of how far along the processing is.

Common Callback Parameters

The following parameters are added to all callbacks made:

id

The MediaItem ID to which the callback refers.

event

The type of update. One of the following values:

CONVERSION_START - an encoding job has started.
CONVERSION_SUCCESSFUL - an encoding job has successfully completed.
CONVERSION_FAILED - an encoding job has failed. All further pending jobs will be cancelled and the item will be set to a failed state.

acquire

The state of the content acquisition. yospaceCDS must fetch your content from the URL you specified in the MediaItem Create method; this parameter indicates the state of this operation. It can be one of three values:

PROCESSING - the item is being acquired.
SUCCESSFUL - the item was acquired successfully (and processing will begin)
FAILED - the item could not be acquired. All further processing will stop. If this occurs, check that the URL you supplied is correct and internet accessible.

Update Notification Parameters

The following parameters are added to callbacks except the first.

queue: The approximate percentage of encoding work currently queued for execution.
process: The approximate percentage of encoding work currently executing.
success: The approximate percentage of encoding work currently completed.
failed: The approximate percentage of encoding work that has failed to complete successfully. Please note that in the event that a single job fails, all subsequent jobs are cancelled, with the exception of jobs currently running.

Failure Description Parameter

In the event of a failure, the additional parameter message containing a textual description of the reason for failure. The purpose of this message is to assist developers during testing and debugging. The error descriptions may change over time and therefore should be subject only to human interpretation.

Content Ready Parameter

The final notification will contain the parameter complete (set to TRUE if successful). Your callback handler can simply ignore all other callbacks except this one if it simply wants to know when the content is ready.

Example

This example assumes that the callback URL (as set by the stateChangeUrl parameter) is:

http://myserver.net/cds

Initial Callback

The acquisition of the content starts. Callback is:

http://myserver.net/cds?id=13300836&event=CONVERSION_START&acquire=PROCESSING

Acquisition Phase Callbacks

The acquisition of the content succeeds, the callback is:

http://myserver.net/cds?process=0&id=13300836&queue=100&event=CONVERSION_SUCCESSFUL
                                 &acquire=SUCCESSFUL&failed=0&success=0

However, if the content acquistion fails, the following callback is made:

http://myserver.net/cds?message=DOWNLOAD_404_FILE_NOT_FOUND&id=13300872
                               &event=CONVERSION_FAILED&acquire=FAILED

Subsequent Callbacks

Each encoding job that commences is notified as such:

http://myserver.net/cds?process=18&id=13300836&queue=54&event=CONVERSION_START
                                   &acquire=SUCCESSFUL&failed=0&success=27

When this encoding job completes, it is notified as shown below. Please note that jobs may run in parallel, so you cannot always guarantee that a job start notification will be followed by its corresponding job completed notification.

http://myserver.net/cds?process=18&id=13300836&queue=18&event=CONVERSION_SUCCESSFUL
                                       &acquire=SUCCESSFUL&failed=0&success=63

In the event a conversion fails, the following callback is made:

http://myserver.net/cds?message=VIDEO_TRANSCODE_FAILED&process=18&id=13300836&queue=18
                        &event=CONVERSION_FAILED&acquire=SUCCESSFUL&failed=0&success=63

Final Notification

The final notification that informs you that the content is available to end users is made as:

http://myserver.net/cds?process=0&id=13300836&queue=0&complete=TRUE
                                 &event=CONVERSION_SUCCESSFUL&acquire=SUCCESSFUL
                                 &failed=0&success=100

Release Notes

VoD Workflow & Delivery