react-soundplayer

Create highly-customizable SoundCloud players with React.

Demo

Usage

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.

API

Pure Components

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:

PlayButton

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}
/>

NextButton

Switch to the next track in a playlist.

<NextButton 
    className={String}
    onNextClick={Function}
    soundCloudAudio={instanceof SoundCloudAudio}
/>

PrevButton

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.

Progress

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*/
    } 
/>

Timer

Shows current time of the track and its' duration in (hh:)mm:ss/(hh:)mm:ss format.

<Timer
    className={String} 
    duration={Number}
    currentTime={Number}
/>

Cover

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

<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.

Props

`resolveUrl`

(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"

`streamUrl`

(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"

`clientId`

(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={client}>
                {/* your custom player components */}
            </SoundPlayerContainer>
        </div>
    }
}

React.render(<AppPlayer />, document.body);

Children Props

All of these self-descriptive state properties are passed into <SoundPlayerContainer /> children components as props:

playing (Boolean) - true if audio is playing currently
seeking (Boolean) - true if audio is seeking for position
track (Object) or tracks (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 using resolveUrl prop)
duration (Number) - audio duration in seconds
currentTime (Number) - audio current time in seconds
soundCloudAudio (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);

Icon Components

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;

SoundCloud API

If you're curious what data you can use inside player just take a look into official SoundCloud Developers docs for tracks.

Troubleshooting

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.

References

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

liquidautumn / react-soundplayer