Download the PHP package errogaht/transcribe-bundle without Composer

TranscribeBundle

Symfony-first audio, video, speaker diarization, timestamps, subtitles and live speech transcription. Configure named profiles in YAML, autowire them like Flysystem storages, and keep provider-specific HTTP, polling and WebSocket details out of application code.

Palatine is the first built-in provider. The public contracts are provider-neutral, so another speech provider can be added as a normal Symfony service.

Requirements

• PHP 8.1 or newer
• Symfony 6.4, 7.4 or 8.x
• ext-curl and ext-fileinfo
• ffmpeg and ffprobe for video, WebM and traffic-efficient normalization

Installation

If Symfony Flex has not enabled the bundle, add it to config/bundles.php:

Keep the API key in an environment secret:

Create config/packages/transcribe.yaml:

Use a configured transcriber

The default profile is available through TranscriberInterface:

Each named profile is also a non-shared, autowireable service. The argument name selects it:

For dynamic selection, inject TranscriberRegistry and call get('subtitles'). Inputs may be a path, SplFileInfo, or in-memory bytes:

Per-call options can override a profile without mutating it:

Audio and video preparation

The default auto strategy passes compact AAC, M4A, MP3 and Ogg/Opus audio through unchanged. Video, browser WebM, lossless and unknown inputs are converted to mono Ogg/Opus at 16 kHz and 24 kbit/s. This extracts only the first audio stream and normally reduces upload traffic significantly.

Caller-owned files are never modified or deleted. Temporary files have mode 0600 and are removed in a finally block, including provider failures.

Live WebSocket transcription

Palatine live audio uses a full-duplex session. Audio chunks must already match the configured codec, sample rate and channel count.

The provider token stays server-side. Browsers should connect to an application-owned WebSocket or streaming controller; do not expose Palatine credentials to frontend code.

Output formats

TranscriptionResult always contains normalized text, language, duration, segments, words, provider, model and safe metadata. Inject FormatterRegistry to render text, timestamped, speaker, json, srt or vtt.

The CLI offers the same path:

Long files, polling and retries

In auto transport mode, diarization, media at least 55 seconds long, or prepared files at least 5 MB use Palatine's task API. The bundle schedules, polls, normalizes and releases the task internally; application code receives one completed result. Direct calls are used for smaller files. Retryable transport, rate-limit and server failures are retried with bounded backoff.

All thresholds and timeouts are configurable under a provider. Set transport: direct or transport: polling on a profile only when you need an explicit override.

For durable Messenger workflows, autowire the named task service separately:

Call submit() once, persist the returned opaque TranscriptionTask, and use short delayed messages to call check() until the state is terminal. A successful status contains the same normalized TranscriptionResult; call release() only after the result is durably stored. This flow survives worker restarts without uploading or billing the source twice. The primary TranscriberInterface remains the convenient completed-result API.

Messenger

The bundle intentionally does not own your queue, retries or result persistence. Put the same configured transcriber inside an application message handler:

Do not pass audio bytes through the queue. Pass an immutable storage identifier or path that remains valid until the worker finishes.

Neuron AI integration

There is no hard dependency on errogaht/neuron-ai-bundle. Inject a configured transcriber into an agent tool or orchestration service and pass TranscriptionResult::text to the named agent:

This keeps speech recognition replaceable and lets Neuron AI agents, workflows, RAG and Messenger remain configured by their own bundle.

Custom providers and formatters

Implement TranscriptionProviderInterface and register the service:

Implement StreamingTranscriptionProviderInterface on the same service if it supports live sessions. A custom formatter implements TranscriptFormatterInterface and carries the transcribe.formatter tag.

See architecture graph.

Events, errors and observability

Completed file calls dispatch TranscriptionStartedEvent, TranscriptionCompletedEvent and TranscriptionFailedEvent. Live sessions dispatch StreamOpenedEvent, StreamEventReceivedEvent and StreamClosedEvent. Logs include profile, provider, media size, duration and normalized counts, but never API keys, raw audio or transcript text.

All bundle failures implement TranscriptionExceptionInterface. Provider exceptions expose isRetryable() and statusCode() so application and Messenger policies can distinguish invalid credentials from temporary failures.

Development

License: MIT.