SoundCloudAudio

The SoundCloud Widget plays public and private SoundCloud tracks and sets. This component drives the widget and reports its state like a native <audio> element, so a player skin can control it.

Import

pnpm add @videojs/soundcloud-audio

import { SoundCloudAudio } from '@videojs/react/media/soundcloud-audio';

Load a source

src takes any of these SoundCloud URLs:

• A track: soundcloud.com/<user>/<track>
• A set: soundcloud.com/<user>/sets/<set>
• A private track or set, with its secret token: soundcloud.com/<user>/<track>/s-<token>
• An API resource: api.soundcloud.com/tracks/<id> or api.soundcloud.com/playlists/<id>, with an optional secret_token. The id can also be a URN such as soundcloud:tracks:<id>
• A widget embed URL: w.soundcloud.com/player/?url=..., as SoundCloud’s own embed code gives it

m.soundcloud.com links work too. Add #t= to start at a given time, in seconds (#t=90), clock time (#t=1:30), or units (#t=1m30s). Profiles, likes, and other pages that list sounds are not supported.

<SoundCloudAudio src="https://soundcloud.com/forss/flickermood#t=1:30" />

Controls

The widget is the only UI SoundCloud offers, so controls decides whether the component is visible at all. Without controls, the component hides itself and plays as an invisible transport: a hidden iframe still loads and plays, so a player skin drives playback while the widget takes no room on the page.

<AudioPlayer>
  <AudioSkin>
    <SoundCloudAudio src="https://soundcloud.com/forss/flickermood" />
  </AudioSkin>
</AudioPlayer>

With controls, the component shows the widget, and the audio skin draws its controls below it, so the two do not overlap. Anything the listener does in the widget shows in the skin: play, pause, seeking on the waveform, and picking another track of a set. The widget is also the part of the page that credits the uploader and links back to the sound on SoundCloud (see SoundCloud’s terms of use).

<SoundCloudAudio src="https://soundcloud.com/forss/flickermood" controls />

With controls, the component is 166 pixels tall by default, SoundCloud’s classic layout. Set a height to change it. From about 300 pixels, a set also shows its track list, and 450 pixels shows most of it. The large artwork layout of visual: true (see widget parameters) needs 300 pixels or more. At the default height, the artwork shows only behind the waveform.

<SoundCloudAudio
  source={{ src: 'https://soundcloud.com/forss/flickermood', engine: { soundcloud: { visual: true } } }}
  controls
  style={{ height: 300 }}
/>

Widget parameters

By default, the component hides the parts of the widget a skin has no use for: the buy, share, and download buttons, comments, reposts, the teaser, the related tracks shown after a track ends, and the large artwork layout. The uploader, the title, the artwork, and the SoundCloud logo stay whenever the widget shows.

Change any of these, or set color, under source.engine.soundcloud, spelled as SoundCloud spells them:

<SoundCloudAudio
  source={{
    src: 'https://soundcloud.com/forss/sets/soulhack',
    engine: { soundcloud: { color: '#ff5500', start_track: 2, sharing: true } },
  }}
/>

Engine options win over the parameters of a widget embed URL, which win over the defaults. Set an option to null to drop a default.

Behavior

• A set plays as one source. When the widget moves on to the next track, duration changes, currentTime starts again from 0, and durationchange fires. ended fires only after the last track. play() after the end starts the set again from its first track.
• loop replays the track, or the set from its first track. If the widget does not start again, ended still fires.
• Volume and mute both work. The widget has no separate mute, so muting sets its volume to 0 and unmuting restores the previous level. Mute applies before autoplay starts, so a muted autoplay starts muted.
• autoplay starts playback once the widget is ready. Browsers can still refuse it, as they do for any embed. The widget’s own auto_play parameter does the same and is never written to the widget URL, so the volume always applies first.
• buffered is the stretch the widget reports as loaded, from where playback last started or landed.
• The widget does not support playback rate, picture-in-picture, fullscreen, or text tracks, so the component offers none of them, and a player skin hides those controls.
• preload, playsinline, and poster are accepted for parity with <audio> but have no effect.
• A track that is private without its secret token, removed, or not available in the listener’s region reports a MEDIA_ERR_SRC_NOT_SUPPORTED error, and so does a URL the component does not recognize. A widget that has not finished loading after 5 seconds reports a MEDIA_ERR_NETWORK error. An error the widget reports during playback fires a non-fatal error event but leaves error empty, because a set moves on to its next track by itself.

SoundCloud’s terms of use

The widget is covered by the SoundCloud Terms of Use, in the section about players and widgets. Without written consent from SoundCloud, you may not use the widget to:

• Aggregate SoundCloud content into a separate destination that substantially replicates what SoundCloud offers, or into a content service where SoundCloud content is a material part.
• Embed content on a site dedicated to one artist, unless the content is yours and you are that artist or represent them, or on a site dedicated to one genre.

These limits apply to commercial and non-commercial use. You also may not use the widget in a way that suggests that SoundCloud, an artist, or anyone else endorses or supports your site. SoundCloud can block your use of the widget at any time, for any reason.

The SoundCloud API terms, which ask you to credit the uploader and SoundCloud with links back to the sound, apply when you use the SoundCloud API, for example to play stream URLs in a player of your own. This component uses the widget, which SoundCloud says handles that credit itself. The widget gives that credit only while it shows, which is with controls. Without controls, we recommend that your page give the credit itself: name the uploader, name SoundCloud as the source, and link to the sound on SoundCloud. The Terms of Use also say you must not remove trademark, copyright, or other proprietary or legal notices that appear on content from SoundCloud.

Privacy

The widget loads from SoundCloud as soon as the component renders. The SoundCloud Privacy Policy says that SoundCloud may receive personal data when a visitor opens a page with an embedded widget, including which site they are on, and may recognize the visitor. The widget also stores data in the visitor’s browser. SoundCloud does not document an embed mode that avoids this, so if your site needs consent before it loads third-party content, render the component only after the visitor agrees.

Examples

Basic Usage

import { SoundCloudAudio } from '@videojs/react/media/soundcloud-audio';

export default function BasicUsage() {
  return (
    <div className="soundcloud-audio">
      <SoundCloudAudio src="https://soundcloud.com/forss/flickermood" controls />
    </div>
  );
}

.soundcloud-audio {
  width: 100%;
}

{ src?: string; engine?: SoundCloudSourceEngineConfig } | null

const ref = useRef<HTMLIFrameElement>(null);

<SoundCloudAudio ref={ref} />

import type { SoundCloudAdapter } from '@videojs/soundcloud-audio';

const mediaRef = useRef<SoundCloudAdapter>(null);

<SoundCloudAudio mediaRef={mediaRef} />

// In an event handler
mediaRef.current?.play();