bodhi-api-sdk 1.0.0__py3-none-any.whl

bodhi/__init__.py

@@ -0,0 +1,23 @@
+"""
+Bodhi Python SDK - Streaming Speech Recognition
+"""
+
+__version__ = "1.0.0"
+
+EOF_SIGNAL = '{"eof": 1}'
+
+from .transcription_client import BodhiClient
+from .transcription_config import TranscriptionConfig, Hotword
+from .transcription_response import TranscriptionResponse
+from .events import LiveTranscriptionEvents
+from bodhi.utils.error_utils import BodhiErrors
+
+__all__ = [
+    "BodhiClient",
+    "TranscriptionConfig",
+    "TranscriptionResponse",
+    "Hotword",
+    "LiveTranscriptionEvents",
+    "EOF_SIGNAL",
+    BodhiErrors,
+]

bodhi/audio_processor.py

@@ -0,0 +1,54 @@
+"""Audio Processing Module for Bodhi Client"""
+
+import wave
+import asyncio
+from typing import BinaryIO, Any
+from .utils.logger import logger
+from . import EOF_SIGNAL
+
+
+class AudioProcessor:
+    @staticmethod
+    async def process_file(
+        ws: Any,
+        wf: wave.Wave_read,
+    ) -> None:
+        """Process and stream audio file data.
+
+        Args:
+            ws: WebSocket connection
+            wf: Wave file object
+        """
+        try:
+
+            REALTIME_RESOLUTION = 0.02  # 20ms
+            byte_rate = wf.getframerate() * wf.getsampwidth() * wf.getnchannels()
+            data = wf.readframes(wf.getnframes())
+            audio_cursor = 0
+
+            while len(data):
+                i = int(byte_rate * REALTIME_RESOLUTION)
+                chunk, data = data[:i], data[i:]
+                if not ws.closed:
+                    await ws.send_bytes(chunk)
+                    logger.debug(f"Sent {len(chunk)} bytes of audio data")
+                audio_cursor += REALTIME_RESOLUTION
+                await asyncio.sleep(REALTIME_RESOLUTION)
+
+            if not ws.closed:
+                await ws.send_str(EOF_SIGNAL)
+                logger.debug("Sent EOF signal")
+        except Exception as e:
+            return e
+
+    @staticmethod
+    async def process_stream(stream: BinaryIO, ws: Any) -> None:
+        """Process and stream generic binary stream data."""
+        try:
+            data = stream.read()
+            if not ws.closed:
+                await ws.send_bytes(data)
+                logger.debug(f"Sent {len(data)} bytes of stream data")
+        except Exception as e:
+            logger.exception("Error during stream processing")
+            raise e

bodhi/events.py

@@ -0,0 +1,9 @@
+from enum import Enum
+
+
+class LiveTranscriptionEvents(Enum):
+    Transcript = "Transcript"
+    UtteranceEnd = "UtteranceEnd"
+    SpeechStarted = "SpeechStarted"
+    Error = "Error"
+    Close = "Close"

bodhi/examples/__init__.py

@@ -0,0 +1,7 @@
+"""Runnable examples for the Bodhi SDK integrations.
+
+Each module runs as a script, so nothing needs cloning:
+
+    python -m bodhi.examples.pipecat_mic_bot
+    python -m bodhi.examples.pipecat_stream_wav call.wav
+"""

bodhi/examples/pipecat_mic_bot.py

@@ -0,0 +1,107 @@
+#
+# A live Pipecat bot that transcribes your microphone with Bodhi. Transcripts
+# appear in the browser UI (over RTVI) and in this terminal.
+#
+# It needs no OpenAI or Cartesia keys, because there is no LLM or TTS in the
+# pipeline -- it is the smallest thing that exercises a real browser, real VAD
+# and real Bodhi:
+#
+#   pip install "bodhi-api-sdk[pipecat]" "pipecat-ai[webrtc,silero,runner]"
+#   export BODHI_API_KEY=...
+#   python -m bodhi.examples.pipecat_mic_bot
+#
+# Set BODHI_URL to point at another deployment, e.g. wss://stt.navana.ai.
+#
+# Then open http://localhost:7860/client and click Connect.
+#
+# To hear a bot answer back, use the official quickstart
+# (https://docs.pipecat.ai/pipecat/get-started/quickstart) and replace its
+# DeepgramSTTService with the BodhiSTTService built below.
+#
+
+import os
+import time
+from pipecat.audio.vad.silero import SileroVADAnalyzer
+from pipecat.frames.frames import Frame, InterimTranscriptionFrame, TranscriptionFrame
+from pipecat.pipeline.pipeline import Pipeline
+from pipecat.pipeline.task import PipelineParams
+from pipecat.pipeline.worker import PipelineWorker
+from pipecat.processors.frame_processor import FrameDirection, FrameProcessor
+from pipecat.runner.run import main
+from pipecat.runner.types import RunnerArguments
+from pipecat.runner.utils import create_transport
+from pipecat.transports.base_transport import TransportParams
+from pipecat.workers.runner import WorkerRunner
+
+from bodhi.integrations.pipecat_stt import BODHI_DEFAULT_URL, BodhiHotword, BodhiSTTService
+
+MODEL = os.getenv("BODHI_MODEL", "hi-general-v2-8khz")
+URL = os.getenv("BODHI_URL", BODHI_DEFAULT_URL)
+
+# Comma-separated, each "phrase" or "phrase:score", e.g. "बजाज फिनसर्व:2.0".
+HOTWORDS = [
+    BodhiHotword(*(p.split(":")[0], float(p.split(":")[1]) if ":" in p else None))
+    for p in filter(None, os.getenv("BODHI_HOTWORDS", "").split(","))
+]
+
+
+class TranscriptPrinter(FrameProcessor):
+    """Prints transcription frames as they flow past."""
+
+    def __init__(self):
+        super().__init__()
+        self._started = time.monotonic()
+
+    async def process_frame(self, frame: Frame, direction: FrameDirection):
+        """Print transcription frames, then pass everything along."""
+        await super().process_frame(frame, direction)
+
+        elapsed = time.monotonic() - self._started
+        if isinstance(frame, TranscriptionFrame):
+            print(f"[{elapsed:6.2f}s] FINAL   {frame.text}", flush=True)
+        elif isinstance(frame, InterimTranscriptionFrame):
+            print(f"[{elapsed:6.2f}s] partial {frame.text}", flush=True)
+
+        await self.push_frame(frame, direction)
+
+
+async def bot(runner_args: RunnerArguments):
+    """Run the transcription pipeline for one browser connection."""
+    api_key = os.getenv("BODHI_API_KEY")
+    if not api_key:
+        raise SystemExit("set BODHI_API_KEY first")
+
+    # Whichever leg the client connects on: browser WebRTC, or a websocket.
+    def params():
+        return TransportParams(
+            audio_in_enabled=True,
+            # No TTS in this pipeline, so nothing is spoken back. The output
+            # leg is still needed: it carries the RTVI messages that put the
+            # transcripts on screen.
+            audio_out_enabled=True,
+            vad_analyzer=SileroVADAnalyzer(),
+        )
+
+    transport = await create_transport(runner_args, {"webrtc": params, "websocket": params})
+
+    stt = BodhiSTTService(
+        api_key=api_key,
+        model=MODEL,
+        url=URL,
+        settings=BodhiSTTService.Settings(hotwords=HOTWORDS or None),
+    )
+
+    print(f"transcribing with Bodhi model {MODEL} at {URL}; speak into the browser tab", flush=True)
+
+    worker = PipelineWorker(
+        Pipeline([transport.input(), stt, TranscriptPrinter(), transport.output()]),
+        params=PipelineParams(audio_in_sample_rate=16000),
+    )
+
+    runner = WorkerRunner(handle_sigint=runner_args.handle_sigint)
+    await runner.add_workers(worker)
+    await runner.run()
+
+
+if __name__ == "__main__":
+    main()

bodhi/examples/pipecat_stream_wav.py

@@ -0,0 +1,143 @@
+#
+# Stream a WAV file through BodhiSTTService in a real Pipecat pipeline and
+# print the transcripts as they arrive.
+#
+#   pip install "bodhi-api-sdk[pipecat]"
+#   export BODHI_API_KEY=...
+#   python -m bodhi.examples.pipecat_stream_wav call.wav --model hi-general-v2-8khz
+#
+# Audio is fed in real time (100 ms at a time), so partials and finals land
+# with the same timing a live call would see.
+#
+
+import argparse
+import asyncio
+import os
+import time
+import wave
+from pathlib import Path
+
+from pipecat.frames.frames import (
+    EndFrame,
+    Frame,
+    InputAudioRawFrame,
+    InterimTranscriptionFrame,
+    TranscriptionFrame,
+)
+from pipecat.pipeline.pipeline import Pipeline
+from pipecat.pipeline.task import PipelineParams
+from pipecat.pipeline.worker import PipelineWorker
+from pipecat.processors.frame_processor import FrameDirection, FrameProcessor
+from pipecat.workers.runner import WorkerRunner
+
+from bodhi.integrations.pipecat_stt import BODHI_DEFAULT_URL, BodhiHotword, BodhiSTTService
+
+CHUNK_SECONDS = 0.1
+
+
+class TranscriptPrinter(FrameProcessor):
+    """Prints transcription frames as the pipeline produces them."""
+
+    def __init__(self):
+        super().__init__()
+        self._started = time.monotonic()
+
+    async def process_frame(self, frame: Frame, direction: FrameDirection):
+        """Print transcription frames, then pass everything along."""
+        await super().process_frame(frame, direction)
+
+        elapsed = time.monotonic() - self._started
+        if isinstance(frame, TranscriptionFrame):
+            print(f"[{elapsed:6.2f}s] FINAL   {frame.text}", flush=True)
+        elif isinstance(frame, InterimTranscriptionFrame):
+            print(f"[{elapsed:6.2f}s] partial {frame.text}", flush=True)
+
+        await self.push_frame(frame, direction)
+
+
+def read_wav(path: Path) -> tuple[bytes, int]:
+    """Read a mono 16-bit WAV file.
+
+    Args:
+        path: Path to the WAV file.
+
+    Returns:
+        Its PCM bytes and sample rate.
+    """
+    with wave.open(str(path), "rb") as wav:
+        if wav.getsampwidth() != 2 or wav.getnchannels() != 1:
+            raise SystemExit(
+                f"{path} is {wav.getnchannels()}ch/{wav.getsampwidth() * 8}-bit; "
+                "convert it first: ffmpeg -i in.wav -ac 1 -ar 8000 -sample_fmt s16 out.wav"
+            )
+        return wav.readframes(wav.getnframes()), wav.getframerate()
+
+
+async def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("wav", type=Path, help="mono 16-bit WAV file to stream")
+    parser.add_argument("--model", default=os.getenv("BODHI_MODEL", "hi-general-v2-8khz"))
+    parser.add_argument("--url", default=os.getenv("BODHI_URL", BODHI_DEFAULT_URL))
+    parser.add_argument("--api-key", default=os.getenv("BODHI_API_KEY"))
+    parser.add_argument("--hotword", action="append", default=[], metavar="PHRASE[:SCORE]")
+    parser.add_argument("--parse-number", action="store_true", help="normalise numbers and dates")
+    parser.add_argument("--no-partials", action="store_true", help="finals only")
+    args = parser.parse_args()
+
+    if not args.api_key:
+        raise SystemExit("set BODHI_API_KEY (or pass --api-key)")
+
+    hotwords = []
+    for spec in args.hotword:
+        phrase, _, score = spec.partition(":")
+        hotwords.append(BodhiHotword(phrase, float(score) if score else None))
+
+    audio, sample_rate = read_wav(args.wav)
+    print(
+        f"streaming {len(audio) / 2 / sample_rate:.1f}s of {sample_rate} Hz audio "
+        f"to {args.url} as {args.model}",
+        flush=True,
+    )
+
+    stt = BodhiSTTService(
+        api_key=args.api_key,
+        model=args.model,
+        url=args.url,
+        interim_results=not args.no_partials,
+        settings=BodhiSTTService.Settings(
+            parse_number=args.parse_number,
+            hotwords=hotwords or None,
+        ),
+    )
+
+    worker = PipelineWorker(
+        Pipeline([stt, TranscriptPrinter()]),
+        params=PipelineParams(audio_in_sample_rate=sample_rate),
+        cancel_on_idle_timeout=False,
+    )
+
+    async def feed_audio():
+        # Let the pipeline start and the websocket handshake finish.
+        await asyncio.sleep(0.5)
+        chunk_bytes = int(sample_rate * CHUNK_SECONDS) * 2
+        for offset in range(0, len(audio), chunk_bytes):
+            await worker.queue_frame(
+                InputAudioRawFrame(
+                    audio=audio[offset : offset + chunk_bytes],
+                    sample_rate=sample_rate,
+                    num_channels=1,
+                )
+            )
+            await asyncio.sleep(CHUNK_SECONDS)
+        # Give Bodhi a moment to endpoint the last utterance.
+        await asyncio.sleep(1.5)
+        await worker.queue_frame(EndFrame())
+        print(f"transaction_id: {stt.transaction_id}", flush=True)
+
+    runner = WorkerRunner(handle_sigint=False)
+    await runner.add_workers(worker)
+    await asyncio.gather(runner.run(), feed_audio())
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

bodhi/integrations/__init__.py

@@ -0,0 +1,9 @@
+"""Integrations that plug Bodhi into third-party frameworks.
+
+Each module here needs its framework installed; nothing in this package is
+imported by the core SDK. For Pipecat::
+
+    pip install "bodhi-api-sdk[pipecat]"
+
+    from bodhi.integrations.pipecat_stt import BodhiSTTService
+"""