Download the PHP package phpmlkit/soundfile without Composer
On this page you can find all versions of the php package phpmlkit/soundfile. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
FAQ
Example:
In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
- Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
- To use Composer is sometimes complicated. Especially for beginners.
- Composer needs much resources. Sometimes they are not available on a simple webspace.
- If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
- Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Informations about the package soundfile
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
SoundFileclass with read, write, seek, tell, and block iteration - One-shot convenience —
sf_read()andsf_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 genre tags
- Type-safe — PHP 8.2+ with backed enums, readonly value objects, and strict types throughout
Installation
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
Resample
Streaming with SoundFile
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.
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.
sf_write()
Write an NDArray to an audio file.
1D arrays are automatically expanded to [frames, 1] before writing. The NDArray dtype is converted to match the target
subtype.
sf_info()
Read signal properties without loading audio data. Opens the file, reads the header, and closes immediately.
sf_metadata()
Read string tags (title, artist, album, etc.) without loading audio data.
sf_check_format()
Validate that a container format and encoding subtype are compatible.
sf_resample()
Convert an NDArray from one sample rate to another.
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.
Classes
SoundFile
An opened audio file handle for streaming read/write.
Constructor:
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 |
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.
SampleFormat
Encoding subtypes (20 cases). Values are libsndfile SF_FORMAT_* subtype constants.
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
Development
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
All versions of soundfile with dependencies
ext-ffi Version *
phpmlkit/ndarray Version ^2.0
codewithkyrian/platform-package-installer Version ^2.0