--- 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 `` section of `web/index.html`: ```html ``` 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); ``` ### 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()); } ``` - **`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. ## 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