vocal_helper.api module

Vocal Helper — FastAPI HTTP surface.

Exposes the offline batch pipeline over HTTP so vocal-helper can be dropped behind any reverse proxy and consumed by other services. The online streaming pipeline lives on-process (queues + coroutines) and is not exposed as REST endpoints — it is either driven from the CLI, the Python API, or a WebSocket surface that lives elsewhere.

What ships here

  • POST /transcribe — one-shot ASR of an uploaded WAV / mp3 / m4a / ogg / flac. Returns {"text": ..., "language": ...}.

  • POST /pipeline — full offline pipeline (VAD + diarization + STT + optional Gemma summary) on an uploaded audio file or a media URL (url form field, fetched locally via yt-dlp, [stream] extra). Returns a list of Utterance events, optionally the summary.

  • GET /gui — self-contained transcript-viewer GUI (drop a file or paste a URL → speaker colour-coded transcript + rolling summary).

  • GET /health — liveness probe.

Install the extra to get the runtime dependencies:

pip install 'vocal-helper[api]'

Then run the app with any ASGI server:

uvicorn vocal_helper.api:app --host 0.0.0.0 --port 8000

Usage Example

>>> # Start the server:
>>> #   uvicorn vocal_helper.api:app --reload
>>> # One-shot transcription:
>>> #   curl -F 'file=@clip.wav' -F 'language=en' \
>>> #        http://localhost:8000/transcribe
>>> # Full offline pipeline:
>>> #   curl -F 'file=@meeting.wav' -F 'llm=true' \
>>> #        http://localhost:8000/pipeline
>>> # Full OpenAPI docs at http://localhost:8000/docs

Author

Warith Harchaoui, Ph.D. — https://linkedin.com/in/warith-harchaoui/

vocal_helper.api.gui()

Serve the self-contained single-page transcript-viewer GUI.

The page (defined in vocal_helper.gui) is a build-step-free HTML + Tailwind-CDN + vanilla-JS client that POSTs to the very same /pipeline endpoint below: drop a file or paste a URL, get back a speaker-labelled, colour-coded transcript plus the rolling summary. It adds no server-side logic — it is purely a friendlier front door.

Returns:

The complete HTML document (status 200, text/html).

Return type:

HTMLResponse

vocal_helper.api.health()

Simple liveness probe — no dependency check, just proves the app is up.

Return type:

dict

vocal_helper.api.pipeline(background, file=fastapi.File, url=fastapi.Form, language=fastapi.Form, whisper_model=fastapi.Form, threads=fastapi.Form, diar_backend=fastapi.Form, llm=fastapi.Form, llm_model=fastapi.Form, llm_recent_window_s=fastapi.Form)

Run the full OfflinePipeline on the uploaded file and return the events.

Parameters:

  • background (BackgroundTasks)

  • file (UploadFile | None)

  • url (str)

  • language (str)

  • whisper_model (str)

  • threads (int)

  • diar_backend (str)

  • llm (bool)

  • llm_model (str)

  • llm_recent_window_s (float)

Return type:

JSONResponse

vocal_helper.api.root()

Redirect the bare root to the transcript viewer so opening the server just works.

Return type:

fastapi.responses.RedirectResponse

vocal_helper.api.transcribe(background, file=fastapi.File, language=fastapi.Form, whisper_model=fastapi.Form, threads=fastapi.Form)

One-shot transcription of the uploaded audio — no VAD, no diarization.

Parameters:

  • background (fastapi.BackgroundTasks)

  • file (fastapi.UploadFile)

  • language (str)

  • whisper_model (str)

  • threads (int)

Return type:

fastapi.responses.JSONResponse