> ## Documentation Index
> Fetch the complete documentation index at: https://neo.tvk.company/llms.txt
> Use this file to discover all available pages before exploring further.

# Sounds

> Plays Neo's sounds, like the sound Neo controls make when interaction sounds are on.

> [!WARNING]
>
> BETA `NeoSounds` and interaction sounds are in beta. They may change before the stable release.

> [!NOTE]
>
> `NeoSounds` is initialized by `NeoInitializer.initialize()` in `main.dart`. Neo controls play the click only when [`NeoConfig.enableInteractionSounds`](https://neo.tvk.company/utilities/config) is `true`. It is `false` by default.

> [!WARNING]
>
> On web, add the `flutter_soloud` loader script to `web/index.html`. Without it, `NeoInitializer.initialize()` waits about 5 seconds and the sounds do not load. See [Install Neo](https://neo.tvk.company/install.md#4-web).

## Examples

> [tab] Interaction Sounds
>
> ```dart Turn On for the App lines theme={null}
> NeoApp(
>   title: "My Neo App",
>   config: NeoConfig(
>     enableInteractionSounds: true,
>   ),
>   routerConfig: neoRouter.config(),
> ),
> ```
>
> ```dart Turn On at Runtime lines theme={null}
> ref.read(neoConfigProvider.notifier).updateConfig(
>   ref.read(neoConfigProvider).copyWith(
>     enableInteractionSounds: true,
>   ),
> );
> ```

> [tab] Play the Click
>
> ```dart Press lines theme={null}
> NeoSounds.press();
> ```
>
> ```dart Turned On lines theme={null}
> NeoSounds.press(scale: NeoSounds.onScale);
> ```
>
> ```dart Follow the App Setting lines theme={null}
> if (ref.read(neoConfigProvider).enableInteractionSounds) {
>   NeoSounds.press(volume: 0.5);
> }
> ```

## Platform Support

> [!NOTE]
>
> **iOS**: Neo sets the shared audio session to ambient when it initializes. The click mixes with other audio, and the Ring/Silent switch mutes it. The session is shared by the whole app, so an app that plays media sets its own category after `NeoInitializer.initialize()`.
>
> **Web**: Needs the `flutter_soloud` loader script in `web/index.html`. See [Install Neo](https://neo.tvk.company/install.md#4-web).

## Methods

### NeoSounds.initialize()

Loads the click and starts the audio engine. **This method is called by `NeoInitializer.initialize()` and typically shouldn't be called manually.**

#### Return Value

**returns** `Future\<void\>`

A Future that completes when the click is loaded, or when loading failed.

### NeoSounds.press()

Plays the click once. It plays whether or not `enableInteractionSounds` is on.

#### Optional Parameters

**scale** `double` (default: 1)

Playback speed. Above 1 plays the click higher and shorter. Below 1 plays it lower and longer. Use the [scale constants](#constants) to match Neo's controls.

**volume** `double` (default: 1)

Volume of the click. `1` is full volume.

**sequenced** `bool` (default: false)

When `true`, schedules the click on the audio clock, so clicks less than 400 ms apart keep the spacing between your calls. Use it for a run of clicks, like ticks.

## Constants

**NeoSounds.onScale** `double`

Two semitones up (about `1.12`). [`NeoCheckbox`](https://neo.tvk.company/widgets/inputs/checkbox) and [`NeoToggleSwitch`](https://neo.tvk.company/widgets/controls/toggle-switch) use it when they turn on.

**NeoSounds.offScale** `double`

Two semitones down (about `0.89`). [`NeoCheckbox`](https://neo.tvk.company/widgets/inputs/checkbox) and [`NeoToggleSwitch`](https://neo.tvk.company/widgets/controls/toggle-switch) use it when they turn off.

**NeoSounds.releaseScale** `double`

Four semitones up (about `1.26`). A hold-to-confirm [`NeoButton`](https://neo.tvk.company/widgets/buttons/button) reaches this pitch at the end of its hold.

## Best Practices

* Check `enableInteractionSounds` before you call `press` from your own widget, so the app setting applies.
* Build a custom control on [`NeoInteractable`](https://neo.tvk.company/widgets/utilities/interactable) to get the click without calling `press` yourself.

## Behavior

* If the click fails to load, `press` does nothing. The failure is logged with [`NeoLogger`](https://neo.tvk.company/utilities/logger).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.