2015-09-01-player.html

---
layout: post
title: Player API Documentation
weight: 0
category: player-api
categoryItemType: documentation
categoryItemIsShown: 1
categoryItemWidth: 6
categoryItemDescription: Control the features of the IBM Cloud Video player and customize its layout, while maintaining a continuous, interactive data connection with Ustream’s backend. Embed the player anywhere and manage it according to your needs and preferences.
categoryItemLabel: Read the documentation
--- 

<article data-sidenav="sidenav">
                <section>
                    <h2>Overview</h2>
                        <p>Enables sites using the <a href="https://video.ibm.com/" target="_blank">IBM Cloud Video</a> embed iframe to build and adapt on the embed live player.</p>
                        <p>The Player API provides basic methods to control the live stream or recorded video playback, and enables the user to access essential events of the live stream or the played video.</p>
                        <p>The Player API requires <a href="http://www.w3.org/TR/webmessaging/" target="_blank">postMessage</a> DOM API, it won't work in browsers that does not support the postMessage API.</p>
                </section>
                
                
                
                <section>
                    <h2>Usage</h2>
                    <p>Create an instance of the Embed API by providing the ID of the iframe, or the iframe DOM object itself:</p>
                    <pre><code class="html">&lt;iframe id=&quot;UstreamIframe&quot; src=&quot;//www.ustream.tv/embed/1524&quot; width=&quot;640&quot; height=&quot;480&quot; allowfullscreen webkitallowfullscreen&gt;&lt;/iframe&gt;</code></pre>
                    <pre><code class="javascript">var viewer = UstreamEmbed('UstreamIframe');</code></pre>
                    
					
				
					<h3>URL parameters</h3>
					<p>The default behaviour of the player can be modified by extending the src URL with any of the following parameters:</p>
                    <table class="table responsive">
						<thead>
							<tr>
								<th>Parameter</th>
								<th>Effect</th>
								<th>Values</th>
								<th>Default</th>
							</tr>
						</thead>
						<tbody>
							<tr>
								<td>allowfullscreen</td>
								<td>Disables fullscreen and remove the button.</td>
								<td>true/false</td>
								<td>true</td>
							</tr>
							<tr>
								<td>autoplay</td>
								<td>Starts video playback automatically.</td>
								<td>true/false</td>
								<td>false</td>
							</tr>
							<tr>
								<td>controls</td>
								<td>Hides all UI elements.</td>
								<td>true/false</td>
								<td>true</td>
							</tr>
							<tr>
								<td>offaircontent</td>
								<td>Disables displaying offair content.</td>
								<td>true/false</td>
								<td>true</td>
							</tr>
							<tr>
								<td>quality</td>
								<td>Overrides the automatic quality selection.</td>
								<td>low, med, high, auto</td>
								<td>auto</td>
							</tr>
							<tr>
								<td>showtitle</td>
								<td>Hides title and viewer count.</td>
								<td>true/false</td>
								<td>true</td>
							</tr>
							<tr>
								<td>volume</td>
								<td>Overrides the default volume. 0 is mute, 1 is max volume.</td>
								<td>0.0-1.0</td>
								<td>user setting</td>
							</tr>
						</tbody>
					</table>
                    
                    <h3>callMethod</h3>
                    <p>Calls a command method of the embed player, passing in any arguments.<br/>Available commands through <code>callMethod</code>:</p>

                    
                    <h4>play</h4>
                    <p>Starts playing the currently loaded channel or video.</p>

                    <h6>Example</h6>
                    <pre><code class="javascript">viewer.callMethod('play');</code></pre>
                    
                    
                    <h4>pause</h4>
                    <p>Pauses the live stream, or the playback of a video.</p>

                    <h6>Example</h6>
                    <pre><code class="javascript">viewer.callMethod('pause');</code></pre>
                    
                    
                    <h4>stop</h4>
                    <p>Pauses the live stream, or stops the video and jumps back to the start.</p>

                    <h6>Example</h6>
                    <pre><code class="javascript">viewer.callMethod('stop');</code></pre>
                    
                    
                    <h4>load</h4>
                    <p>Loads a channel or a video in the player. Requires two additional arguments:</p>
                    <ul>
                        <li><code>type</code> - the loaded content type (channel | video)</li>
                        <li><code>id</code> - the loaded content id</li>
                    </ul>

                    <h6>Example</h6>
                    <pre><code class="javascript">viewer.callMethod('load', 'video', 5903947);
viewer.callMethod('load', 'channel', 1524);</code></pre>
                    
                    
                    <h4>seek</h4>
                    <p>Jumps to given position in played recorded video. Requires one argument:</p>
                    <ul>
                        <li>position in seconds</li>
                    </ul>

                    <h6>Example</h6>
                    <pre><code class="javascript">viewer.callMethod('seek', 180);</code></pre>
                    
                    
                    <h4>volume</h4>
                    <p>Sets the playback sound volume. Requires one argument:</p>
                    <ul>
                        <li>volume percent between 0-100</li>
                    </ul>

                    <h6>Example</h6>
                    <pre><code class="javascript">viewer.callMethod('volume', 0); //mute</code></pre>
                    
                    
                    <h4>quality</h4>
                    <p>Sets the stream quality, if available. Requires one argument:</p>
                    <ul>
                        <li>a <code>qualityID</code> key from received quality options in <code>quality</code> event</li>
                    </ul>

                    <h6>Example</h6>
                    <pre><code class="javascript">viewer.callMethod('quality', 16); //set to high</code></pre>
			
		    <h4>cc (closed caption)</h4>
                    <p>Enables the selected closed caption if available. Requires one argument:</p>
                    <ul>
                        <li>a <code>ccIndex</code> key from the received closed caption array in <code>cc</code> event</li>
                    </ul>

                    <h6>Example</h6>
<pre><code class="javascript">viewer.callMethod('cc', 1); //enable the closed caption with index 1</code>
<code class="javascript">viewer.callMethod('cc', -1); //disables the closed caption</code></pre>

										<h4>multi audio</h4>
										<p>Sets the audio language of the stream. Requires one argument:</p>
										<ul>
											<li>an <code>audioIndex</code> key from the received audio tracks array in <code>audio</code> event</li>
										</ul>

										<h6>Example</h6>
										<pre><code class="javascript">viewer.callMethod('audio', 1); //select audio track with index 1</code></pre>

                    <h3>getProperty</h3>
                    <p>Read a property of the embed player. This method is <strong>asynchronous</strong>, the data will be passed to a callback function, given as argument.<br/></p>
                    <p>Accessible properties by <code>getProperty</code>:</p>
                    
                    <h4>duration</h4>
                    <p>Get the video duration in seconds.</p>

                    <h6>Example</h6>
                    <pre><code class="javascript">viewer.getProperty('duration', function (duration) {
    ...
});</code></pre>
                    
                    
                    <h4>viewers</h4>
                    <p>Get the current viewer count for the loaded live stream.</p>

                    <h6>Example</h6>
                    <pre><code class="javascript">viewer.getProperty('viewers', function (viewerNumber) {
    ...
});</code></pre>
                    
                    
                    <h4>progress</h4>
                    <p>Get the current progress for recorded video playback, in seconds.</p>

                    <h6>Example</h6>
                    <pre><code class="javascript">viewer.getProperty('progress', function (progress) {
    ...
});</code></pre>
                    
                    
                    <h4>content</h4>
                    <p>Get the current content type and id as an array.</p>

                    <h6>Example</h6>
                    <pre><code class="javascript">viewer.getProperty('content', function (content) {
    // content == ['channel', 1524]
    // or
    // content == ['recorded', 123456]
    ...
});</code></pre>
					
					<h4>playingContent</h4>
                    <p>Get the actual content type and id as an array. This will return the currently played offair video's id if the loaded content is an offair channel or with the channel id if the channel is live.</p>

                    <h6>Example</h6>
                    <pre><code class="javascript">viewer.callMethod('load', 'channel', 1524);

// ...

viewer.getProperty('playingContent', function (content) {
    // content == ['channel', 1524]
    //  - if it's live, or
    // content == ['recorded', 123456]
    //  - if it's offair and has offair video content, or
    // content == []
    //  - if it's offair and doesn't have offair video content
});</code></pre>
                    
                    
                    
                    <h3>addListener &amp; removeListener</h3>
                    <p>The embed player dispatches several events during playback. This method adds or removes event handlers to these events.</p>
                    <p>The event handler callback receives two arguments:</p>
                    <ul>
                        <li><code>type</code> the type of the event</li>
                        <li><code>data</code> optional data sent along the event</li>
                    </ul>
                    <p>Available events for <code>addListener</code> and <code>removeListener</code>:</p>
                    
                    
                    <h4>live</h4>
                    <p>Called when the currently loaded offline channel becomes live.</p>

                    <h6>Example</h6>
                    <pre><code class="javascript">viewer.addListener('live', callBack);</code></pre>
                    
                    
                    <h4>offline</h4>
                    <p>Called when the currently loaded live channel goes offline.</p>

                    <h6>Example</h6>
                    <pre><code class="javascript">viewer.addListener('offline', callBack);</code></pre>
                    
                    
                    <h4>finished</h4>
                    <p>Called when the currently loaded and played recorded video reaches its end.</p>

                    <h6>Example</h6>
                    <pre><code class="javascript">viewer.addListener('finished', callBack);</code></pre>
                    
                    
                    <h4>playing</h4>
                    <p>Called when the currently loaded content playback is started or stopped. Sends data along the event:</p>
                    <ul>
                        <li><code>playing</code> (boolean)</li>
                    </ul>

                    <h6>Example</h6>
                    <pre><code class="javascript">viewer.addListener('playing', callBack);</code></pre>
                    
                    
                    <h4>size</h4>
                    <p>Called when the stream size is available, or changed (changes reported only in flash mode). Sent data is the size of the calculated embed iframe according to the player width, and the stream aspect ratio. The player bar height is included, if the controls are visible.</p>
                    <p>Sends data along the event:</p>
                    <ul>
                        <li><code>size</code> (array) as [<code>width</code>, <code>height</code>] in pixels</li>
                    </ul>

                    <h6>Example</h6>
                    <pre><code class="javascript">viewer.addListener('size', callBack);</code></pre>
                    
                    
                    <h4>quality</h4>
                    <p>Fired when the stream quality options are available.</p>
                    <p>Receives an object, with the <code>qualityID</code> as keys, and an object with two properties as values:</p>
                    <ul>
                        <li><code>label</code> (string) label to show to users on control UI, eg.: "480p"</li>
                        <li><code>active</code> (booelan) if this quality is used or set</li>
                    </ul>

                    <h6>Example</h6>
                    <pre><code class="javascript">viewer.addListener('quality', callBack);</code></pre>
                    <pre><code class="javascript">// example quality object
{
    "0":{"label":"240p","active":false},
    "1":{"label":"360p","active":false},
    "2":{"label":"480p","active":false},
    "16":{"label":"BEST","active":true}
}</code></pre>
			
		    <h4>cc (closed caption)</h4>
                    <p>Fired when there are closed captions available on the stream.</p>
                    <p>Returns an array containing closed captions as objects.</p>
                    <ul>
			<li><code>index</code> (integer) unique index of the closed caption</li>
			<li><code>label</code> (string) label of the closed caption</li>
                        <li><code>language</code> (string) language code of the closed caption (en, etc.)</li>
                        <li><code>active</code> (booelan) if this closed caption is shown</li>
                    </ul>

                    <h6>Example</h6>
                    <pre><code class="javascript">viewer.addListener('cc', callBack);</code></pre>
                    <pre><code class="javascript">// example cc object
[
    {"index":0, "label":"English", "language":"en", "active":false}
]</code></pre>

										<h4>multi audio</h4>
										<p>Fired when there are multiple audio tracks.</p>
										<p>Returns an array containing audio tracks as objects.</p>
										<ul>
											<li><code>index</code> (integer) unique index of the audio track</li>
											<li><code>label</code> (string) label of the audio</li>
											<li><code>language</code> (string) language code of the audio</li>
											<li><code>country</code> (string) country code of the audio</li>
											<li><code>active</code> (booelan)</li>
										</ul>

										<h6>Example</h6>
										<pre><code class="javascript">viewer.addListener('audio', callBack);</code></pre>
										<pre><code class="javascript">// example audio object
[
    { "index": 0, "label": "English (US)", "language": "en", "country": "US", "active": true },
    { "index": 1, "label": "French", "language": "fr", "country": "00", "active": false }
]</code></pre>

                    <h4>content</h4>
                    <p>Called when a the player content changes for some reason. Same data as received in <code>getProperty('content')</code></p>
                    <p>Received arguments: <code>data</code> (object)</p>

                    <h6>Example</h6>
                    <pre><code class="javascript">viewer.addListener('content', callBack);</code></pre>
                </section>
</article>