Media Conversion

Media conversion has two stages, which are described in this section:

• request is sent to yospaceCDS to perform conversions
• when processing is finished, yospaceCDS confirms that the conversion is complete

Remember that this only applies to converted media. Conversion scripts do not run on static content.

Conversion Request

You must convert the media you have uploaded in order to make it available for retrieval (that is, downloading or streaming). Do this by sending requests to yospaceCDS to run the conversion scripts that perform the conversions you want.

The fields in the conversion request are described below, but in particular pay attention to the content ID, which you got back in the upload response, and the conversion ID, which specifies which conversion you are applying.

When the conversion is complete, the notification tells you that the media content (that is, a converted variant of the uploaded original) is now available for download.

Note that even if you have uploaded the media in the format you expect to download, it cannot be downloaded without explicitly being converted. This protects the integrity of the original data (the data in its canonical form). It may be necessary to apply a conversion which does not internally change the format of the data.

Example

This is the example from Example Conversion Request XML:

<soap:Envelope
         xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<ns2:contentConvertRequest
         xmlns:ns2="http://www.yospace.com/tundra/ContentService/">
    
<clientApplicationId>petshow</clientApplicationId>
<clientApplicationCredentials>Wf</clientApplicationCredentials>

<conversionId>13</conversionId>
<restricted>false</restricted>

<scriptParameter>     
    <key>key1</key>  
    <value>value1</value>
</scriptParameter>
    
<scriptParameter>
    <key>key2</key>
    <value>value2</value>
</scriptParameter>

<successUrl>http://www.site.com/callback.pl?myId=45</successUrl>
<failureUrl>http://www.site.com/cb_error.pl?myIdd=45</failureUrl>
<contentIdentifier>1/2/3/4/adsd/petshow</contentIdentifier>
     
<addressType>m</addressType>
     
<priority>10</priority>
  
</ns2:contentConvertRequest>
 </soap:Body>
</soap:Envelope>

Request Fields

The web request for converting media can contain the following fields. Several are mandatory—see the following entries for details.

Client Application ID & Credentials

Conversion access to yospaceCDS is restricted in the same way as upload requests. See Client Application ID & Credentials for details.

Conversion ID

Conversion scripts have unique IDs. Typically a conversion script changes the media from its canonical, uploaded form into a format that can be downloaded. Of course, conversions are not solely about format, but this is perhaps their most common use. Conversely, if you don’t specify a particular conversion, then it won’t be possible to retrieve this content via that conversion.

There are many standard conversion scripts available—see Conversion ID Reference. yospaceCDS also supports third-party scripts, which are called in the same way.

The conversion ID field is mandatory.

Restricted Flag

The restricted flag indicates whether or not the content is freely available for download (false) or only by authorized access (true).

Script Parameters

Some conversion scripts may need additional information in order to run. For example, a format converter may need additional information due to variations of format within a given MIME type, or the required dimensions.

Similarly, some conversion scripts need additional media. For example, if you are splicing a standard introduction or title sequence onto an uploaded video, you need to specify the media clip that contains the intro. This can be a plain CDS media ID, or a combination including conversions.

The script parameters field is optional. You must check the details of the conversion scripts you are calling in order to see what name/value pairs, if any, are required.

Success and Failure Notification URLs

See Notification URLs, for details of these fields.

Content Identifier

This field specifies the media content to which the conversion is to be applied. This is the ID that was in the success response that yospaceCDS sent back to you when you uploaded the content.

This field is mandatory.

Job Priority

This optional field specifies the priority assigned to this conversion request. Priority is an integer value starting at 0. The higher the value, the higher the priority—the job scheduler will schedule the highest priority job in the queue first.

Your account is assigned a maximum priority. If you specify a priority greater than your account’s maximum, the maximum value will be used. It is up to you how you use the priority levels within the priority range you are given.

Batch Parameters

This field is optional—you only need to provide batch parameters if this conversion is part of a batch job. A batch job is a group of conversions that have some dependency on each other such that some must be completed before the others can begin. See Batch Jobs for an explanation of how batch jobs work.

Specifically, the batch parameters are specified as the ID of the batch to which this conversion job belongs, together with any number of job IDs, each one identifying a job which must be completed before this one can run.

For example, the following batch parameters indicate that this conversion is part of batch 19202, and can only be performed when jobs 19204 and 19205 have been completed.

<batchParameters>
            <batchId>19202</batchId>
            <prerequisiteJobId>19204</prerequisiteJobId>
            <prerequisiteJobId>19205</prerequisiteJobId>
</batchParameters> 

If you include batchParameters like this, yospaceCDS will not execute the job in the normal way. Instead, the job will wait until the batch to which it belongs is started explicitly. This means you can add more jobs to the batch with subsequent conversion requests, and all of them will effectively be held in the queue. Only when the batch is started will they be run. See Start Conversion Batch for details of how to do this.

Notification URLs

When the conversion has been performed, yospaceCDS lets you know by sending a notification request to a URL that you specify. You should provide two URLs: one for notification in the event of success, and one for failure.

The URLs must be fully qualified, and accessible externally (that is, yospaceCDS must be able to access them). Both http and https protocols are supported. If your server requires it, you can also specify a username/password combination using this syntax:

http://username:password@www.example.com/example/path/

 

Success Notification URL

This field provides the URL to which yospaceCDS should send a notification request if the conversion was successful. If you don’t specify such a call-back URL, then yospaceCDS won’t issue any success notification. Although this field is optional, we strongly recommend that you do always provide such a URL.

The notification request from yospaceCDS usually indicates that the content is now available for download—effectively this means that the content is now “published”. So typically the URL you provide is a CGI script or servlet which monitors the responses and cross-references them with your outstanding conversion requests.

The notification URL you specify is appended with two parameters. The parameter jobid is set to the Job ID that is being reported, and log provides a series of name/value pairs supplying information about the resulting file, including the duration of the video.

Conversely, if you don’t make sure the URL is unique, you won’t be able to differentiate between different conversion responses.

Remember that the delay between requesting a conversion and receiving notification that it has been stored may vary depending on a number of factors—for example, some lengthy conversions may be queued for processing when the system is not busy. Notifications will not necessarily arrive in the same order that the conversions were requested.

Failure Notification URL

This field provides the URL to which yospaceCDS should send a notification request if the upload or subsequent conversions fail. If you don’t specify such a call-back URL, then yospaceCDS won’t issue any failure notification. Although this field is optional, we recommend that you always provide such a URL.

Depending on the configuration of your own servers, this URL may be identical to the success notification URL. The request issued by yospaceCDS includes a status code so that success or failure can be determined—see Conversion Response Status Codes for details. See also the note above about including a unique reference in your URL so you can identify the conversion request to which the notification refers.

Failure URLs are appended with the parameter jobid corresponding to the Job ID that has failed.

Conversion Response

When yospaceCDS receives an conversion request, a job is scheduled to run the specified conversion script. yospaceCDS responds synchronously with a status code and a unique job ID. You can use this job ID to query its status in the queue.

Later, when the job completes, yospaceCDS sends a notification request to the nominated call-back URL.

Example

This is the example from Example Conversion Response XML:

<soap:Envelope
         xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>

<ns2:contentConvertResponse
        xmlns:ns2="http://www.yospace.com/tundra/ContentService/">
     
<status>200</status>
<jobId>15189</jobId>
   
</ns2:contentConvertResponse>
</soap:Body>
</soap:Envelope>

Job ID

The job ID allows you to uniquely identify the scheduled job. This is useful if you want to check on its progress before the conversion has been completed. The job ID only refers to the scheduled job-you cannot use it to access content. For that, you must wait for the variant ID, which is sent to you as part of the conversion notification when yospaceCDS finishes the job. See Conversion Completion Notification for a full description of this mechanism.

For details of how you can use the job ID to determine the job's current status, see Conversion Status Request.

If the conversion request failed (that is, the status contained in the response is not 200), then no job will have been scheduled and the job ID returned will be -1.

Conversion Response Status Codes

yospaceCDS returns a status code in response to the incoming request. Remember that this does not indicate that the conversion has been applied, only that it has been placed into the job queue, awaiting processing.

Conversion Completion Notification

When a conversion script completes, yospaceCDS sends a notification request to the call-back URL that was specified with the conversion request. This URL will be either the success notification URL or the failure notification URL depending on the result of the conversion.

The notification is sent only when the conversion job has been fully processed. The delay between requesting a conversion and receiving notification therefore depends on a number of factors including how busy yospaceCDS server is, and the complexity or size of the conversion. It is important that you track the notifications sent by yospaceCDS because this is the only way you know that the content you have uploaded is available for retrieval.

Returned Query Parameters

yospaceCDS adds query parameters to the notification URL to which it sends its conversion notification request. These are variant, log and mimetype

Variant ID

The variant parameter contains the generated ID for the data created by this conversion. Many scripts are capable of producing different variants-for example, different frame rates for a video conversion. If a script has only one variant, by convention this typically has a variant ID of 1. The variant descriptor does not uniquely identify content within yospaceCDS. You must combine it with other details, such as the content ID and the conversion ID to generate a URL that can be used to retrieve the content-see Retrieval URLs for examples of this in practice.

Report or Error Log

The log parameter contains the string output from the conversion script job. If you receive an unsuccessful response (for example, there is a bad reference ID error) there may be useful diagnostic information in this string. The reasons why a script may fail are largely dependent on the individual script, which is why you need to check the log string to determine what the problem was. Two examples of more general errors that a script may encounter are shown here:

• Generated duplicate content
  The conversion script generated new content which is already stored in yospaceCDS (assuming your account has been configured to check for duplicates).
• Incorrect additional media content ID
  yospaceCDS was unable to find the media content that the conversion script needs. Either you sent the wrong ID, or else you haven't provided one at all. For example, you've asked for a title sequence to be spliced to the beginning of the video, but you haven't specified the content ID, within the media farm, of that title clip.

MIME Type

The mimetype parameter contains the MIME type of the content that has been generated.

Notification Failure

If there is a problem sending the request (for example, the notification request does not get a 200 HTTP OK reply from the call-back URL) yospaceCDS will queue the notification and try again later. This behaviour is configurable, so it will vary from installation to installation. Typically after several failed retries the failure is logged and the notification will not be sent. If you have not received a notification of a conversion, you can check to see if the job is still being held in the job queue and, if so, what its current status is-for example, whether it is yet to be processed (perhaps because the conversion processors are very busy), or else if it did complete but yospaceCDS was unable to reach the notification URL. See Conversion Status Request for details on how to do this.