---
title: Xiph Libraries & Codecs
description: Build options, remote prebuilts, system package installation, Windows downloads, and platform-specific configuration for Ogg, Vorbis, Opus, and FLAC codecs in flutter_soloud
---

## Overview

*flutter_soloud* supports audio streaming and real-time playback for compressed audio formats including **Ogg**, **Vorbis**, **Opus**, and **FLAC** via libraries from [Xiph.org](https://www.xiph.org/).

Starting in version 5.1+, *flutter_soloud* uses **Dart Native Assets build hooks** to provide flexible options for handling Xiph libraries across all platforms:

```mermaid
flowchart TD
    A["hook/build.dart"] --> B{"no_xiph_libs: true?"}
    B -- Yes --> C["Mode 1: Without Xiph libs<br/>(Reduced binary size, no Ogg/Opus/FLAC)"]
    B -- No --> D{"<platform>_use_system_libs: true?"}
    D -- Yes --> E["Mode 2: System Libraries<br/>(Links system apt, brew, pacman, vcpkg)"]
    D -- No --> F{"<platform>_force_build_libs: true?"}
    F -- Yes --> G["Mode 3: Build from Source<br/>(Git clone + CMake build into .dart_tool)"]
    F -- No --> H["Default: Remote Prebuilt Libraries<br/>(Downloaded on-demand from GitHub releases)"]
```

1. **Default Mode (Remote Prebuilt Libraries)**: No configuration is required. Tested, precompiled static and shared Xiph libraries are hosted in the companion repository [flutter_soloud_prebuilds](https://github.com/alnitak/flutter_soloud_prebuilds). On the first build, Dart's Native Assets build hook automatically downloads and caches the matching archive for your target platform and architecture into `.dart_tool/flutter_soloud/xiph/prebuild/`. This keeps the pub package lightweight while ensuring apps run out of the box with zero setup.
2. **System Libraries Mode (`<platform>_use_system_libs: true`)**: Links against system-installed packages (apt, pacman, dnf, Homebrew, vcpkg). Ideal for Linux distribution packages (`.deb`, `.rpm`, Arch AUR) and custom desktop environments.
3. **Build from Source Mode (`<platform>_force_build_libs: true`)**: Clones the pinned Xiph Git repositories (`ogg`, `vorbis`, `opus`, `flac`) and builds them locally using CMake into `.dart_tool/flutter_soloud/xiph/install/<os>/<arch>` (or `install/ios/<simulator|device>/<arch>` on iOS).
4. **Without Xiph Mode (`no_xiph_libs: true`)**: Skips Xiph libraries entirely across all platforms to reduce application binary size.

---

## 1. Default Mode: Remote Prebuilt Libraries

**No configuration is needed in your `pubspec.yaml`!**

To keep the `flutter_soloud` package footprint small on [pub.dev](https://pub.dev/packages/flutter_soloud), precompiled binaries and C headers are hosted and maintained in the dedicated companion repository:

👉 **[alnitak/flutter_soloud_prebuilds](https://github.com/alnitak/flutter_soloud_prebuilds)**

### About `flutter_soloud_prebuilds`
The [flutter_soloud_prebuilds](https://github.com/alnitak/flutter_soloud_prebuilds) repository provides automated, reproducible CMake build scripts and multi-platform GitHub Actions workflows. Each release provides pre-compiled, optimized, and stripped libraries for all Flutter-supported targets:
- **Android**: Prebuilt shared `.so` libraries for all 4 ABIs (`arm64-v8a`, `armeabi-v7a`, `x86`, `x86_64`).
- **iOS**: Universal static `.a` archives covering physical devices (`arm64`) and simulators (`arm64`, `x86_64`).
- **macOS**: Universal static `.a` archives supporting both Apple Silicon (`arm64`) and Intel (`x86_64`).
- **Windows**: Precompiled 64-bit (`x64`) and 64-bit ARM (`arm64`) `.zip` packages with DLLs and import libraries.
- **Linux**: Precompiled 64-bit (`x86_64`) and 64-bit ARM (`aarch64`) `.so` shared libraries.
- **Include Headers**: Canonical Xiph C headers (`ogg/`, `vorbis/`, `opus/`, `FLAC/`) including generated configuration headers.

### How Download & Caching Work
When you run `flutter run` or `flutter build`:
1. The Dart Native Assets build hook (`hook/build.dart`) checks whether prebuilts already exist in the local project cache at `.dart_tool/flutter_soloud/xiph/prebuild/<platform>/`.
2. If not found, it automatically downloads the matching archive from the latest [GitHub Release](https://github.com/alnitak/flutter_soloud_prebuilds/releases) and extracts it into the cache.
3. It records the release tag in `flutter_soloud_prebuild_version.txt` inside the cache.
4. Subsequent builds reuse the cached libraries instantly without downloading again.

### Optional: Pinning a Specific Prebuild Version (`prebuild_tag`)
By default, the build hook queries the `latest` GitHub release. If your team or CI/CD environment requires pinning a specific release tag, specify `prebuild_tag` in your app's `pubspec.yaml`:

```yaml
hooks:
  user_defines:
    flutter_soloud:
      prebuild_tag: 'v1.0.1' # Optional: pin to a specific release tag
```

---

## 2. Using System-Installed Libraries (`<platform>_use_system_libs`)

On desktop platforms, you can instruct *flutter_soloud* to link against libraries installed in the operating system.

<Warning>
If you package an application with system libraries, the end user running your application **must** have those libraries installed on their machine. If missing, the app will fail to load the native library on startup (with an actionable error message indicating how to install them).
</Warning>

### Step 1: Install System Packages

Install the Xiph development packages using your platform's package manager:

#### Ubuntu / Debian / Raspberry Pi OS
```bash
sudo apt update
sudo apt install libogg-dev libvorbis-dev libopus-dev libflac-dev pkg-config
```

#### Arch Linux / Manjaro
```bash
sudo pacman -S libogg libvorbis opus flac pkgconf
```

#### Fedora / RHEL
```bash
sudo dnf install libogg-devel libvorbis-devel opus-devel flac-devel pkgconf-pkg-config
```

#### macOS (Homebrew)
```bash
brew install libogg libvorbis opus flac pkg-config
```

#### Windows (vcpkg)
```powershell
# For x64
vcpkg install libogg:x64-windows libvorbis:x64-windows opus:x64-windows flac:x64-windows

# For ARM64
vcpkg install libogg:arm64-windows libvorbis:arm64-windows opus:arm64-windows flac:arm64-windows
```
Set the `VCPKG_ROOT` environment variable if not already set (e.g., `C:\vcpkg`).

### Downloading Prebuilt Binaries for Windows

If you are on Windows and prefer to download prebuilt binaries manually:

1. **Download the Binaries**:
   - **FLAC**: [FLAC Download Page](https://xiph.org/flac/download.html) and [FLAC Official GitHub Releases](https://github.com/xiph/flac/releases)
   - **Ogg**: [Xiph Ogg Downloads](https://xiph.org/downloads/) and [Ogg Official GitHub Releases](https://github.com/xiph/ogg/releases)
   - **Vorbis**: [Xiph Vorbis Downloads](https://xiph.org/downloads/) and [Vorbis Official GitHub Releases](https://github.com/xiph/vorbis/releases)
   - **Opus**: [Opus Codec Downloads](https://opus-codec.org/downloads/) and [Opus Official GitHub Releases](https://github.com/xiph/opus/releases)

2. **Where to Place the Files**:
   When `windows_use_system_libs: true` is configured, the build hook searches:
   - `%VCPKG_ROOT%\installed\<arch>-windows\lib`
   - `C:\vcpkg\installed\<arch>-windows\lib`
   - `C:\Program Files\Xiph\lib` and `C:\Program Files\Xiph\include`
   - `C:\Xiph\lib` and `C:\Xiph\include`

### Step 2: Enable in `pubspec.yaml`

Add the platform-specific flag under `hooks.user_defines.flutter_soloud` in your app's `pubspec.yaml`:

```yaml
hooks:
  user_defines:
    flutter_soloud:
      linux_use_system_libs: true
      # and/or macos_use_system_libs: true
      # and/or windows_use_system_libs: true
```

---

## 3. Forcing Source Compilation (`<platform>_force_build_libs`)

If you want to compile the Xiph libraries from the official pinned Git repositories using CMake on your own machine:

```yaml
hooks:
  user_defines:
    flutter_soloud:
      linux_force_build_libs: true
      # and/or macos_force_build_libs: true
      # and/or windows_force_build_libs: true
      # and/or android_force_build_libs: true
      # and/or ios_force_build_libs: true
```

<Warning>
**Build time impact:** Setting `<platform>_force_build_libs: true` significantly increases build times. The build hook will `git clone` all four Xiph repositories (`ogg`, `vorbis`, `opus`, `flac`) and compile them from source via CMake.

Keep in mind that:
- **Android** compiles across 4 architectures (`arm64-v8a`, `armeabi-v7a`, `x86`, `x86_64`).
- **Apple (iOS / macOS)** compiles for both device and simulator architectures.
- Compilation artifacts are cached in `flutter_soloud`'s `.dart_tool/` directory, meaning they persist even after running `flutter clean` in your application (a re-clone and re-compile only occurs if the plugin's `.dart_tool/` is removed or on fresh CI/CD environments without cache).

For everyday development, leaving this option at its default (`false`) to use the remote precompiled libraries is strongly recommended.
</Warning>

### Requirements
- **Git** installed on your system PATH (`git --version`).
- **CMake** installed on your system PATH (`cmake --version`).
- A C/C++ compiler (GCC/Clang on Linux, Xcode on macOS/iOS, MSVC on Windows, Android NDK for Android).

Artifacts are compiled into `.dart_tool/flutter_soloud/xiph/install/<os>/<arch>` (or `install/ios/<simulator|device>/<arch>` on iOS) and cached for future builds.

---

## 4. Building Without Xiph Libraries (`no_xiph_libs`)

If your app only plays uncompressed PCM / WAV audio or built-in synthesizer waveforms and you want to reduce your app's binary size by **600 KB to 3 MB**:

Add `no_xiph_libs: true` to your `pubspec.yaml`:

```yaml
hooks:
  user_defines:
    flutter_soloud:
      no_xiph_libs: true
```

When built without Xiph:
- The compiler defines `NO_XIPH_LIBS`.
- No Xiph libraries are linked or bundled.
- Compressed audio streaming with Opus/Vorbis/FLAC formats is disabled (`SoLoudXiphLibsNotAvailableException` is thrown if attempted).
- All standard WAV, MP3, and synthesis features remain 100% operational.

See [Without Xiph libs](/get_started/no_xiph_libs) for full details.

---

## 5. Platform User Defines Reference

All build customization options are configured in your application's `pubspec.yaml` under `hooks.user_defines.flutter_soloud`:

| User Define | Type | Default | Supported Platforms | Description |
|---|---|---|---|---|
| `no_xiph_libs` | `bool` | `false` | All | Excludes Xiph codecs entirely, reducing final binary size by 0.6–3 MB. Disables Ogg, Vorbis, Opus, and FLAC streaming. |
| `prebuild_tag` | `string` | `'latest'` | All | Specific GitHub release tag to download from [flutter_soloud_prebuilds](https://github.com/alnitak/flutter_soloud_prebuilds) (e.g. `'v1.0.1'`). Default queries latest. |
| `linux_use_system_libs` | `bool` | `false` | Linux | Links against system-installed libraries via `pkg-config` (`apt`, `pacman`, `dnf`). |
| `use_system_xiph_libs` | `bool` | `false` | Linux | Legacy alias for `linux_use_system_libs`. |
| `linux_force_build_libs` | `bool` | `false` | Linux | Clones and builds Xiph libraries from Git source tree using CMake and GCC/Clang. |
| `macos_use_system_libs` | `bool` | `false` | macOS | Links against system or Homebrew-installed Xiph libraries. |
| `macos_force_build_libs` | `bool` | `false` | macOS | Clones and builds universal Apple Silicon & Intel static libraries from source via CMake. |
| `windows_use_system_libs` | `bool` | `false` | Windows | Links against system or `vcpkg`-installed libraries. |
| `windows_force_build_libs` | `bool` | `false` | Windows | Clones and builds Xiph libraries from Git source tree using CMake and MSVC. |
| `android_force_build_libs` | `bool` | `false` | Android | Clones and builds shared libraries across all 4 Android ABIs using Android NDK and CMake. |
| `ios_force_build_libs` | `bool` | `false` | iOS | Clones and builds static libraries for device (`arm64`) and simulator (`arm64`, `x86_64`) via CMake. |