Redux Sounds

3.3.2 verified Thu Apr 23 auth: no javascript

Redux Sounds is a Redux middleware designed to integrate sound effects into Redux applications by dispatching actions. It acts as a bridge between your Redux store and the Howler.js audio library, allowing developers to play sounds declaratively. The current stable version is 3.3.2. This package has a moderate release cadence, with significant updates historically aligning with major Howler.js versions and adding features like dynamic sound loading, playlists, and sprite support. Its key differentiator is the declarative Redux-first approach to sound management, abstracting away direct Howler.js API calls for common use cases, making it easier to manage sound logic within a predictable application state.

Common errors

error TypeError: Cannot read properties of undefined (reading 'play') ↓

cause The `Howl` constructor from `howler.js` was not passed as the second argument to `createSoundMiddleware`, or `howler` is not installed.

fix

Ensure npm install howler is run and createSoundMiddleware(soundData, Howl) is correctly configured, importing Howl from howler.

error Redux-sounds: `sound` meta property missing from action ↓

cause An action was dispatched that passed through the sound middleware but lacked the `meta.sound` property, which is required for sound playback.

fix

Add a meta object to your action with a sound property, for example: dispatch({ type: 'PLAY_BEEP', meta: { sound: 'beep' } }).

error Uncaught (in promise) DOMException: The element has no supported sources. ↓

cause The audio file paths provided in `soundData` are incorrect, the files are missing, or there are browser limitations (e.g., autoplay without user interaction).

fix

Double-check all sound paths in soundData. Ensure files exist at the specified locations and are accessible. Consider browser autoplay policies for initial sounds.

Warnings

breaking The structure of `action.meta.sound` for controlling Howler methods changed in v3.0.0. Instead of a direct string, it now expects an object to allow for more granular control over various Howler methods. ↓

fix Update `action.meta.sound` from a string like `'jumps.lowJump'` to an object like `{ fade: ['jumps.lowJump', 0, 1, 2] }` or `{ play: 'soundId' }` to use Howler methods explicitly.

breaking The `urls` key in `soundData` was renamed to `src` in v2.0.0 to align with Howler.js v2 API changes. ↓

fix Change any `urls` property in your `soundData` configuration objects to `src` (e.g., `{ src: ['path/to/sound.mp3'] }`).

gotcha To ensure `redux-sounds` works correctly, `howler.js` (specifically `Howl`) must be installed and passed as the second argument to `createSoundMiddleware`. This is not explicitly listed as a `peerDependency` but is a runtime requirement. ↓

fix Install `howler` via `npm install howler` or `yarn add howler` and ensure `Howl` is imported and passed: `createSoundMiddleware(soundData, Howl)`.

gotcha When using sound sprites, ensure the `sprite` object is correctly attached to your sound data. Incorrect configuration can lead to sounds not playing or playing incorrectly. ↓

fix Refer to the documentation for sprite configuration, e.g., `{ urls: ['path/to/sprite.mp3'], sprite: { soundA: [0, 1000], soundB: [1500, 500] } }`.

Install

npm install redux-sounds

yarn add redux-sounds

pnpm add redux-sounds

Imports

createSoundMiddleware
wrong
```
import { createSoundMiddleware } from 'redux-sounds';
```
correct
```
import createSoundMiddleware from 'redux-sounds';
```
This is a default export, not a named export. Ensure you import it directly.
soundData
```
// The soundData object is typically defined by the user and passed to the middleware.
```
While `soundData` isn't imported, it's a crucial configuration object. It should map sound IDs to file paths or Howler.js configuration objects.

Quickstart

This quickstart demonstrates setting up `redux-sounds` with a Redux store, defining `soundData`, and dispatching actions that trigger sound playback via the middleware.

import { createStore, applyMiddleware } from 'redux';
import createSoundMiddleware from 'redux-sounds';
import { Howl } from 'howler'; // Required by redux-sounds, install if not present

// 1. Define your sound data
const soundData = {
  jump: '/path/to/jump.mp3',
  gameOver: {
    src: ['/path/to/game_over.ogg', '/path/to/game_over.mp3'],
    loop: false,
    volume: 0.8
  },
  backgroundMusic: {
    src: ['/path/to/music.mp3'],
    loop: true,
    volume: 0.5
  }
};

// 2. Create the sound middleware
const soundMiddleware = createSoundMiddleware(soundData, Howl);

// 3. Create a simple reducer (for demonstration)
const initialState = { score: 0 };
function appReducer(state = initialState, action) {
  switch (action.type) {
    case 'PLAYER_JUMP':
      return { ...state, score: state.score + 10 };
    case 'GAME_OVER':
      return { ...state, score: 0 };
    default:
      return state;
  }
}

// 4. Create the Redux store with the middleware
const store = createStore(
  appReducer,
  applyMiddleware(soundMiddleware)
);

// 5. Dispatch actions to play sounds
store.dispatch({
  type: 'PLAYER_JUMP',
  meta: { sound: 'jump' }
});

store.dispatch({
  type: 'GAME_OVER',
  meta: {
    sound: {
      play: 'gameOver',
      volume: 0.9 // Override default volume for this play
    }
  }
});

store.dispatch({
  type: 'START_MUSIC',
  meta: { sound: { play: 'backgroundMusic', loop: true } }
});

console.log('Redux store configured and sounds dispatched.');
// In a real app, Howler.js would handle sound playback in the browser/Node environment.