{"id":17683,"library":"howler-pixi-loader-middleware","title":"Howler.js PixiJS Audio Loader Parser","description":"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.","status":"active","version":"5.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/seleb/HowlerPixiLoaderMiddleware","tags":["javascript","howler","pixi","loader"],"install":[{"cmd":"npm install howler-pixi-loader-middleware","lang":"bash","label":"npm"},{"cmd":"yarn add howler-pixi-loader-middleware","lang":"bash","label":"yarn"},{"cmd":"pnpm add howler-pixi-loader-middleware","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Runtime dependency for creating Howl instances from loaded audio files.","package":"howler","optional":false},{"reason":"Peer dependency as it integrates directly with PixiJS's asset loading system.","package":"pixi.js","optional":false}],"imports":[{"note":"The package is primarily designed for ESM environments, aligning with modern PixiJS usage. CommonJS `require` is not officially supported and may lead to issues.","wrong":"const HowlerLoaderParser = require('howler-pixi-loader-middleware');","symbol":"HowlerLoaderParser","correct":"import HowlerLoaderParser from 'howler-pixi-loader-middleware';"},{"note":"Required from `pixi.js` to add the loader parser and manage asset loading.","symbol":"Assets","correct":"import { Assets, extensions } from 'pixi.js';"},{"note":"While this package returns `Howl` instances, you might still need to import `Howl` directly from `howler` for type definitions or manual instantiation.","symbol":"Howl","correct":"import { Howl } from 'howler';"}],"quickstart":{"code":"import HowlerLoaderParser from 'howler-pixi-loader-middleware';\nimport { Assets, extensions } from 'pixi.js';\n\n// Add the HowlerLoaderParser as a PixiJS extension before loading any audio assets.\n// This tells PixiJS how to handle audio files with Howler.js.\nextensions.add(HowlerLoaderParser);\n\nasync function loadAndPlayAudio() {\n  // Configure specific audio extensions to be handled by the parser, if not default\n  // For example, if you only want .mp3 and .ogg to be handled:\n  // HowlerLoaderParser.audioExtensions = ['.mp3', '.ogg'];\n\n  try {\n    // Load your audio file using PixiJS's Assets system.\n    // The loaded asset will be a Howl instance.\n    const myAudio = await Assets.load('my_audio.mp3');\n    console.log('Audio loaded successfully!', myAudio);\n\n    // Check if it's a Howl instance before playing\n    if (myAudio && typeof myAudio.play === 'function') {\n      myAudio.play();\n      console.log('Audio playing...');\n\n      // Example of stopping after a few seconds\n      setTimeout(() => {\n        myAudio.stop();\n        console.log('Audio stopped.');\n      }, 3000);\n\n      // Example of unloading the asset\n      // Assets.unload('my_audio.mp3');\n    } else {\n      console.error('Loaded asset is not a Howl instance.');\n    }\n  } catch (error) {\n    console.error('Failed to load audio:', error);\n  }\n}\n\nloadAndPlayAudio();\n","lang":"javascript","description":"Demonstrates how to register the HowlerLoaderParser with PixiJS and load an audio file, then play and stop it, confirming it's a Howl instance."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=5.0.0"},{"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()`.","message":"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.","severity":"breaking","affected_versions":">=4.0.0"},{"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.","message":"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).","severity":"breaking","affected_versions":">=4.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=4.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"fix":"Update your code to use the new PixiJS loader parser extension API: `extensions.add(HowlerLoaderParser);`.","cause":"Attempting to use the old PixiJS loader middleware API (loader.use) with `howler-pixi-loader-middleware` v4.x or newer.","error":"Uncaught TypeError: loader.use is not a function"},{"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).","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.","error":"Error: Asset for 'my_audio.mp3' not found in cache"},{"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.","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.","error":"Uncaught (in promise) TypeError: Cannot read properties of undefined (reading 'play')"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}