Xiph Libraries & Codecs

flutter_soloud supports audio streaming and real-time playback for compressed audio formats including Ogg, Vorbis, Opus, and FLAC via libraries from 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:

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. 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.

No configuration is needed in your pubspec.yaml!

To keep the flutter_soloud package footprint small on pub.dev, precompiled binaries and C headers are hosted and maintained in the dedicated companion repository:

👉 alnitak/flutter_soloud_prebuilds

The 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.

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 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.

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:

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

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

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

sudo apt update
sudo apt install libogg-dev libvorbis-dev libopus-dev libflac-dev pkg-config

sudo pacman -S libogg libvorbis opus flac pkgconf

sudo dnf install libogg-devel libvorbis-devel opus-devel flac-devel pkgconf-pkg-config

brew install libogg libvorbis opus flac pkg-config

# 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).

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

1. Download the Binaries:

   • FLAC: FLAC Download Page and FLAC Official GitHub Releases
   • Ogg: Xiph Ogg Downloads and Ogg Official GitHub Releases
   • Vorbis: Xiph Vorbis Downloads and Vorbis Official GitHub Releases
   • Opus: Opus Codec Downloads and Opus Official GitHub 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

Add the platform-specific flag under hooks.user_defines.flutter_soloud in your app's pubspec.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

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

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

• 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.

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:

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 for full details.

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