Download the PHP package codewithkyrian/whisper.php without Composer

whisper.php

A PHP binding for whisper.cpp, enabling high-performance automatic speech recognition and transcription.

Requirements

• PHP 8.1+
• FFI Extension

Platform Support

Currently, whisper.php supports the following platforms:

• Linux (x86_64 and arm64)
• macOS (Apple Silicon and Intel)

Note: Windows support is currently in development. Contributions and help are welcome to expand platform compatibility!

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

Install the library using Composer:

Whisper.php requires the FFI extension to be enabled. In your php.ini configuration file, uncomment or add:

Quick Start

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:

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.

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

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

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.

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

For those seeking a more straightforward experience, the high-level API offers a simpler more abstracted workflow:

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

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

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

While the whisper model is remarkably good at automatic language detection, there are scenarios where manually specifying the language can improve accuracy:

Threading

Computational performance can be fine-tuned by adjusting the number of threads used during transcription:

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

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.

Progress Callback

Provide a callback to the full params to get access to the transcription 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

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.

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:

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:

OR with Laravel Application Logger

Contributing

Contributions are welcome! Especially for:

• Windows platform support
• Additional features
• Bug fixes

License

This project is licensed under the MIT License. See the LICENSE file for more information.

Acknowledgements

• whisper.cpp - The underlying speech recognition technology