Whisper Transcriptions

Tools now includes a permission-gated Whisper transcription queue.

Access model

User web UI: /whisper (requires permission:whisper.use)
Admin web UI: /admin/whisper (requires permission:whisper.manage)
API: /api/whisper/* (requires authenticated user + whisper.use)
Admin queue trigger API: POST /api/whisper/run-now (requires whisper.manage)

Admin users are allowed by admin bypass.

How it works

A user submits a media URL.
A queue row is created in whisper_transcriptions with status queued.
Scheduled command whisper:process claims queued rows and runs transcription.
Progress is updated in stages (downloading, transcribing, finalizing, completed or failed).
Owner and admins can poll job status and transcript text.

Required host dependencies

Typical Debian/Ubuntu setup:

sudo apt-get update
sudo apt-get install -y ffmpeg python3 python3-venv python3-pip
python3 -m venv ~/.venvs/whisper
~/.venvs/whisper/bin/pip install --upgrade pip
~/.venvs/whisper/bin/pip install openai-whisper

Then set WHISPER_BIN to your binary path if needed.

Environment variables

WHISPER_ENABLED=true
WHISPER_BIN=whisper
WHISPER_DEFAULT_MODEL=small
WHISPER_VERIFY_SSL=true
WHISPER_DOWNLOAD_TIMEOUT=180
WHISPER_PROCESS_TIMEOUT=3600
WHISPER_MAX_ATTEMPTS=3
WHISPER_RETRY_DELAY_SECONDS=120

Scheduler

The queue is processed via Laravel scheduler every minute:

php artisan whisper:process --limit=1

Manual run:

php artisan whisper:process --limit=5

API endpoints

All endpoints are authenticated (web session or JWT from /api/account/login) and permission-gated.

`GET /api/whisper/status`

Returns queue counters and client capability flags.

`GET /api/whisper/jobs?limit=100`

Returns visible jobs for current user.

Users without manage-permission see only their own jobs.
limit range is capped server-side.

`POST /api/whisper/jobs`

Queue a new transcription request.

Request body:

{
  "source_url": "https://example.com/audio.mp3",
  "model": "small",
  "language": "sv"
}

`GET /api/whisper/jobs/{jobId}`

Returns one visible queue item.

`POST /api/whisper/run-now`

Admin/manager endpoint for immediate queue processing pass.

Request body (optional):

{
  "limit": 1
}

Job status fields

Each job includes:

status: queued|downloading|transcribing|finalizing|completed|failed
progress_percent: integer percent used by UI polling
last_error: latest processing error text
transcript_text: populated when job is completed

Tornevall Networks