User Tools

Site Tools


player_api

JavaScript Player API

License

The use of this 'application programming interface - API' is subject to the creative commons license Attribution-NonCommercial-NoDerivatives 4.0 International License.

About

This API allows you to implement a JavaScript/jQuery based DIY.fm Player on your website. You can can completely customize the look of the player by creating your own stylesheet (css). You can also add more functionality using the player's JavaScript API.


Browser Support

The player is a beta version. Nevertheless, it has successfully been testet by the DIY.fm users for over a year now. It runs smoothly in most of the popular browsers:

Desktop:

  • IE Version >=8
  • Firefox (Win & Mac)
  • Safari (Win & Mac)
  • Chrome (Win & Mac)
  • Opera (Win & Mac)

Mobile:

  • iOS Safari
  • Android (native browser)

Developer Authentication

To use the DIY Player you must have a valid API key. If you don't have one yet:

  1. Request a developer API key by email, please let us know your DIY.fm user name.

Don't lose your API key, without it the player won't work.


Download

You can download the latest version of the player here. There is a working example included, you can use it as a starting point for your customization, if you like.


Setup

The DYI.fm player is based on jQuery and jQuery jPlayer. Therefore a couple of JavaScripts must be included in the header of your HTML document:

<!-- jQuery -->
<script src="http://code.jquery.com/jquery-1.10.2.min.js"></script>
<script src="http://code.jquery.com/jquery-migrate-1.2.1.min.js"></script>
 
<!-- jQuery UI -->
<script src="js/jquery-ui-custom.min.js"></script>
 
<!-- jQuery cookie - If the user changes the player's volume, it'll be saved to a cookie -->
<script src="js/jquery.cookie.js"></script>
 
<!-- jPlayer -->
<script src="js/jplayer.2.4.0/jquery.jplayer.min.js"></script>
 
<!-- diyPlayer -->
<script src="js/diyPlayer.js"></script>

In the example player there is the default stylesheet (css) of the DIY.fm player included. Feel free to create your own css. You can use the default stylesheet as a starting point, if you like.

<!-- diyPlayer stylesheet - Feel free to adapt it or create your own css -->
<link rel="stylesheet" type="text/css" href="styles/diyfm/style.css" />

To initialize the player, you can use this code in the header of your HTML document (or in an external JavaScript file, of course):

$(document).ready(function() {
    diyPlayer = new diyPlayer({
        "apiKey": "xxxxxx", //use your API key here
        "userId": 316, //the id of the DIY.fm user whose program should be played
        "userToken": "xxxxxx", //the user must be logged in for some player features
        "jPlayerSwfPath": "js/jplayer.2.4.0/", //change this if you move it to somewhere else
        "autoPlay": true //default = false
    });
});

Put the HTML structure of the player in the body of your HTML document:

<div id="diy-player-container">
 
	<!-- Audio player (hidden) -->
	<div id="diy-player"></div>
 
	<!-- Player user interface -->
	<div id="diy-player-interface">
 
		<!-- Play & pause controls -->
    	<ul class="diy-player-controls-1">
    	    <li><a href="javascript:;" class="jp-play" tabindex="1" title="Play">play</a></li>
    	    <li><a href="javascript:;" class="jp-pause" tabindex="1" title="Pause">pause</a></li>
    	</ul>
 
        <!-- Skip, hear later, add to program, share & settings controls -->
        <ul class="diy-player-controls-2">
        	<li><a href="javascript:;" class="diy-player-skip" tabindex="1" title="Skip">skip</a></li>
    	    <li><a href="javascript:;" class="diy-player-hear-later" tabindex="1" title="Hear later">hear later</a></li>
    	    <li><a href="javascript:;" class="diy-player-add-to-program" tabindex="1" title="Add to my program settings">add to my program settings</a></li>
    	    <li class="diy-player-share-inactive"></li>
    	    <li><a href="#" class="diy-player-settings" tabindex="1" title="Program settings">settings</a></li>
    	</ul>
 
        <!-- Player info -->
        <div class="diy-player-state">
        	<div class="diy-player-img-container"><img class="diy-player-img" /></div>
        	<div class="diy-player-info-1"></div>
			<div class="diy-player-info-2"></div>	            
        	<div class="jp-current-time"></div>
        	   	<div class="jp-duration"></div>
            	<div class="jp-progress">
					<div class="jp-seek-bar">
					<div class="jp-play-bar"></div>
				</div>
			</div>
        </div>
 
         <!-- Player volume -->
        <div class="diy-player-volume">
           	<div class="diy-player-volume-bar"></div>
           	<a href="javascript:;" class="diy-player-volume-off" tabindex="1" title="Unmute"></a>
           	<a href="javascript:;" class="diy-player-volume-on" tabindex="1" title="Mute"></a>
        </div>
 
         <!-- Program recommendations -->    
        <ul class="diy-player-recommendations">
           	<li><a href="javascript:;" class="diy-player-prev-next" tabindex="1" title="Back"></a></li>
    	    <li id="diy-player-recom-1" class="diy-player-recom"></li>
    	    <li id="diy-player-recom-2" class="diy-player-recom"></li>
    	    <li id="diy-player-recom-3" class="diy-player-recom"></li>
    	    <li id="diy-player-recom-4" class="diy-player-recom"></li>
    	    <li class="diy-player-recom-next"><a href="javascript:;" class="diy-player-recom-next" tabindex="1" title="Forth"></a></li>
    	</ul>
	</div>
</div>
 
<!-- PubNub -->
<div sub-key="sub-2f430857-f376-11e1-bd7c-41ff068715f9" ssl="off" origin="pubsub.pubnub.com" id="pubnub"></div>
<script src="http://cdn.pubnub.com/pubnub-3.1.min.js"></script>

If you don't need something (e.g. the hear later button) just take it away from the HTML structure and adapt the css accordingly.

That's it! You can downlaod the full code here.


Player Info API

Use this part of the API to get information about the player state (current playback, current volume etc.).

Get now playing type

diyPlayer.getNowPlaying('type')

Get now playing setting ID

diyPlayer.getNowPlaying('settingId')

Get now playing media ID

diyPlayer.getNowPlaying('mediaId')

Get now playing URL

diyPlayer.getNowPlaying('url')

Get now playing file url

diyPlayer.getNowPlaying('fileUrl')

Get now playing info 1

diyPlayer.getNowPlaying('info1')

Get now playing info 2

diyPlayer.getNowPlaying('info2')

Get now playing img url

diyPlayer.getNowPlaying('imgUrl')

Get now playing info link

diyPlayer.getNowPlaying('infoLink')

Get now playing isRecommended

diyPlayer.getNowPlaying('isRecommended')

Get now playing isAlreadyInSettings

diyPlayer.getNowPlaying('isAlreadyInSettings')

Get volume

diyPlayer.getVolume('volume')

Get isMuted

diyPlayer.getVolume('isMuted')

Player Control API

Use this part of the API to control the players behaviour from outside of the player.

Start playback

diyPlayer.play()

Pause playback

diyPlayer.pause()

Skip

diyPlayer.skip()

Hear later

diyPlayer.hearLater()

Mute

diyPlayer.mute()

Unmute

diyPlayer.unmute()

Set volume

diyPlayer.setVolume(volume) //volume = 0.0 - 1.0

Show next recommendations

diyPlayer.nextRecommendations()

Show previous recommendations

diyPlayer.previousRecommendations()

playRecommendation

diyPlayer.playRecommendation(index) //index starting with 0

Add currently playing recommendation to users' program settings

diyPlayer.addToProgram()

Player Event API

You can use these event listeners to add custom functionality when a specific player event occurs.

Play event

$(document).on("playerPlay", function(event) {
    alert("play event");
});

Pause event

$(document).on("playerPause", function(event) {
    alert("pause event");
});

Ended event: this event occurs when a podcast has ended

$(document).on("playerEnded", function(event) {
    alert("ended event");
});

Skip event

$(document).on("playerSkip", function(event) {
    alert("skip event");
});

HearLater event

$(document).on("playerHearLater", function(event) {
    alert("hearLater event");
});

AddToProgram event

$(document).on("playerAddToProgram", function(event) {
   alert("addToProgram event");
});

Share event

$(document).on("playerShare", function(event) {
   alert("share event");
});

VolumeChange event

$(document).on("playerVolumeChange", function(event) {
    alert("volumeChange event");
});

Mute event

$(document).on("mute", function(event) {
    alert("mute event");
});

Unmute event

$(document).on("unmute", function(event) {
    alert("unmute event");
});

MediaChange event

$(document).on("mediaChange", function(event) {
    alert("mediaChange event");
});

playRecommendedMedia event

$(document).on("playRecommendedMedia", function(event) {
    alert("playRecommendedMedia event");
});

UserTokenExpired event

$(document).on("userTokenExpired", function(event) {
    alert("userTokenExpired event");
});
player_api.txt · Last modified: 2017/02/24 16:11 (external edit)