Whisper-MLCCS-Remote

Whisper-MLCCS-Remote is a Windows client/server transcription system for running Faster-Whisper-XXL on a host machine while controlling jobs from lightweight remote clients.

The client extracts and compresses audio locally before upload, so remote users do not need to send full video files over the network. The server runs without a GUI, keeps a single GPU-friendly queue, streams transcription output back to the client, and exposes authenticated status checks so clients can choose an idle server automatically.

Features

• Windows no-GUI HTTPS server powered by FastAPI and Uvicorn.
• PyQt6 desktop client with drag-and-drop media input.
• Client-side audio extraction with bundled ffmpeg.exe; Opus upload is preferred for low bandwidth use.
• SHA-256 key authentication. Plaintext keys stay on the server; clients send only hashes.
• Multiple server profiles in the client, ordered by priority, each with its own URL and key.
• Server idle/busy status API for automatic server selection.
• WebSocket event streaming with reconnect and HTTP polling fallback.
• Resumable chunk upload with server offset recovery.
• One-file client and server executables via PyInstaller.
• Windows Scheduled Task install script for persistent server startup after login.

Repository Layout

whisper_mlccs_remote/
  client/      PyQt6 client
  server/      FastAPI host service and CLI
  common/      shared auth, protocol, certificate, and command mapping code
packaging/     PyInstaller specs
scripts/       runtime copy and deployment scripts
tests/         unit and API tests
resources/     icons and logo assets

Large runtime files are intentionally not stored in source control:

• server/runtime/bin/faster-whisper-xxl.exe
• server/runtime/bin/ffmpeg.exe
• server/runtime/bin/_xxl_data
• server/runtime/bin/_models

Copy them from an existing Whisper-MLCCS/Faster-Whisper-XXL runtime before running the server.

Install for Development

cd D:\MLCCSapps\Whisper-MLCCS-Remote
python -m pip install -r requirements.txt

Prepare Server Runtime

python -m whisper_mlccs_remote.server.cli runtime-copy D:\MLCCSapps\Whisper-MLCCS\dist\bin
python -m whisper_mlccs_remote.server.cli init
python -m whisper_mlccs_remote.server.cli key generate
python -m whisper_mlccs_remote.server.cli models verify

Server keys are stored in:

server/config/keys.txt

Each key uses this format:

ABCDE-FGHIJ-KLMNO-PQRST-UVWXY;

Run

Start the server:

python -m whisper_mlccs_remote.server.cli serve

Start the client:

python -m whisper_mlccs_remote.client.app

The default server URL is:

https://127.0.0.1:8765

Server CLI

python -m whisper_mlccs_remote.server.cli init
python -m whisper_mlccs_remote.server.cli serve
python -m whisper_mlccs_remote.server.cli install-task
python -m whisper_mlccs_remote.server.cli uninstall-task
python -m whisper_mlccs_remote.server.cli key generate
python -m whisper_mlccs_remote.server.cli key add ABCDE-FGHIJ-KLMNO-PQRST-UVWXY
python -m whisper_mlccs_remote.server.cli key list-hashes
python -m whisper_mlccs_remote.server.cli models list
python -m whisper_mlccs_remote.server.cli models verify

Build Executables

pyinstaller --clean -y packaging\Whisper-MLCCS-Remote-Client.onefile.spec
pyinstaller --clean -y packaging\Whisper-MLCCS-Remote-Server.onefile.spec

The generated files are:

dist/Whisper-MLCCS-Remote-Client.exe
dist/Whisper-MLCCS-Remote-Server.exe

Build Server Deployment Zip

After building the server exe and copying the runtime:

powershell -ExecutionPolicy Bypass -File scripts\build_server_deploy_zip.ps1

The deployment zip contains:

• Whisper-MLCCS-Remote-Server.exe
• full server/runtime/bin
• install_server_task.ps1

On the target Windows host, extract the zip and run PowerShell as Administrator:

powershell -ExecutionPolicy Bypass -File .\install_server_task.ps1 -ResetKeys

The script initializes config/certificates, generates 10 keys, installs a login Scheduled Task, and starts the server.

Test

python -m pytest -q

License

This project is GPL-3.0 licensed and keeps upstream attribution for the Faster-Whisper-XXL-GUI lineage.