TypeScript icon, indicating that this package has built-in type declarations

1.0.32 • Public • Published

Mixmotion Player

Latest npm version GPLv3 License Monthly npm downloads

An immersive music player with Mixcloud integration and dynamic visual effects


Click the image to try out the app

How to use

For casual users who just want to discover some new music with fullscreen visuals, hit the image above or link below to launch the Mixmotion web app on your mobile, desktop or TV device.


On playback, you'll enter an immersive lean-back mode, with a huge variety of dynamic backgrounds appearing after a few seconds of user inactivity. Below is a quick video of the app transitioning between playback modes:


More screenshots and videos at the end of this doc.


Developers can also install Mixmotion Player as an open source component to use in React apps. Quickest install method is via the npm i command below. Alternatively, integrate it manually by grabbing the lib folder in this repo along with the associated dependencies.

npm install mixmotion-player

Basic Usage

Import the player and render MixmotionPlayer in your own app with a Mixcloud URL. It will use default settings for the other non declared props.

import { useEffect, useState } from "react";
import { MixmotionPlayer } from "mixmotion-player";

function Demo() {
  const [url, setUrl] = useState("");

  useEffect(() => {
  }, []);

  return <MixmotionPlayer url={url} />;

export default Demo;

Advanced Usage

The advanced demo and official web app illustrate how the component can be customised further. Props are specified for custom buttons, video backgrounds and local data (saved items). A complete list of props are detailed further down this page.


Why Another Music Player?

There are plenty of web players and widgets already available from the likes of Soundcloud and Mixcloud that you can integrate into your app.

Mixmotion offers something different; an immersive, full-screen playback experience with unique visual effects, while still providing free access to Mixcloud's vast music catalogue.

What Sets It Apart?

  • Mixcloud Integration: Simple yet versatile access to Mixcloud content that goes beyond their official widget. Access playlists, user sets, genres, tags and individual shows, with the ability to privately save favourites via local storage and share mixes.
  • Dynamic Visuals: Artwork combined with canvas effects and video motion backgrounds generate a captivating blend of imagery within a rich, immersive music player.
  • Broad Device Support: Designed for mobile, desktop and TV devices. Touch, cursor and arrow-key navigation help make the user experience smooth across platforms.
  • Future Considerations: Integration with local file paths, audio streams and other music services like Soundcloud. Real-time audio visualizations and beat detection are also being considered.

How Does It Work?

Under the hood, the component is built on top of the official Mixcloud API and Mixcloud Widget.

It also utilises another custom component of mine - Dynamic Backdrop - to create a blend of videos layered with css and canvas animation effects. Videos are given random 'blend modes' so they merge with the canvas background to give various colour effects.


Prop Description Default
url The Mixcloud URL of the content to play
◦ Most URLs are supported such as playlists, users, genres, tags and individual shows/sets
◦ This can be a full URL or a partial Mixcloud key
showsData An array of locally stored shows data that can be used instead of a URL.
◦ The app utilises this for local-storage saved shows.
backdropVideoList A string array of background video URLs which appear in a random sequence during playback mode when there is no user activity null
enableBackdropVideo Set to true to show the above background videos when there is no user activity.
◦ The video toggle button in the UI (and local storage flag) will override this
enableUserLink Set to true to turn the user/artist sub-title into a react-router link. (used in the deployed app) false
collapsed Set to true to minimise the player metadata and controls, in order to make space for other content.
◦ Used in the app for home and search page content.
activityTimeout Override the timeout period of user inactivity, which then triggers an 'innactive mode' during playback to show full dynamic visuals
◦ Used in the app to provide longer timeout periods in home and search pages.
showWidget Display the official Mixcloud widget at bottom of page - with its own controls and progress bar - instead of the custom progress bar.
◦ The official widget does not support arrow-key navigation for TV devices.
width Override the width of the player.
◦ Note: full-screen is the intended user experience, with content layered over
◦ You may need to modify the CSS if you override width
height Override the height of the player.
◦ Note: full-screen is the intended user experience, with content layered over
◦ You may need to modify the CSS if you override height
customButtons Specify a collection of custom buttons for the player UI
  ◦  A set of default buttons will be used if none are specified.
autoplay Set to false to disable the attempt to auto-play content true
withExclusives Set to true to include exclusive content from the Mixcloud API.
◦ Note: exclusive content is unlikely to play without further development to support Mixcloud user sign-in authentication
listIndex Set the initial media index number if you have multiple shows/sets in the requested URL or local showData array 0
style add inline CSS styles to the player null

Callback Props

Callback props get fired on various player events, so you can take further actions when they occur:

Prop Description
onReady Called when media is loaded and ready to play
onPlay Called when media starts or resumes playing after pausing or buffering
onPause Called when media is paused
onBuffering Called when media starts buffering
onEnded Called when media finishes playing
onError Called when an error occurs whilst attempting to play media

Custom Buttons

As illustrated in the advanced demo, the player can be overridden with custom buttons. There is a selection of pre-built action types with their own icons and behaviours or you can add your own with the "custom" action type.

import { MixmotionPlayer, ButtonProps } from "mixmotion-player";
import { faBars } from "@fortawesome/free-solid-svg-icons";

const customButtons: ButtonProps[] = [
  { action: "save", align: "right" },
  { action: "previous", align: "center" },
  { action: "playpause", align: "center" },
  { action: "next", align: "center" },
    action: "custom",
    align: "right",
    label: "Queue",
    faIcon: faBars,
    onPress: () => {
      console.log("my custom button pressed");

function Demo() {
  return <MixmotionPlayer url={url} customButtons={customButtons} />;
Button Props Description
action Choose from custom or one of the pre-built actions: collapse, github, mixcloud, mute, next, playpause, previous, save, videos
align Alignment of the button. Choose from left,center, right
label A hint text label to appear below the current button in focus. Pre-built button actions use relevent labels.
faIcon A font-awesome icon. Pre-built button actions use relevent icons.
onPress Called when a button is pressed. Pre-built button actions have their own behaviours.
onRelease Called when a button is released. Currently unused.
isSelectedFill Allows support of toggle behaviour (in the form of a button fill) when set to true.
disable Prevents button action when set to true.

useSavedItems Hook

This custom hook is used to update and retrieve shows that are favourited/liked by the user. The below snippet from the advanced demo illustrates how to load the player with local saved data.

import { MixmotionPlayer,
} from "./lib/MixmotionPlayer";

function Demo() {
  const { getSavedItems } = useSavedItems();

  const getSavedData = useMemo(() => {
    const savedItems = getSavedItems();
    if (savedItems.length)
      return {
        label: "Saved Sets",
        shows: savedItems.reverse(),
      } as ShowsDataType;
  }, [getSavedItems]);

  return (

useStore Hook

For more control you can import the useStore custom hook to globally access player state. View the inner components like MixmotionPlayerUI for examples of use. The below snippet shows basic usage to get current show title and playing state:

// 1. import useStore
import { MixmotionPlayer, useStore } from "mixmotion-player";

// 2. get desired state values
const playing = useStore((s) => s.playing);
const title = useStore((s) => s.title);

console.log("playing: state ", playing);
console.log("Current title: ", title);

<MixmotionPlayer ... />;

App Screenshots and Videos

https://lewhunt.github.io/mixmotion/ https://lewhunt.github.io/mixmotion/
Player UI on Desktop on Mobile



Search Page



Playback Mode



Playback Mode (example 1)



Playback Mode (example 2)



Playback Mode (example 3)


Mixmotion video on YouTube

Click to view video promo on YouTube



Package Sidebar


npm i mixmotion-player

Weekly Downloads






Unpacked Size

759 kB

Total Files


Last publish


  • lewhunt