transcriptor — audio transcription for PHP

Native PHP extension for audio transcription (speech-to-text) embedding whisper.cpp. Ready-to-use binaries — no compilation, no dependencies to install.

• Model loaded once per process (instant between FPM requests)
• Self-healing: an inference engine crash never kills PHP (process isolation, retry, automatic model reload)
• Async (transcribeAsync), timeouts, built-in statistics
• WAV / MP3 / FLAC audio (automatically resampled) or raw PCM
• Whisper GGML .bin models (tiny → large-v3-turbo, quantized or not)

Installation

curl -fsSL https://raw.githubusercontent.com/akramzerarka/transcriptor/main/install.sh | bash

Requirements: Linux x86-64 (glibc ≥ 2.27 — Ubuntu 18.04+, Debian 10+, RHEL/Alma 8+, Fedora 29+…), PHP 8.4 or 8.5 NTS. Binary integrity is verified via SHA256. (Alpine/musl, ARM, and PHP ZTS are not supported.)

Then download a model:

./scripts/download-model.sh base q5_1        # ~60 MB, multilingual, fast
./scripts/download-model.sh large-v3-turbo   # best quality

Usage

use Transcriptor\Engine;

$engine = Engine::load('/opt/models/ggml-base-q5_1.bin');   // loaded once per process

$res = $engine->transcribe('/uploads/meeting.mp3', ['language' => 'en']);

echo $res->text;                  // full text
foreach ($res->segments as $s) {  // timestamped segments
    printf("[%.1fs–%.1fs] %s\n", $s['start'], $s['end'], $s['text']);
}

Async:

$job = $engine->transcribeAsync('/uploads/episode.mp3');
// … other work …
$res = $job->wait(60_000);        // null if not finished (job continues)

Full API (IDE autocompletion): stubs/transcriptor.stub.php. Complete example: examples/transcribe.php.

Configuration (php.ini)

Directive	Default	Purpose
transcriptor.isolation	fork	fork = crash-proof (recommended); direct = minimal latency
transcriptor.max_retries	2	Retries after a crash before CrashException
transcriptor.timeout_ms	0	Max time per transcription (0 = unlimited)
transcriptor.max_models	2	Simultaneous models in cache (LRU eviction)
transcriptor.max_concurrency	2	Async pool threads
transcriptor.default_threads	0	Inference threads (0 = auto)

Production tips: account for model RAM per FPM worker; with concurrency N, give cores/N threads per call.

Binaries

File	PHP	Platform
bin/transcriptor-php8.4-nts-linux-x86_64.so	8.4 NTS	Linux x86-64, glibc ≥ 2.27
bin/transcriptor-php8.5-nts-linux-x86_64.so	8.5 NTS	Linux x86-64, glibc ≥ 2.27

Checksums: bin/SHA256SUMS. Each .so only depends on libc/libm (libstdc++ statically linked) and targets x86-64-v2 (any CPU since ~2009).

License

MIT. Embeds whisper.cpp (MIT) and miniaudio (MIT-0).