Alta Call Issues and Incidents Nomenclature

The Alta Voce telemetry service continuously analyzes performance and status reports sent by the desktop client. Based on this data, the backend class App\Services\Telemetry\IssueDetectionService automatically detects software, hardware, and acoustic anomalies, generating or resolving incidents associated with each workstation.

1. Primary Audio States Nomenclature

The Alta Call desktop client reports the real-time status of its audio engine using the root-level audio_state parameter:

  • RUN: Audio engine is operational and active (speech processing in progress).
  • STP: Audio engine is cleanly stopped (e.g. locked Windows session, or no audio devices available).
  • LOD: The configured capture/playback audio device has been lost or disconnected.
  • FAI: Audio API failed to initialize with the requested configuration.
  • CRA: Audio engine has crashed unexpectedly (usually due to antivirus sandboxing, lack of permissions, or firewalls).

2. Incident Catalog & Detection Conditions

Here is the exhaustive list of error/incident codes managed by the system, along with their actual technical trigger and resolution rules:

VERSION_NOTSUPPORTED

  • Trigger Condition: The installed desktop client version is strictly lower than the minimum required version configured in the backend settings (VMOCALL_MIN_REQUIRED_VERSION).
  • Resolution: Upgrade the client software to a supported version.

AUDIO_STOPPED

  • Trigger Condition: The reported audio state is STP.
  • Exceptions (No incident created):
    • If the user's Windows session is locked (session_is_locked == true).
    • If the active voice transformation preset ID corresponds to the stopped speech processing transformation ID.

AUDIO_API_NONE

  • Trigger Condition: Unable to connect to the Windows WASAPI audio engine (the ACP field is completely empty in the telemetry payload) AND the reported audio state is FAI (failed).
  • Resolution: Usually requires IT intervention to grant microphone permissions or whitelist Alta Call in the workstation's antivirus software.

AUDIO_SETUP_FAILED

  • Trigger Condition: The Windows audio system is accessible (ACP is present) but the audio stream failed to initialize (audio_state == FAI).

AUDIO_DEVICES_NONE

  • Trigger Condition: The ACP data is transmitted, but the client explicitly reports that both capture (microphone) and playback (headphones/speakers) devices are undetected/inactive.

AUDIO_DEVICE_LOST

  • Trigger Condition: The audio device currently in use was suddenly unplugged or lost during runtime (audio_state == LOD), provided the user's Windows session is not locked.

AUDIO_CRASHED

  • Trigger Condition: The audio engine crashed unexpectedly during execution (audio_state == CRA).

AUDIO_DISCONNECTED

  • Trigger Condition: Physical audio devices are functional, but no active target client application (such as Zoiper, Genesys, Teams, Skype, or other communication/softphone tools) is connected to Alta Call's virtual audio output to broadcast the processed voice, while the Windows session is unlocked and active.

MULTI_INSTANCES (Historical)

  • Trigger Condition: More than one concurrent Alta Call process running on the same workstation (machine_nbrunningproc > 1) on legacy client versions (versions older than 0.25.0).

MULTI_INSTANCES_SAMESESSION

  • Trigger Condition: Multiple processes of the Alta Call application are running concurrently within the same active Windows user session (nbrunningproc_insamesession > 1).

3. Acoustic Performance & System Anomalies

These incidents are triggered based on performance thresholds configurable in the backend API environment:

HIGH_LATENCY

  • Trigger Condition: Audio transformation is active and the measured cumulative roundtrip latency exceeds the SLA limit.
  • Default Threshold: 150 ms (PT.full_latency.mean_ms > 150).

EXCESSIVE_XRUNS

  • Trigger Condition: The combined count of audio buffer underruns (playback) and overruns (capture) exceeds the threshold, leading to audio dropouts or voice distortions audible to the callee.
  • Default Threshold: 500 buffer xruns (total_xruns > 500).

HIGH_CPU

  • Trigger Condition: CPU utilization dedicated to the Alta Call desktop process exceeds safety limits.
  • Default Threshold: 50% of a full CPU core (cpu_usage > 0.5).

AUDIO_SATURATION

  • Trigger Condition: Digital audio signal clipping or saturation is detected during capture or playback.
  • Default Threshold: 0 saturations allowed (capture_saturations + playback_saturations > 0).