EasyMedia - Sound Player and Recorder Library for ZeppOS

The EasyMedia library provides two classes, SoundPlayer and SoundRecorder, for playing and recording sounds. The library further encapsulates our raw approach, is more user-friendly, and introduces extra features like play queue, play cancelation, and more.

Install the library from NPM registry

npm i @silver-zepp/easy-media

SoundPlayer

The SoundPlayer class allows you to play sound files. Here's an example of how to use it:

import { SoundPlayer } from '@silver-zepp/easy-media';

// create a new SoundPlayer
const player = new SoundPlayer(); 
player.play("assets://raw/media/my-sound.mp3"); // play any file by its path
// or
const player = new SoundPlayer({ file: "my-sound.mp3" }); 
player.play();  // plays the first file

// in case later you have to change the file (.mp3, .opus)
player.changeFile('path-to-another-audio-file');  // stops the first file and prepares the second one

// pause the playing sound
player.pause()

// resume playback
player.resume()

// stops the playing sound
player.stop();

// setters/getters
// (!) NOTE the change from `player.get.volume` to `player.get.volume()`
const volume = player.get.volume();       // get the current playback volume
const duration = player.get.duration();   // get the total duration of the currently playing media file
const title = player.get.title();         // get the title of the currently playing media file
const artist = player.get.artist();       // get the artist of the currently playing media file
const media_info = player.get.mediaInfo();// get the media info of the currently playing media file
const status = player.get.status();       // get the current status of the player

player.set.volume(50);  // set the playback volume to 50%

// ======================
// NEW (!) ADD: 1/19/2025
// ======================

// more verbose logs from the library (1-3), default 1 (critical logs)
SoundPlayer.SetLogLevel(3); 

// destroy the player and its callbacks
player.destroy(); 

// on play complete callback with usefull info
player.onComplete((info) => {
  // ...print filename, path, full path and exact duration in milliseconds
  console.log(`Name: ${info.name}`);
  // can print duration below 1s which the Media library missing - ie 324ms
  console.log(`Duration: ${info.duration} ms`); 
  console.log(`Full path: ${info.full_path}`);
  console.log(`Path: ${info.path}`);  
});

// reduce the fail detection timeout (default 3000ms). 
// lower numbers are less stable.
player.setFailTimeout(2000);

// executes if the playback fails
player.onFail((info) => {
  console.log(`Failed to play ${info.name}.`);
});

// check if the device has a speaker
player.isSpeakerAvailable((bool)=> {
  if (bool) {
    console.log("Speaker OK.");
  } else {
    console.log("Speaker NOT available.");
    console.log("Try connecting BLE Headphones.");
  }
})

// status name getter 
// IDLE, INITIALIZED, PREPARING, PREPARED, STARTED, PAUSED
const status = player.get.statusName();

// more status getters in the Get subclass: 
const is_playing = player.get.isPlaying(); 
player.get.isPaused();
player.get.isStopped();

Methods

play():

Starts playing the sound. If the sound is already playing, it stops and prepares the sound again.

stop():

Stops the sound. If the sound is playing, it stops the sound and releases the player.

changeFile(filename):

Changes the sound file to play.

destroy():

Destroys the player. If the sound is playing, it stops the sound and removes event listeners.

SoundRecorder

The SoundRecorder class allows you to record sounds. Here’s an example of how to use it:

import { SoundRecorder } from '@silver-zepp/easy-media/recorder';

const recorder = new SoundRecorder('mic-recording.opus');
recorder.start();

Methods

start():

Starts recording.

stop():

Stops recording.

changeFile(target_file):

Changes the target file for the recording.