audio

Control the system master volume and play WAV sound files.

import { audio } from "system";

Availability

Available in the Main script only.

Table of Contents

• Methods
• Practical Examples

Methods

audio.getVolume() #

audio

Returns the current master system volume level as an integer percentage. The value is rounded to the nearest integer.

Returns 0 on failure

If the system audio device cannot be accessed (e.g. no audio hardware, COM failure), getVolume returns 0 — the same value as a silent device. There is no separate error indicator.

RETURNS: number Current master volume as an integer in the range 0–100. Returns 0 if the audio device is unavailable.

import { audio } from "system";

const vol = audio.getVolume();
console.log("Volume:", vol); // e.g. 75

// Use with a tray tooltip
appTray.setToolTip("Volume: " + vol + "%");

audio.setVolume(value) #

audio

Sets the master system volume. Values outside 0–100 are automatically clamped before being applied. Throws TypeError if no argument is provided.

PARAMETERS

value number

Target volume as a percentage (0–100). Values below 0 are clamped to 0. Values above 100 are clamped to 100.

RETURNS: boolean true if the volume was set successfully. false if the audio device is unavailable or the operation failed.

import { audio } from "system";

audio.setVolume(50);       // set to 50%
audio.setVolume(0);        // mute
audio.setVolume(100);      // max volume
audio.setVolume(-10);      // clamped to 0
audio.setVolume(150);      // clamped to 100

const ok = audio.setVolume(75);
if (!ok) {
  console.error("Failed to set volume — no audio device?");
}

audio.playSound(path [, loop]) #

audio

Plays a WAV file asynchronously using the Win32 PlaySoundW API. Only WAV format is supported. Playing a new sound automatically stops any previously playing sound.

Absolute paths recommended

Pass an absolute path to guarantee the file is found. Use path.join(__dirname, "alert.wav") to build the full path. Relative paths are resolved by the OS relative to the process working directory, which may differ from your widget's directory.

Only WAV is supported

The underlying Win32 PlaySoundW API only supports .wav files. Other formats (MP3, OGG, etc.) will fail silently and return false.

PARAMETERS

path string

Absolute path to a WAV file. Relative paths resolve from the process working directory, not from __dirname.

loop boolean OPTIONAL

true to loop playback until stopSound() is called. Defaults to false.

RETURNS: boolean true if playback started, false if the file was not found or could not be opened.

import { audio } from "system";

// Play once
audio.playSound(path.join(__dirname, "alert.wav"));

// Loop until stopped
audio.playSound(path.join(__dirname, "ambient.wav"), true);

// Stop after 5 seconds
setTimeout(() => audio.stopSound(), 5000);

audio.stopSound() #

audio

Stops any WAV sound currently playing via audio.playSound(). Safe to call even when nothing is playing.

RETURNS: boolean Always returns true.

import { audio } from "system";

audio.playSound(path.join(__dirname, "alarm.wav"), true);

setTimeout(() => {
  audio.stopSound();
}, 3000);

Practical Examples

Volume control widget with tray scroll wheel

import { audio, tray } from "system";  // Note: tray is in novadesk module
import { tray as appTray } from "novadesk";

const t = new appTray(path.join(__dirname, "assets", "speaker.ico"));

function updateTip() {
  t.setToolTip("Volume: " + audio.getVolume() + "%");
}

updateTip();

t.on("scroll-up", () => {
  const vol = Math.min(100, audio.getVolume() + 5);
  audio.setVolume(vol);
  updateTip();
});

t.on("scroll-down", () => {
  const vol = Math.max(0, audio.getVolume() - 5);
  audio.setVolume(vol);
  updateTip();
});

Play a notification sound on an event

import { audio } from "system";

ipcMain.on("alert", () => {
  audio.playSound(path.join(__dirname, "assets", "notify.wav"));
});

Mute on widget open, restore on close

import { audio, widgetWindow } from "novadesk";
import { audio as sys } from "system";

const savedVolume = sys.getVolume();
sys.setVolume(0);

const win = new widgetWindow({ id: "demo", width: 300, height: 200, script: "script.ui.js" });

win.on("close", () => {
  sys.setVolume(savedVolume);
});