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:

1import { SoundPlayer } from '@silver-zepp/easy-media';
2
3// create a new SoundPlayer
4const player = new SoundPlayer(); 
5player.play("assets://raw/media/my-sound.mp3"); // play any file by its path
6// or
7const player = new SoundPlayer({ file: "my-sound.mp3" }); 
8player.play();  // plays the first file
9
10// in case later you have to change the file (.mp3, .opus)
11player.changeFile('path-to-another-audio-file');  // stops the first file and prepares the second one
12
13// pause the playing sound
14player.pause()
15
16// resume playback
17player.resume()
18
19// stops the playing sound
20player.stop();
21
22// setters/getters
23// (!) NOTE the change from `player.get.volume` to `player.get.volume()`
24const volume = player.get.volume();       // get the current playback volume
25const duration = player.get.duration();   // get the total duration of the currently playing media file
26const title = player.get.title();         // get the title of the currently playing media file
27const artist = player.get.artist();       // get the artist of the currently playing media file
28const media_info = player.get.mediaInfo();// get the media info of the currently playing media file
29const status = player.get.status();       // get the current status of the player
30
31player.set.volume(50);  // set the playback volume to 50%
32
33// ======================
34// NEW (!) ADD: 1/19/2025
35// ======================
36
37// more verbose logs from the library (1-3), default 1 (critical logs)
38SoundPlayer.SetLogLevel(3); 
39
40// destroy the player and its callbacks
41player.destroy(); 
42
43// on play complete callback with usefull info
44player.onComplete((info) => {
45  // ...print filename, path, full path and exact duration in milliseconds
46  console.log(`Name: ${info.name}`);
47  // can print duration below 1s which the Media library missing - ie 324ms
48  console.log(`Duration: ${info.duration} ms`); 
49  console.log(`Full path: ${info.full_path}`);
50  console.log(`Path: ${info.path}`);  
51});
52
53// reduce the fail detection timeout (default 3000ms). 
54// lower numbers are less stable.
55player.setFailTimeout(2000);
56
57// executes if the playback fails
58player.onFail((info) => {
59  console.log(`Failed to play ${info.name}.`);
60});
61
62// check if the device has a speaker
63player.isSpeakerAvailable((bool)=> {
64  if (bool) {
65    console.log("Speaker OK.");
66  } else {
67    console.log("Speaker NOT available.");
68    console.log("Try connecting BLE Headphones.");
69  }
70})
71
72// status name getter 
73// IDLE, INITIALIZED, PREPARING, PREPARED, STARTED, PAUSED
74const status = player.get.statusName();
75
76// more status getters in the Get subclass: 
77const is_playing = player.get.isPlaying(); 
78player.get.isPaused();
79player.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:

1import { SoundRecorder } from '@silver-zepp/easy-media/recorder';
2
3const recorder = new SoundRecorder('mic-recording.opus');
4recorder.start();

Methods

start():

Starts recording.

stop():

Stops recording.

changeFile(target_file):

Changes the target file for the recording.