getStatus

Info

getStatus returns the current state of the audio analysis engine. It reports whether the analyzer is actively capturing audio and the last error encountered. Returns an AnalyzerStatus object.

Signature

function getStatus(): AnalyzerStatus

Parameters

This function takes no parameters.

Usage

Call getStatus to check whether the analyzer is running before calling getResult or to diagnose why analysis stopped. Common use cases:

• Guarding against reading empty results when the analyzer is idle
• Displaying connection status in a UI
• Detecting if the target process exited

Tips

Call getStatus before getResult to avoid reading stale or empty data. If isRunning is false, there is no active analysis and getResult will return default zeros.

Note

The error field persists across stop/start cycles. It is only cleared when a new start call succeeds. This allows you to inspect the failure reason even after the analyzer has stopped.

Return Value

Returns an AnalyzerStatus object.

Type	Description
AnalyzerStatus	{ isRunning: boolean, error: string | null }

Warning

isRunning reflects whether the native capture process is alive, not whether audio data is valid. The target process may be silent or have exited its audio session while the capture process is still running.

Example

TypeScript

import { getStatus, getResult, AnalyzerStatus } from '@eisland/windows-volume-analyzer';

const status: AnalyzerStatus = getStatus();

if (status.isRunning) {
  // Safe to read results
  const result = getResult();
  console.log(`Volume: ${(result.amplitude.rms * 100).toFixed(0)}%`);
} else {
  console.log('Analyzer is not running');
  if (status.error) {
    console.log(`Reason: ${status.error}`);
  }
}

JavaScript

const { getStatus, getResult } = require('@eisland/windows-volume-analyzer');

const status = getStatus();

if (status.isRunning) {
  // Safe to read results
  const result = getResult();
  console.log(`Volume: ${(result.amplitude.rms * 100).toFixed(0)}%`);
} else {
  console.log('Analyzer is not running');
  if (status.error) {
    console.log(`Reason: ${status.error}`);
  }
}

Notes

Note

getStatus is a lightweight synchronous call — it reads internal state without querying the native process. You can call it frequently without performance concerns.

Tips

Use getStatus in a polling loop to detect when the analyzer stops unexpectedly (e.g. the target process crashes). When isRunning transitions from true to false, check error for the reason and restart if needed.

Important

The error field is not cleared by stop. If you need a clean status, start a new analysis session with start — a successful start clears the previous error.

Danger Avoidance

Caution

Do not rely solely on isRunning to determine if audio data is valid. The analyzer may be running but the target process may have no active audio sessions. Always check AudioAnalysisResult.error from getResult for data-level issues.