PHPackages cldt/whisper.php - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. cldt/whisper.php ActivePlatform-package[Utility & Helpers](/categories/utility) cldt/whisper.php ================ PHP bindings for OpenAI Whisper made possible by whisper.cpp v1.1.1(1y ago)01.1k↓35%MITPHPPHP ^8.1 Since Apr 4Pushed 1y agoCompare [ Source](https://github.com/c-delouvencourt/whisper.php)[ Packagist](https://packagist.org/packages/cldt/whisper.php)[ RSS](/packages/cldt-whisperphp/feed)WikiDiscussions main Synced 1mo ago READMEChangelog (1)Dependencies (6)Versions (2)Used By (0) whisper.php =========== [](#whisperphp) A PHP binding for [whisper.cpp](https://github.com/ggerganov/whisper.cpp/), enabling high-performance automatic speech recognition and transcription. [![Total Downloads](https://camo.githubusercontent.com/4a31fa745c32e63834f390d1f8117ee07f190c5d551f8bf61f529c13b2132335/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f636f6465776974686b797269616e2f776869737065722e706870)](https://packagist.org/packages/codewithkyrian/whisper.php)[![Latest Stable Version](https://camo.githubusercontent.com/da88e38d712878981cbb765b2e79fc19db1f0c521309ae394508ed19534e540c/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f636f6465776974686b797269616e2f776869737065722e706870)](https://packagist.org/packages/codewithkyrian/whisper.php)[![License](https://camo.githubusercontent.com/4a11ce8bb25743a5493f03d08e63c39127fbedf5feda2bcf711acdd9704f94d6/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f636f6465776974686b797269616e2f776869737065722e706870)](https://github.com/CodeWithKyrian/whisper.php/blob/main/LICENSE)[![Tests](https://github.com/CodeWithKyrian/whisper.php/actions/workflows/tests.yml/badge.svg)](https://github.com/CodeWithKyrian/whisper.php/actions/workflows/tests.yml) Requirements ------------ [](#requirements) - PHP 8.1+ - FFI Extension Platform Support ---------------- [](#platform-support) Currently, whisper.php supports the following platforms: - Linux (x86\_64 and arm64) - macOS (Apple Silicon and Intel) - Windows (x86\_64) Features -------- [](#features) Speech recognition can be complex, but it doesn't have to be. Whisper.php simplifies the process by providing: - 🚀 High and low-level APIs - 📁 Model auto-downloading - 🎧 Support for various audio formats - 📝 Multiple output format exports - 🔊 Callback support for streaming and progress tracking Installation ------------ [](#installation) Install the library using Composer: ``` composer require codewithkyrian/whisper.php ``` Whisper.php requires the FFI extension to be enabled. In your php.ini configuration file, uncomment or add: ``` extension = ffi ``` Quick Start ----------- [](#quick-start) ### Low-Level API [](#low-level-api) The low-level API provides developers with granular control over the transcription process. It closely mimics the original C implementation, allowing for detailed configuration and manual segment processing: ``` // Initialize context with a model $contextParams = WhisperContextParameters::default(); $ctx = new WhisperContext("path/to/model.bin", $contextParams); // Create state and set parameters $state = $ctx->createState(); $fullParams = WhisperFullParams::default() ->withNThreads(4) ... ->withLanguage('en'); // Transcribe audio $state->full($pcm, $fullParams); // Process segments $numSegments = $state->nSegments(); for ($i = 0; $i < $numSegments; $i++) { $segment = $state->getSegmentText($i); $startTimestamp = $state->getSegmentStartTime($i); $endTimestamp = $state->getSegmentEndTime($i); printf( "[%s - %s]: %s\n", toTimestamp($startTimestamp), toTimestamp($endTimestamp), $segment ); } ``` #### Model Loading [](#model-loading) Downloading and managing whisper models can be a complex process. Whisper.php simplifies this with the ModelLoader, a convenient utility that streamlines model acquisition and management. ``` // Automatically download and load a model if it's already downloaded $modelPath = ModelLoader::loadModel('tiny.en', __DIR__.'/models'); ``` The `ModelLoader::loadModel()` method accepts two key parameters: 1. **Model Name**: Specify the model variant you want to use: - Supported base models: tiny, tiny.en, base, base.en, small, small.en, medium, medium.en, large, large.en - Note: Quantized models (q5, q8, etc.) are not supported by this utility 2. **Model Directory**: Specify the local directory where models should be stored and searched In the example above, it looks for `ggml-tiny.en.bin` in the `__DIR__./models` directory and if the model isn't found locally, it automatically downloads it from the official `whisper.cpp` huggingface repository #### Libraries Loading [](#libraries-loading) Whisper.php relies on platform-specific shared libraries, which are automatically downloaded the first time you initialize a model context. While this may cause a slight delay on the initial run, the process is one-time (unless you update the library via Composer). Once the libraries are cached, subsequent runs will perform as expected. #### Audio Input [](#audio-input) THe Whisper model expects a float array of sampled audio data at 16kHz. While tools like ffmpeg can generate this data, Whisper.php provides a built-in helper function to simplify the process for you. ``` // Convenient audio reading function $pcm = readAudio($audioPath); ``` The `readAudio()`helper function Supports multiple audio formats (MP3, WAV, OGG, M4A), automatically resamples to 16kHz and does these efficiently using `libsndfile` and `libsamplerate` The low level approach is ideal for developers who need: - Exact control over transcription parameters - Custom segment processing - Integration with existing complex audio processing pipelines ### High-Level API [](#high-level-api) For those seeking a more straightforward experience, the high-level API offers a simpler more abstracted workflow: ``` // Simple transcription $whisper = Whisper::fromPretrained('tiny.en', baseDir: __DIR__.'/models'); $audio = readAudio(__DIR__.'/sounds/sample.wav'); $segments = $whisper->transcribe($audio, 4); // Accessing segment data foreach ($segments as $segment) { echo toTimestamp($segment->startTimestamp) . ': ' . $segment->text . "\n"; } ``` The Whisper::fromPretrained() method simplifies the entire setup process with three key parameters: 1. **Model Name**: Specify the whisper model variant (e.g., 'tiny.en', 'base', 'small.en') 2. **Base Directory**: Specify where models should be stored and searched 3. **Transcription Parameters**: Optionally customize transcription behavior ``` // Advanced usage with custom parameters $params = WhisperFullParams::default() ->withNThreads(4) ->withLanguage('en'); $whisper = Whisper::fromPretrained( 'tiny.en', // Model name baseDir: __DIR__.'/models', // Model storage directory params: $params // Custom transcription parameters ); ``` The high-level API is perfect for quick prototyping, simple projects, or when you want to minimize boilerplate code while maintaining the power of the underlying whisper.cpp technology. Whisper Full Parameters ----------------------- [](#whisper-full-parameters) The `WhisperFullParams` offers a comprehensive and flexible configuration mechanism for fine-tuning the transcription process. It's designed with a fluent interface thus enabling method chaining and creating a clean, readable way to configure transcription parameters. ### Language Detection [](#language-detection) While the whisper model is remarkably good at automatic language detection, there are scenarios where manually specifying the language can improve accuracy: ``` $fullParams = WhisperFullParams::default() ->withLanguage('en'); // Specify two-letter language code eg. 'en' (English), 'de' (German), 'es' (Spanish) ``` ### Threading [](#threading) Computational performance can be fine-tuned by adjusting the number of threads used during transcription: ``` $fullParams = WhisperFullParams::default() ->withNThreads(8); // Default is 4 ``` More threads can speed up transcription on multi-core systems. For very short audio files however, more threads might introduce overhead. Experiment with thread counts to find the sweet spot for your specific use case and hardware configuration. ### Segment Callback [](#segment-callback) In many real-world applications, you'll want to process transcription segments as they're generated, rather than waiting for the entire transcription to complete. You can achieve that by providing a callback to the full params object that accepts a `SegmentData` object. ``` $fullParams = WhisperFullParams::default() ->withSegmentCallback(function (SegmentData $data) { printf("[%s - %s]: %s\n", toTimestamp($data->startTimestamp), toTimestamp($data->endTimestamp), $data->text ); }) ``` ### Progress Callback [](#progress-callback) Provide a callback to the full params to get access to the transcription progress. ``` $fullParams = $fullParams ->withProgressCallback(function (int $progress) { printf("Transcribing: %d%%\n", $progress); }); ``` There are lots of configurations in the `WhisperFullParams`. Modern IDEs with robust PHP intellisense will reveal a comprehensive list of configuration methods as you type, offering real-time suggestions and documentation for each parameter. Simply start typing `withXXX()` after `WhisperFullParams::default()`, and your IDE will guide you through the available configuration options. Exporting Outputs ----------------- [](#exporting-outputs) Once you've generated your transcription segments, you'll often need to export them in various formats for different use cases. Whisper.php provides convenient helper methods to export transcription segments to the most popular and widely-used formats. The exported segments are derived from an array of `SegmentData` objects, each containing precise timestamp and text information. ``` outputTxt($segments, 'transcription.txt'); // Ideal for quick reading, documentation, or further text processing outputVtt($segments, 'subtitles.vtt'); // Primarily used for web-based video subtitles, compatible with HTML5 video players outputSrt($segments, 'subtitles.srt'); // Widely supported by media players, video editing software, and streaming platforms outputCsv($segments, 'transcription.csv'); // Perfect for data analysis and spreadsheet applications ``` Logging ------- [](#logging) Whisper.php provides flexible logging capabilities, fully compatible with PSR-3 standards, which means seamless integration with popular logging libraries like Monolog and Laravel's logging system. By default, logging is disabled, but the library includes a built-in `WhisperLogger` that allows quick and easy logging: ``` // Log to a file Whisper::setLogger(new WhisperLogger('whisper.log')); // Log to standard output Whisper::setLogger(new WhisperLogger(STDOUT)); ``` Just make sure to call this `setLogger` method before initializing your WhisperContext. For more advanced logging needs, whisper.php integrates perfectly with Monolog, the most popular PHP logging library: ``` $monologLogger = new Logger('whisper'); $monologLogger->pushHandler(new StreamHandler('whisper.log', Logger::DEBUG)); $monologLogger->pushHandler(new FirePHPHandler()); // Set the Monolog logger Whisper::setLogger($monologLogger); ``` OR with Laravel Application Logger ``` // Using Laravel's Log facade Whisper::setLogger(Log::getLogger()); // Or directly with Laravel's logger Whisper::setLogger(app('log')); ``` Contributing ------------ [](#contributing) Contributions are welcome! Especially for: - Additional features - Bug fixes License ------- [](#license) This project is licensed under the MIT License. See the [LICENSE](https://github.com/codewithkyrian/whisper.php/blob/main/LICENSE) file for more information. Acknowledgements ---------------- [](#acknowledgements) - [whisper.cpp](https://github.com/ggerganov/whisper.cpp) - The underlying speech recognition technology ### Health Score 32 — LowBetter than 72% of packages Maintenance46 Moderate activity, may be stable Popularity19 Limited adoption so far Community8 Small or concentrated contributor base Maturity46 Maturing project, gaining track record Bus Factor1 Top contributor holds 98.6% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Unknown Total 1 Last Release 409d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/f9f297bd2d9cafd14dc7b7f55220bb058c82eaee69181facc3df0e0fc5b32cc3?d=identicon)[cldt](/maintainers/cldt) --- Top Contributors [![CodeWithKyrian](https://avatars.githubusercontent.com/u/48791154?v=4)](https://github.com/CodeWithKyrian "CodeWithKyrian (73 commits)")[![cldt-fr](https://avatars.githubusercontent.com/u/26087186?v=4)](https://github.com/cldt-fr "cldt-fr (1 commits)") ### Code Quality TestsPest Code StyleLaravel Pint ### Embed Badge ![Health badge](/badges/cldt-whisperphp/health.svg) ``` [![Health](https://phpackages.com/badges/cldt-whisperphp/health.svg)](https://phpackages.com/packages/cldt-whisperphp) ``` ### Alternatives [ecotone/ecotone Supporting you in building DDD, CQRS, Event Sourcing applications with ease. 558549.8k17](/packages/ecotone-ecotone)[civicrm/civicrm-core Open source constituent relationship management for non-profits, NGOs and advocacy organizations. 728272.9k20](/packages/civicrm-civicrm-core)[j0k3r/php-readability Automatic article extraction from HTML 186808.8k6](/packages/j0k3r-php-readability)[symfony/ai-platform PHP library for interacting with AI platform provider. 51927.7k136](/packages/symfony-ai-platform)[symfony/ai-agent PHP library for building agentic applications. 30536.7k44](/packages/symfony-ai-agent)[spomky-labs/pwa-bundle Progressive Web App Manifest Generator Bundle for Symfony. 6144.4k1](/packages/spomky-labs-pwa-bundle) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)