From 81268a7ca36e66c9c67fd7ccb19b9aa889596ee7 Mon Sep 17 00:00:00 2001 From: Quentin Fuxa Date: Wed, 19 Mar 2025 15:40:54 +0100 Subject: [PATCH] update CLI launch --- README.md | 115 ++++++++++++++++++--------------- setup.py | 2 +- whisperlivekit/basic_server.py | 86 ++++++++++++++++++++++++ whisperlivekit/core.py | 5 +- 4 files changed, 153 insertions(+), 55 deletions(-) create mode 100644 whisperlivekit/basic_server.py diff --git a/README.md b/README.md index 99b7743..b2a18d7 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,7 @@ This project is based on [Whisper Streaming](https://github.com/ufal/whisper_str ## Installation -### Via pip +### Via pip (recommended) ```bash pip install whisperlivekit @@ -46,67 +46,75 @@ pip install whisperlivekit You need to install FFmpeg on your system: -- Install system dependencies: - ```bash - # Install FFmpeg on your system (required for audio processing) - # For Ubuntu/Debian: - sudo apt install ffmpeg - - # For macOS: - brew install ffmpeg - - # For Windows: - # Download from https://ffmpeg.org/download.html and add to PATH - ``` +```bash +# For Ubuntu/Debian: +sudo apt install ffmpeg -- Install required Python dependencies: +# For macOS: +brew install ffmpeg - ```bash - # Whisper streaming required dependencies - pip install librosa soundfile +# For Windows: +# Download from https://ffmpeg.org/download.html and add to PATH +``` - # Whisper streaming web required dependencies - pip install fastapi ffmpeg-python - ``` -- Install at least one whisper backend among: +### Optional Dependencies - ``` - whisper - whisper-timestamped - faster-whisper (faster backend on NVIDIA GPU) - mlx-whisper (faster backend on Apple Silicon) - ``` -- Optionnal dependencies - - ``` - # If you want to use VAC (Voice Activity Controller). Useful for preventing hallucinations - torch +```bash +# If you want to use VAC (Voice Activity Controller). Useful for preventing hallucinations +pip install torch - # If you choose sentences as buffer trimming strategy - mosestokenizer - wtpsplit - tokenize_uk # If you work with Ukrainian text +# If you choose sentences as buffer trimming strategy +pip install mosestokenizer wtpsplit +pip install tokenize_uk # If you work with Ukrainian text - # If you want to run the server using uvicorn (recommended) - uvicorn +# If you want to use diarization +pip install diart +``` - # If you want to use diarization - diart - ``` +Diart uses [pyannote.audio](https://github.com/pyannote/pyannote-audio) models from the _huggingface hub_. To use them, please follow the steps described [here](https://github.com/juanmc2005/diart?tab=readme-ov-file#get-access-to--pyannote-models). - Diart uses by default [pyannote.audio](https://github.com/pyannote/pyannote-audio) models from the _huggingface hub_. To use them, please follow the steps described [here](https://github.com/juanmc2005/diart?tab=readme-ov-file#get-access-to--pyannote-models). +## Usage + +### Using the command-line tool + +After installation, you can start the server using the provided command-line tool: + +```bash +whisperlivekit-server --host 0.0.0.0 --port 8000 --model tiny.en +``` + +Then open your browser at `http://localhost:8000` (or your specified host and port). + +### Using the library in your code + +```python +from whisperlivekit import WhisperLiveKit +from fastapi import FastAPI, WebSocket + +# Initialize WhisperLiveKit with custom parameters +kit = WhisperLiveKit( + model="tiny.en", + diarization=True, +) + +# Create a FastAPI application +app = FastAPI() + +@app.get("/") +async def get(): + # Use the built-in web interface + return HTMLResponse(kit.web_interface()) + +# Your websocket endpoints for audio processing... +``` + +For a complete audio processing example, check [whisper_fastapi_online_server.py](https://github.com/QuentinFuxa/WhisperLiveKit/blob/main/whisper_fastapi_online_server.py) -3. **Run the FastAPI Server**: +## Configuration Options - ```bash - python whisper_fastapi_online_server.py --host 0.0.0.0 --port 8000 - ``` +The following parameters are supported when initializing `WhisperLiveKit`: - **Parameters** - - The following parameters are supported: - - `--host` and `--port` let you specify the server's IP/port. - `-min-chunk-size` sets the minimum chunk size for audio processing. Make sure this value aligns with the chunk size selected in the frontend. If not aligned, the system will work but may unnecessarily over-process audio data. - `--transcription`: Enable/disable transcription (default: True) @@ -135,12 +143,13 @@ You need to install FFmpeg on your system: - Open your browser at `http://localhost:8000` (or replace `localhost` and `8000` with whatever you specified). - The page uses vanilla JavaScript and the WebSocket API to capture your microphone and stream audio to the server in real time. -### How the Live Interface Works + +## How the Live Interface Works - Once you **allow microphone access**, the page records small chunks of audio using the **MediaRecorder** API in **webm/opus** format. - These chunks are sent over a **WebSocket** to the FastAPI endpoint at `/asr`. - The Python server decodes `.webm` chunks on the fly using **FFmpeg** and streams them into the **whisper streaming** implementation for transcription. -- **Partial transcription** appears as soon as enough audio is processed. The “unvalidated” text is shown in **lighter or grey color** (i.e., an ‘aperçu’) to indicate it’s still buffered partial output. Once Whisper finalizes that segment, it’s displayed in normal text. +- **Partial transcription** appears as soon as enough audio is processed. The "unvalidated" text is shown in **lighter or grey color** (i.e., an 'aperçu') to indicate it's still buffered partial output. Once Whisper finalizes that segment, it's displayed in normal text. - You can watch the transcription update in near real time, ideal for demos, prototyping, or quick debugging. ### Deploying to a Remote Server @@ -155,4 +164,4 @@ No additional front-end libraries or frameworks are required. The WebSocket logi ## Acknowledgments -This project builds upon the foundational work of the Whisper Streaming project. We extend our gratitude to the original authors for their contributions. +This project builds upon the foundational work of the Whisper Streaming project. We extend our gratitude to the original authors for their contributions. \ No newline at end of file diff --git a/setup.py b/setup.py index b7eb28b..5cbcb1e 100644 --- a/setup.py +++ b/setup.py @@ -28,7 +28,7 @@ setup( }, entry_points={ 'console_scripts': [ - 'whisperlivekit-server=whisperlivekit.server:run_server', + 'whisperlivekit-server=whisperlivekit.basic_server:main', ], }, classifiers=[ diff --git a/whisperlivekit/basic_server.py b/whisperlivekit/basic_server.py new file mode 100644 index 0000000..ef979d7 --- /dev/null +++ b/whisperlivekit/basic_server.py @@ -0,0 +1,86 @@ +from contextlib import asynccontextmanager +from fastapi import FastAPI, WebSocket, WebSocketDisconnect +from fastapi.responses import HTMLResponse +from fastapi.middleware.cors import CORSMiddleware + +from whisperlivekit import WhisperLiveKit +from whisperlivekit.audio_processor import AudioProcessor + +import asyncio +import logging +import os + +logging.basicConfig(level=logging.INFO, format="%(asctime)s - %(levelname)s - %(message)s") +logging.getLogger().setLevel(logging.WARNING) +logger = logging.getLogger(__name__) +logger.setLevel(logging.DEBUG) + +kit = None + +@asynccontextmanager +async def lifespan(app: FastAPI): + global kit + kit = WhisperLiveKit() + yield + +app = FastAPI(lifespan=lifespan) +app.add_middleware( + CORSMiddleware, + allow_origins=["*"], + allow_credentials=True, + allow_methods=["*"], + allow_headers=["*"], +) + + +@app.get("/") +async def get(): + return HTMLResponse(kit.web_interface()) + + +async def handle_websocket_results(websocket, results_generator): + """Consumes results from the audio processor and sends them via WebSocket.""" + try: + async for response in results_generator: + await websocket.send_json(response) + except Exception as e: + logger.warning(f"Error in WebSocket results handler: {e}") + + +@app.websocket("/asr") +async def websocket_endpoint(websocket: WebSocket): + audio_processor = AudioProcessor() + + await websocket.accept() + logger.info("WebSocket connection opened.") + + results_generator = await audio_processor.create_tasks() + websocket_task = asyncio.create_task(handle_websocket_results(websocket, results_generator)) + + try: + while True: + message = await websocket.receive_bytes() + await audio_processor.process_audio(message) + except WebSocketDisconnect: + logger.warning("WebSocket disconnected.") + finally: + websocket_task.cancel() + await audio_processor.cleanup() + logger.info("WebSocket endpoint cleaned up.") + +def main(): + """Entry point for the CLI command.""" + import uvicorn + + temp_kit = WhisperLiveKit(transcription=False, diarization=False) + + uvicorn.run( + "whisperlivekit.basic_server:app", + host=temp_kit.args.host, + port=temp_kit.args.port, + reload=True, + log_level="info" + ) + +if __name__ == "__main__": + main() diff --git a/whisperlivekit/core.py b/whisperlivekit/core.py index 9363668..5d1e266 100644 --- a/whisperlivekit/core.py +++ b/whisperlivekit/core.py @@ -1,4 +1,7 @@ -from whisperlivekit.whisper_streaming_custom.whisper_online import backend_factory, warmup_asr +try: + from whisperlivekit.whisper_streaming_custom.whisper_online import backend_factory, warmup_asr +except: + from whisper_streaming_custom.whisper_online import backend_factory, warmup_asr from argparse import Namespace, ArgumentParser def parse_args():