Howler.js PixiJS Audio Loader Parser
raw JSON → 5.0.0 verified Thu Apr 23 auth: no javascript
howler-pixi-loader-middleware is a utility package that enables PixiJS's asset loader to seamlessly integrate audio files using the Howler.js library. It maps loaded audio assets directly to `Howl` instances, simplifying audio management within PixiJS applications. The current stable version is 5.0.0, which specifically supports PixiJS v8.x and Howler.js v2.x. This package's release cadence is tightly coupled with major PixiJS releases, requiring updates to match new PixiJS loader APIs (e.g., transitioning from middleware to loader parser in v4 for PixiJS v7.x). Its primary differentiator is providing a direct, standardized way to load and manage audio through PixiJS's robust asset pipeline, making it a go-to choice for games and interactive experiences built with PixiJS that require advanced audio features from Howler.js, such as sprite management and Web Audio API capabilities. It abstracts away the need for manual Howler.js instantiation for assets loaded via Pixi's `Assets` system.
Common errors
error Uncaught TypeError: loader.use is not a function ↓
cause Attempting to use the old PixiJS loader middleware API (loader.use) with `howler-pixi-loader-middleware` v4.x or newer.
fix
Update your code to use the new PixiJS loader parser extension API:
extensions.add(HowlerLoaderParser);. error Error: Asset for 'my_audio.mp3' not found in cache ↓
cause This error can occur if the `HowlerLoaderParser` was not registered before attempting to load audio, or if there's a PixiJS version mismatch with the loader middleware.
fix
Verify that
extensions.add(HowlerLoaderParser); is called before Assets.load('my_audio.mp3'); and that your howler-pixi-loader-middleware version is compatible with your pixi.js version (e.g., v5.x for PixiJS v8.x). error Uncaught (in promise) TypeError: Cannot read properties of undefined (reading 'play') ↓
cause The loaded audio asset might not be a `Howl` instance, often due to the loader parser failing or not being correctly applied to the asset.
fix
Ensure the audio file path is correct, the
HowlerLoaderParser is correctly added as an extension, and that howler.js is installed and functioning. Check browser console for earlier loading errors. Warnings
breaking Version 5.0.0 updates the package to support PixiJS v8.x exclusively, dropping compatibility with PixiJS v7.x. Applications using PixiJS v7.x must remain on howler-pixi-loader-middleware v4.x. ↓
fix Upgrade your PixiJS installation to v8.x or newer, or downgrade howler-pixi-loader-middleware to a v4.x release if you need to maintain PixiJS v7.x.
breaking Version 4.0.0 introduced a significant API change for PixiJS v7.x. It transitioned from being a loader middleware (added to `loader.use()`) to a loader parser extension (added to `extensions.add()`). The old middleware approach will not work with v4.x and above. ↓
fix For PixiJS v7.x and v8.x, ensure you are adding the parser via `extensions.add(HowlerLoaderParser)` as shown in the quickstart example, not `loader.use()`.
breaking Version 4.0.0 also dropped support for PixiJS v6.x. If you are using PixiJS v6.x or below, you must use an older version of this package (e.g., v3.x). ↓
fix For PixiJS v6.x, use howler-pixi-loader-middleware v3.x. For PixiJS v7.x and up, upgrade this package and update your integration as per the new API.
gotcha Ensure `HowlerLoaderParser` is added to PixiJS extensions *before* any audio assets are loaded. If audio assets are loaded before the parser is registered, PixiJS will not know how to handle them, leading to loading failures. ↓
fix Place `extensions.add(HowlerLoaderParser);` at the earliest point in your application initialization, ideally before `Assets.load()` or `Assets.add()` calls that involve audio files.
gotcha The package relies on `howler.js` and `pixi.js` as peer dependencies. Mismatched versions between these core libraries and this loader middleware can lead to runtime errors or unexpected behavior. ↓
fix Always install `howler` and `pixi.js` versions that are compatible with the specific major version of `howler-pixi-loader-middleware` you are using. Check the `peerDependencies` in the package's `package.json` for guidance.
Install
npm install howler-pixi-loader-middleware yarn add howler-pixi-loader-middleware pnpm add howler-pixi-loader-middleware Imports
- HowlerLoaderParser wrong
const HowlerLoaderParser = require('howler-pixi-loader-middleware');correctimport HowlerLoaderParser from 'howler-pixi-loader-middleware'; - Assets
import { Assets, extensions } from 'pixi.js'; - Howl
import { Howl } from 'howler';
Quickstart
import HowlerLoaderParser from 'howler-pixi-loader-middleware';
import { Assets, extensions } from 'pixi.js';
// Add the HowlerLoaderParser as a PixiJS extension before loading any audio assets.
// This tells PixiJS how to handle audio files with Howler.js.
extensions.add(HowlerLoaderParser);
async function loadAndPlayAudio() {
// Configure specific audio extensions to be handled by the parser, if not default
// For example, if you only want .mp3 and .ogg to be handled:
// HowlerLoaderParser.audioExtensions = ['.mp3', '.ogg'];
try {
// Load your audio file using PixiJS's Assets system.
// The loaded asset will be a Howl instance.
const myAudio = await Assets.load('my_audio.mp3');
console.log('Audio loaded successfully!', myAudio);
// Check if it's a Howl instance before playing
if (myAudio && typeof myAudio.play === 'function') {
myAudio.play();
console.log('Audio playing...');
// Example of stopping after a few seconds
setTimeout(() => {
myAudio.stop();
console.log('Audio stopped.');
}, 3000);
// Example of unloading the asset
// Assets.unload('my_audio.mp3');
} else {
console.error('Loaded asset is not a Howl instance.');
}
} catch (error) {
console.error('Failed to load audio:', error);
}
}
loadAndPlayAudio();