From a2bd3ea822a46986bb5987f1e9865b7848600d7f Mon Sep 17 00:00:00 2001 From: Space-Banane Date: Sun, 24 May 2026 14:35:54 +0200 Subject: [PATCH 1/5] Add compose-based backend runtime on python 3.14 --- README.md | 12 +++++++++++- docker-compose.yml | 22 ++++++++++++++++++++++ 2 files changed, 33 insertions(+), 1 deletion(-) create mode 100644 docker-compose.yml diff --git a/README.md b/README.md index ad99fce..7681db4 100644 --- a/README.md +++ b/README.md @@ -9,8 +9,17 @@ Two separate Python packages live here: The repo also includes a Gitea Actions workflow at `.gitea/workflows/ci.yml` that tests and builds both packages on pushes to `main` and pull requests. -## Backend setup +## Docker backend (no image build) +Run the backend directly from an official Python image without creating a Dockerfile: + +```bash +docker compose up backend +``` + +This uses `python:3.14-slim`, installs `ffmpeg` and `openai-whisper` at container startup, mounts this repo into the container, and serves the API on `http://localhost:8000`. + +## Backend setup ```bash cd backend pip install -e . @@ -50,3 +59,4 @@ whisper-remote ./audio.mp3 --model base --language en --output-format txt - backend-side cleanup of uploaded and generated files after each request By default the CLI prints the returned transcript to stdout. Use `--to-file` to save it locally. + diff --git a/docker-compose.yml b/docker-compose.yml new file mode 100644 index 0000000..998c5b8 --- /dev/null +++ b/docker-compose.yml @@ -0,0 +1,22 @@ +services: + backend: + image: python:3.14-slim + working_dir: /app/backend + ports: + - "8000:8000" + volumes: + - ./:/app + - whisper_cache:/root/.cache + environment: + - PYTHONUNBUFFERED=1 + command: >- + sh -lc " + apt-get update + && apt-get install -y --no-install-recommends ffmpeg + && rm -rf /var/lib/apt/lists/* + && pip install --no-cache-dir -e . openai-whisper + && uvicorn server:app --app-dir src --host 0.0.0.0 --port 8000 + " + +volumes: + whisper_cache: From 2b1c26781e14a7f09161f057b6d8fde59697abe8 Mon Sep 17 00:00:00 2001 From: Luna Date: Mon, 25 May 2026 17:18:31 +0000 Subject: [PATCH 2/5] cli: surface HTTP status and body on backend errors --- cli/src/main.py | 7 ++++++- cli/tests/test_main.py | 15 +++++++++++++++ 2 files changed, 21 insertions(+), 1 deletion(-) diff --git a/cli/src/main.py b/cli/src/main.py index 277c741..5ddbe54 100644 --- a/cli/src/main.py +++ b/cli/src/main.py @@ -59,6 +59,11 @@ def save_response(response: httpx.Response, destination: Path) -> None: destination.write_bytes(response.content) +def format_http_error(response: httpx.Response, endpoint: str) -> str: + body = response.text.strip() or "" + return f"HTTP {response.status_code} from {endpoint}: {body}" + + def main() -> int: parser = build_parser() args = parser.parse_args() @@ -84,7 +89,7 @@ def main() -> int: try: response.raise_for_status() except httpx.HTTPStatusError as exc: - message = exc.response.text.strip() or str(exc) + message = format_http_error(exc.response, endpoint) parser.exit(1, f"{message}\n") if args.to_file: diff --git a/cli/tests/test_main.py b/cli/tests/test_main.py index a77e9ab..b1c4c1e 100644 --- a/cli/tests/test_main.py +++ b/cli/tests/test_main.py @@ -8,6 +8,7 @@ import pytest sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src")) import main +import httpx def test_resolve_server_from_env(monkeypatch) -> None: @@ -29,3 +30,17 @@ def test_infer_output_path_for_directory(tmp_path: Path) -> None: def test_infer_output_path_for_explicit_file(tmp_path: Path) -> None: destination = main.infer_output_path(tmp_path / "custom-name.txt", Path("clip.wav"), "txt") assert destination == tmp_path / "custom-name.txt" + + +def test_format_http_error_with_body() -> None: + request = httpx.Request("POST", "http://localhost:8000/transcriptions") + response = httpx.Response(500, text="Internal Server Error", request=request) + message = main.format_http_error(response, "http://localhost:8000/transcriptions") + assert message == "HTTP 500 from http://localhost:8000/transcriptions: Internal Server Error" + + +def test_format_http_error_with_empty_body() -> None: + request = httpx.Request("POST", "http://localhost:8000/transcriptions") + response = httpx.Response(500, text="", request=request) + message = main.format_http_error(response, "http://localhost:8000/transcriptions") + assert message == "HTTP 500 from http://localhost:8000/transcriptions: " From 1c6415d306abd5e4124929165112a9d0f0f7fb10 Mon Sep 17 00:00:00 2001 From: Luna Date: Wed, 27 May 2026 13:08:56 +0000 Subject: [PATCH 3/5] Handle CLI request errors and backend whisper timeout --- backend/src/server.py | 10 ++++++++++ backend/tests/test_server.py | 19 +++++++++++++++++++ cli/src/main.py | 31 +++++++++++++++++++++---------- cli/tests/test_main.py | 17 +++++++++++++++++ 4 files changed, 67 insertions(+), 10 deletions(-) diff --git a/backend/src/server.py b/backend/src/server.py index 1368c91..d871a76 100644 --- a/backend/src/server.py +++ b/backend/src/server.py @@ -17,6 +17,7 @@ CONTENT_TYPES = { } app = FastAPI(title="whisper-remote-backend") +WHISPER_PROCESS_TIMEOUT_SECONDS = 300 def validate_output_format(output_format: str) -> str: @@ -112,12 +113,21 @@ async def transcribe( check=False, capture_output=True, text=True, + timeout=WHISPER_PROCESS_TIMEOUT_SECONDS, ) except FileNotFoundError as exc: raise HTTPException( status_code=500, detail="The 'whisper' CLI was not found on PATH on the backend host.", ) from exc + except subprocess.TimeoutExpired as exc: + raise HTTPException( + status_code=504, + detail=( + "Whisper CLI timed out after " + f"{WHISPER_PROCESS_TIMEOUT_SECONDS}s and was terminated." + ), + ) from exc if completed.returncode != 0: detail = completed.stderr.strip() or completed.stdout.strip() or "Whisper CLI failed." diff --git a/backend/tests/test_server.py b/backend/tests/test_server.py index 59baf5d..1e95638 100644 --- a/backend/tests/test_server.py +++ b/backend/tests/test_server.py @@ -64,3 +64,22 @@ def test_transcriptions_maps_subprocess_failure(monkeypatch) -> None: assert response.status_code == 502 assert response.json()["detail"] == "bad whisper day" + + +def test_transcriptions_maps_subprocess_timeout(monkeypatch) -> None: + def fake_run(command: list[str], check: bool, capture_output: bool, text: bool, timeout: int): + raise server.subprocess.TimeoutExpired(cmd=command, timeout=timeout) + + monkeypatch.setattr(server.subprocess, "run", fake_run) + + response = client.post( + "/transcriptions", + data={"model": "base", "output_format": "txt"}, + files={"file": ("clip.wav", b"audio", "audio/wav")}, + ) + + assert response.status_code == 504 + assert ( + response.json()["detail"] + == f"Whisper CLI timed out after {server.WHISPER_PROCESS_TIMEOUT_SECONDS}s and was terminated." + ) diff --git a/cli/src/main.py b/cli/src/main.py index 5ddbe54..ae533db 100644 --- a/cli/src/main.py +++ b/cli/src/main.py @@ -64,6 +64,14 @@ def format_http_error(response: httpx.Response, endpoint: str) -> str: return f"HTTP {response.status_code} from {endpoint}: {body}" +def format_request_error(exc: httpx.RequestError, endpoint: str) -> str: + if isinstance(exc, httpx.TimeoutException): + return f"Request to {endpoint} timed out." + + reason = str(exc).strip() or exc.__class__.__name__ + return f"Request to {endpoint} failed: {reason}" + + def main() -> int: parser = build_parser() args = parser.parse_args() @@ -75,16 +83,19 @@ def main() -> int: server = resolve_server(args) endpoint = f"{server}/transcriptions" - with input_file.open("rb") as handle, httpx.Client(timeout=300.0) as client: - response = client.post( - endpoint, - data={ - "model": args.model, - "language": args.language or "", - "output_format": args.output_format, - }, - files={"file": (input_file.name, handle, "application/octet-stream")}, - ) + try: + with input_file.open("rb") as handle, httpx.Client(timeout=300.0) as client: + response = client.post( + endpoint, + data={ + "model": args.model, + "language": args.language or "", + "output_format": args.output_format, + }, + files={"file": (input_file.name, handle, "application/octet-stream")}, + ) + except httpx.RequestError as exc: + parser.exit(1, f"{format_request_error(exc, endpoint)}\n") try: response.raise_for_status() diff --git a/cli/tests/test_main.py b/cli/tests/test_main.py index b1c4c1e..42fca89 100644 --- a/cli/tests/test_main.py +++ b/cli/tests/test_main.py @@ -44,3 +44,20 @@ def test_format_http_error_with_empty_body() -> None: response = httpx.Response(500, text="", request=request) message = main.format_http_error(response, "http://localhost:8000/transcriptions") assert message == "HTTP 500 from http://localhost:8000/transcriptions: " + + +def test_format_request_error_timeout() -> None: + request = httpx.Request("POST", "http://localhost:8000/transcriptions") + exc = httpx.ReadTimeout("read timed out", request=request) + message = main.format_request_error(exc, "http://localhost:8000/transcriptions") + assert message == "Request to http://localhost:8000/transcriptions timed out." + + +def test_format_request_error_network_failure() -> None: + request = httpx.Request("POST", "http://localhost:8000/transcriptions") + exc = httpx.ConnectError("connection refused", request=request) + message = main.format_request_error(exc, "http://localhost:8000/transcriptions") + assert ( + message + == "Request to http://localhost:8000/transcriptions failed: connection refused" + ) From 575e2d6747efb8a9ea2f031aad31bd46ac84997d Mon Sep 17 00:00:00 2001 From: Luna Date: Wed, 27 May 2026 13:22:50 +0000 Subject: [PATCH 4/5] Fix backend test mocks for subprocess timeout kwarg --- backend/tests/test_server.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/backend/tests/test_server.py b/backend/tests/test_server.py index 1e95638..5eb7fe1 100644 --- a/backend/tests/test_server.py +++ b/backend/tests/test_server.py @@ -21,7 +21,7 @@ def test_validate_output_format_rejects_unknown() -> None: def test_transcriptions_returns_generated_artifact(monkeypatch, tmp_path: Path) -> None: - def fake_run(command: list[str], check: bool, capture_output: bool, text: bool): + def fake_run(command: list[str], check: bool, capture_output: bool, text: bool, timeout: int): output_dir = Path(command[command.index("--output_dir") + 1]) (output_dir / "clip.txt").write_text("hello world", encoding="utf-8") @@ -46,7 +46,7 @@ def test_transcriptions_returns_generated_artifact(monkeypatch, tmp_path: Path) def test_transcriptions_maps_subprocess_failure(monkeypatch) -> None: - def fake_run(command: list[str], check: bool, capture_output: bool, text: bool): + def fake_run(command: list[str], check: bool, capture_output: bool, text: bool, timeout: int): class Result: returncode = 1 stdout = "" From 32fb8d9813bb4072c7611d460f93be245f5fac87 Mon Sep 17 00:00:00 2001 From: Luna Date: Thu, 28 May 2026 08:47:13 +0000 Subject: [PATCH 5/5] chore: ignore local build and venv artifacts --- .gitignore | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.gitignore b/.gitignore index d9f2830..a8f8d31 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,6 @@ __pycache__/ .pytest_cache/ *.egg-info/ +.venv/ +.venv-ci/ +build/