Welcome!

This is a yarn v4 monorepo that primarily manages the react-use-audio-player package, which helps React developers better control sound in their web applications.

yarn add react-use-audio-player

npm install react-use-audio-player

For complete package documentation, see the package README

Monorepo Setup

In order to contribute to the project, build the package locally, or run the demo applications, you will need to make sure your environment is set up correctly.

I recommend using NVM to make sure you use the correct NodeJS version.

The repo uses modern Yarn which requires one to enable corepack on their NodeJS installation. This feature is only available on newer releases which is why it is important to use the established NodeJS version in the .nvmrc file.

1. git clone the repository
2. cd useAudioPlayer
3. nvm use
4. corepack enable
5. yarn install

Examples

You can view example applications using the package in the demos directory. If you would like to run them yourself please following the following steps:

1. Complete the steps in Monorepo Setup above
2. Build the react-use-audio-player package locally with - yarn g:build-package
3. cd into any of the demo workspaces and run yarn start
4. or leverage yarn workspace commands - yarn workspace [NAME OF DEMO FOLDER] start
5. follow terminal output or the demo's README for further assistance

Contributing

Please consider opening an Issue or Feature Request in Github and I will do my best to respond to these in a timely manner. However, as a sole contributor, it can often be hard to set aside time to make meaningful changes to the project. I will be happy to review and discuss pull requests with anyone who wants to help.

Change Log

All notable changes made to this project from v3.0.0 and up will be documented in this file. This project uses semver standards.

4.0.2 (2025-03-16)

Fixes 🐛

• Fixes issue #166 in which the hook can get stuck in a loading state after seeking on an audio resource loaded via HTML5 audio elements
• Fixes issue #105 in which seeking on streaming audio would cause an error

Other

• Add page for debugging to the showcase demo app

4.0.1 (2025-03-02)

Fixes 🐛

• Fixes an issue where while using the optional arguments of useAudioPlayer, the audio could be left stuck in an unloaded state due to React StrictMode
• Stabilizes the hook state during hydration to better support server-side rendered frameworks

Other

• Add new remix-app example to the demos folder. To run: yarn workspace remix-app start

4.0.0 (2025-02-25)

Version 4.0 marks a big shift for the react-use-audio-player package. In this version, we've adopted a modern version of React, rewritten the internals to align with the best practices of modern React and pivoted away from an over-reliance on global state.

Breaking 💣

• Bump React peer dependency version. The min React version is now >= 18.0.0
• Delete deprecated useGlobalAudioPlayer. Consumers must migrate to useAudioPlayerContext
• Rename several AudioPlayer state properties for consistency
  • playing => isPlaying
  • muted => isMuted
  • paused => isPaused
  • stopped => isStopped
  • looping => isLooping

New Features 🚀

• New properties and methods on AudioPlayer
  • isUnloaded
  • explicit loopOn, loopOff functions
  • explicit mute, unmute functions
  • escape hatch for accessing underlying Howl object via player
  • toggle functions for certain states: toggleLoop, toggleMute, togglePlayPause
• New optional arguments for useAudioPlayer to declaratively load audio

Fixes 🐛

• https://github.com/E-Kuerschner/useAudioPlayer/issues/141
• https://github.com/E-Kuerschner/useAudioPlayer/issues/107

3.1.0 (2025-02-21)

New Features

• deprecates useGlobalAudioPlayer in favor of new additions
• exports new component: AudioPlayerProvider and companion hook: useAudioPlayerContext
  • See GitHub Discussion

3.0.2 (2025-01-05)

Fixes

• Repair broken file extensions in package.json exports

3.0.1 (2025-01-05)

Fixes

• Update bundled README
• Cleanup yarn config

3.0.0 (2025-01-05)

This set of changes is intened to be non-breaking, but due to using a different bundler (tsup) I decided to release this as a major version as the exported files from the package have technically changed. Please report any issue using this new version.

Refactors

• Replace unmaintained TSDX with modern tsup
• modernize project with monorepo setup for package and demo apps
• upgrade yarn to modern version
• modernize package.json (using exports key)
• switch to GH Actions instead of Circle CI