• Create a feed. Start by creating a universal feed. (For more details on how to manage syndications, please see the syndications section.)

  
  [POST] /v2/syndications
  
  {
      "name": "my custom feed",
      "type": "universal"
  }
  			

• Upload a custom template.

  
  [PUT] /v2/syndications/{syndication_id}/template
  
  <template body>
  

  The "syndication_url" property (found in the syndication object) contains the feed URL.

  If there are syntax errors in the template, the server will return an error message and the template will not be uploaded.

• Retrieve a custom template.

  
  [GET] /v2/syndications/{syndication_id}/template
  			

For template examples, see this reference.

A collection of all the assets in that syndication is available via the 'assets' collection. Each asset contains the following properties, available via the '.' (dot) operator.

asset.name
asset.description
asset.preview_image.url
asset.metadata["key"]
asset.duration
asset.flight_start_time
asset.flight_end_time
asset.created_at
asset.updated_at
asset.embed_code
asset.asset_type
asset.hosted_at
asset.uploaded_by_user
asset.aspect_ratio
asset.original_file_name
asset.closed_captions_url
asset.status
asset.external_id

Live stream assets (deprecated) also contain the following properties:

asset.primary_entry_point
asset.backup_entry_point
asset.is_flash
asset.is_ios
asset.encodings

You can easily access the streams available for each asset, by using the following properties:

asset.streams     // Non-remote assets
asset.abr_stream_urls // Non-remote assets
asset.stream_urls // Remote assets

Refer to the Streams section for details on each of these properties.

You can access labels through the asset.labels property. Refer to the Labels section for details.

Preview images

A preview image is the image that is shown in the player before the movie starts. The following properties are available for a preview image: "url", "width", and "height". For example:

asset.preview_image.url
asset.preview_image.width
asset.preview_image.height

You can set your own preview images for an asset using the assets API. If you do not set your own preview images, a default preview image will be used. There may be several different resolutions for a preview image (all having the same aspect ratio). You can specify one of the preview images using constraints on the height or width. For example,

asset.preview_image[height > 400].url
asset.preview_image[height <= 640].url
asset.preview_image[width >= 400].url
asset.preview_image[width = 320].url
asset.preview_image[max height].url
asset.preview_image[max width].url
asset.preview_image[min height].url
asset.preview_image[min width].url

If you specify a constraint of [height > 400], for example, then you will get the smallest preview image whose height is greater than 400. If there is no such image, then an empty string will be returned.

Streams

The meaning of a stream is different for different asset types.

Remote assets

Remote assets have a stream_urls property with the following sub-properties:

asset.stream_urls.flash
asset.stream_urls.iphone
asset.stream_urls.ipad
asset.stream_urls.itunes
asset.stream_urls.source_file

These correspond to the asset properties set through the API; see the documentation under [assets] for more information.

Non-Remote Assets (Video, Ad)

For regular assets, streams are available through the special asset.streams collection. Items in this collection have the following properties:

asset.streams.audio_codec
asset.streams.container      // container format - mp4, 3gp, etc.
asset.streams.file_size      // specified in bytes
asset.streams.url            // not available for filtering
asset.streams.video_bitrate  // specified in kbs
asset.streams.video_codec
asset.streams.video_height
asset.streams.video_width

Example: Print video dimensions for all streams:

{% for stream in asset.streams %}
  width:{{ stream.video_width }}
  height:{{ stream.video_height }}
{% endfor %}

The streams collection can be filtered using a the bracket notation according to any of these properties (except url), as well as the following device classes:

iphone
ipad

These device classes will include only streams playable on the named devices. If multiple filters are given, only streams matching all of them will be included. Note that numeric fields may use inequalities, while only equality is valid for non-numeric fields.

Example: Print urls for all streams with width at least 640 using the MP4 container format:

{% for stream in asset.streams[video_width >= 640, container = mp4] %}
  {{ stream.url }}
{% endfor %}

Example: Print resolutions of iPhone compatible streams with file size less than 5 MB:

{% for stream in asset.streams[iphone, file_size < 5242880] %}
  {{ stream.video_width }}x{{ stream.video_height }}
{% endfor %}

Selecting individual streams

If a streams collection is used outside of a for loop, a specific stream will be chosen. The default is the highest bitrate stream matching all the constraints; an additional min or max constraint may be specified to modify this behavior.

Example: Print the bitrate of the widest stream:

{{ asset.streams[max video_width].bitrate }}

Example: Print the URL of the smallest iPad-compatible stream:

{{ asset.streams[ipad, min file_size].url }}

Example: Assign the highest-bitrate (by default) stream with width 640 to a variable and print some of its properties:

{% assign stream = asset.streams[width = 640] %}
<filesize>{{ stream.file_size }}</filesize>
<width>{{ stream.video_width }}</width>
<height>{{ stream.video_height }}</height>
<codec>{{ stream.video_codec }}</codec>

Empty stream sets

A stream set may be empty for some assets. In this case, all fields of streams in the set will empty. To avoid inserting empty fields into your feed, you can check the exists property of a stream or stream set.

Example: Print out an iphone feed if one exists:

{% if asset.streams[iphone].exists %}
  <stream type="iphone">
    <url>{{ asset.streams[iphone].url }}</url>
  </stream>
{% endif %}

Example: Print out a high-resolution stream if one exists, or a note to upload one if it doesn't

{% if asset.streams[video_width >= 720].exists %}
  <stream type="hd">
    <url>{{ asset.streams[iphone].url }}</url>
  </stream>
{% else %}
  <placeholder>HD stream needed</placeholder>
{% endif %}

ABR streams

An asset may also have ABR streams for iPhone and iPad as m3u8 files. These are available as part of the abr_stream_urls property of the asset:

asset.abr_stream_urls.iphone
asset.abr_stream_urls.ipad

Labels

The following properties are supported for labels:

label.id
label.name
label.full_name

For an example that displays the labels associated with assets, please see the template examples.

To restrict the assets in a feed to a label or set of labels, set the include_labels property on the universal syndication. (Please see syndications.) You can also set the labels for a syndication using the web interface, under the "Publish" tab.

There are two types of markup in templates: Output and Tag.

• Output markup (which may resolve to text) is surrounded by

  
  {{ matched pairs of curly braces }}
  

• Tag markup (which cannot resolve to text) is surrounded by

  
  {% matched pairs of curly braces and percent signs %}
  

Output

Example: print details about an asset:

"{{asset.name}}" was a great movie.
Description: {{asset.description}}

Filters

You can supply optional filters to output tags, in order to format and modify the resulting value.

Hello {{ "dave" | upcase }}
"dave" has {{ "dave" | size }} letters!

Multiple filters can be chained on a single output value.

capitalize     # capitalize words in the input sentence
downcase       # convert an input string to lowercase
upcase         # convert an input string to uppercase
size           # return the size of a string
strip_html     # strip html from string
strip_newlines # strip all newlines (\n) from string
newline_to_br  # replace each newline (\n) with html break
replace        # replace each occurrence e.g. {{ 'foofoo' | replace:'foo','bar' }} => 'barbar'
replace_first  # replace the first occurrence e.g. {{ 'barbar' | replace_first:'bar','foo' }} => 'foobar'
remove         # remove each occurrence e.g. {{ 'foobarfoobar' | remove:'foo' }} => 'barbar'
remove_first   # remove the first occurrence e.g. {{ 'barbar' | remove_first:'bar' }} => 'bar'
truncate       # truncate a string down to x characters
truncatewords  # truncate a string down to x words
prepend        # prepend a string e.g. {{ 'bar' | prepend:'foo' }} => 'foobar'
append         # append a string e.g. {{ 'foo' | append:'bar' }} => 'foobar'
date           # format a date e.g. {{ asset.updated_at | date: "%a, %b %d, %Y" }} => 'Thu, Jan 26, 2012'

Tags

Tags are used for the logic in your template.

comment
if
unless
case/when
for

Comment

You may add comments to your templates. It simply makes the content between the tags invisible.

There is some text {% comment %} here {% endcomment %} that will not be shown.

If / Else

You may write simple expressions in the if or unless (and optionally, elsif and else) clause:

{% if asset.name == "First" and asset.name != "loser" %}
  The winner is First
{% elsif asset.name == "Second" %}
  The winner is Second
{% endif %}

Case / When

To test for multiple values of a variable, you may use the case statement:

{% case template %}
{% when "label" %}
  {{ label.title }}
{% when "product" %}
  {{ product.vendor | link_to_vendor }} / {{ product.title }}
{% else %}
  {{ page_title }}
{% endcase %}

For loops

You may loop over collections:

{% for item in collection %}
  {{ item }}
{% endfor %}

In a for loop, the following helper variables are available for extra styling needs:

forloop.length  # => length of the entire for loop
forloop.index   # => index of the current iteration
forloop.index0  # => index of the current iteration (zero based)
forloop.rindex  # => how many items remain
forloop.rindex0 # => how many items remain (zero based)
forloop.first   # => is this the first iteration?
forloop.last    # => is this the last iteration?

You can also reverse the loop

{% for item in collection reversed %} {{item}} {% endfor %}

Power users

The feed template language is based on Liquid.

Language design details are available online.