---
title: Installation
description: Learn how to set up flutter_soloud in your project
---

## Platform Setup

### Web Platform

To add the plugin to a web app, add the following line to the `<body>` section of `web/index.html`:
```html
<script src="assets/packages/flutter_soloud/web/init_soloud.js" defer></script>
```
This script automatically picks the best WASM build for the current page (see below). The old two-tag form that also loads `libflutter_soloud_plugin.js` explicitly is still supported, but no longer needed. See the [Web Platform Guide](/get_started/web_notes) for details.

### Linux Setup

Linux distributions require an audio server or library (ALSA, PulseAudio, or PipeWire/JACK) for audio playback. The underlying audio engine (`miniaudio`) dynamically loads these libraries at runtime (`libasound.so.2`, `libpulse.so`, `libjack.so`), so no extra development packages or compile-time headers are required to build `flutter_soloud`.

If an audio runtime library is missing on your system, install it using your package manager:

```bash
# Debian/Ubuntu
sudo apt install libasound2 libpulse0

# Arch Linux
sudo pacman -S alsa-lib libpulse

# Fedora
sudo dnf install alsa-lib pulseaudio-libs

# OpenSUSE
sudo zypper install libasound2 libpulse0
```

#### Audio Backend Selection

On Linux, `flutter_soloud` supports ALSA, PulseAudio, and JACK backends. By default, it uses `LinuxAudioBackend.auto_` which checks and prioritizes **ALSA first**, then PulseAudio, then JACK.

You can specify a preferred backend during initialization:

```dart
await SoLoud.instance.init(
  linuxAudioBackend: LinuxAudioBackend.pulseAudio, // auto_, alsa, pulseAudio, jack
);
```

Or switch the backend dynamically at runtime:

```dart
await SoLoud.instance.setLinuxAudioBackend(LinuxAudioBackend.pulseAudio);
```

#### Extended Audio Formats on Linux (M4A, MP4, AAC, AC-3, E-AC-3)

While core audio formats (MP3, WAV, FLAC, and OGG Opus/Vorbis/FLAC) are decoded by built-in and bundled libraries, extended OS-native formats on Linux (**M4A**, **MP4 audio tracks**, **AAC**, **AC-3**, and **E-AC-3**) rely on **FFmpeg** shared libraries (`libavcodec` and `libavformat`).

The native engine dynamically loads these shared libraries at runtime using `dlopen` (probing for `libavcodec.so.58` through `libavcodec.so.61`), so no development headers or compile-time dependencies are required to build your app.

To enable playback and streaming of these formats on Linux, ensure FFmpeg runtime libraries are installed on the user's system:

```bash
# Debian / Ubuntu / Linux Mint
sudo apt install ffmpeg libavcodec-extra

# Arch Linux / Manjaro
sudo pacman -S ffmpeg

# Fedora
sudo dnf install ffmpeg-free # or ffmpeg from RPM Fusion

# OpenSUSE
sudo zypper install ffmpeg
```

<Info>
If FFmpeg libraries are not installed on a Linux host, core formats (MP3, WAV, FLAC, OGG) continue to play normally. Loading an M4A/MP4/AAC/AC-3/E-AC-3 file without FFmpeg will throw an error indicating that `libavformat`/`libavcodec` was not found.
</Info>

### Native Build System

Native C/C++ engine sources and Xiph audio codecs (Ogg, Vorbis, Opus, FLAC) are compiled and integrated automatically using [Dart build hooks](https://dart.dev/tools/hooks). By default, tested prebuilt Xiph libraries are automatically downloaded on demand from [flutter_soloud_prebuilds](https://github.com/alnitak/flutter_soloud_prebuilds) on first build and cached without manual setup.

To use system-installed libraries (`apt`, `brew`, `vcpkg`, or Windows downloads) or build without Xiph to minimize binary size, see the [Xiph Libraries & Codecs Guide](/get_started/xiph_libs) and [Without Xiph libs](/get_started/no_xiph_libs).

### iOS and macOS

Native assets are compiled and bundled seamlessly whether your Flutter app uses CocoaPods or Swift Package Manager (SPM). No CMake installation is required.

⚠️ When building release archives (IPA/app) with **Swift Package Manager** (SPM), if you encounter symbol stripping warnings, you can adjust:
1. Open your project in Xcode
2. Navigate to Target Runner > Build Settings > Strip Style
3. Set to "Non-Global Symbols"

### Windows & Linux Setup (Pre-Flutter 3.16 apps)

If your Flutter application was created prior to Flutter 3.16, make sure your `windows/CMakeLists.txt` (and/or `linux/CMakeLists.txt`) contains the native assets installation step under the `=== Installation ===` section:

```cmake
# Copy the native assets provided by the build.dart from all packages.
set(NATIVE_ASSETS_DIR "${PROJECT_BUILD_DIR}native_assets/windows/") # or /linux/
install(DIRECTORY "${NATIVE_ASSETS_DIR}"
   DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
   COMPONENT Runtime)
```

## AI Agent Skills

`flutter_soloud` bundles **Agent Skills** that teach AI coding assistants (such as Claude, Cursor, Gemini, GitHub Copilot, Cline, Codex, OpenCode, etc.) how to properly use every feature of this plugin, including sample-accurate scheduling, mixing buses, 3D audio, filters, streaming, and mixer output capture.

To install or update the skills in your project, run:

```bash
dart run flutter_soloud:skills
```

To check whether newer skill versions are available without writing any files:

```bash
dart run flutter_soloud:skills --check
```

## Basic Usage

Initialize SoLoud in your app:

```dart
void main() async {
  await SoLoud.instance.init(
    sampleRate: 44100,          // Sample rate (default 44100)
    bufferSize: 2048,           // Mix buffer size affects latency/stability
    channels: Channels.stereo,  // Output channels
    lowLatency: true,           // Native low latency mode
    devicePeriodFrames: 512,    // Hardware device period (used with renderAheadFrames)
    renderAheadFrames: 0,       // Render-ahead ring depth (native only, default 0/disabled)
  );
  
  runApp(const MyApp());
}
```

<Info>
- **`bufferSize`**: The mixing buffer quantum. The smaller the buffer size, the lower the latency, but smaller buffers leave less CPU headroom for audio DSP/filters. Defaults to 2048.
- **`renderAheadFrames` / `devicePeriodFrames`**: When `renderAheadFrames > 0` on native platforms, the engine enables the experimental render-ahead ring, which decouples the hardware device period from the mixing buffer size to deliver ultra-low reactive playback latency. See [Playback Controls](/audio/playback#render-ahead-ring-native-only).
- **`lowLatency`**: Configures native low-latency output modes where available.
</Info>

## Best Practices

- Initialize SoLoud early in your app lifecycle
- Handle initialization errors appropriately
- Configure buffer size and render-ahead based on your latency and app needs
- Clean up resources when your app closes