Download the PHP package shadowfiend/whisper without Composer

Whisper

Whisper is a PHP library for managing multiple audio transcription providers through a single API. It handles provider registration and selection, accepts file paths or custom audio sources The package provides the integration layer rather than a built-in connection to a specific external Whisper service.

Features

• Register and select named transcription providers.
• Transcribe a local file or any custom AudioSourceInterface implementation.
• Work with Transcript class and fields: text, duration, language, metadata, and timed segments.
• Whisper service works with psr streams

Requirements

• PHP 8.4 or later
• Composer

Installation

Install the package with Composer:

How to use it

Basic usage of your own whisper provider

Register a provider, select it by name, and pass an audio file to transcribe():

A string passed to transcribe() is automatically converted to a FileAudioSource. You can also select a provider through the magic __get method:

Usage of Transcript

Every provider returns a Transcript. Besides casting it to a string, you can inspect all available result data:

By default Transcript works with fields:

• text
• segments TranscriptSegment[] by default
• duration 0 by default
• language
• metadata

Providers can preserve timing information by adding TranscriptSegment objects:

How to create custom whisper provider

Create a provider by extending AbstractWhisperProvider and implementing doTranscribe(). The method receives a PSR-7 stream opened at the beginning of the audio.

[!NOTE] Do not close stream inside of doTranscribe method because AbstractWhisperProvider always closes the stream after transcription.

[!NOTE] Provider-specific configuration is available through setOptions() and getOptions().

Custom Audio Sources

Implement AudioSourceInterface when audio does not come from a local file. Each extract() call must return a new PSR-7 stream positioned at the beginning.

Custom Error Exceptions

• WhisperException is thrown when transcription is requested before selecting a provider.
• TranscribeException wraps any exception thrown by a provider and keeps the original exception as previous.

Mock Components

MockWhisperProvider and MockAudioSource are included for tests and examples. They exchange predefined JSON data and do not transcribe real audio.

Development

Development commands run in Docker through Make:

• make install builds the development image and installs Composer dependencies into vendor/.
• make install-hooks enables the repository's Git hooks after cloning. The pre-push hook runs the same build, lint, and test checks as CI.
• make lint runs PHPStan at the maximum level over src/ and tests/.
• make test builds the image and runs the PHPUnit test suite.

License

This project is available under the MIT License.