MixcloudAudio

The Mixcloud Widget plays Mixcloud shows. 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/mixcloud-audio

import { MixcloudAudio } from '@videojs/react/media/mixcloud-audio';

Load a source

src takes either of these Mixcloud URLs:

• A show: mixcloud.com/<user>/<show>/
• A widget embed URL with its widget parameters, as Mixcloud’s embed code gives it: www.mixcloud.com/widget/iframe/?feed=...

www. and m. links work too. Profiles, playlists, and other pages that list shows are not supported.

<MixcloudAudio src="https://www.mixcloud.com/spartacus/lambiance/" />

Controls

The widget is the only UI Mixcloud 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>
    <MixcloudAudio src="https://www.mixcloud.com/spartacus/lambiance/" />
  </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, and seek. The widget is also the part of the page that credits the show and links back to it on Mixcloud (see Mixcloud’s terms of use).

<MixcloudAudio src="https://www.mixcloud.com/spartacus/lambiance/" controls />

With controls, the component is 120 pixels tall by default, Mixcloud’s classic layout. Set a height to change it. With widget parameters, mini: true selects the mini layout, which needs 60 pixels, and hide_cover: false selects the picture layout, a large cover that needs about 400 pixels. The widget hides the Mixcloud logo when it is narrower than 560 pixels.

Widget parameters

By default, the component sets hide_cover, so the widget does not use its picture layout. Change it, or set mini, hide_artwork, hide_tracklist, or light, under source.engine.mixcloud, spelled as Mixcloud spells them:

<MixcloudAudio
  source={{
    src: 'https://www.mixcloud.com/spartacus/lambiance/',
    engine: { mixcloud: { light: true, hide_artwork: 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. The widget applies mini, hide_cover, hide_artwork, hide_tracklist, and light without reloading the show. Other options reload it.

light is the only theme option: Mixcloud offers no other colors. The widget has no start time parameter, so it ignores start_time. Set currentTime instead.

Behavior

• play() asks the widget to play. Browsers apply their autoplay policy to the widget as they do to any embed, so a play without a user gesture can be refused. Then the widget reports nothing, and the media stays paused.
• autoplay starts playback once the widget is ready, after the volume applies. The widget’s own autoplay parameter does the same and is never written to the widget URL.
• The widget loads from player-widget.mixcloud.com, the host that Mixcloud’s embed URL redirects to. A frame that redirects to another host loses the autoplay permission of the page, and then the widget cannot start playback from the skin.
• Seeking uses whole seconds, as the widget does. The widget ignores a seek before the show first plays, so the component keeps that seek and applies it when playback starts.
• Mixcloud limits seeks and replays for listeners without a Mixcloud subscription: 6 fast-forwards and 6 rewinds per show in a rolling 60-minute period, and 4 replays of a show in a rolling 14-day period (see Mixcloud’s help center). When the widget refuses a seek, currentTime goes back to the position of the widget, and seeked fires.
• loop plays the show again from the start when it ends.
• Volume and mute both work. The widget has no separate mute, so muting sets its volume to 0, and unmuting restores the previous level.
• buffered is always empty, because the widget does not report how much of the show it has loaded.
• 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 URL that is not a Mixcloud show reports a MEDIA_ERR_SRC_NOT_SUPPORTED error, and so does a show the widget cannot find, such as a private or removed show. A show whose audio the widget does not load within 15 seconds reports a MEDIA_ERR_NETWORK error. An error the widget reports before playback starts is a MEDIA_ERR_SRC_NOT_SUPPORTED error, and an error during playback is a MEDIA_ERR_NETWORK error.

Mixcloud’s terms of use

The Mixcloud widget is subject to Mixcloud’s own terms. Before you use this component, read the Mixcloud Terms of Use and the Widget documentation to learn where and how you can use the widget. To keep the widget visible on the page, set controls.

Privacy

The widget is subject to Mixcloud’s own privacy policy. Read the Mixcloud Privacy Policy to learn what the widget collects from visitors and what you must do when you embed it. The widget loads from Mixcloud as soon as the component renders, so to wait for a visitor’s consent, render the component only after the visitor agrees.

Examples

Basic Usage

import { MixcloudAudio } from '@videojs/react/media/mixcloud-audio';

export default function BasicUsage() {
  return (
    <div className="mixcloud-audio">
      <MixcloudAudio src="https://www.mixcloud.com/spartacus/lambiance/" controls />
    </div>
  );
}

.mixcloud-audio {
  width: 100%;
}

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

const ref = useRef<HTMLIFrameElement>(null);

<MixcloudAudio ref={ref} />

import type { MixcloudAdapter } from '@videojs/mixcloud-audio';

const mediaRef = useRef<MixcloudAdapter>(null);

<MixcloudAudio mediaRef={mediaRef} />

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