voxrun

High-performance speech-to-text inference library derived from faster-whisper.

voxrun preserves the existing faster-whisper inference API while packaging the Python implementation as Nuitka-compiled, CPython-specific binary wheels. Nuitka compilation increases reverse-engineering cost; it is not cryptographic encryption and does not make the implementation impossible to reverse engineer.

Installation

voxrun Phase 1 supports Linux x86_64 on glibc 2.28 or newer and CPython 3.10, 3.11, and 3.12. Each wheel is built for a specific CPython ABI.

uv add voxrun

The conventional pip installer is also supported:

python -m pip install voxrun

Do not install the upstream ctranslate2 distribution together with voxrun-ctranslate2; both provide the ctranslate2 import and their package files conflict.

Usage

from voxrun import WhisperModel

model = WhisperModel(
    "large-v3",
    device="cuda",
    compute_type="float16",
)

segments, info = model.transcribe("audio.mp3")

for segment in segments:
    print(f"[{segment.start:.2f}s -> {segment.end:.2f}s] {segment.text}")

segments is a generator. Consume it to run the transcription to completion:

segments, _ = model.transcribe("audio.mp3")
segments = list(segments)

The existing public APIs remain available, including WhisperModel, BatchedInferencePipeline, decode_audio, Segment, Word, TranscriptionInfo, WhisperModel.transcribe(), BatchedInferencePipeline.transcribe(), download_model, available_models(), and format_timestamp().

Batched transcription

from voxrun import BatchedInferencePipeline, WhisperModel

model = WhisperModel("turbo", device="cuda", compute_type="float16")
batched_model = BatchedInferencePipeline(model=model)
segments, info = batched_model.transcribe("audio.mp3", batch_size=16)

Contextual biasing

Decoder-level contextual phrases require voxrun-ctranslate2>=4.8.1.post1, which exposes ctranslate2.ContextGraph. Calls without context_phrases preserve the graph-free path.

segments, info = model.transcribe(
    "audio.mp3",
    context_phrases=["NVIDIA", "H200", ("BRM9206", 5.0)],
    context_score=3.0,
)

See Contextual biasing for scoring, tokenizer boundaries, graph lifetime, and validation details.

Streaming decode (AlignAtt)

WhisperModel.streaming_decode decodes one step of a SimulStreaming-style stream. It needs voxrun-ctranslate2>=4.8.1.post2, which has native AlignAtt (ctranslate2.models.WhisperAlignAttOptions); check with voxrun.streaming.supports_streaming_decode().

Each call re-decodes the current audio window (at most 30 s) and returns only the tokens that are stable. Decoding stops before a token whose most attended audio frame is too close to the end of the window. The policy runs inside CTranslate2; voxrun prepares features and the prompt, and wraps the result. The caller keeps all stream state:

from voxrun import StreamingDecodeOptions

graph = model.compile_context_graph(["高育安"], 3.0, language="zh")  # once per session
stable, previous = [], None
for window, is_final in windows:  # growing audio of the current utterance
    out = model.streaming_decode(
        window,
        StreamingDecodeOptions(language="zh", previous_attended_frame=previous, is_final=is_final),
        stable_tokens=stable,
        context_graph=graph,
    )
    if out.stop_reason != "alignatt_rewind":
        stable += out.tokens
    previous = out.last_attended_frame

Behaviour:

• Defaults follow the SimulStreaming reference runtime: frame_threshold=25, final_frame_threshold=4, rewind_threshold=200 (20 ms encoder frames), greedy.
• Encoder input. Audio is padded to 30 s with silence before the log-Mel, as in the reference. variable_length_input=True opts out.
• Stable tokens are fed as context and seed the context graph, so a phrase split across calls keeps its bias. The static prompt never seeds it.
• Result fields: tokens, text, stop_reason, per-token attended_frames, last_attended_frame, content_frames, no_speech_prob and inference_time_s (complete: generate returns host token IDs only after the device work).
• transcribe() and BatchedInferencePipeline are unchanged.

VAD filter

PyAV handles audio decoding, so a separate system FFmpeg installation is not required.

segments, _ = model.transcribe(
    "audio.mp3",
    vad_filter=True,
    vad_parameters={"min_silence_duration_ms": 500},
)

The packaged Silero VAD ONNX model is loaded from voxrun/assets.

Logging

import logging

logging.basicConfig()
logging.getLogger("voxrun").setLevel(logging.DEBUG)

Migration from faster-whisper

The namespace is intentionally breaking; no faster_whisper compatibility alias is installed.

# Before
from faster_whisper import WhisperModel

# After
from voxrun import WhisperModel

Model repository IDs such as Systran/faster-whisper-large-v3 are external runtime identifiers and remain unchanged.

Development

The project uses uv as its package and environment manager.

uv sync
uv run pytest

Build and audit the local binary wheel:

uv build --wheel
VERSION="$(uv version --short)"
python scripts/verify_wheel.py --expected-version "$VERSION" dist/*.whl

Nuitka build intermediates and the final wheel are excluded from the public release by the wheel verifier.

Attribution and license

voxrun was originally derived from SYSTRAN/faster-whisper and retains the applicable MIT license notices. See LICENSE.

The ContextGraph design also references the applicable CTranslate2 license and documentation.