Media Retrieval: Getting Content Out

This section describes the two types of CDS download:

  • variant content, which has been processed, or converted, before it is requested
  • dynamic content, which yospaceCDS processes whenever it is requested

Retrieval URLs

Content is retrieved from yospaceCDS with a simple URL. The URL contains the media content's unique ID together with the conversion ID of the derivative from the original upload. Typically the conversion ID describes a format change.

The basic URL looks like this:

protocol://host/accessType/format/err/addressType/contentid[?name=title]

Where the components of the URL are as follows:

  • protocol
    Use http for download, or rtsp for streaming. The server you use depends on the protocol, so the protocol and host combined must be one of the following:
    • http://d.cds1.yospace.com for downloads
    • rstp://s.cds1.yospace.com for streaming
  • host
    The address of host server, which depends on the protocol you have specified (see above). When you create the URL you should check if there are multiple servers from which to choose-typically an implementation may have many proxy servers and you should pick them in a round-robin fashion.
  • accessType
    The method of access restriction, if any. Possible values are:
    • u
      unrestricted any access is permitted (standard).
    • r-<downloadWindow>-<token>
      restricted access: downloads are only permitted before the window specified expires and the URL can be authenticated with the token provided. See the note on Restricted Access below.
  • format
    The format definition of the required output format (equivalent to the MIME type). For typically variant retrieval, this also includes the conversion ID and the variant-see the note on Format Definition below.
  • err
    An integer representing the error domain of any error content returned (typically related to the service). The error domain allows yospaceCDS to send appropriately branded errors if there is a problem, such as a bad URL or an unauthorised attempt to view restricted content. The domain will usually be the same for all of an operator's requests, so usually you will always use the same domain. Alternatively, use 0 for the default, generic unbranded error domain. 
  • addressType
    the address type, which must be set to m
  • contentId
    the path to the content. yospaceCDS provided the content ID in its conversion response-see Variant ID.
  • ?name=title
    An optional query string parameter for streaming URLs only, which sets the name of the content to the value of title as viewed in some streaming clients (for example, RealPlayer on Nokia handsets)

Restricted Access

Content which is unrestricted can be freely downloaded.

Content which is restricted is only available to download if the requester provides an authenticated secret key-furthermore this key is only active for a limited duration (specifically, within a time window). For example, this mechanism allows media content to be made available only to users who have just purchased it.

You need to use yospaceCDS authentication library to generate keys. These are included in the URLs as shown above. Refer to the library API documentation for details.

Format Definition

The format definition describes the required output format. It has the general form:

<adapter>[~<adapter specific parameters>]

The adapter indicates the type of handler. Typical values are one of the following:

  • file - no further processing
    Content which has already been processed by a conversion script falls into this category, that is, variant content. You must specify a MIME type in the format-see the note below.

module - specific named module with special effects on a per-module basis

File Handlers (MIME type, conversion ID, variant

For file-type handlers, the adapter-specific parameters will be the MIME type, with hyphens replaced with underscores:

file~<mimeType>~<conversionId-variant>

For example, file~image_jpeg~1203-foo would indicate a pass-through handler request for a JPEG image of variant foo produced by conversion script 1203 (where foo might indicate a predefined scaling and image quality for this conversion, for example). Since file-type handlers are really just returning content, the MIME type must be explicit because no processing is performed on the content itself to determine what it is. That is, yospaceCDS uses the MIME type that is in the URL as the MIME type of the returned content. See the example URLs below to see this in context.

Summary of URL Composition

See the previous section for details of each of the components shown in this diagram.

Content Retrieval URL Composition

Example URLs

The following are examples of URLs generated for content retrieval. Note that, because they are long, most of these URLs are wrapped over two lines.

http://d.cds1.yospace.com/u/file~video_mpeg~13-foo/0/m/1/2/3/4/abcd/petshow

This is the URL for unrestricted media content that has been processed by a conversion script (conversion ID 13). In this case, it’s a MPEG video. The conversion ID is 13 and the variant is foo.

http://d.cds1.yospace.com/r-12344556-0123456789abcdef/file~video_mpeg~13-foo/0/m/1/2/3/4/abcd/petshow

This URL is for an image similar to the previous example, except that this time it is restricted and will only be released if the key and time window are successfully authenticated.

rtsp://s.cds1.yospace.com/u/file~video_mpeg~3-99/0/m/7/4/5/5/fdrf/feast?title=Dog%20Biscuit

This is identical to the previous example, except that it is being streamed rather than downloaded.

Converted Media Content

The commonest form of retrieval is to request variant content, that is, content that is the result of a previously-run conversion. Remember that you can only retrieve converted media if you have the variant ID for it, that is, yospaceCDS sent a confirmation request to indicate that the conversion had been successfully completed.

This is converted media content because the conversion was applied before the download request was made. Effectively the download is retrieving a static file.

Use the file adapter, the conversion ID and the variant together as follows:

http://d.cds1.yospace.com/u/file~mimeType~conversionID-variant/0/m/contentId