Upload and Transcoding: A Simple Example

This simple example demonstrates three basic processes:
  • upload media (a video) to yospaceCDS
  • apply some conversions to it
  • download the video, which has been converted

Put a Video Clip In

You have a video clip of a dog balancing a biscuit on its nose (dogbiscuit.mov). The file is in QuickTime format. Uploading the file to yospaceCDS is the first step in making it available for download in a variety of video formats.

To put data into yospaceCDS, you need to give it the following:
  • Media content
    You must provide the data itself (in this case, the video clip)
  • Submitter
    Upload access is, of course, limited to those with authority to add content to the database. An ID and credentials uniquely identify this request as coming from an authorised submitter.
  • Metadata
    Additional information can be supplied which will be stored as metadata alongside the content media itself, such as the width and height of a video clip, the original filename, or the frame rate, and so on.
There are other fields that can be sent with the upload request-see Request Fields for details. 

Example Upload Request XML with Inline Data

The following XML describes the example upload request where the actual content is passed with the SOAP message: 
<soap:Envelope
    xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
   
<ns2:contentUploadRequest xmlns:ns2="http://www.yospace.com/tundra/ContentService/">
     
<clientApplicationId>petshow</clientApplicationId>
     
<clientApplicationCredentials>Wf</clientApplicationCredentials>
<contentMetaData>
        <key>subject</key>
        <value>dog balancing biscuit on nose</value>
        <key>copyright</key>
        <value>(c) 2008 Acme Dog Films</value>
</contentMetaData>
<content>PSJTYXZlIHRvIGRlbC5pY2lvLnVzIj48aW1nIHNyYz0iaHR0cDovL2RlbC5pY2lvLnVzL2Z
hdmljb24uaWNvIiB3aWR0aD0iMTYiIGhlaWdodD0iMTYiIGFsdD0iZGVsLmljaW8udXMiIGNsYXNzPSJmYmRfbGlua19zb
2NpYWwiLz48L2E+PGENCmhyZWY9Imh0dHA6Ly9yZWRkaXQuY29tL3N1Ym1pdD91cmw9aHR0cCUzQSUyRiUyRnd3
dy5iZWhvbGRlci5jby51ayUyRnBsYW5ldGFy...</content>
     
<addressType>m</addressType>
   
</ns2:contentUploadRequest>
  </soap:Body>
</soap:Envelope>
Note that the original .mov filename does not occur in the request, but the content of the file is represented in the content element as base 64 encoded data. Once the content has been uploaded to yospaceCDS, you refer to it using the unique content ID which yospaceCDS allocates.

Example Upload Response XML

The response, which yospaceCDS sends synchronously, looks like this: 

<soap:Envelope
   
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
   
<ns2:contentUploadResponse
        xmlns:ns2="http://www.yospace.com/tundra/ContentService/">
     
<contentIdentifier>1/2/3/4/adsd/petshow</contentIdentifier>
     
<status>200</status>
   
</ns2:contentUploadResponse>
  </soap:Body>
</soap:Envelope>
 

In this case, the content has been allocated a unique content ID of /1/2/3/4/adsd/petshow successfully (the status of 200 indicates a successful upload). 

Apply Conversions

After you have uploaded content into yospaceCDS, you must convert it so that it can be downloaded. The converted form may simply be a different file format or different resolution. It may be the original movie clip with a title sequence spliced onto the front of it, or a branding watermark added to every frame.

To convert content, you need two things: the content ID that yospaceCDS gave you in response to your upload, and the ID of the conversion script you want to run. There are many standard conversion scripts (these typically perform the most common format conversions) as well as bespoke scripts. To apply a conversion, you need to supply the following:
  • Content ID
    Specify the media content to be converted-this is the unique ID that yospaceCDS sent you in response to your upload request.
  • Conversions
    The conversions you want applied are, for example, the formats in which you want to make this video available, or the logo you want watermarked throughout it. Conversions are performed by conversion scripts (identified by unique IDs-see Conversion ID Reference) that yospaceCDS runs for you before making the media available for retrieval.
  • Script Parameters
    Some conversions need additional parameters or media. Parameters are provided as name-value pairs. For example,  if you are stamping a logo onto all frames of a video, or splicing a two-second splash at the start, you need to nominate which logo graphic or splash clip to use. Assuming that media is also stored in yospaceCDS, the script may require its content ID.
  • Submitter
    Converting content is restricted in the same way as uploading. Access is  limited to those with authority to add content to the database.
  • Notification URL
    Preparing the content for retrieval (specifically, running it through all the conversions required) is not instant, especially for large files or complex conversions. You provide a call-back URL that yospaceCDS will use to notify you when the content is available for retrieval (that is, when the conversion script has finished). If for any reason the conversion script fails, yospaceCDS can notify you via a failure call-back URL. You can leave the notification URLs blank if you do not want to implement a call-back URL, but if you do that you will not know when your content is ready, or if the conversion failed.
There are other fields that can be sent with the upload request-see Request Fields for details. 

Example Conversion Request XML

The following XML is an example conversion request. It is issued when the upload response has been received-this provides the unique content ID that yospaceCDS needs in order to reference any of the content in the media farm.

<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>
    
<scriptParameter>
    <key>key1</key>    
    <value>value1</value>
</scriptParameter>
    
<scriptParameter>    
    <key>key2</key>  
    <value>value2</value>   
</scriptParameter>

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

Example Conversion Response XML

When yospaceCDS receives the conversion request, it schedules the conversion script 13 to run (specified by conversionId).  yospaceCDS confirms your request synchronously. This only tells you that the job has been added to the queue for processing (or else, why it was not)-this does not mean that the conversion itself has been performed. 

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

The status maps to a success code (200 = success), meaning that the conversion is now a job in the queue, waiting to be processed. yospaceCDS also returns the unique ID that it has assigned to this job. You can use this later to query the current status of the job. yospaceCDS runs the conversion as soon as it can. When it has completed, it sends a request to the notification URL (you provided the URL in your initial request, either successUrl or failureUrl, depending on the result). As before, it's important that you ensure these URLs contain a unique reference to this conversion request-in this case, myId, with a unique value of 45-because yospaceCDS does not include one in its response. If you don't do this, and you've submitted many conversion requests, you won't know to which one this notification applies. A conversion script may be able to produce multiple output types (for example, mp4 format video at 30, 60 or 90 frames per second). The script issues a variant ID to distinguish which type it has produced. When yospaceCDS notifies you of conversion completion, it adds the variant ID of the converted content as an additional parameter on the URL. It also adds the MIME type it has generated, and the output message, if any, from the script. The variant ID is important-you need it to construct the URL for the converted content. See the following section to see this in use. For the example given above, success would result in a call being made to a URL like this:

http://www.site.com/callback.pl?myId=45&mimetype=video/mp4&variant=1977&log=ok

If the conversion fails, the URL would look something like this:

http://www.site.com/callback_on_error.pl?myId=45&log=fail

In this case, note that the failure URL (rather than the success URL) is being used, and the only parameter provided by yospaceCDS is the log, which contains the error message from the conversion script.

Get the Video Back Out

The video is available from yospaceCDS via a unique URL. The URL contains the variant ID that was returned by the conversion notification.

For example, a download URL may look like this:

http://d.cds1.yospace.com/u/file~video_mp4~1001-1/2/1/2/3/4/adsd/petshow

The URL for streaming rather than downloading may look like this:

rtsp://s.cds1.yospace.com/u/file~video_mp4~1001-1/2/1/2/3/4/adsd/petshow

For more details, see page 30, Retrieval URLs.