recipes: soundfile 0.14.0 + libsndfile and its codec chain

[ndonkoHenri]

Adds soundfile — the library nearly every scientific-Python audio pipeline opens with — plus the seven native recipes it needs. Answers flet-dev/flet#6834.

Why it needs a recipe at all

soundfile ships no compiled code: soundfile_build.py calls ffibuilder.set_source("_soundfile", None), so it is cffi ABI mode — a pure-Python wrapper that dlopens libsndfile. It still cannot work unpatched, because its loader branches on sys.platform over darwin/win32/linux and both fallbacks end in a bare raise. Confirmed against PyPI's own wheel on an emulator before touching anything:

OSError: no packaged library for this platform
OSError: sndfile library not found using ctypes.util.find_library

What's here

Eight recipes. flet-libogg 1.3.6, flet-libvorbis 1.3.7, flet-libflac 1.5.0, flet-libopus 1.5.2, flet-libmpg123 1.33.7 and flet-libmp3lame 3.100 are built as static PIC archives and declared requirements.host_build of flet-libsndfile 1.2.2, which absorbs them into a single shared library. They are deliberately not requirements.host: nothing of them is loaded at runtime, so promoting them would make every consuming app download six wheels whose contents already live inside libsndfile.so. Only that one library ships — 1.9–2.7 MB per Android ABI, 2.9–3.2 MB per iOS slice — and soundfile itself is a 21 KB pure-Python wheel.

The result is that FLAC, Ogg Vorbis, Opus and MP3 all work, so sf.available_formats() on a phone returns the same list as on a desktop.

The loader patch is the interesting part. ffi.dlopen is a raw dlopen(3) and, unlike ctypes.CDLL, cannot dereference the .fwork text pointer serious-python leaves when it relocates a library into an iOS framework — that dereference lives only in iOS CPython's patched ctypes/__init__.py. So patches/mobile.patch wraps ctypes.util.find_library, lets ctypes resolve the name, and hands cffi the absolute path ctypes settled on (CDLL(candidate)._name), trying the bare soname (Android jniLibs), opt/lib/libsndfile.fwork (iOS) and opt/lib/libsndfile.so in turn. Everything downstream of find_library is upstream's, untouched.

Three smaller decisions worth a reviewer's eye:

• flet-libflac/patches/android-api-level.patch — FLAC reads the Android API level from CMAKE_SYSTEM_VERSION, which the NDK toolchain pins to 1. It therefore disables fseeko at every API level, and compat.h's #define fseeko fseek then collides with bionic's 64-bit-off_t declaration on armeabi-v7a only. Passing -DCMAKE_SYSTEM_VERSION does not help — the toolchain shadows it with a non-cache set().
• flet-libsndfile/patches/security-backports.patch — 1.2.2 (August 2023) is still the only libsndfile release, and ~80 commits have landed since. Five heap-overflow and over-read fixes are cherry-picked from master, all clean. A mobile app hands libsndfile whatever file a user picked, so these are reachable.
• iOS symbol hygiene — the shared image is hand-linked from the static build (CMake emits a versioned dylib triplet, which serious-python's first-dot framework naming collapses into one name), with -Wl,-exported_symbol,'_sf_*' so the absorbed codec symbols stay hidden, matching what libsndfile's own version script already does on Android. 41 exported symbols per iOS slice.

One platform limitation, documented not worked around

sf.read(io.BytesIO(...)) raises MemoryError on iOS. Virtual I/O hands libsndfile a ffi.callback(); cffi writes that trampoline at runtime and iOS refuses write+execute pages without the JIT entitlement. Only the file-object form is affected — paths and integer file descriptors (sf_open_fd) use no callbacks and pass. The README leads its reading section with "a real path is the only form that works everywhere" and gives the write-a-file replacement, and the tests assert the MemoryError on iOS rather than skipping, so a future cffi or OS change that lifts it does not go unnoticed.

Validation

CI run 34905677660 — 6/6 jobs green, both platforms × Python 3.12 / 3.13 / 3.14, with on-device tests on the 3.12 and 3.14 legs. Each of the four test legs: 17 passed, 1 skipped, EXIT 0 (the skip is the other platform's arm of the virtual-I/O split). 18 cases from 9 test functions, one parametrized across ten containers.

Wheel hygiene checked per slice: correct Machine per ABI, SONAME exactly libsndfile.so, DT_NEEDED limited to libc/libm/libdl, every Android LOAD segment aligned 0x4000; iOS filetype DYLIB, otool -L showing only libSystem, LC_BUILD_VERSION platform 2 on device and 7 on the simulators. soundfile's METADATA promotes flet-libsndfile (==1.2.2) and none of the six codec libraries.

Locally, the consumer example round-trips all seven containers on an Android emulator. The iOS half was never runnable on this machine (Xcode has no iOS platform component installed), so iOS rests on the CI run above.

Consumer notes

soundfile reads and writes audio files as numpy arrays and is the front door for librosa-, wfdb- and pywavelets-shaped pipelines. With this build a Flet app gets WAV, AIFF, AU, CAF/ALAC, W64, RF64, FLAC, Ogg Vorbis, Opus and MP3 on both platforms, from a single dependencies = ["soundfile"].

Details, the storage and threading guidance, the iOS file-object limitation and the traps worth knowing are in recipes/soundfile/README.md, with a runnable app in recipes/soundfile/examples/codec-roundtrip.

Also in this branch

.claude/skills/ picks up the three findings: the cffi-ABI-mode recipe shape in new-mobile-recipe, the cffi/.fwork and CMAKE_SYSTEM_VERSION entries in forge-error-catalogue, and a correction in local-recipe-testing — flet build 0.86.5 bundles Python 3.14, and for a pure-Python recipe a cp312-only build produces no error at all, it just silently loses to PyPI's unpatched wheel.