Documentation

WhisperApiHandler
in package
implements ApiRoutableInterface uses ApiRoutableTrait

Handler for Whisper transcription API endpoints.

Proxies requests to the NLP microservice for Whisper transcription.

Tags
since
3.0.0

Table of Contents

Interfaces

ApiRoutableInterface
Interface for API handlers that participate in route dispatch.

Constants

ALLOWED_EXTENSIONS  = ['mp3', 'mp4', 'wav', 'webm', 'ogg', 'm4a', 'mkv', 'flac', 'avi', 'mov', 'wma', 'aac']
Allowed audio/video file extensions.
ALLOWED_MIME_PREFIXES  = ['audio/', 'video/', 'application/ogg']
Allowed MIME-type prefixes.
MAX_FILE_SIZE  = 500 * 1024 * 1024
Maximum file size in bytes (500MB).

Properties

$client  : WhisperClient
$jobs  : WhisperJobRepository

Methods

__construct()  : mixed
formatCancelJob()  : array{cancelled: bool}
Cancel a transcription job.
formatGetLanguages()  : array{languages: array}
Get list of supported languages.
formatGetModels()  : array{models: array}
Get list of available Whisper models.
formatGetResult()  : array{job_id: string, text: string, language: string, duration_seconds: float}
Get the result of a completed transcription.
formatGetStatus()  : array{job_id: string, status: string, progress: int, message: string}
Get the status of a transcription job.
formatIsAvailable()  : array{available: bool}
Check if Whisper transcription is available.
formatStartTranscription()  : array{job_id: string}
Start a transcription job.
routeDelete()  : JsonResponse
Handle a DELETE request for this resource.
routeGet()  : JsonResponse
Handle a GET request for this resource.
routePost()  : JsonResponse
Handle a POST request for this resource.
routePut()  : JsonResponse
frag()  : string
Extract a fragment from the fragments array.
assertAudioVideoMime()  : void
Reject uploads whose detected MIME doesn't match an audio/video media type. Throws InvalidArgumentException on mismatch.
sanitizeFilename()  : string
Strip path components, control characters, and Unicode bidi-override runs from a client-supplied filename. Thin wrapper around the shared {@see InputValidator::sanitizeUploadName} — kept here so the existing test suite continues to exercise the Whisper-specific input path.

Constants

ALLOWED_EXTENSIONS

Allowed audio/video file extensions.

private mixed ALLOWED_EXTENSIONS = ['mp3', 'mp4', 'wav', 'webm', 'ogg', 'm4a', 'mkv', 'flac', 'avi', 'mov', 'wma', 'aac']

ALLOWED_MIME_PREFIXES

Allowed MIME-type prefixes.

private mixed ALLOWED_MIME_PREFIXES = ['audio/', 'video/', 'application/ogg']

We don't pin the full type because finfo varies across distros (e.g. m4a as audio/mp4 vs audio/x-m4a). Prefix matching is narrow enough: a text/html masquerading as .mp3 is rejected, but legitimate variants of audio/* and video/* go through. application/ogg covers Ogg containers that finfo sometimes tags under application instead of audio.

MAX_FILE_SIZE

Maximum file size in bytes (500MB).

private mixed MAX_FILE_SIZE = 500 * 1024 * 1024

Properties

Methods

formatCancelJob()

Cancel a transcription job.

public formatCancelJob(string $jobId) : array{cancelled: bool}
Parameters
$jobId : string

Job ID

Return values
array{cancelled: bool}

formatGetLanguages()

Get list of supported languages.

public formatGetLanguages() : array{languages: array}
Return values
array{languages: array}

formatGetModels()

Get list of available Whisper models.

public formatGetModels() : array{models: array}
Return values
array{models: array}

formatGetResult()

Get the result of a completed transcription.

public formatGetResult(string $jobId) : array{job_id: string, text: string, language: string, duration_seconds: float}
Parameters
$jobId : string

Job ID

Return values
array{job_id: string, text: string, language: string, duration_seconds: float}

formatGetStatus()

Get the status of a transcription job.

public formatGetStatus(string $jobId) : array{job_id: string, status: string, progress: int, message: string}
Parameters
$jobId : string

Job ID

Return values
array{job_id: string, status: string, progress: int, message: string}

formatIsAvailable()

Check if Whisper transcription is available.

public formatIsAvailable() : array{available: bool}
Return values
array{available: bool}

formatStartTranscription()

Start a transcription job.

public formatStartTranscription(array{name?: string, tmp_name?: string, size?: int} $file, string|null $language[, string $model = 'small' ]) : array{job_id: string}
Parameters
$file : array{name?: string, tmp_name?: string, size?: int}

Uploaded file from $_FILES

$language : string|null

Language code (null for auto-detect)

$model : string = 'small'

Whisper model name

Tags
throws
InvalidArgumentException

If file is invalid

throws
RuntimeException

If Whisper is not available

Return values
array{job_id: string}

routeDelete()

Handle a DELETE request for this resource.

public routeDelete(array<string|int, mixed> $fragments, array<string|int, mixed> $params) : JsonResponse
Parameters
$fragments : array<string|int, mixed>

URL path segments (resource name already consumed)

$params : array<string|int, mixed>

Query/body parameters

Return values
JsonResponse

routeGet()

Handle a GET request for this resource.

public routeGet(array<string|int, mixed> $fragments, array<string|int, mixed> $params) : JsonResponse
Parameters
$fragments : array<string|int, mixed>

URL path segments (resource name already consumed)

$params : array<string|int, mixed>

Query parameters

Return values
JsonResponse

routePost()

Handle a POST request for this resource.

public routePost(array<string|int, mixed> $fragments, array<string|int, mixed> $params) : JsonResponse
Parameters
$fragments : array<string|int, mixed>

URL path segments (resource name already consumed)

$params : array<string|int, mixed>

POST/JSON body parameters

Return values
JsonResponse

routePut()

public routePut(array<string|int, mixed> $fragments, array<string|int, mixed> $params) : JsonResponse
Parameters
$fragments : array<string|int, mixed>
$params : array<string|int, mixed>
Return values
JsonResponse

frag()

Extract a fragment from the fragments array.

protected frag(array<int, string> $fragments, int $index) : string
Parameters
$fragments : array<int, string>

The URL path fragments

$index : int

The index to extract

Return values
string —

The fragment at the index, or empty string if not present

assertAudioVideoMime()

Reject uploads whose detected MIME doesn't match an audio/video media type. Throws InvalidArgumentException on mismatch.

private static assertAudioVideoMime(string $tmpName) : void
Parameters
$tmpName : string

sanitizeFilename()

Strip path components, control characters, and Unicode bidi-override runs from a client-supplied filename. Thin wrapper around the shared {@see InputValidator::sanitizeUploadName} — kept here so the existing test suite continues to exercise the Whisper-specific input path.

private static sanitizeFilename(string $name) : string
Parameters
$name : string
Return values
string 

        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results