Audio_x NPM | npm.io

audio_x

A simple audio player for all your audio playing needs, based on HTML5 audio element.Supports most popular formats.

Formats	Support
.mp3	✓
.aac	✓
.mp4	✓
.m3u8 (hls)	✓

For a comprehensive list of formats support visit MDN audio codec guide

Features

Supports all modern browsers.
Light Weight just 18kb.
Zero dependencies, and type-safe.
No Built in UI to have full control over the player, bring in your own UI.
Simple API to use.
Works on React no external package needed.
Access to audio element to use your own event listeners or use the default listeners to get up & running in a ziffy.
MediaSession Support, shows notification and lock-screen actions on mobile devices.
Playlog - Get actual playtime of a track.

Upcoming Features

Casting support
Dash media playback
DRM
~~Equalizer~~ ✓ Done
Updates to APIs for better DX
React hooks to easily get started with React.
Ads Support
Queue Support and etc.

Installation

Currently there is no npm package so you have to install directly from github. Will be publishied to npm soon.

Note: This library is in active development phase so, there might be some changes that would come, that might be breaking, but be assured will try not to make them.

npm install audio_x

Usage

import { AUDIO_STATE, AudioState, AudioX, MediaTrack } from "audio_x";


// create an audio_x Instance
const audio = new AudioX();


// Initialize audio_x
audio.init({
  autoPlay: false,  // should auto play
  useDefaultEventListeners: true, // use Default event listeners
  showNotificationActions: true, // show notifications on devices
  preloadStrategy: "auto",   // preloading strategy
  playbackRate: 1,  // set playback rate
  enablePlayLog: true,  // enable playlog support
  enableHls: true,    // enable hls support
  hlsConfig: { backBufferLength: 2000 } // Hls init config
});

// create track
const track:MediaTrack ={
  id: 1,
  artwork: [
    {
      src: "https://example.com/image.png",
      name: "image-name",
      sizes: "512x512",
    },
  ],
  source:
    "https://example.com/stream.mp3",
  title: "My Awesome Song",
  album: "Awesome Album",
  artist: "Amazing Artist",
  comment: "",
  duration: 309,
  genre: "Pop",
  year: 2023,
};

// add a track
audio.addMedia(track);

// play
audio.play();

//pause
audio.pause();

// Get the Audio State
audio.subscribe("AUDIO_X_STATE", (data: AudioState) => {
  console.log(data);
});

// Sample Audio State
{
  "playbackState": "paused",
  "duration": null,
  "bufferedDuration": 0,
  "progress": 35.003483,
  "volume": 50,
  "playbackRate": 1,
  "error": {
    "code": null,
    "message": "",
    "readable": ""
  },
  "currentTrack": {
    "artwork": [
      {
        src: "https://example.com/image.png",
        name: "image-name",
        sizes: "512x512",
      }
    ],
    "source": "https://example.com/stream.mp3",
    title: "My Awesome Song",
    album: "Awesome Album",
    artist: "Amazing Artist",
    comment: "",
    duration: 309,
    genre: "Pop",
    year: 2023,
  },
  "currentTrackPlayTime": 35.003483,
  "previousTrackPlayTime": 35.003483
}

Getting the audio Instance

audio_x exports audioInstance, through a static method, so that you can add your own event-listeners directly on the HTML5 audio element.

const instance = AudioX.getAudioInstance();

Attaching custom event listeners

There are two ways to attach custom event listeners.

Method 1

// Create an object of Events and callbacks as below

const eventListenerMap: EventListenerCallbackMap = {
  CAN_PLAY_THROUGH: (e, audioInstance, isPlayLogEnabled) => {
    console.log(e, audioInstance, isPlayLogEnabled);
  },
  PLAY: (e, audioInstance, isPlayLogEnabled) => {
    console.log(e, audioInstance, isPlayLogEnabled);
  },
};

audio.init({
    autoPlay: false,
    useDefaultEventListeners: false, // set default event listener to false
    mode: "REACT",
    showNotificationActions: true,
    customEventListeners: eventListenerMap, // provide custom event listeners at init
    preloadStrategy: "auto",
    playbackRate: 1,
    enableEQ: true,
    enablePlayLog: true,
    enableHls: true,
  });

NOTE: if custom event listeners are provided at init it will take priority even if useDefaultEventListeners is set to true, to use default event listener set useDefaultEventListeners to true and customEventListeners to null. Once custom event listener is added AUDIO_X_STATE will not not be fired, in favor of custom event listeners. All the events should be handled manually, This method only allows audio events.

Method 2

 audio.addEventListener("pause", (data: any) => {
    console.log(data);
  });

NOTE: This method allows adding events directly to audio element, and all the events can be added to the audio element, When using this set useDefaultEventListeners to false and customEventListeners to null to reduce un-necessary events being fired.All the events should be handled manually

Setting up the equalizer

// Getting the Presets
const presets = audio.getPresets(); // will return array of pre-tuned filters

// Sample Preset
[
  {
    "id": "preset_default",
    "name": "Default",
    "gains": [0, 0, 0, 0, 0, 0, 0, 0, 0, 0 ]
  }
]

// Setting a Preset
audio.setPreset(id);

// example:
audio.setPreset('preset_default');  // will set default preset


// Custom EQ Setting

const gainsValue = preset[index].gains;
gainsValue[index] = value;  // value ranges from -10 to 10
audio.setCustomEQ(gainsValue);

// Example
const gainsValue = preset[0].gains;   // default preset gains [0, 0, 0, 0, 0, 0, 0, 0, 0, 0 ]
gainsValue[0] = 2.5;   // updated gain values [2.5, 0, 0, 0, 0, 0, 0, 0, 0, 0 ]
audio.setCustomEQ(gainsValue);