PHP SoundFile

Low-level audio I/O and resampling for PHP, backed by libsndfile and libsamplerate

Features

• Read & write audio files — WAV, FLAC, Ogg Vorbis, MP3, AIFF, and 20+ other formats
• NDArray-native — data flows in and out as [frames × channels] NDArrays, no intermediate buffers
• Streaming I/O — instance-based SoundFile class with read, write, seek, tell, and block iteration
• One-shot convenience — sf_read() and sf_write() for simple load/save without managing a handle
• Sample rate conversion — sf_resample() with chunked progressive mode for large files, one-shot simple mode for small signals, and four quality levels
• Metadata — read and write title, artist, album, track number, and arbitrary tags
• Type-safe — PHP 8.2+ with backed enums, readonly value objects, and strict types throughout

Installation

composer require phpmlkit/soundfile

Requirements: PHP 8.2 or higher with the FFI extension enabled.

The package ships pre-compiled shared libraries for macOS (arm64, x86_64), Linux (x86_64, arm64), and Windows (x64).

Quick Start

Read and write

use function PhpMlKit\SoundFile\{sf_read, sf_write, sf_info};

// Read a file — returns [NDArray, SfInfo]
[$audio, $info] = sf_read('input.wav');
// $audio shape: [441000] (mono, Float32)

// Write it back (format and subtype auto-detected from extension)
sf_write('output.wav', $audio, $info->sampleRate);

// Probe signal properties without loading data
$info = sf_info('input.wav');
echo "{$info->frames} frames, {$info->channels} channels, {$info->duration()}s";

Resample

use function PhpMlKit\SoundFile\sf_resample;
use PhpMlKit\SoundFile\Enums\ResampleQuality;

// Chunked progressive — safe for large files (default)
$resampled = sf_resample($audio, inputRate: 44100, outputRate: 22050);

// One-shot simple — best for small signals
$resampled = sf_resample($audio, 44100, 16000, chunkSize: null);

// Best quality, explicit chunk size
$resampled = sf_resample(
    $audio, 44100, 8000,
    quality: ResampleQuality::Best,
    chunkSize: 4096,
);

Streaming with SoundFile

use PhpMlKit\SoundFile\SoundFile;
use PhpMlKit\SoundFile\Enums\FileMode;

// Open for reading
$sf = new SoundFile('input.wav', FileMode::Read);

// Seek and read
$sf->seek(44100);
$chunk = $sf->read(512);
echo $sf->tell(); // 44612

// Iterate in blocks
foreach ($sf->blocks(1024) as $block) {
    process($block);
}
$sf->close();

// Open for writing
$out = new SoundFile('output.wav', FileMode::Write,
    sampleRate: 44100, channels: 2,
);
$out->setTitle('My Track');
$out->setArtist('My Artist');
$out->write($stereoData);
$out->close();

See the full documentation for detailed guides, tutorials, and a complete API reference.

Core Concepts

Audio data layout

All NDArrays in this library use the shape [frames × channels] — time first, channel second. A mono file produces [N] or [N, 1] depending on the always2d flag. Stereo files always produce [N, 2].

DType, SampleFormat, and AudioFormat

Three independent choices interact when writing a file:

Concept	What it controls	Example
NDArray DType	How the data is stored in memory	Float32, Int16, Float64
SampleFormat	The file's encoding subtype	Pcm16, Float, Vorbis
AudioFormat	The container	Wav, Flac, Ogg

When you call sf_write(), the NDArray's dtype is automatically converted to match the target SampleFormat. You never need to call astype() yourself. The combination of AudioFormat and SampleFormat is validated against libsndfile's compatibility table — an incompatible pair (like Ogg + Pcm16) throws a SoundFileException before any data is written.

API Reference

Global Functions

These are importable with use function PhpMlKit\SoundFile\{...} and provide the simplest path for common operations.

sf_read()

Read an audio file into a single NDArray.

function sf_read(
    string $file,
    ?int $start = null,     // First frame (0-based; null = beginning)
    ?int $stop = null,      // One past last frame (null = EOF)
    bool $always2d = false, // If true, mono returns [frames, 1] instead of [frames]
    int $blocksize = 4096,  // Chunk size for internal read loop
): array // [NDArray, SfInfo]

The dtype matches the file's native format. The returned SfInfo object contains the file's signal properties (frames, channels, sample rate, format, etc.). For partial reads, use start and stop to specify a frame range. With $always2d = false (default), mono files return a 1D array for convenience.

[$data, $info] = sf_read('song.wav');
[$part, $info] = sf_read('song.wav', start: 44100, stop: 88200);
[$data, $info] = sf_read('song.wav', always2d: true);

sf_write()

Write an NDArray to an audio file.

function sf_write(
    string $file,
    NDArray $data,               // [frames] or [frames, channels]
    int $sampleRate,             // Sample rate in Hz
    ?AudioFormat $format = null, // Inferred from extension if null
    ?SampleFormat $subtype = null, // Format's default if null
): void

1D arrays are automatically expanded to [frames, 1] before writing. The NDArray dtype is converted to match the target subtype.

sf_write('out.wav', $data, sampleRate: 44100);
sf_write('out.flac', $data, 44100, subtype: SampleFormat::Pcm24);

sf_info()

Read signal properties without loading audio data. Opens the file, reads the header, and closes immediately.

function sf_info(string $file): SfInfo

sf_metadata()

Read string tags (title, artist, album, etc.) without loading audio data.

function sf_metadata(string $file): SfMetadata

$meta = sf_metadata('song.wav');
echo $meta->artist;

sf_check_format()

Validate that a container format and encoding subtype are compatible.

function sf_check_format(AudioFormat $format, SampleFormat $subtype): bool

sf_check_format(AudioFormat::Wav, SampleFormat::Pcm16);  // true
sf_check_format(AudioFormat::Ogg, SampleFormat::Pcm16);  // false

sf_resample()

Convert an NDArray from one sample rate to another.

function sf_resample(
    NDArray $input,                     // [frames, channels]
    int $inputRate,                     // Source sample rate in Hz
    int $outputRate,                    // Target sample rate in Hz
    ResampleQuality $quality = ResampleQuality::Best,
    ?int $chunkSize = 2048,             // null = one-shot, int = chunked progressive
): NDArray                                // [newFrames, channels] Float32

When $chunkSize is non-null (default), the function uses src_process in a loop with a single pre-allocated output buffer — safe for large signals. When null, it uses src_simple for a single-pass conversion.

The output is always Float32 regardless of input dtype. Inputs of other dtypes are automatically converted.

$resampled = sf_resample($data, 44100, 22050);           // chunked progressive
$resampled = sf_resample($data, 44100, 8000, chunkSize: null); // one-shot simple

Classes

SoundFile

An opened audio file handle for streaming read/write.

Constructor:

new SoundFile(
    string $path,
    FileMode $mode = FileMode::Read,
    // Write-mode parameters:
    ?int $sampleRate = null,
    ?int $channels = null,
    ?AudioFormat $format = null,
    ?SampleFormat $subtype = null,
)

In read mode, only $path and $mode are needed — metadata is read from the file header. In write mode, $sampleRate, $channels, $format, and $subtype are required (format defaults to the file extension, subtype defaults to the format's preferred).

Instance methods:

Method	Description
read(?int $numFrames): NDArray	Read up to N frames from current position. Null = all remaining.
write(NDArray $data): void	Write frames. Shape must match the file's channel count.
seek(int $offset, int $whence = SEEK_SET): void	Move the read/write position.
tell(): int	Current frame position.
eof(): bool	Whether the position has reached the end.
blocks(int $size = 4096): Generator	Yield NDArrays of up to $size frames.
close(): void	Close the handle (called automatically by destructor).
info(): SfInfo	Signal properties (frames, channels, sample rate, format).
frames(): int	Total frames.
channels(): int	Channel count.
sampleRate(): int	Sample rate in Hz.

Metadata getters/setters (read/write on open handles):

Getter	Setter	SF_STR constant
title()	setTitle(string)	0x01
copyright()	setCopyright(string)	0x02
software()	setSoftware(string)	0x03
artist()	setArtist(string)	0x04
comment()	setComment(string)	0x05
date()	setDate(string)	0x06
album()	setAlbum(string)	0x07
license()	setLicense(string)	0x08
trackNumber()	setTrackNumber(string)	0x09
genre()	setGenre(string)	0x10

Plus getString(int $strType) and setString(int $strType, string $value) for arbitrary SF_STR constants.

SfInfo

Immutable signal properties describing an audio file.

Factory methods:

Method	Description
SfInfo::probe(string $path): self	Open file, read header, close.
SfInfo::fromSfInfo(FFI\CData $sfInfo): self	Create from a populated libsndfile SF_INFO struct.
SfInfo::forWrite(int $frames, int $channels, int $sampleRate, AudioFormat $format, SampleFormat $subtype): self	Create write-ready info.

Properties:

Property	Type	Description
frames	int	Total frame count
channels	int	Number of audio channels
sampleRate	int	Sample rate in Hz
format	AudioFormat	Container format
sampleFormat	SampleFormat	Encoding subtype
sections	int	Number of data sections
seekable	bool	Whether the file supports seeking

Derived values:

Method	Returns	Description
duration()	float	Duration in seconds
nSamples()	int	Total sample values (frames × channels)

Immutable builders — return a copy with one field changed:

Method	Description
withFrames(int $f): self	Change frame count
withChannels(int $c): self	Change channel count
withSampleRate(int $sr): self	Change sample rate

Enums

AudioFormat

Container formats (25 cases). Values are libsndfile SF_FORMAT_* constants.

AudioFormat::Wav->extension();           // 'wav'
AudioFormat::fromExtension('flac');      // AudioFormat::Flac
AudioFormat::fromPath('song.mp3');       // AudioFormat::Mpeg
AudioFormat::Wav->defaultSampleFormat(); // SampleFormat::Pcm16
AudioFormat::Wav->compatibleSampleFormats(); // [PcmS8, Pcm16, Pcm24, ...]

SampleFormat

Encoding subtypes (20 cases). Values are libsndfile SF_FORMAT_* subtype constants.

SampleFormat::Pcm16->bitDepth();    // 16
SampleFormat::Pcm16->isInteger();   // true
SampleFormat::Float->isPcm();       // false
SampleFormat::Float->toDtype();     // DType::Float32
SampleFormat::fromDtype(DType::Int16); // SampleFormat::Pcm16

FileMode

File open modes.

Case	Description
FileMode::Read	Open for reading
FileMode::Write	Open for writing (creates/truncates)
FileMode::ReadWrite	Open for both reading and writing

ResampleQuality

libsamplerate converter quality levels.

Case	Description
ResampleQuality::Best	Band-limited sinc, highest quality, slowest
ResampleQuality::Medium	Band-limited sinc, medium quality
ResampleQuality::Fastest	Band-limited sinc, fastest
ResampleQuality::Linear	Linear interpolation, fastest but lowest quality

Exceptions

SoundFileException — thrown for I/O errors, invalid format combinations, closed-file operations, and resampling failures. Extends \RuntimeException.

Documentation

• Full Documentation
• What is SoundFile?
• Quick Start
• API Reference

Development

# Install PHP dependencies
composer install

# Run tests
composer test

# Run static analysis (PHPStan level 8)
composer lint

# Format code
composer cs:fix

License

MIT

Credits

• libsndfile — the C library for reading and writing audio files
• libsamplerate — the C library for sample rate conversion
• phpmlkit/ndarray — high-performance N-dimensional arrays for PHP