Creating a MediaItem

All MediaItem objects must belong to a Content Group.  If you are intending to use yospaceCDS as an unstructured store, then you simply need to create a single Content Group in your account and assign all MediaItems to that.  There is no limit to the number of MediaItem objects that can exist within a Content Group.  

However, if you would like to output items from yospaceCDS within feeds (however for performance reasons, you should limit your output feeds to less than 1,000 items), then you will need to create the Content Groups you need, and assign these to the appropriate Output Feeds.  More information can be found on our chapters covering Content Groups and Output Feeds.

The create MediaItem call supports the following parameters:

Standard Parameters

Account Name (username)

The username you use to log in to the yospaceCDS Content Management Console

Password (password)

The password associated with the username you use to log in to the yospaceCDS Content Management Console

URL to Asset to Upload (contentUrl)

an internet accessible URL of the video content. Supported video formats are described in our Quick Start Guide.

Content Group ID (contentGroupId)

you must create at least one Content Group within the yospaceCDS Content Management interface and use this ID.

HQ Processing Required (hq)

specify true or false depending on whether you want H.264 processing on your video content. H.264 processing improves the quality of video for modern SmartPhone devices. It is recommended that you set this value to 'true'.

Large Format Required - optional - (largeFormat)

specify true or false depending on whether you want the video available in a large format suitable for the iPad. This option makes the content available in 640x360 (or 512x384 for 4:3) subject to the source content being available in the same or higher resolution.  This parameter is optional, and defaults to false if not supplied.

MIME type - optional- (mimeType)

the MIME type of the uploaded content (if different from the MIME type given by the server)

RSS Publish Date (rssPubDate)

the publishDate of the video (used for RSS output feeds to determine ordering).  If you do not set this, the time and date of ingestion is used instead. [

Dates are specified in the format as determined by xsd:dateTime which follows the form defined by Chapter 5.4 in ISO 8601, which is:

 ­CCYY-MM-DDThh:mm:ss[Z|(+|-)hh:mm] 

The time zone may be specified as Z (UTC) or (+|-)hh:mm. Time zones that aren't specified are considered undetermined.

Example valid timestamps are:

• 2009-10-26T21:32:52
• 2009-10-26T21:32:52+02:00
• 2009-10-26T19:32:52Z
• 2009-10-26T19:32:52+00:00

RSS Item Title - optional - (rssTitle)

the title of the video, as shown in an RSS Feed or on the User Choice Page

RSS Item Description - optional- (rssDescription)

the description of the video, as shown in an RSS Feed or on the User Choice Page

RSS Teaser Text - optional - (rssTeaserText)

Thumbnail URL - optional - (thumbnailUrl)

a URL of a thumbnail image that will be associated with the video within an RSS Feed.  If you do not set this and publish this item via an RSS Feed, a default thumbnail grabbed from a few seconds into the video will be used instead.

Usage Profile ID - optional - (usageProfileId)

If you want the content to be ingested under a specific Usage Profile, then specify the ID of the Usage Profile using this parameter. You will need to obtain the ID of your Usage Profile from Yospace Support.

Cue Points - optional - (cuePoints)

Specify a comma separated list of cue points (defined as floating point numbers in seconds). For example:

23.4, 102.3, 201.42

yospaceCDS will ingest the content and make cut points at the specified times in the video. These cut points can then be used for mid-roll dynamic insertion of advertising.

Set metadata fields (metadata)

Field Name fieldName

The name of the field to be set.

Field Value value

The value to be set.

Status Update Callback - optional - (URLstateChangeUrl)

The URL to use for status callbacks. If omitted, no callbacks are made.

MD5 checksum - optional - (checksum)

yospaceCDS will compute an MD5 checksum of the content it acquires and compare this against this parameter, if it supplied. If the checksums do not match, the content ingestion fails.

Optional Content Adjustment Settings

The following optional parameters can be set to apply adjustments to the content before it is ingested into the yospaceCDS. To use this settings, we recommend reading the separate article on Content Adjustment Settings.

Aspect Switch Policy (aspectSwitchMethod)

How the frame size will be adjusted to fit a target different aspect ratio. Valid values are BOX, CROP, CROPNBOX and STRETCH. If not specified, the default value is CROP

Min and Max Aspect Ratio (minAspectRatio and maxAspectRatio)

When using the Aspect Switch Policy "Crop and Box" these values determine the emphasis on crop versus box to achieve the target aspect. Floating point numbers allowed.

Deinterlace Content (deinterlaceContent)

Whether or not to apply a deinterlacing filter. Valid values are true or false.

End Crop (endCutSeconds)

Allows you to specify a number of seconds from the end of the video to cut, thus making video shorter by the number of seconds you specify. Floating point numbers allowed.

Start Crop (startCutSeconds)

Allows you to specify a number of seconds of video to chop from the beginning. Floating point numbers allowed.

Horizontal and Vertical Crop (horizontalCropPercentage and verticalCropPercentage)

Crops the specified percentage from the vertical or horizontal dimension of the frame. Floating point numbers allowed.

Thumbnail Snapshot Position (thumbnailPointSeconds)

Determines the number of seconds into the video where the default thumbnail snapshot will be taken. Floating point numbers allowed.

Volume Multiplier (volumeMultiplier)

Determins the volume adjustment made to the audio track. Floating point numbers allowed.

An example MediaItem creation request:

In the response, you will receive status code of your request, and if successful, the MediaItem ID. You can use this MediaItem in calls to the MediaItem Status and Deletion calls, as well as using to create your own Access URLs to create a single URL that all devices can use to access the video. 

Possible status code (with descriptions) are as follows:

• 200, OK
• 602, BAD_CONTENT_GROUP_ID
• 604, USER_DOES_NOT_OWN_RESOURCE
• 601, AUTHENTICATION_FAIL
• 599, GENERAL_ERROR

An example successful response is given below:

Setting Metadata

R2.4.1 of yospaceCDS introduced the ability to set metadata at the same time as creating the Media Item (previously, a separate call was required to set the metadata after creating it). Here is an example of the creation request including metadata fields.

Geo-Restricting Items

It is possible set the geo-restriction policy on an item via the Media Item API.  yospaceCDS uses metadata fields to determine the geo-restriction policy for a given item, therefore to do this via the MediaItem API is simply a matter of setting these fields appropriately.

To be able to set the geo-restriction status of an item via this MediaItem API (or for that matter, via RSS input feeds), your account must have these fields defined within its Metadata Setup.

To understand how the geo restriction fields are defined, see the explanation on this page.

The following example assumes that the account is set-up with the fields Restriction and Restriction Relationship.  Please note that when using the MediaItem API to define metadata fields, you should use the display name.