SteelSeries Sonar Node.js API

Overview

This Node.js package provides a convenient interface for interacting with the SteelSeries Sonar application API. The Sonar application allows users to control and display volumes for various audio channels. This is a TypeScript/JavaScript conversion of the original Python package steelseries-sonar-py.

Installation

To use this package, follow these steps:

1. Install the package using npm:

   npm install steelseries-sonar-js

2. Import the Sonar class in your TypeScript/JavaScript file:

   import { Sonar } from 'steelseries-sonar-js';

Usage

Initializing the Sonar Object

The Sonar class is initialized using a static async method init(). It accepts an optional options object with two properties: streamerMode: Set to true to use streamer mode (default is false). appDataPath: Specify a custom path for the SteelSeries Engine 3 coreProps.json file. The default path for the current OS is used automatically.

import { Sonar } from 'steelseries-sonar-js';

async function main() {
    // Initialize with default settings
    const sonar = await Sonar.init();

    // or with custom options
    const sonarWithOptions = await Sonar.init({
        appDataPath: "C:\path\to\coreProps.json",
        streamerMode: true
    });
}

main();

Streamer Mode

The SteelSeries Sonar API supports a streamer mode, which allows users to manage two separate sliders: streaming and monitoring.

To check if streamer mode is enabled:

const isStreaming = sonar.isStreamerMode();
console.log("Is Streamer Mode:", isStreaming);

To enable or disable streamer mode:

// Enable streamer mode
await sonar.setStreamerMode(true);

// Disable streamer mode
await sonar.setStreamerMode(false);

Retrieving Volume Information

Retrieve information about the current volume settings for all channels:

const volumeData = await sonar.getVolumeData();
console.log(volumeData);

Setting Volume for a Channel

Set the volume for a specific channel. The channel parameter should be one of the following: master, game, chatRender, media, aux, chatCapture. The volume parameter should be a number between 0 and 1. An optional streamerSlider can be provided, with values "streaming" (default) or "monitoring".

import { Channel, StreamerSlider } from 'steelseries-sonar-js';

const channel: Channel = "master";
const volume = 0.75;
const streamerSlider: StreamerSlider = "streaming"; // or "monitoring"

const result = await sonar.setVolume(channel, volume, streamerSlider);
console.log(result);

Muting/Unmuting a Channel

Toggle mute status for a specific channel. The muted parameter should be a boolean.

const channel: Channel = "game";
const muted = true;
const streamerSlider: StreamerSlider = "monitoring";

const result = await sonar.muteChannel(channel, muted, streamerSlider);
console.log(result);

Chatmix

Retrieve chat-mix data:

const chatmixData = await sonar.getChatMixData();
console.log(chatmixData);

Set chat-mix value between -1 and 1 to focus sound from the game or chatRender channel:

const result = await sonar.setChatMix(0.5);
console.log(result);

Exceptions

The package exports a set of custom error classes that might be thrown. It is advisable to handle these exceptions in your code. You can import them from steelseries-sonar-js/dist/exceptions.js.

• EnginePathNotFoundError: Raised when SteelSeries Engine 3 is not installed or the coreProps.json file cannot be found.
• ServerNotAccessibleError: Raised when the SteelSeries server is not accessible. Provides the HTTP status code.
• SonarNotEnabledError: Raised when SteelSeries Sonar is not enabled.
• ServerNotReadyError: Raised when SteelSeries Sonar is not ready.
• ServerNotRunningError: Raised when SteelSeries Sonar is not running.
• WebServerAddressNotFoundError: Raised when the web server address is not found.
• ChannelNotFoundError: Raised when the specified channel is not found.
• InvalidVolumeError: Raised when an invalid volume value is provided.
• InvalidMixVolumeError: Raised when an invalid mix volume value is provided.
• SliderNotFoundError: Raised when an unknown slider name is provided as streamerSlider value.

Example

Here is a complete example demonstrating the usage of the API:

import { Sonar } from 'steelseries-sonar-js';
import { EnginePathNotFoundError } from 'steelseries-sonar-js/dist/exceptions.js';

async function example() {
    try {
        // Initialize Sonar object
        const sonar = await Sonar.init();

        // Retrieve volume data
        const volumeData = await sonar.getVolumeData();
        console.log("Volume Data:", volumeData);

        // Set volume for the 'master' channel
        const resultVolume = await sonar.setVolume("master", 0.8, "streaming");
        console.log("Set volume for master:", resultVolume);

        // Mute the 'game' channel
        const resultMute = await sonar.muteChannel("game", true, "monitoring");
        console.log("Mute game:", resultMute);

        // Retrieve chat-mix data
        const chatmixData = await sonar.getChatMixData();
        console.log("Chatmix Data:", chatmixData);

        // Set chat-mix value
        const resultChatmix = await sonar.setChatMix(0.5);
        console.log("Set Chatmix:", resultChatmix);

    } catch (error) {
        if (error instanceof EnginePathNotFoundError) {
            console.error("Engine not found!", error.message);
        } else {
            console.error("An error occurred:", error);
        }
    }
}

example();

Special Thanks

Thanks to all contributors who made the original Python package possible - wex for figuring out the API, TotalPanther317 for understanding streamer mode and cookie for features like chat mix and streamer mode detection. Grateful for their efforts!