API.md

Open Media Player

The Open Media Player is an online audio and video player that is designed to be simple to integrate into student, public and staff facing web sites at The Open University. It can be incorporated via an <iframe> or an oEmbed API.

The Open Medua Player has three variants:

1. OU Podcast player - audio and video hosted at OU Podcasts
2. OUVLE player - audio/video hosted on the OU's VLE
3. OpenLearn player - audio/video hosted on OpenLearn-LearningSpace/LabSpace

A note on Open Player installations:

1. The OU Player will be available at, https://mediaplayer.open.ac.uk and http://mediaplayer.open.edu
2. There will be an acceptance test install at, http://mediaplayer-acct.open.ac.uk
3. There is a development install at, http://mediaplayer-dev.open.ac.uk (behind the firewall)
4. Currently (Nov. 2012) there is a test install at, http://iet-embed-acct.open.ac.uk (public, to be deprecated)
5. Currently there is a live-beta install at, https://embed.open.ac.uk (to be deprecated)

If you use Embed.open.ac.uk at present you should be prepared to migrate to Mediaplayer.open.ac.uk in due course.

OU Podcast player -- API

We'll use as our example the Podcast video "Student views of the OU",

• http://podcast.open.ac.uk/pod/student-experiences#!db6cc60d6b

The Player currently supports individual podcast tracks, not whole collections. In the example above,

1. student-experiences is the collection identifier,
2. #! (shebang or hash-exclamation-mark) are the separators,
3. db6cc60d6b is the track identifier.

The above example is the short form of the URL. There is also a longer form and the two can be freely interchanged in the oEmbed API,

• http://podcast.open.ac.uk/oulife/podcast-student-experiences#!db6cc60d6b

..Where oulife is a Podcast category. There can be multiple categories, for example,

• http://podcast.open.ac.uk/oulearn/languages/spanish/podcast-l314-spanish#!fe481a4d1d

oEmbed endpoint

The endpoint for the oEmbed API is,

• Endpoint: https://mediaplayer.open.ac.uk/oembed
• Example: https://mediaplayer.open.ac.uk/oembed?url=http%3A//podcast.open.ac.uk/pod/student-experiences%23!db6cc60d6b

GET parameters

See this matrix for a comparison of the HTTP GET parameters supported by the various player variants.

• url : Required, standard oEmbed
• format: Optional, standard oEmbed, two possible values, format=json (default), format=xml; The output format
• maxwidth: Optional, standard oEmbed, integer pixels;
• maxheight: Optional, standard oEmbed;
• pcwidth: Optional, extension, experimental, integer; Use video width expressed as a percentage, pcwidth=0 (default), pcwidth=1 (100%), pcwidth=99 (99%) and so on,
• callback: Optional, extension; JSON-P callback function name, for example, callback=myFunction
• theme: Optional, extension; An OU Player theme name, for example, theme=oup-light (default)
• site_access: Optional, extension; How to display private podcasts on restricted-access sites, two possible values, site_access=public (default), site_access=private
• lang: Optional, extension; User-interface language/locale, lang=en, lang=zh-CN and so on.

OU-Drupal

The Drupal 6.x oEmbed module does not currently support custom additional parameters to oEmbed. As a workaround there is an extended endpoint - see below.

• Endpoint: https://mediaplayer.open.ac.uk/oembed
• Extended endpoint: https://mediaplayer.open.ac.uk/oembed/ex/name1:value1/name2:value2/..
• Example endpoint: https://mediaplayer.open.ac.uk/oembed/ex/theme:oup-light
• Schemes: http://podcast.open.ac.uk/*/*
• (Behind the scenes: https://mediaplayer.open.ac.uk/oembed/ex/theme:oup-light?url=http%3A//podcast.open.ac.uk/pod/student-experiences%23db6cc60d6b )

Important: remove the exclamation mark ! from the URL in Drupal node content.

jquery-oembed

The jQuery-oEmbed plugin (extended from Chamorro's plugin) is available via Embed.open.ac.uk.

A simple HTML example:

<a class="embed" href="http://podcast.open.ac.uk/pod/student-experiences#!db6cc60d6b">A video</a>

<script src="https://unpkg.co/[email protected]/dist/jquery.min.js"></script>
<script src="https://embed.open.ac.uk/scripts/jquery.oembed.js"></script>
<script>
  jQuery(function ($) {
    $('a.embed').oembed();
  });
</script>

An example with a custom parameter (theme: oup-light):

<script>
  jQuery(function ($) {
    $('a.embed').oembed(null, {
      oupodcast: {
        theme: 'oup-light'
      }
    });
  });
</script>

Iframe {#iframe}

This is the suggested syntax for a direct embed using a HTML5 <iframe> — example embed,

<iframe
  width="560"
  height="315"
  frameborder="0"
  src="https://mediaplayer.open.ac.uk/embed/pod/student-experiences/db6cc60d6b"
  allowfullscreen
>
</iframe>

Notes:

1. width="100%" is useful, it appears to be widely supported in browsers, but it is not valid HTML5 ("...valid non-negative integers"),
2. frameborder="0" is not valid HTML5. However, it is easier to override in stylesheets and more backwards-compatible than style="border:none",
3. allowfullscreen was not part of the HTML5 specification. It is needed to make fullscreen work (allowfullscreen is in a separate document, Mozilla page and bug tracker).
4. See also, embedding a YouTube player.