Create custom SoundCloud players with HTML & CSS
HTML JavaScript
Latest commit a557e8c Aug 30, 2015 @jxnblk jxnblk Update readme
Permalink
Failed to load latest commit information.
dist Rebuild Jul 27, 2015
docs Remove default config Apr 15, 2015
scripts Bump version Mar 29, 2015
src fix broken secret links Jul 9, 2015
test Clean up Mar 28, 2015
.gitignore Remove default config Apr 15, 2015
README.md Update readme Aug 30, 2015
bower.json Bump bower Apr 15, 2015
index.html Remove default config Apr 15, 2015
package.json Bump s3 version Jul 27, 2015

README.md

⚠️ This repo is no longer being maintained

For creating custom SoundCloud players, I highly recommend react-soundplayer or for a more general solution, see plyr.

Plangular

Angular directive for custom SoundCloud players jxnblk.com/plangular

Getting Started

npm install plangular-3

Or install with Bower:

bower install plangular

Or use the CDN:

<script src="http://d2v52k3cl9vedd.cloudfront.net/plangular/3.1.0/plangular.min.js"></script>

Angular app

Include a link to plangular after including Angular.

<script src="//ajax.googleapis.com/ajax/libs/angularjs/1.3.15/angular.min.js"></script>
<script src="bower_components/plangular/dist/plangular.min.js"></script>

Initialize the app

Configure Plangular with your own client_id. For new SoundCloud apps, you can register at https://developers.soundcloud.com/

<body ng-app="app">

  <script>
    var app = angular.module('app', ['plangular'])
      .config(function(plangularConfigProvider){
        plangularConfigProvider.clientId = '[YOUR-CLIENT-ID]';
      });
  </script>
</body>

Create a plangular directive instance

<div plangular="http://soundcloud.com/jxnblk/plangular">
</div>

Include track info

<div plangular="http://soundcloud.com/jxnblk/plangular">
  <h3>{{track.user.username}} - {{track.title}}</h3>
  <a ng-href="{{track.permalink_url}}">View on SoundCloud</a>
</div>

Add player controls

<button ng-click="playPause()">Play/Pause</button>

Or with separate play/pause controls:

<button ng-click="play()">Play</button>
<button ng-click="pause()">Pause</button>

Show current time and duration

Use the hhmmss filter to format seconds as hh:mm:ss strings.

<small>{{ currentTime | hhmmss }} | {{ duration | hhmmss }}</small>

Progress bar

<progress ng-value="currentTime / duration || 0">
  {{ currentTime / duration || 0 }}
</progress>

Add scrubber functionality

<progress
  ng-click="seek($event)"
  ng-value="currentTime / duration">
  {{ currentTime / duration }}
</progress>

Add images

<img ng-src="{{ track.artwork_url  }}" alt="{{ track.title }}" />
<img ng-src="{{ track.waveform_url }}" alt="waveform" />

Note: The waveform image that the SoundCloud API provides is a 1200 x 280px PNG with a light gray frame and transparent middle. To show progress use absolute positioning with the waveform in front. The light gray color is #efefef.

Loading states

Use the ng-if directive to show and hide content based on whether the track has loaded.

<div ng-if="!track"><!-- Loading state --></div>
<div ng-if="track"><!-- Player --></div>

Playlists

Use the tracks array and ng-repeat when using a SoundCloud playlist. Pass the $index to the playPause() method to trigger playback on a per-track basis. Determine which track is currently playing with player.playing === track.src.

<ul>
  <li ng-repeat="track in tracks">
    <button
      ng-click="playPause($index)"
      ng-class="{'active': player.playing === track.src}">
      {{track.user.username}} - {{track.title}}
    </button>
  </li>
</ul>

User tracks

To load the most recent tracks from a given user, use the tracks endpoint. Use ng-repeat to iterate over the tracks array.

<div plangular="http://soundcloud.com/jxnblk/tracks">
</div>

User likes

To load the most recent likes from a given user, use the likes endpoint.

<div plangular="http://soundcloud.com/jxnblk/likes">
</div>

Previous/next controls

To skip to the next and previous track in a playlist or array of tracks, use the previous() and next() methods.

<button ng-click="previous()">Previous</button>
<button ng-click="next()">Next</button>

Example templates

See more examples and starter templates in docs/examples


API

track

Object returned from the SoundCloud API

tracks

An array of track objects if the instance is a playlist or list of tracks

player

Audio player object

audio

The HTML5 <audio> element used by the player, exposed for access to media events.

currentTime

Angular-friendly currentTime from the audio element

duration

Angular-friendly duration from the audio element. Note: you can also access duration in milliseconds from the SoundCloud track object.

index

Currently playing track index in a playlist or other array of tracks.

playlist

Cloned object of track if track.tracks exists. This is useful for displaying the title of the playlist.

play(i)

Plays the track. Optionally pass an index when handling playlists.

pause()

Pauses the player.

playPause(i)

Toggles playback. Optionally pass an index when handling playlists.

previous()

Skip to previous track when handling playlists

next()

Skip to next track when handling playlists

seek($event)

Sets the audio element’s currentTime property based on a pointer event.


Using the SoundCloud API

Track object

For more details on the SoundCloud track object, see https://developers.soundcloud.com/docs/api/reference#tracks

Terms

According to the SoundCloud API terms you must:

  • Credit the user as the creator of the content
  • Credit SoundCloud as the source
  • Include a link to the sound on SoundCloud (i.e. a link using track.permalink_url)

Read more here: http://developers.soundcloud.com/docs/api/terms-of-use

Troubleshooting

SoundCloud provides an option for users to prevent streaming to third-party apps. If your sound isn't playing check the track.streamable variable. If it's set to false, there is no way to play that sound with the API.