/ 
Langertha-0.504
/ Langertha::Engine::Whisper

NAME

Langertha::Engine::Whisper - Whisper compatible transcription server

VERSION

version 0.504

SYNOPSIS

use Langertha::Engine::Whisper;

my $whisper = Langertha::Engine::Whisper->new(
    url                 => 'http://localhost:8000/v1',
    api_key             => $ENV{WHISPER_API_KEY},   # if the server checks one
    transcription_model => 'Systran/faster-whisper-small',
);

print $whisper->simple_transcription('recording.ogg');

DESCRIPTION

Provides access to a self-hosted Whisper-compatible transcription server. Extends Langertha::Engine::TranscriptionBase and transcribes through the server's /audio/transcriptions endpoint.

url is required. The API key defaults to 'whisper' and is sent as Authorization: Bearer .... The transcription model defaults to an empty string, and then no model field is sent, for servers that pick their own default.

speaches (formerly faster-whisper-server) is a compatible server. Its answers differ from OpenAI's in these points (seen on speaches 0.8.3, 2026-10):

  • model is required: without transcription_model the request fails with 422 and "loc":["body","model"],"msg":"Field required". Name a model the server has installed; GET /v1/models lists them (Hugging Face IDs such as Systran/faster-whisper-small), an unknown one answers 404.

  • A server started with API_KEY checks the bearer token; a wrong key answers 403, not 401.

  • Errors are FastAPI's {"detail": ...}, not OpenAI's {"error": {...}}. The croak message carries the body, so the detail text is in $@.

  • verbose_json reports language as a code (en), where OpenAI says english and Groq English. Segment ids start at 1. Each word in words keeps its leading space (" This"), and so does each segment's text; the top-level text has none.

  • Fields a request did not ask for are present as JSON null, not missing: words without word timestamps, usage and logprobs. Read @{ $result->{words} // [] }. A null usage gives a Langertha::CallResult without usage.

  • srt and text come as text/plain; charset=utf-8, vtt as text/vtt; charset=utf-8. "transcription_response" in Langertha::Role::OpenAICompatible returns each body as text.

Langertha::Engine::OpenAI exposes a whisper attribute that returns a Langertha::Engine::TranscriptionBase bound to the OpenAI cloud (sharing its api_key and url) — use that when you want OpenAI's hosted Whisper endpoint without re-stating credentials.

THIS API IS WORK IN PROGRESS

SEE ALSO

SUPPORT

Issues

Please report bugs and feature requests on GitHub at https://github.com/Getty/langertha/issues.

IRC

Join #langertha on irc.perl.org or message Getty directly.

CONTRIBUTING

Contributions are welcome! Please fork the repository and submit a pull request.

AUTHOR

Torsten Raudssus <getty@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by Torsten Raudssus https://raudssus.de/.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.