Content Media

New in MP 2.9:

With MP 2.9, Articles, reviews and events can have multiple media attached to it.

(also see ChangeLog)

A content object can have multiple media attached to it, so-called media slots. Each media slot has the following attributes:

• type
• title
• content (XML)
• thumbnail

Depending on the type, the media slot has additional attributes.

There are three main types of media that can be attached to a content object:

• file (an image or audio file from MP's file library)
• embed (embed code, e.g. from a video service)
• external (asset from a CDN or one of the providers recognized by MP)

An external asset is split up into the following subtypes:

• youtube
• vimeo
• soundcloud
• audio
• video

External assets of the type youtube, vimeo or soundcloud have the required attribute url while external assets of the type audio or video have the required attribute urls which is a list of information about the different urls for that specific media slot (see external assets).

The content object's media will be presented to the MP website's visitors similar to a slideshow, i.e. the website visitor can move back and forth between the media and can view a gallery of thumbnails of all media for that content object.

Goal

In the last chapter, we created an article:

• Title: My Last Trip to Rome
• UUID: 11111111-1111-1111-1111-111111111111

In this chapter, we want to spruce it up a little with a picture, two videos and an audio report of the trip. The image has already been uploaded to the MP instance (see The File Library):

• Image
  • UUID: ffffffff-ffff-ffff-ffff-ffffffffffff

Let's say one video was uploaded to YouTube, one uploaded to a different video service that allows embeding of the video on another website, and the audio report is stored on a CDN.

Adding Media

As mentioned in the introduction to this chapter, all media can have a title, (xml-compliant [1]) content and a thumbnail. The respective parameters (title, content, thumb_uuid) are optional. If no thumbnail is specified for a media object, either a default thumbnail is used or, in the case of an image from the file library, the image is resized and used as thumbnail.

The API resource POST /{iid}/content/{uuid}/media is used to add one media slot to the possibly existing list of media of a content object. See Setting a Content Object's Media for a way to replace the entire list of media in one call.

Image from File Library

The first media we want to attach to the article (UUID: 11111111-1111-1111-1111-111111111111) is an image (UUID: ffffffff-ffff-ffff-ffff-ffffffffffff) that already exists in the MP instance's file library:

>>> POST("/123/content/11111111-1111-1111-1111-111111111111/media",
...      {"type": "file",
...       "title": "Beautiful View of Rome at Night",
...       "content": "<p>I took this picture from the balcony of my hotel room.</p>",
...       "image_uuid": "ffffffff-ffff-ffff-ffff-ffffffffffff"})
{'msg': 'media added'}

The parameter type declares this media to be from MP's file library, which means this is an internal link between two objects inside the MP instance's database: an article and an image. Therefore, we need to specify the UUID of the image using the parameter image_uuid. This parameter is required for media slots of the type 'file'.

Embed

The second media we want to attach is a video that was uploaded to a video streaming service similar to YouTube and Vimeo. YouTube and Vimeo are services recongnized by MP and can be added as external asset (see External Assets).

>>> POST("/123/content/11111111-1111-1111-1111-111111111111/media",
...      {"type": "embed",
...       "embed_code": '<iframe width="420" height="315" src="//www.videoservice.com/path/to/file" frameborder="0" allowfullscreen></iframe>'})
{'msg': 'media added'}

External Assets

External assets are created using the parameter type='external' and a specfic subtype (url_type). If the parameter type of a media slot is set to 'external', the parameter url_type becomes required. The additional parameter url or urls is required depending on the value set in url_type.

YouTube, Vimeo, SoundCloud

MP recognizes the video/audio streaming providers YouTube, Vimeo and SoundCloud which means we can easily add such media slots by sending, for example, the YouTube url to the POST /{iid}/content/{uuid}/media resource:

>>> POST("/123/content/11111111-1111-1111-1111-111111111111/media",
...      {"type": "external",
...       "url_type": "youtube",
...       "url": "http://youtu.be/OSGv2VnC0go"})
{'msg': 'media added'}

Similarly, Vimeo and SoundCloud media slots can be added by sending the following to the resource:

POST("/123/content/11111111-1111-1111-1111-111111111111/media",
     {"type": "external",
      "url_type": "vimeo",
      "url": "http://vimeo.com/40375317"})

POST("/123/content/11111111-1111-1111-1111-111111111111/media",
     {"type": "external",
      "url_type": "soundcloud",
      "url": "https://soundcloud.com/david-greilsammer/mozart-piano-concerto-no-9"})

CDN Audio, CDN Video

The next media slot we'll add to the article is an audio file. Actually, it is a list of URLs to audio files in different codecs. MP uses the HTML 5 audio (and video) tags to play audio (and video) files. For a more detailed explanation of HTML 5 audio (and video) and the complications, please read Dive Into HTML 5 - Video on the Web.

Suffice to say, when adding CDN audio and video media slots, you usually need to a provide a list of URLs to a file in different codecs in order for the media to play in various browsers.

The following request sent to the POST /{iid}/content/{uuid}/media resource adds a CDN Audio media slot providing URLs for two differently encoded audio files:

>>> POST("/123/content/11111111-1111-1111-1111-111111111111/media",
...      {"type": "external",
...       "title": "Media 4",
...       "image_uuid": "ffffffff-ffff-ffff-ffff-ffffffffffff",
...       "url_type": "audio",
...       "urls": [{"url": "http://www.cdndomain.com/files/rometrip.mp3"},
...                {"url": "http://www.cdndomain.com/files/rometrip.ogg",
...                 "mimetype": "audio/vorbis"}]
...      })
{'msg': 'media added'}

The two items in the list of urls are slightly different: one has a mimetype, the other doesn't. Though sending the mimetype for each URL is not required, it is advised to always sent the mimetype for each URL.

Retrieving a Content Object's Media

Now that we've added several media slots to our article (UUID: 11111111-1111-1111-1111-111111111111), we can retrieve a list of these media slots by sending a GET request to /{iid}/content/{uuid}/media:

>>> GET("/123/content/11111111-1111-1111-1111-111111111111/media")
{'items': [{'content': '<p>I took this picture from the balcony of my hotel room.</p>',
            'image_mimetype': 'image/jpeg',
            'image_url': 'https://api.metropublisher.com/123/files/ffffffff-ffff-ffff-ffff-ffffffffffff',
            'image_uuid': 'ffffffff-ffff-ffff-ffff-ffffffffffff',
            'slot_uuid': '...',
            'thumb_mimetype': None,
            'thumb_url': None,
            'thumb_uuid': None,
            'title': 'Beautiful View of Rome at Night',
            'type': 'file'},
           {'content': None,
            'embed_code': '<iframe width="420" height="315" src="//www.videoservice.com/path/to/file" frameborder="0" allowfullscreen></iframe>',
            'slot_uuid': '...',
            'thumb_mimetype': None,
            'thumb_url': None,
            'thumb_uuid': None,
            'title': None,
            'type': 'embed'},
           {'content': None,
            'slot_uuid': '...',
            'thumb_mimetype': None,
            'thumb_url': None,
            'thumb_uuid': None,
            'title': None,
            'type': 'external',
            'url': 'http://youtu.be/OSGv2VnC0go',
            'url_type': 'youtube'},
           {'content': None,
            'image_mimetype': 'image/jpeg',
            'image_url': 'https://api.metropublisher.com/123/files/ffffffff-ffff-ffff-ffff-ffffffffffff',
            'image_uuid': 'ffffffff-ffff-ffff-ffff-ffffffffffff',
            'slot_uuid': '...',
            'thumb_mimetype': None,
            'thumb_url': None,
            'thumb_uuid': None,
            'title': 'Media 4',
            'type': 'external',
            'url_type': 'audio',
            'urls': [{'mimetype': None,
                      'url': 'http://www.cdndomain.com/files/rometrip.mp3'},
                     {'mimetype': 'audio/vorbis',
                      'url': 'http://www.cdndomain.com/files/rometrip.ogg'}]}]}

Depending on the media slot's type (and where available url_type), the individual items in the returned list contain different information. For example, the first item is a file from MP's file library (type = 'file') and has image_* information while the second item is an embed media slot (type = 'embed') and has embed_code information but no image_* information.

Setting a Content Object's Media

Attention

Using this resource overwrites the existing media slots of the content object.

In the section adding media, we created individual media slots and appended them to the content object's list of media. There's an easier way to set the entire list of media using the PUT /{iid}/content/{uuid}/media resource:

>>> PUT("/123/content/11111111-1111-1111-1111-111111111111/media",
...     {'items': [{"type": "file",
...                 "title": "Beautiful View of Rome at Night",
...                 "content": "<p>I took this picture from the balcony of my hotel room.</p>",
...                 "image_uuid": "ffffffff-ffff-ffff-ffff-ffffffffffff"},
...                {"type": "external",
...                 "url_type": "youtube",
...                 "url": "http://youtu.be/OSGv2VnC0go"}]})
{'msg': 'media updated'}

This resource takes the parameter items. Each item of the list defines one media slot.

Footnotes

[1]	The content field of media slots allows XML-compliant HTML, with restrictions. The field value must comply with the html_text.rng schema shown in RelaxNG Schema for XML-compliant HTML.