whisper-fastapi

KO | EN

gitlite — search

#python #hacktoberfest #golang #android #linux #macos #java #windows #awesome #kubernetes #vue #pytorch #mcp #openai

whisper-fastapi

(★ 82)

A very simple whisper Python FastAPI for OpenAI API, Android voice-typing (konele), Home Assistant (wyoming), and a voice-typing script on Linux and MacOS!

whisper-fastapi Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Whisper-FastAPI

Whisper-FastAPI is a very simple Python FastAPI interface for konele and OpenAI services. It is based on the `faster-whisper` project and provides an API for konele-like interface, where translations and transcriptions can be obtained by connecting over websockets or POST requests.

## Features

- **Translation and Transcription**: The application provides an API for konele service, where translations and transcriptions can be obtained by connecting over websockets or POST requests.
- **Language Support**: If no language is specified, the language will be automatically recognized from the first 30 seconds.
- **Konele Support**: Konele (or k6nele) is an open-source voice typing application on Android. This project supports a websocket (`/konele/ws`) and a POST method to `/konele/post`.
- **Home Assistant Support**: By default it listen to `tcp://0.0.0.0:3001` for wyoming protocol.
- **Audio Transcriptions**: The `/v1/audio/transcriptions` endpoint allows users to upload an audio file and receive transcription in response, with an optional `response_type` parameter. The `response_type` can be 'json', 'text', 'tsv', 'srt', and 'vtt'.
- **Simplified Chinese**: The traditional Chinese will be automatically convert to simplified Chinese for konele using `opencc` library.

## GPT Refine Result

You can choose to use the OpenAI GPT model for post-processing transcription results. You can also provide context to GPT to allow it to modify the text based on your context.

Set the environment variables `OPENAI_BASE_URL=https://api.openai.com/v1` and `OPENAI_API_KEY=your-sk` to enable this feature.

When the client sends a request with `gpt_refine=True`, this feature will be activated. Specifically:

- For `/v1/audio/transcriptions`, submit using `curl <api_url> -F file=audio.mp4 -F gpt_refine=True`.
- For `/v1/konele/ws` and `/v1/konele/post`, use the URL format `/v1/konele/ws/gpt_refine`.

The default model is `gpt-4o-mini` set by environment variable `OPENAI_LLM_MODEL`.

You can easily edit the code LLM's prompt to better fit your workflow. It's just a few lines of code. Give it a try, it's very simple!

## Usage

### Konele Voice Typing

For konele voice typing, you can use either the websocket endpoint or the POST method endpoint.

- **Websocket**: Connect to the websocket at `/konele/ws` (or `/v1/konele/ws`) and send audio data. The server will respond with the transcription or translation.
- **POST Method**: Send a POST request to `/konele/post` (or `/v1/konele/post`) with the audio data in the body. The server will respond with the transcription or translation.

You can also use the demo I have created to quickly test the effect at <https://yongyuancv.cn/v1/konele/post>

### Home Assistant Service

By default it listen to `tcp://0.0.0.0:3001` for wyoming protocol. You can specify `--wyoming-uri tcp://0.0.0.0:3001` to modify it.

Beside the main program `whisper_fastapi.py`, there is another script `wyoming-forward.py` which provides the same Wyoming API, but instead of transcribing audio with a local model, it forwards the audio request to any OpenAI-compatible endpoint. For example:

```bash
pip install wyoming aiohttp  # There are only two dependencies.
export OPENAI_API_KEY=your-secret-key
export OPENAI_BASE_URL=https://api.openai.com/v1  # this is the default
python wyoming-forward.py --wyoming-uri tcp://0.0.0.0:3001
```

### OpenAI Whisper Service

To use the service that matches the structure of the OpenAI Whisper service, send a POST request to `/v1/audio/transcriptions` with an audio file. The server will respond with the transcription in the format specified by the `response_type` parameter.

You can also use the demo I have created to quickly test the effect at <https://yongyuancv.cn/v1/audio/transcriptions>

My demo is using the large-v2 model on RTX3060.

## Getting Started

To run the application, you need to have Python installed on your machine. You can then clone the repository and install the required dependencies.

```bash
git clone https://github.com/heimoshuiyu/whisper-fastapi.git
cd whisper-fastapi
pip install -r requirements.txt
```

You can then run the application using the following command: (model will be downloaded from huggingface if not exists in cache dir)

```bash
python whisper_fastapi.py --host 0.0.0.0 --port 5000 --model large-v2
```

Available command-line options:
- `--host`: Host address (default: `0.0.0.0`)
- `--port`: Port (default: `5000`)
- `--model`: Model size (default: `large-v3`)
- `--device`: Device (`cpu`, `cuda`, `auto`)
- `--compute_type`: Computation type (default: `default`)
- `--threads`: CPU threads (default: `4`)

**compute_type options:**
- `default` - Use model's native precision
- `auto` - Auto-select fastest type
- `int8` - Faster, less memory
- `float16` - Half precision (GPU)
- `float32` - Full precision

This will start the application on `http://<your-ip-address>:5000`.

### Voice Typing Script

> This script currently supports Linux and macOS. If you're familiar with Windows, feel free to contribute via a PR!

1. Grant execution permissions to the `voice-typing` script using the command:
   ```bash
   chmod +x voice-typing
   ```

2. Optionally, place the script in a directory included in your system's PATH, such as `/usr/bin/`. This step is not mandatory.

3. Bind a keyboard shortcut to execute this script in your KDE or Gnome settings.

How it works

- **First Execution**: When you run the script for the first time, it creates a PID file in the `/tmp` directory and starts recording audio from your microphone.

- **Second Execution**: Running the script again will send a termination signal to the recording process using the PID file. This stops the recording and initiates the transcription process via an API. The transcribed text is then saved to your clipboard.

Whisper can improve transcription accuracy based on **context**. For:

- **macOS and Wayland**: The script uses the current clipboard content as context.

- **X11 Environment**: The script uses the text selected by the mouse as context for transcription.

### Deploy with docker

```bash
docker run -d \
    --tmpfs /tmp \
    -v ~/.cache/huggingface:/root/.cache/huggingface \
    --gpus all --device nvidia.com/gpu=all --security-opt=label=disable \
    -e OPENAI_BASE_URL=https://api.openai.com/v1 -e OPENAI_API_KEY=key -e OPENAI_LLM_MODEL=gpt-4o \
    -p 5000:5000 -p 3001:3001 \
    docker.io/heimoshuiyu/whisper-fastapi:latest \
    --model large-v2
```

The `--gpus all` flag indicates that all GPUs are passed to the container. You might want to specify which GPU to use by setting `--gpus 0` or `--gpus 1`.

The `OPENAI_*` related environment variables are used for the GPT refine feature. If you are not using the GPT refine feature, you can ignore these environment variables.

## Limitation

Defect: Due to the synchronous nature of inference, this API can actually only handle one request at a time.

whisper-fastapi

whisper-fastapi Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

whisper-fastapi

whisper-fastapi Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README