# מערכת הסאונד

> תיעוד מקור. מקור: docs/sound-system.md · 6a466bf.

## Experience

One `SoundProvider` lives at the product root for Personal, Family, Business and Enterprise. It survives client-side navigation and does not run on the company website. Sound is enabled at a quiet 22% by default, only after a real user interaction. The header has a quick mute button; account/profile and workspace settings expose volume, interactions, action results, notifications, optional typing and seven sound previews.

Preferences use `lne:sound:v1` in this browser, across workspaces and tabs. They are device preferences, not tenant data. Muting and volume zero override all sounds including previews. Category switches affect normal playback; previews intentionally audition a selected cue regardless of its category switch. Typing is off by default and never applies to password fields. No typed text or audio is recorded or sent anywhere.

## Sound language

All sounds are synthesized locally with Web Audio sine/triangle oscillators and smooth gain envelopes. There are no downloaded samples, third-party audio services, microphone access, loops or autoplay on page load. Sound never replaces visible feedback.

| Cue          | Meaning                                      | Length |
| ------------ | -------------------------------------------- | ------ |
| press        | Button/link activation                       | 45 ms  |
| toggle       | Selection changed                            | 110 ms |
| type         | Optional text-field key feedback             | 18 ms  |
| start        | An operation began, without implying success | 130 ms |
| success      | A save, lookup or scan succeeded             | 285 ms |
| complete     | A workflow completed                         | 490 ms |
| warning      | Input or permission needs attention          | 280 ms |
| error        | An operation failed                          | 310 ms |
| notification | Informational update                         | 310 ms |

## Integration contract

Native buttons, links, tabs, switches, checkboxes, radio buttons, summaries and select changes receive automatic interaction feedback. Keyboard activation uses the control's click event so Enter/Space do not double-play. Disabled/busy controls and synthetic clicks are ignored. Native form validation produces one warning, not a chorus for every field.

Use `playSound("success")` only after a confirmed result. Current explicit integrations cover organization details/logos, provider selection, vehicle saves and registration lookup, onboarding, workspace edits, QR resolution, first location fix, save toasts and demo charging completion. Loading existing data and continuous GPS updates do not emit success tones. Aborted QR/plate lookups do not emit late results. `notification` is available for real future notification events; this feature does not create push notifications or live charging integrations.

`data-sound="none"` suppresses automatic interaction sounds for a control or subtree. Settings use this to avoid double playback when previewing or muting. Components may explicitly choose another interaction cue with `data-sound`, while asynchronous outcomes should use the event API. The event contains only a cue name and preview boolean.

## Runtime safeguards

The audio context is created/resumed only from a real interaction, and semantic events cannot initialize it on initial page load. Browser autoplay policies remain in force. Requests are not queued for a later user gesture. A first gesture may wait at most 250 ms for resume; pause/mute invalidates that wait. Unsupported or blocked audio leaves every product action usable.

One context and at most four short voices are used. Fast clicks are rate-limited; result/error cues have priority over interaction ticks and stop the preceding voices. Hidden pages pause immediately, discard sound requests and do not replay missed events on return. Unmount closes the audio context and removes event listeners. There is no background alarm or guarantee of sound on a locked/muted device.
