Novadesk Docs

Appearance

AppVolume Addon ​

Read and control Windows audio sessions per application. For system-wide volume, see the audio module — ideal for per-app volume sliders and mute toggles.

What is AppVolume? ​

The AppVolume addon lets you interact with every app that is currently playing sound on your computer. You can:

  • List all active audio sessions (e.g. Chrome, Spotify, Discord)
  • Get the current volume, peak level, and mute state for any app
  • Set the volume or mute/unmute any app individually

Think of it like the Windows Volume Mixer, but from your NovaDesk widget script.

Getting Started ​

First, load the addon in your script:

javascript
import { addon } from "novadesk";

// Load the AppVolume addon DLL
const appVolume = addon.load("path/to/AppVolume.dll");

TIP

Replace "path/to/AppVolume.dll" with the actual path to the AppVolume.dll file on your system. If the DLL is in the same folder as your script, you can use just "AppVolume.dll".

INFO

This API comes from the AppVolume addon, not the built-in system module.

Table of Contents ​

Quick Example ​

Here is a minimal example that lists all active audio sessions and prints their names and volumes:

javascript
import { addon } from "novadesk";
const appVolume = addon.load("path/to/AppVolume.dll");

// Get all apps currently playing audio
const sessions = appVolume.listSessions();

for (const s of sessions) {
  console.log(`${s.processName}: volume ${Math.round(s.volume * 100)}%`);
}
appVolume.listSessions() #
AppVolume

Returns all active Windows output audio sessions. Each session maps to an application currently playing (or having recently played) audio.

How it works internally: This function connects to the Windows audio session manager, enumerates every active session on the default audio output device, and collects details about each one.

Each session object has:

Property Type Description
pid number Process ID — a unique number Windows assigns to each running app.
processName string Executable file name (e.g. chrome.exe).
fileName string Executable file name (same as processName).
filePath string Full executable path when available (e.g. C:\Program Files\...).
iconPath string Path to a cached .ico file of the app's icon, or empty string if unavailable.
displayName string Session display name set by the app.
volume number Session volume from 0.0 (silent) to 1.0 (full volume).
peak number Current audio peak level from 0.0 to 1.0.
muted boolean Whether the session is muted.
RETURNS: object[] Array of audio session objects. Returns an empty array if enumeration fails.
javascript
const sessions = appVolume.listSessions();
console.log("Active sessions:", sessions.length);

for (const s of sessions) {
  console.log(s.processName, "vol:", s.volume, "muted:", s.muted);
}
appVolume.getByPid(pid) #
AppVolume

Gets aggregated volume details for all sessions belonging to a process ID. If an app has multiple audio sessions (e.g. multiple tabs in a browser), this combines them into one result.

The returned object has:

Property Type Description
volume number Average volume across all matching sessions (0.0–1.0).
muted boolean true if any matching session is muted.
peak number Maximum peak level across all matching sessions.

PARAMETERS

pid number
Target process ID. Must be greater than 0.
RETURNS: object | null Aggregated volume info for matching sessions, or null if no session matches the PID.
javascript
const sessions = appVolume.listSessions();
const s = sessions[0];

// Get aggregated info by process ID
const info = appVolume.getByPid(s.pid);
if (info) {
  console.log("Volume:", info.volume, "Muted:", info.muted);
}
appVolume.getByProcessName(name) #
AppVolume

Same as getByPid() but matches by process name instead of PID. The comparison is case-insensitive, so "spotify.exe" and "Spotify.exe" both work.

PARAMETERS

name string
Process name to match (case-insensitive), e.g. chrome.exe.
RETURNS: object | null Aggregated volume info for matching sessions, or null if no session matches the name.
javascript
const info = appVolume.getByProcessName("Spotify.exe");
if (info) console.log("Spotify volume:", info.volume);
appVolume.setVolumeByPid(pid, volume01) #
AppVolume

Sets the volume for all audio sessions belonging to a process ID.

PARAMETERS

pid number
Target process ID. Must be greater than 0.
volume01 number
Target volume from 0.0 (silent) to 1.0 (full). Values outside this range are clamped.
RETURNS: boolean true if at least one matching session was updated, false otherwise.
javascript
const s = appVolume.listSessions()[0];
appVolume.setVolumeByPid(s.pid, 0.5); // Set to 50%
appVolume.setVolumeByProcessName(name, volume01) #
AppVolume

Sets the volume for all audio sessions matching a process name.

PARAMETERS

name string
Process name to match (case-insensitive).
volume01 number
Target volume from 0.0 (silent) to 1.0 (full). Values outside this range are clamped.
RETURNS: boolean true if at least one matching session was updated, false otherwise.
javascript
appVolume.setVolumeByProcessName("chrome.exe", 0.3); // Set Chrome to 30%
appVolume.setMuteByPid(pid, mute) #
AppVolume

Mutes or unmutes all audio sessions belonging to a process ID.

PARAMETERS

pid number
Target process ID. Must be greater than 0.
mute boolean
true to mute, false to unmute.
RETURNS: boolean true if at least one matching session was updated, false otherwise.
javascript
const s = appVolume.listSessions()[0];
appVolume.setMuteByPid(s.pid, true); // Mute this app
appVolume.setMuteByProcessName(name, mute) #
AppVolume

Mutes or unmutes all audio sessions matching a process name.

PARAMETERS

name string
Process name to match (case-insensitive).
mute boolean
true to mute, false to unmute.
RETURNS: boolean true if at least one matching session was updated, false otherwise.
javascript
appVolume.setMuteByProcessName("Spotify.exe", true); // Mute Spotify

Full Example ​

Here is a complete example that lists sessions, reads volume info, and demonstrates setting volume and mute:

javascript
import { addon } from "novadesk";
const appVolume = addon.load("path/to/AppVolume.dll");

const sessions = appVolume.listSessions();
if (sessions.length > 0) {
  const first = sessions[0];
  console.log("App:", first.processName, "Vol:", first.volume, "Muted:", first.muted);

  // Set volume to 50%
  appVolume.setVolumeByProcessName(first.processName, 0.5);

  // Unmute the app
  appVolume.setMuteByPid(first.pid, false);

  // Read back the aggregated info
  const agg = appVolume.getByPid(first.pid);
  console.log("Aggregated:", agg);
}