286 |

287 |

Plangular

288 |

289 | Angular directive for custom SoundCloud players 290 | jxnblk.com/plangular 291 |

292 |

293 | 294 |

Getting Started

npm install plangular-3

Or install with Bower:

295 |

bower install plangular

Or use the CDN:

296 |

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

Angular app

Include a link to plangular after including Angular.

297 |

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

Initialize the app

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

300 |

<body ng-app="app">
301 | 
302 |   <script>
303 |     var app = angular.module('app', ['plangular'])
304 |       .config(function(plangularConfigProvider){
305 |         plangularConfigProvider.clientId = '[YOUR-CLIENT-ID]';
306 |       });
307 |   </script>
308 | </body>

Create a plangular directive instance

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

Include track info

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

Add player controls

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

Or with separate play/pause controls:

313 |

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

Show current time and duration

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

315 |

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

Progress bar

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

Add scrubber functionality

<progress
318 |   ng-click="seek($event)"
319 |   ng-value="currentTime / duration">
320 |   {{ currentTime / duration }}
321 | </progress>

Add images

<img ng-src="{{ track.artwork_url  }}" alt="{{ track.title }}" />
322 | <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.

323 |

Loading states

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

324 |

<div ng-if="!track"><!-- Loading state --></div>
325 | <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.

326 |

<ul>
327 |   <li ng-repeat="track in tracks">
328 |     <button
329 |       ng-click="playPause($index)"
330 |       ng-class="{'active': player.playing === track.src}">
331 |       {{track.user.username}} - {{track.title}}
332 |     </button>
333 |   </li>
334 | </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.

335 |

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

User likes

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

337 |

<div plangular="http://soundcloud.com/jxnblk/likes">
338 | </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.

339 |

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

Example templates

See more examples and starter templates in 341 | docs/examples

342 |

343 |

API

`track`

Object returned from the SoundCloud API

344 |

`tracks`

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

345 |

`player`

Audio player object

346 |

`audio`

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

347 |

`currentTime`

Angular-friendly currentTime from the audio element

348 |

`duration`

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

349 |

`index`

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

350 |

`playlist`

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

351 |

`play(i)`

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

352 |

`pause()`

Pauses the player.

353 |

`playPause(i)`

Toggles playback. Optionally pass an index when handling playlists.

354 |

`previous()`

Skip to previous track when handling playlists

355 |

`next()`

Skip to next track when handling playlists

356 |

`seek($event)`

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

357 |

358 |

Using the SoundCloud API

Track object

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

359 |

Terms

According to the SoundCloud API terms you must:

360 |

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)

365 |

366 |

Troubleshooting

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

369 | 370 |

Plangular

{{track.user.username}} - {{track.title}}

{{track.user.username}}

{{track.title}}

{{track.user.username}} - {{track.title}}

{{track.user.username}}

{{track.title}}

Jxnblk’s Likes

{{playlist.user.username}}

{{playlist.title}}

{{track.user.username}}

{{track.title}}

{{track.user.username}}

{{track.title}}

Jxnblk

{{track.user.username}}

{{track.title}}

71 | Examples 72 |

87 | 88 | More Examples 89 | 90 |

75 | Examples 76 |

{{track.user.username}} - {{track.title}}

{{track.user.username}}

{{track.title}}

{{playlist.user.username}}

{{playlist.title}}

Jxnblk

Jxnblk’s Likes

Plangular

374 | 375 | More Examples 376 | 377 |

{{track.user.username}}

{{track.title}}

{{track.user.username}}

{{track.title}}

{{track.user.username}}

{{track.title}}