### AudioStreamControl for Stream Management

Source: https://context7.com/ukasz123/soundpool/llms.txt

Illustrates how to use `playWithControls` to get an `AudioStreamControl` object, which allows for direct manipulation of playback state, volume, and rate.

```APIDOC
## AudioStreamControl

`AudioStreamControl` is returned by `playWithControls()` and wraps a stream ID with stateful `playing` and `stopped` flags. It provides `stop()`, `pause()`, `resume()`, `setVolume()`, and `setRate()` directly on the object.

### Usage

```dart
import 'package:flutter/services.dart';
import 'package:soundpool/soundpool';

final pool = Soundpool.fromOptions(
  options: const SoundpoolOptions(maxStreams: 2),
);

Future<void> audioStreamControlDemo() async {
  final int soundId = await pool.load(await rootBundle.load('sounds/ambient.mp3'));

  // Get a control handle
  AudioStreamControl ctrl = await pool.playWithControls(soundId, repeat: -1);

  print('Stream ID: ${ctrl.stream}');
  print('Playing: ${ctrl.playing}');  // true
  print('Stopped: ${ctrl.stopped}');  // false

  // Volume and rate through the control object
  await ctrl.setVolume(volume: 0.7);
  await ctrl.setRate(playbackRate: 1.5);

  await Future.delayed(const Duration(seconds: 3));
  await ctrl.pause();
  print('After pause — playing: ${ctrl.playing}'); // false

  await Future.delayed(const Duration(seconds: 1));
  await ctrl.resume();
  print('After resume — playing: ${ctrl.playing}'); // true

  await Future.delayed(const Duration(seconds: 2));
  await ctrl.stop();
  print('After stop — stopped: ${ctrl.stopped}'); // true
  // ctrl.resume() after stop() has no effect
}
```
```

--------------------------------

### Initialize Soundpool Instance with Options

Source: https://context7.com/ukasz123/soundpool/llms.txt

Use `Soundpool.fromOptions` to create and configure a Soundpool instance. Specify stream type, maximum simultaneous streams, and platform-specific options like iOS AVAudioSession settings.

```dart
import 'package:soundpool/soundpool';

// Basic music pool (default)
final pool = Soundpool.fromOptions();

// Notification pool allowing up to 3 simultaneous streams
final notificationPool = Soundpool.fromOptions(
  options: const SoundpoolOptions(
    streamType: StreamType.notification,
    maxStreams: 3,
  ),
);

// iOS pool with explicit AVAudioSession configuration
final iosPool = Soundpool.fromOptions(
  options: SoundpoolOptions(
    streamType: StreamType.music,
    maxStreams: 5,
    iosOptions: SoundpoolOptionsIos(
      enableRate: true,
      audioSessionCategory: AudioSessionCategory.playback,
      audioSessionMode: AudioSessionMode.moviePlayback,
    ),
    macosOptions: SoundpoolOptionsMacos(enableRate: true),
  ),
);
```

--------------------------------

### SoundpoolOptions Configuration

Source: https://context7.com/ukasz123/soundpool/llms.txt

Demonstrates how to create a fully configured Soundpool instance using SoundpoolOptions, including platform-specific settings for Android, iOS, and macOS.

```APIDOC
## SoundpoolOptions

`SoundpoolOptions` is the unified configuration class that combines stream type, max streams, and all platform-specific options into a single immutable value passed to `Soundpool.fromOptions`.

### Usage

```dart
import 'package:soundpool/soundpool';

// Full configuration example
final options = SoundpoolOptions(
  streamType: StreamType.music,   // Android only: ring | alarm | music | notification
  maxStreams: 4,                   // Max simultaneous streams (Android emulated on iOS)
  androidOptions: SoundpoolOptionsAndroid(), // No extra options currently
  iosOptions: SoundpoolOptionsIos(
    enableRate: true,
    audioSessionCategory: AudioSessionCategory.playback,
    audioSessionMode: AudioSessionMode.moviePlayback,
  ),
  macosOptions: SoundpoolOptionsMacos(enableRate: true),
  webOptions: SoundpoolOptionsWeb(), // No extra options currently
);

final pool = Soundpool.fromOptions(options: options);

// Use kDefault for zero-configuration
final defaultPool = Soundpool.fromOptions(options: SoundpoolOptions.kDefault);
```
```

--------------------------------

### Soundpool.fromOptions

Source: https://context7.com/ukasz123/soundpool/llms.txt

Creates and initializes a Soundpool instance with configurable options for stream type, maximum simultaneous streams, and platform-specific settings.

```APIDOC
## Soundpool.fromOptions — Create a Soundpool instance

Creates and initializes a `Soundpool` with configurable stream type, maximum simultaneous streams, and platform-specific options. This is the primary constructor; the old positional `Soundpool(...)` factory is deprecated.

### Usage

```dart
import 'package:soundpool/soundpool';

// Basic music pool (default)
final pool = Soundpool.fromOptions();

// Notification pool allowing up to 3 simultaneous streams
final notificationPool = Soundpool.fromOptions(
  options: const SoundpoolOptions(
    streamType: StreamType.notification,
    maxStreams: 3,
  ),
);

// iOS pool with explicit AVAudioSession configuration
final iosPool = Soundpool.fromOptions(
  options: SoundpoolOptions(
    streamType: StreamType.music,
    maxStreams: 5,
    iosOptions: SoundpoolOptionsIos(
      enableRate: true,
      audioSessionCategory: AudioSessionCategory.playback,
      audioSessionMode: AudioSessionMode.moviePlayback,
    ),
    macosOptions: SoundpoolOptionsMacos(enableRate: true),
  ),
);
```
```

--------------------------------

### Initialize and Play Sound

Source: https://github.com/ukasz123/soundpool/blob/master/soundpool/README.md

Demonstrates how to initialize a Soundpool instance with a specific stream type, load an audio file from assets, and play it. Ensure the audio file exists in your assets.

```dart
import 'package:soundpool/soundpool.n';

Soundpool pool = Soundpool.fromOptions(
                      options: const SoundpoolOptions(streamType: StreamType.notification),
                  );

int soundId = await rootBundle.load("sounds/dices.m4a").then((ByteData soundData) {
                  return pool.load(soundData);
                });
int streamId = await pool.play(soundId);
```

--------------------------------

### Configure Soundpool with SoundpoolOptions

Source: https://context7.com/ukasz123/soundpool/llms.txt

Use SoundpoolOptions to set stream type, max streams, and platform-specific configurations for Android, iOS, macOS, and Web. Use SoundpoolOptions.kDefault for zero-configuration.

```dart
import 'package:soundpool/soundpool.n';

// Full configuration example
final options = SoundpoolOptions(
  streamType: StreamType.music,   // Android only: ring | alarm | music | notification
  maxStreams: 4,                   // Max simultaneous streams (Android emulated on iOS)
  androidOptions: SoundpoolOptionsAndroid(), // No extra options currently
  iosOptions: SoundpoolOptionsIos(
    enableRate: true,
    audioSessionCategory: AudioSessionCategory.playback,
    audioSessionMode: AudioSessionMode.moviePlayback,
  ),
  macosOptions: SoundpoolOptionsMacos(enableRate: true),
  webOptions: SoundpoolOptionsWeb(), // No extra options currently
);

final pool = Soundpool.fromOptions(options: options);

// Use kDefault for zero-configuration
final defaultPool = Soundpool.fromOptions(options: SoundpoolOptions.kDefault);
```

--------------------------------

### Soundpool.loadAndPlayUri

Source: https://context7.com/ukasz123/soundpool/llms.txt

Loads a sound from a URI and plays it immediately after loading. Useful for one-off playback of remote audio.

```APIDOC
## `Soundpool.loadAndPlayUri` — Load from URI and play immediately

Loads a sound from a URI and plays it immediately after loading. Useful for one-off playback of remote audio without needing to cache the `soundId`.

### Parameters
- **uri** (String) - The URI of the audio file to load.
- **repeat** (int) - Optional. Number of times to repeat the sound (0 = play once, -1 = loop indefinitely).
- **rate** (double) - Optional. Playback rate, from 0.5 to 2.0.

### Request Example
```dart
const url = 'https://example.com/sounds/alert.mp3';
final int soundId = await pool.loadAndPlayUri(url, repeat: 0, rate: 1.0);
```

### Response
#### Success Response
- **soundId** (int) - The ID of the loaded and playing sound. Returns a negative value if loading or playback failed.
```

--------------------------------

### Soundpool.loadUint8List

Source: https://context7.com/ukasz123/soundpool/llms.txt

Loads a sound from a Uint8List (raw bytes) into memory, returning a sound ID for playback. Returns -1 on failure.

```APIDOC
## Soundpool.loadUint8List — Load sound from raw bytes

Loads a sound from a `Uint8List` (e.g., bytes received from the network or generated in-memory). Returns a `soundId > -1` on success or `-1` on failure.

### Usage

```dart
import 'dart:typed_data';
import 'package:http/http.dart' as http;
import 'package:soundpool/soundpool.n

final pool = Soundpool.fromOptions();

Future<int> loadSoundFromBytes() async {
  final response = await http.get(
    Uri.parse('https://example.com/sounds/click.wav'),
  );
  if (response.statusCode == 200) {
    final Uint8List bytes = response.bodyBytes;
    final int soundId = await pool.loadUint8List(bytes);
    print('Loaded sound id: $soundId');
    return soundId;
  }
  return -1;
}
```
```

--------------------------------

### Load and Play Sound from Asset

Source: https://context7.com/ukasz123/soundpool/llms.txt

Loads a sound from a ByteData asset and plays it immediately upon completion. Supports looping and rate adjustments. On web, repeat and rate are ignored.

```dart
import 'package:flutter/services.dart';
import 'package:soundpool/soundpool.dart';

final pool = Soundpool.fromOptions();

Future<void> playOnLoad() async {
  final ByteData data = await rootBundle.load('sounds/notification.wav');
  // Plays once at normal rate
  final int soundId = await pool.loadAndPlay(data);

  // Or loop 3 times at half speed
  final int loopingSoundId = await pool.loadAndPlay(
    data,
    repeat: 3,
    rate: 0.5,
  );
  print('Playing soundId=$soundId, loopingSoundId=$loopingSoundId');
}
```

--------------------------------

### Soundpool.loadAndPlay

Source: https://context7.com/ukasz123/soundpool/llms.txt

Loads a sound from ByteData and plays it immediately upon completion. Returns the sound ID. On web, repeat and rate are ignored.

```APIDOC
## `Soundpool.loadAndPlay` — Load from asset and play immediately

Loads a sound from a `ByteData` asset and starts playing it as soon as loading completes. Returns the `soundId`. On web, `priority` and `repeat` are ignored and the sound plays only once.

### Parameters
- **data** (ByteData) - The audio data to load.
- **repeat** (int) - Optional. Number of times to repeat the sound (0 = play once, -1 = loop indefinitely). Ignored on web.
- **rate** (double) - Optional. Playback rate, from 0.5 to 2.0. Ignored on web.

### Request Example
```dart
final ByteData data = await rootBundle.load('sounds/notification.wav');
final int soundId = await pool.loadAndPlay(data);
final int loopingSoundId = await pool.loadAndPlay(data, repeat: 3, rate: 0.5);
```

### Response
#### Success Response
- **soundId** (int) - The ID of the loaded and playing sound. Returns a negative value if loading or playback failed.
```

--------------------------------

### macOS Network Entitlements for Soundpool

Source: https://github.com/ukasz123/soundpool/blob/master/soundpool_macos/README.md

To load sound files from a network source on macOS, you must add the specified network client entitlement to your project's .entitlements file.

```xml
<key>com.apple.security.network.client</key>
<true/>
```

--------------------------------

### Load and Play Sound from URI

Source: https://context7.com/ukasz123/soundpool/llms.txt

Loads a sound from a URI and plays it immediately after loading. Returns a negative value if loading or playback fails. Useful for one-off remote audio playback.

```dart
import 'package:soundpool/soundpool.dart';

final pool = Soundpool.fromOptions();

Future<void> playRemoteOnLoad() async {
  const url = 'https://example.com/sounds/alert.mp3';
  final int soundId = await pool.loadAndPlayUri(url, repeat: 0, rate: 1.0);
  if (soundId < 0) {
    print('Failed to load or play sound from URI');
  } else {
    print('Playing remote sound: soundId=$soundId');
  }
}
```

--------------------------------

### Load Sound from Raw Bytes (Uint8List)

Source: https://context7.com/ukasz123/soundpool/llms.txt

Load a sound directly from a `Uint8List`, useful for data from network requests or in-memory generation. Returns `soundId > -1` on success, or -1 on failure.

```dart
import 'dart:typed_data';
import 'package:http/http.dart' as http;
import 'package:soundpool/soundpool';

final pool = Soundpool.fromOptions();

Future<int> loadSoundFromBytes() async {
  final response = await http.get(
    Uri.parse('https://example.com/sounds/click.wav'),
  );
  if (response.statusCode == 200) {
    final Uint8List bytes = response.bodyBytes;
    final int soundId = await pool.loadUint8List(bytes);
    print('Loaded sound id: $soundId');
    return soundId;
  }
  return -1;
}
```

--------------------------------

### Soundpool.playWithControls

Source: https://context7.com/ukasz123/soundpool/llms.txt

Plays a sound and returns an AudioStreamControl handle for managing playback lifecycle (stop, pause, resume, volume, rate).

```APIDOC
## `Soundpool.playWithControls` — Play and get an `AudioStreamControl` handle

Like `play()`, but returns an `AudioStreamControl` object that bundles `stop()`, `pause()`, `resume()`, `setVolume()`, and `setRate()` bound to the active stream. This is the recommended approach for full playback lifecycle management.

### Parameters
- **soundId** (int) - The ID of the sound to play.
- **repeat** (int) - Optional. Number of extra loops (0 = play once, -1 = loop forever).
- **rate** (double) - Optional. Playback rate, from 0.5 to 2.0.

### Request Example
```dart
// Assuming _soundId is already loaded
_control = await pool.playWithControls(_soundId, repeat: -1, rate: 1.0);
await _control?.pause();
await _control?.resume();
await _control?.stop();
```

### Response
#### Success Response
- **AudioStreamControl** - An object with methods to control the audio stream (stop, pause, resume, setVolume, setRate).
```

--------------------------------

### Load Sound from URI

Source: https://context7.com/ukasz123/soundpool/llms.txt

Load a sound from a URI string, supporting remote or local file paths. Network loading on macOS requires specific entitlements. Returns `soundId > -1` on success, or -1 on failure.

```dart
import 'package:soundpool/soundpool';

final pool = Soundpool.fromOptions();

Future<void> loadRemoteSound() async {
  const url =
      'https://raw.githubusercontent.com/ukasz123/soundpool/master/soundpool/example/sounds/dices.m4a';
  final int soundId = await pool.loadUri(url);
  if (soundId >= 0) {
    print('Remote sound loaded with id: $soundId');
    await pool.play(soundId);
  } else {
    print('Failed to load sound from URI');
  }
}
```

--------------------------------

### Soundpool.loadUri

Source: https://context7.com/ukasz123/soundpool/llms.txt

Loads a sound from a specified URI (remote or local) into memory, returning a sound ID. Requires network entitlement on macOS for remote URIs. Returns -1 on failure.

```APIDOC
## Soundpool.loadUri — Load sound from a URI

Loads a sound from a remote or local URI string. On macOS, network loading requires the `com.apple.security.network.client` entitlement. Returns `soundId > -1` on success or `-1` on failure.

### Usage

```dart
import 'package:soundpool/soundpool.dart';

final pool = Soundpool.fromOptions();

Future<void> loadRemoteSound() async {
  const url =
      'https://raw.githubusercontent.com/ukasz123/soundpool/master/soundpool/example/sounds/dices.m4a';
  final int soundId = await pool.loadUri(url);
  if (soundId >= 0) {
    print('Remote sound loaded with id: $soundId');
    await pool.play(soundId);
  } else {
    print('Failed to load sound from URI');
  }
}
```
```

--------------------------------

### Load Sound from Asset ByteData

Source: https://context7.com/ukasz123/soundpool/llms.txt

Load a sound file from Flutter assets using `rootBundle`. The returned `soundId` is essential for playback. Returns -1 on failure.

```dart
import 'package:flutter/services.dart';
import 'package:soundpool/soundpool';

final pool = Soundpool.fromOptions(
  options: const SoundpoolOptions(streamType: StreamType.music),
);

// Load during app init; store soundId for repeated playback
late final int dicesSoundId;

Future<void> loadSounds() async {
  final ByteData assetData = await rootBundle.load('sounds/dices.m4a');
  dicesSoundId = await pool.load(assetData);
  if (dicesSoundId == -1) {
    print('Failed to load sound from asset');
  } else {
    print('Loaded sound with id: $dicesSoundId');
  }
}
```

--------------------------------

### Play Sound with AudioStreamControl

Source: https://context7.com/ukasz123/soundpool/llms.txt

Plays a loaded sound and returns an AudioStreamControl object for managing playback lifecycle (stop, pause, resume, volume, rate). This is the recommended method for full control.

```dart
import 'package:flutter/services.dart';
import 'package:soundpool/soundpool.dart';

final pool = Soundpool.fromOptions();
late int _soundId;
AudioStreamControl? _control;

Future<void> setup() async {
  _soundId = await pool.load(await rootBundle.load('sounds/music.mp3'));
}

Future<void> startPlayback() async {
  _control = await pool.playWithControls(_soundId, repeat: -1, rate: 1.0);
  print('playing=${_control!.playing}, stopped=${_control!.stopped}');
}

Future<void> pausePlayback() async {
  await _control?.pause();   // _control.playing == false
}

Future<void> resumePlayback() async {
  await _control?.resume();  // _control.playing == true
}

Future<void> stopPlayback() async {
  await _control?.stop();    // _control.stopped == true, cannot be resumed
}
```

--------------------------------

### Soundpool.load

Source: https://context7.com/ukasz123/soundpool/llms.txt

Loads a sound file from a Flutter asset into memory and returns a unique sound ID for playback. Returns -1 if loading fails.

```APIDOC
## Soundpool.load — Load sound from asset `ByteData`

Loads a sound file from a Flutter asset (via `rootBundle`) into memory and returns a `soundId`. The returned `soundId` must be stored for later use with `play()`. Returns `-1` if loading fails.

### Usage

```dart
import 'package:flutter/services.dart';
import 'package:soundpool/soundpool.dart';

final pool = Soundpool.fromOptions(
  options: const SoundpoolOptions(streamType: StreamType.music),
);

// Load during app init; store soundId for repeated playback
late final int dicesSoundId;

Future<void> loadSounds() async {
  final ByteData assetData = await rootBundle.load('sounds/dices.m4a');
  dicesSoundId = await pool.load(assetData);
  if (dicesSoundId == -1) {
    print('Failed to load sound from asset');
  } else {
    print('Loaded sound with id: $dicesSoundId');
  }
}
```
```

--------------------------------

### Soundpool.play

Source: https://context7.com/ukasz123/soundpool/llms.txt

Plays a previously loaded sound by its ID. Returns a stream ID for controlling playback. Supports looping and rate adjustments.

```APIDOC
## `Soundpool.play` — Play a loaded sound

Plays a previously loaded sound identified by `soundId`. Returns a `streamId > 0` for controlling the active playback, or `0` if playback failed. `repeat` sets the number of extra loops (0 = play once, -1 = loop forever). `rate` must be in the range `[0.5, 2.0]`.

### Parameters
- **soundId** (int) - The ID of the sound to play, obtained from `load()` or `loadAndPlay()`.
- **repeat** (int) - Optional. Number of extra loops (0 = play once, -1 = loop forever).
- **rate** (double) - Optional. Playback rate, from 0.5 to 2.0.

### Request Example
```dart
// Assuming _soundId is already loaded
int streamId = await pool.play(_soundId);
int fastStreamId = await pool.play(_soundId, repeat: 1, rate: 2.0);
int loopStreamId = await pool.play(_soundId, repeat: -1, rate: 0.5);
```

### Response
#### Success Response
- **streamId** (int) - The ID of the active playback stream. Returns a value greater than 0 if successful, otherwise 0.
```

--------------------------------

### Soundpool.stop, Soundpool.pause, Soundpool.resume

Source: https://context7.com/ukasz123/soundpool/llms.txt

Controls the lifecycle of an active audio stream using its stream ID. Pause and resume are not supported on web.

```APIDOC
## `Soundpool.stop` / `pause` / `resume` — Stream lifecycle control

Directly stop, pause, or resume an active audio stream using its `streamId` returned from `play()`. Note: `pause()` and `resume()` do not work on web.

### Parameters
- **streamId** (int) - The ID of the audio stream to control, obtained from `play()` or `playWithControls()`.

### Methods
- **`stop(int streamId)`**: Stops the audio playback. The stream cannot be resumed.
- **`pause(int streamId)`**: Pauses the audio playback. Can be resumed later.
- **`resume(int streamId)`**: Resumes paused audio playback.

### Request Example
```dart
// Assuming streamId is obtained from a play() call
await pool.pause(streamId);
await pool.resume(streamId);
await pool.stop(streamId);
```
```

--------------------------------

### Control Audio Playback with AudioStreamControl

Source: https://context7.com/ukasz123/soundpool/llms.txt

AudioStreamControl, returned by playWithControls(), allows object-oriented control over audio streams. It provides pause(), resume(), stop(), setVolume(), and setRate() methods.

```dart
import 'package:flutter/services.n';
import 'package:soundpool/soundpool.n';

final pool = Soundpool.fromOptions(
  options: const SoundpoolOptions(maxStreams: 2),
);

Future<void> audioStreamControlDemo() async {
  final int soundId = await pool.load(await rootBundle.load('sounds/ambient.mp3'));

  // Get a control handle
  AudioStreamControl ctrl = await pool.playWithControls(soundId, repeat: -1);

  print('Stream ID: ${ctrl.stream}');
  print('Playing: ${ctrl.playing}');  // true
  print('Stopped: ${ctrl.stopped}');  // false

  // Volume and rate through the control object
  await ctrl.setVolume(volume: 0.7);
  await ctrl.setRate(playbackRate: 1.5);

  await Future.delayed(const Duration(seconds: 3));
  await ctrl.pause();
  print('After pause — playing: ${ctrl.playing}'); // false

  await Future.delayed(const Duration(seconds: 1));
  await ctrl.resume();
  print('After resume — playing: ${ctrl.playing}'); // true

  await Future.delayed(const Duration(seconds: 2));
  await ctrl.stop();
  print('After stop — stopped: ${ctrl.stopped}'); // true
  // ctrl.resume() after stop() has no effect
}
```

--------------------------------

### Play Loaded Sound with Variants

Source: https://context7.com/ukasz123/soundpool/llms.txt

Plays a previously loaded sound using its soundId. Allows specifying repeat count and playback rate. Returns a streamId for controlling playback. Ensure the sound is loaded before calling play.

```dart
import 'package:flutter/services.dart';
import 'package:soundpool/soundpool.dart';

final pool = Soundpool.fromOptions(
  options: const SoundpoolOptions(maxStreams: 4),
);
late int _soundId;

Future<void> setup() async {
  _soundId = await pool.load(await rootBundle.load('sounds/click.wav'));
}

Future<void> playVariants() async {
  // Play once at normal speed
  int streamId = await pool.play(_soundId);

  // Play twice (1 repeat) at double speed
  int fastStreamId = await pool.play(_soundId, repeat: 1, rate: 2.0);

  // Loop indefinitely at half speed
  int loopStreamId = await pool.play(_soundId, repeat: -1, rate: 0.5);

  print('streamId=$streamId, fast=$fastStreamId, loop=$loopStreamId');

  // Stop the looping stream after 3 seconds
  await Future.delayed(const Duration(seconds: 3));
  await pool.stop(loopStreamId);
}
```

--------------------------------

### Soundpool.dispose

Source: https://context7.com/ukasz123/soundpool/llms.txt

Permanently destroys the Soundpool instance and releases all associated native resources. After calling this method, the Soundpool instance should no longer be used. It is typically called within the `dispose()` method of a `StatefulWidget` to ensure proper cleanup.

```APIDOC
## `Soundpool.dispose` — Permanently destroy the pool

Disposes of the `Soundpool` instance and all associated native resources. After calling `dispose()`, the instance must not be used. Typically called in a `StatefulWidget.dispose()` override.

### Request Example
```dart
// Ensure the pool is disposed when the widget is removed
@override
void dispose() {
  _pool.dispose(); // Always dispose to free native resources
  super.dispose();
}
```
```

--------------------------------

### Adjust Sound/Stream Volume with Soundpool.setVolume

Source: https://context7.com/ukasz123/soundpool/llms.txt

Use `setVolume` to adjust the playback volume for a specific sound ID or an active stream ID. You can set a uniform volume for both channels or specify separate left and right channel volumes.

```dart
import 'package:flutter/services.dart';
import 'package:soundpool/soundpool.dart';

final pool = Soundpool.fromOptions();

Future<void> volumeControl() async {
  final int soundId = await pool.load(await rootBundle.load('sounds/effect.wav'));

  // Set default volume before playing (affects all future plays of soundId)
  await pool.setVolume(soundId: soundId, volume: 0.8);

  final int streamId = await pool.play(soundId);

  // Adjust live stream volume
  await pool.setVolume(streamId: streamId, volume: 0.5);

  // Set stereo pan: louder on the right
  await pool.setVolume(
    streamId: streamId,
    volumeLeft: 0.3,
    volumeRight: 1.0,
  );
}
```

--------------------------------

### Soundpool.setVolume

Source: https://context7.com/ukasz123/soundpool/llms.txt

Adjusts the playback volume for a specific sound or an active stream. You can set a uniform volume for both channels or specify individual left and right channel volumes.

```APIDOC
## `Soundpool.setVolume` — Adjust volume for a sound or stream

Sets the playback volume for either a specific `soundId` (affects all future plays of that sound) or a currently active `streamId`. Either `volume` (sets both channels) or both `volumeLeft` and `volumeRight` must be provided.

### Parameters
#### Path Parameters
- **soundId** (int) - Required - The ID of the sound to adjust the volume for.
- **streamId** (int) - Required - The ID of the active stream to adjust the volume for.
- **volume** (double) - Optional - Sets the volume for both left and right channels (0.0 to 1.0).
- **volumeLeft** (double) - Optional - Sets the volume for the left channel (0.0 to 1.0).
- **volumeRight** (double) - Optional - Sets the volume for the right channel (0.0 to 1.0).

### Request Example
```dart
// Set default volume for a sound
await pool.setVolume(soundId: soundId, volume: 0.8);

// Adjust live stream volume
await pool.setVolume(streamId: streamId, volume: 0.5);

// Set stereo pan: louder on the right
await pool.setVolume(
  streamId: streamId,
  volumeLeft: 0.3,
  volumeRight: 1.0,
);
```
```

--------------------------------

### Dispose Soundpool Instance with Soundpool.dispose

Source: https://context7.com/ukasz123/soundpool/llms.txt

Call `dispose` to permanently release all native resources associated with the Soundpool instance. This method should be called when the Soundpool is no longer needed, typically in a `StatefulWidget.dispose()` override.

```dart
import 'package:flutter/material.dart';
import 'package:flutter/services.dart';
import 'package:soundpool/soundpool.dart';

class SoundWidget extends StatefulWidget {
  @override
  _SoundWidgetState createState() => _SoundWidgetState();
}

class _SoundWidgetState extends State<SoundWidget> {
  final Soundpool _pool = Soundpool.fromOptions(
    options: const SoundpoolOptions(streamType: StreamType.music),
  );
  int? _soundId;

  @override
  void initState() {
    super.initState();
    _loadSound();
  }

  Future<void> _loadSound() async {
    final data = await rootBundle.load('sounds/tap.wav');
    setState(() async {
      _soundId = await _pool.load(data);
    });
  }

  @override
  void dispose() {
    _pool.dispose(); // Always dispose to free native resources
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return ElevatedButton(
      onPressed: _soundId != null ? () => _pool.play(_soundId!) : null,
      child: const Text('Tap'),
    );
  }
}
```

--------------------------------

### Release Cached Sounds with Soundpool.release

Source: https://context7.com/ukasz123/soundpool/llms.txt

Use `release` to free all audio buffers loaded into the Soundpool instance without destroying the pool itself. This is useful for managing memory when transitioning between game levels or scenes.

```dart
import 'package:soundpool/soundpool.dart';

final levelPool = Soundpool.fromOptions(
  options: const SoundpoolOptions(maxStreams: 8),
);

Future<void> onLevelComplete() async {
  // Release all sounds for the finished level
  await levelPool.release();
  print('Level sounds released from memory');

  // Reload sounds for next level
  // final newSoundId = await levelPool.load(...);
}
```

--------------------------------

### Soundpool.release

Source: https://context7.com/ukasz123/soundpool/llms.txt

Frees all audio buffers that have been loaded into the sound pool from memory. This operation does not destroy the pool itself, allowing sounds to be reloaded later. It is useful for managing memory, especially when transitioning between different game levels or scenes.

```APIDOC
## `Soundpool.release` — Release cached sounds from memory

Frees all audio buffers loaded into this pool, without destroying the pool itself. The pool remains usable after `release()` — sounds can be loaded again. Call this when transitioning between game levels or scenes to free memory.

### Request Example
```dart
// Release all sounds for the finished level
await levelPool.release();
```
```

--------------------------------

### Soundpool.setRate

Source: https://context7.com/ukasz123/soundpool/llms.txt

Changes the playback speed of a currently playing stream. The playback rate can be adjusted within the range of 0.5 to 2.0, where 1.0 represents normal speed.

```APIDOC
## `Soundpool.setRate` — Change playback rate of an active stream

Changes the playback speed of a currently playing stream in the range `[0.5, 2.0]`. A value of `1.0` is normal speed, `0.5` is half speed, `2.0` is double speed. On iOS/macOS this requires `SoundpoolOptionsIos(enableRate: true)` (the default).

### Parameters
#### Path Parameters
- **streamId** (int) - Required - The ID of the active stream to adjust the playback rate for.
- **playbackRate** (double) - Required - The desired playback speed, ranging from 0.5 (half speed) to 2.0 (double speed).

### Request Example
```dart
// Set playback rate to double speed
await pool.setRate(streamId: streamId, playbackRate: 2.0);

// Gradually ramp up speed
for (double r = 1.0; r <= 2.0; r += 0.1) {
  await Future.delayed(const Duration(milliseconds: 200));
  await pool.setRate(streamId: streamId, playbackRate: r);
}
```
```

--------------------------------

### Change Playback Rate with Soundpool.setRate

Source: https://context7.com/ukasz123/soundpool/llms.txt

Modify the playback speed of a currently playing stream using `setRate`. The playback rate can be adjusted between 0.5 (half speed) and 2.0 (double speed). Ensure rate adjustment is enabled in Soundpool options for iOS/macOS.

```dart
import 'package:flutter/services.dart';
import 'package:soundpool/soundpool.dart';

final pool = Soundpool.fromOptions(
  options: SoundpoolOptions(
    iosOptions: SoundpoolOptionsIos(enableRate: true),
    macosOptions: SoundpoolOptionsMacos(enableRate: true),
  ),
);

Future<void> dynamicRate() async {
  final int soundId = await pool.load(await rootBundle.load('sounds/effect.wav'));
  final int streamId = await pool.play(soundId, repeat: -1, rate: 1.0);

  // Ramp up speed gradually
  for (double r = 1.0; r <= 2.0; r += 0.1) {
    await Future.delayed(const Duration(milliseconds: 200));
    await pool.setRate(streamId: streamId, playbackRate: r);
    print('Rate set to: $r');
  }
  await pool.stop(streamId);
}
```

--------------------------------

### Control Audio Stream Lifecycle

Source: https://context7.com/ukasz123/soundpool/llms.txt

Manages the lifecycle of an active audio stream using its streamId. Supports stopping, pausing, and resuming playback. Note that pause and resume are not supported on the web.

```dart
import 'package:flutter/services.dart';
import 'package:soundpool/soundpool.dart';

final pool = Soundpool.fromOptions();

Future<void> controlLifecycle() async {
  final int soundId = await pool.load(await rootBundle.load('sounds/loop.wav'));
  final int streamId = await pool.play(soundId, repeat: -1);

  await Future.delayed(const Duration(seconds: 2));
  await pool.pause(streamId);    // Pauses playback

  await Future.delayed(const Duration(seconds: 1));
  await pool.resume(streamId);   // Resumes from pause

  await Future.delayed(const Duration(seconds: 2));
  await pool.stop(streamId);     // Stops and cannot resume
}
```

--------------------------------

### Register Flutter Service Worker

Source: https://github.com/ukasz123/soundpool/blob/master/soundpool/example/web/index.html

Register the service worker for the Flutter web app. This code should be placed in your main index.html file.

```javascript
if ('serviceWorker' in navigator) {
  window.addEventListener('flutter-first-frame', function () {
    navigator.serviceWorker.register('flutter_service_worker.js');
  });
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.