audio_x

---

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

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

For a comprehensive list of supported formats, visit the MDN audio codec guide.

Features

---

• Supports all modern browsers.
• Lightweight, just 18kb.
• Zero dependencies and type-safe.
• No built-in UI, allowing full control over the player. Bring your own UI.
• Simple API to use.
• Works with React, no external packages needed.
• Access to the audio element to use your own event listeners or the default listeners to get up and running quickly.
• MediaSession support, shows notification and lock-screen actions on mobile devices.
• Playlog - Get the actual playtime of a track.

Upcoming Features

---

• Casting support
• Dash media playback
• DRM
• Ads support
• Equalizer [✓] Done
• Updates to APIs for better DX [✓] Done
• Queue support [✓] Done

Installation

---

1npm install audio_x

Usage

---

1import { AUDIO_STATE, AudioState, AudioX, MediaTrack } from "audio_x";
2
3// Create an audio_x instance
4const audio = new AudioX();
5
6// Initialize audio_x
7audio.init({
8  autoPlay: false,  // Should autoplay
9  useDefaultEventListeners: true, // Use default event listeners
10  showNotificationActions: true, // Show notifications on devices
11  preloadStrategy: "auto",   // Preloading strategy
12  playbackRate: 1,  // Set playback rate
13  enablePlayLog: true,  // Enable playlog support
14  enableHls: true,    // Enable HLS support
15  hlsConfig: { backBufferLength: 2000 } // HLS init config
16});
17
18// Create a track
19const track: MediaTrack = {
20  id: 1,
21  artwork: [
22    {
23      src: "https://example.com/image.png",
24      name: "image-name",
25      sizes: "512x512",
26    },
27  ],
28  source: "https://example.com/stream.mp3",
29  title: "My Awesome Song",
30  album: "Awesome Album",
31  artist: "Amazing Artist",
32  comment: "",
33  duration: 309,
34  genre: "Pop",
35  year: 2023,
36};
37
38// Add a track
39audio.addMedia(track);
40
41// Play
42audio.play();
43
44// Pause
45audio.pause();
46
47// Get the audio state
48audio.subscribe("AUDIO_X_STATE", (audioState: AudioState) => {
49  console.log(audioState);
50});
51
52// Sample audio state
53{
54  "playbackState": "paused",
55  "duration": null,
56  "bufferedDuration": 0,
57  "progress": 35.003483,
58  "volume": 50,
59  "playbackRate": 1,
60  "error": {
61    "code": null,
62    "message": "",
63    "readable": ""
64  },
65  "currentTrack": {
66    "artwork": [
67      {
68        src: "https://example.com/image.png",
69        name: "image-name",
70        sizes: "512x512",
71      }
72    ],
73    "source": "https://example.com/stream.mp3",
74    title: "My Awesome Song",
75    album: "Awesome Album",
76    artist: "Amazing Artist",
77    comment: "",
78    duration: 309,
79    genre: "Pop",
80    year: 2023,
81  },
82  "currentTrackPlayTime": 35.003483,
83  "previousTrackPlayTime": 35.003483
84}

Getting the audio instance

---

audio_x exports an audio instance through a static method, so you can add your own event listeners directly to the HTML5 audio element.

1const instance = AudioX.getAudioInstance();

Attaching custom event listeners

---

There are two ways to attach custom event listeners.

Method 1

1// Create an object of events and callbacks as below
2
3const eventListenerMap: EventListenerCallbackMap = {
4  CAN_PLAY_THROUGH: (e, audioInstance, isPlayLogEnabled) => {
5    console.log(e, audioInstance, isPlayLogEnabled);
6  },
7  PLAY: (e, audioInstance, isPlayLogEnabled) => {
8    console.log(e, audioInstance, isPlayLogEnabled);
9  },
10};
11
12audio.init({
13  autoPlay: false,
14  useDefaultEventListeners: false, // Set default event listener to false
15  mode: "REACT",
16  showNotificationActions: true,
17  customEventListeners: eventListenerMap, // Provide custom event listeners at init
18  preloadStrategy: "auto",
19  playbackRate: 1,
20  enableEQ: true,
21  enablePlayLog: true,
22  enableHls: true,
23});

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

Method 2

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

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

Setting up the equalizer

---

1// Getting the presets
2const presets = audio.getPresets(); // Will return an array of pre-tuned filters
3
4// Sample preset
5[
6  {
7    "id": "preset_default",
8    "name": "Default",
9    "gains": [0, 0, 0, 0, 0, 0, 0, 0, 0, 0 ]
10  }
11]
12
13// Setting a preset
14audio.setPreset(id);
15
16// Example:
17audio.setPreset('preset_default');  // Will set default preset
18
19// Custom EQ setting
20
21const gainsValue = preset[index].gains;
22gainsValue[index] = value;  // Value ranges from -10 to 10
23audio.setCustomEQ(gainsValue);
24
25// Example
26const gainsValue = preset[0].gains;   // Default preset gains [0, 0, 0, 0, 0, 0, 0, 0, 0, 0]
27gainsValue[0] = 2.5;   // Updated gain values [2.5, 0, 0, 0, 0, 0, 0, 0, 0, 0]
28audio.setCustomEQ(gainsValue);

Adding and handling the queue

---

Audio_x allows you to play audio in a queue.

1// To add a queue
2
3const tracks = [track_1, track_2, ...other_tracks]
4audio.addQueue(tracks, "DEFAULT");
5
6// NOTE: addQueue takes two parameters: one is the tracks array, and the second is playback type, i.e., "DEFAULT" | "REVERSE" | "SHUFFLE".
7// If no playbackType is passed, audio_x will play it as DEFAULT.
8
9// To play the queue from the beginning, call addMediaAndPlay like below.
10
11audio.addMediaAndPlay();
12
13// If you are fetching something dynamically to play audio, such as the source of the audio, you can do it like below.
14
15audio.addMediaAndPlay(null, async (currentTrack: MediaTrack) => {
16  const res = await fetch('url');
17  currentTrack.source = res.data.url;
18});
19
20// This will ensure that the above function gets called before every audio that plays in a queue.

1// To add a single track to the queue
2
3audio.addToQueue(track);

1// To add multiple tracks to the queue
2
3audio.addToQueue([track1, track2, track3]);

1// To clear the queue
2
3audio.clearQueue();

1// To play the next track in the queue
2
3audio.playNext();

1// To play the previous track in the queue
2
3audio.playPrevious();

1// To seek to a particular position
2
3audio.seek(position); // Position is basically time in seconds

1// To seek by a particular time range
2
3audio.seekBy(time); // Time range in seconds to seek

1// To enable/disable shuffle
2
3audio.toggleShuffle(); // Time range in seconds to seek

1// To check if queue is shuffled 
2
3audio.isShuffledEnabled(); // Time range in seconds to seek

1// To turn on looping [SINGLE/QUEUE/OFF]
2
3audio.loop("SINGLE"); // SINGLE/QUEUE/OFF

1// To get current Loop Mode
2
3audio.getLoopMode()

Author

---

• Ashish Kumar - afkcodes

Contributions

If you like this and find any issues, please raise a bug, or if you find working on audio stuff interesting, do raise a PR for a feature or a fix.