voice-python-web

Reusable voice input/output components for Python and browser applications.

• Local transcription with faster-whisper
• Optional OpenAI transcription and speech providers
• Native macOS speech through say
• Reusable FastAPI routes
• Browser microphone recording and audio playback

The Python and browser packages can be used together or independently.

Install from GitHub

pip install "voice-python-web[all] @ git+https://github.com/YOUR_USERNAME/voice-python-web.git"

For local development:

git clone https://github.com/YOUR_USERNAME/voice-python-web.git
cd voice-python-web
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[all,dev]"

Run the example

uvicorn examples.app:app --reload

Open http://127.0.0.1:8000, press Speak, talk, then press Stop.

The example uses:

• tiny.en local Whisper transcription
• macOS say for speech output

The first Whisper request downloads the selected model. macOS speech requires the say and afconvert commands.

Python API

from fastapi import FastAPI
from voice_python import (
    LocalWhisperTranscriber,
    MacOSSaySynthesizer,
    VoiceService,
    create_voice_router,
)

app = FastAPI()

voice = VoiceService(
    transcriber=LocalWhisperTranscriber(
        model_name="tiny.en",
        device="cpu",
        compute_type="int8",
    ),
    synthesizer=MacOSSaySynthesizer(),
)

app.include_router(create_voice_router(voice), prefix="/api/voice")

Endpoints:

• GET /api/voice/health
• POST /api/voice/transcriptions with multipart field audio
• POST /api/voice/speech with JSON { "text": "...", "voice": null }

An optional shared secret can protect all routes:

app.include_router(
    create_voice_router(voice, shared_secret="change-me"),
    prefix="/api/voice",
)

Clients then send X-CTRLC-Secret.

Browser API

Serve voice_web/index.js, then import it as an ES module:

import { createVoiceClient } from "/voice-web/index.js";

const voice = createVoiceClient({
  transcriptionEndpoint: "/api/voice/transcriptions",
  speechEndpoint: "/api/voice/speech",
});

await voice.recorder.start();
const transcript = await voice.recorder.stopAndTranscribe();
await voice.player.speak(`You said: ${transcript}`);

Custom headers:

const voice = createVoiceClient({
  headers: { "X-CTRLC-Secret": "change-me" },
});

Microphone access requires localhost or HTTPS.

Provider alternatives

from voice_python import OpenAITranscriber, OpenAISpeechSynthesizer

transcriber = OpenAITranscriber(api_key="...")
synthesizer = OpenAISpeechSynthesizer(api_key="...")

Do not commit API keys. Load them from environment variables or a secret manager.

Publish to GitHub

Replace YOUR_USERNAME in pyproject.toml and this README, then:

git init
git add .
git commit -m "Initial voice library release"
git branch -M main
git remote add origin https://github.com/YOUR_USERNAME/voice-python-web.git
git push -u origin main

License

MIT