Create highly-customizable SoundCloud players with React.
npm install react-soundplayer --save
ReactSoundPlayer is bundled with components and addons inside. You can require them in..
..plain-old ES5:
// require components and addons
var SoundPlayerComponents = require('react-soundplayer/components');
var SoundPlayerAddons = require('react-soundplayer/addons');
var PlayButton = SoundPlayerComponents.PlayButton;
var Progress = SoundPlayerComponents.Progress;
// icons are components too!
var SoundCloudLogoSVG = SoundPlayerComponents.Icons.SoundCloudLogoSVG
var SoundPlayerContainer = SoundPlayerAddons.SoundPlayerContainer;
// ...
..or ES6 syntax:
import { PlayButton, Progress, Icons } from 'react-soundplayer/components';
import { SoundPlayerContainer } from 'react-soundplayer/addons';
const { SoundCloudLogoSVG } = Icons;
// ...
ReactSoundPlayer depends on React.js 0.13.x (or higher) and SoundCloudAudio for managing HTML5 Audio.
With ReactSoundPlayer creation of SoundCloud players becomes as easy as pointing different controls in the right places. Here is the list of available pure so-called "dumb" components that accept data and callbacks only as props
:
Play or pause track.
<PlayButton
className={String}
playing={Boolean}
seeking={Boolean}
seekingIcon={
ReactElement
/*optional icon that will be showed when track is seeking new position to play*/
}
onTogglePlay={Function}
soundCloudAudio={instanceof SoundCloudAudio}
/>
Switch to the next track in a playlist.
<NextButton
className={String}
onNextClick={Function}
soundCloudAudio={instanceof SoundCloudAudio}
/>
Return to the previous track in the playlist.
<PrevButton
className={String}
onPrevClick={Function}
soundCloudAudio={instanceof SoundCloudAudio}
/>
Important note: All buttons accept soundCloudAudio
prop which when passed will add actions to buttons automagically (e.g. play/pause, go to prev/next track), callback function used in onTogglePlay
, onNextClick
and onPrevClick
will still be called after.
Component that replaces native <progress>
DOM element. If soundCloudAudio
prop is passed it automagically updates track audio time due to clicked progress position.
<Progress
className={String}
innerClassName={String}
value={Number}
onSeekTrack={
Function
/*receives `x` position as first argument and `event` as second*/
}
/>
Shows current time of the track and its' duration in (hh:)mm:ss/(hh:)mm:ss
format.
<Timer
className={String}
duration={Number}
currentTime={Number}
/>
Nice looking cover box inspired by original SoundCloud players.
<Cover
className={String}
trackName={String}
artistName={String}
backgroundUrl={String}
/>
As you see each component contains a set of self-descriptive properties. One of them is className
which allows you to setup custom class names as on regular DOM elements and style components as you wish.
<SoundPlayerContainer />
is higher level container that propagates its' children with all necessary props which you might need in order to design an audio player.
When using it, just choose what kind of SoundCloud data you're consuming (via resolveUrl
or streamUrl
)
If you're wondering "Why not mixin?", please read "Why Component Is Better Than Mixin" by @acdlite.
(String) - this could be regular link from SoundCloud web app which points to track or playlist, example urls:
// track
"https://soundcloud.com/thrilljockey/future-islands-balance"
// playlist
"https://soundcloud.com/stepan-i-meduza-official/sets/dolgo-obyasnyat-ep"
(String) - pass here pure stream url as it's returned by SoundCloud API, it has higher priority than resolveUrl
, example:
"https://api.soundcloud.com/tracks/200494743/stream"
(String) - your SoundCloud app's client ID, get it at https://developers.soundcloud.com
SoundCloudAudio will be created per each component instance:
import React from 'react';
import { SoundPlayerContainer } from 'react-soundplayer/addons';
const clientId = 'YOUR CLIENT ID';
const streamUrl = 'https://api.soundcloud.com/tracks/200494743/stream';
class AppPlayer extends React.Component {
render() {
<div>
<SoundPlayerContainer streamUrl={streamUrl} clientId={clientId}>
{/* your custom player components */}
</SoundPlayerContainer>
</div>
}
}
React.render(<AppPlayer />, document.body);
(object) - Use instead of clientId
to pass in a pre-existing instance of soundCloudAudio
for SoundPlayerContainer
to wrap.
All of these self-descriptive state properties are passed into <SoundPlayerContainer />
children components as props
:
playing
(Boolean) -true
if audio is playing currentlyseeking
(Boolean) -true
if audio is seeking for positiontrack
(Object) ortracks
(Array) - data object or array of such objects depends whether the url was pointing to track or playlist, see - https://developers.soundcloud.com/docs/api/reference#tracks (will be available only while usingresolveUrl
prop)duration
(Number) - audio duration in secondscurrentTime
(Number) - audio current time in secondssoundCloudAudio
(instance of SoundCloudAudio)
As you can see it's really easy to create your own components from scratch and wrap them with SoundPlayerContainer
which will provide all the necessary data to them.
import React from 'react';
import { SoundPlayerContainer } from 'react-soundplayer/addons';
const clientId = 'YOUR CLIENT ID';
const resolveUrl = 'https://soundcloud.com/stepan-i-meduza-official/dolgo-obyasnyat';
class TrackInfo extends React.Component {
render() {
let { track } = this.props;
if (!track) {
return <div>Loading...</div>;
}
return (
<div>
<h2>{track.title}</h2>
<h3>{track.user.username}</h3>
</div>
);
}
}
class PlayPause extends React.Component {
togglePlay() {
let { playing, soundCloudAudio } = this.props;
if (playing) {
soundCloudAudio.pause();
} else {
soundCloudAudio.play();
}
}
render() {
let { playing } = this.props;
let text = playing ? 'Pause' : 'Play';
if (!track) {
return <div>Loading...</div>;
}
return (
<button onClick={this.togglePlay.bind(this)}>
{text}
</button>
);
}
}
class CustomPlayer extends React.Component {
render() {
return (
<SoundPlayerContainer resolveUrl={resolveUrl} clientId={clientId}>
<TrackInfo />
<PlayPause />
</SoundPlayerContainer>
);
}
}
React.render(<CustomPlayer />, document.body);
Icons for buttons and SoundCloud logo can be used on their own as well. All of them are pure SVG.
import { Icons } from 'react-soundplayer/components';
// the list of available icons:
const {
SoundCloudLogoSVG,
PlayIconSVG,
PauseIconSVG,
NextIconSVG,
PrevIconSVG
} = Icons;
If you're curious what data you can use inside player just take a look into official SoundCloud Developers docs for tracks.
Please keep in mind that SoundCloud provides an option for users to prevent streaming to third-party apps. If your sound isn't playing check the track's streamable
property. If it's set to false
, there is no way to play that sound with the API.
- simply the best CSS modular toolkit on the web - BASSCSS
- easy management of HTML5 Audio API by SoundCloudAudio
- inspired by Plangular
- we all ❤️ SoundCloud API!
- follow updates on Twitter
MIT Licensed