tomfun-speech-to-text-client

Minimal async Python client for the tomfun speech-to-text web API.

• Token authentication (Authorization: Bearer <token>)
• Language hint passed to Whisper
• Upload local files (chunked) or submit a remote URL
• Streams status via Server-Sent Events

Single runtime dependency: aiohttp.

Install

pip install tomfun-speech-to-text-client

Usage

import asyncio
from tomfun_speech_to_text_client import Client

async def main():
    async with Client("https://speech-to-text.tomfun.co", token="YOUR_TOKEN") as c:
        r = await c.transcribe_file("audio.mp3", language="en")
        print(r.text)

        r = await c.transcribe_url("https://example.com/clip.wav", language="uk")
        print(r.srt)

asyncio.run(main())

With progress callback:

async def on_status(ev):
    print(ev["status"], ev.get("progressLast"))

await c.transcribe_file("audio.mp3", language="en", on_status=on_status)

Cancel a job:

await c.cancel(job_id)

Speaker diarization (server-side pyannote):

r = await c.transcribe_file("meeting.mp3", language="ru", diarize=True)
print(r.diarized)            # SRT with a [SPEAKER_xx] prefix per cue, or None
print(r.speaker_embeddings)  # base64 .npy, shape (numSpeakers, embeddingDim), or None

Both diarization fields are None when diarize wasn't requested — and also when the server's diarization failed on an otherwise successful job, so always check them.

allow_experimental

Off unless you pass it, and that default is deliberate: without it you always get genuine whisper.cpp output.

Turning it on admits models that serve a reduced result contract — for parakeet that means no language selection, no VAD, and a WhisperFullJSON that is schema-valid but synthesized (systeminfo / model / params are placeholders). Diarization is not part of the reduction, but a worker built with ENABLE_DIARIZATION=0 has none regardless.

What it buys: an experimental model can be the most accurate thing in the cluster and still be the only free worker. With the flag off, such a manager is not merely ranked lower — it is not a candidate at all, so a job can sit in the queue for hours next to an idle machine that could have run it. Pass allow_experimental=True when you care more about the job finishing than about the exact shape of the JSON.

TranscriptionResult

Development (uv)

cd python_client
uv sync --group dev
uv run pytest

Publishing to PyPI

1. Create a PyPI API token at https://pypi.org/manage/account/token/.
2. Bump version in pyproject.toml.
3. Build:

   uv build
   

4. Upload. uv publish does not read ~/.pypirc (only --token / UV_PUBLISH_TOKEN, --username/--password, keyring, trusted publishing), so with the token stored there the shortest path is twine, which picks it up on its own — name the new version explicitly, otherwise twine trips over the already-published files in dist/:

   uv tool run --with twine twine upload dist/tomfun_speech_to_text_client-0.0.5*
   

   Or pass the token to uv directly:

   uv publish --token "$PYPI_TOKEN"