Metadata-Version: 2.4
Name: turkish-stt
Version: 0.1.1
Summary: Real-time, low-latency Turkish speech-to-text (STT) that runs on the CPU.
Author: mihu · Speech Systems
Maintainer-email: Deniz Gökdünek <deniz@mihu.ai>
License: mihu Community License
        Version 1.0
        
        These terms govern all use of the turkish-stt materials released by mihu
        ("mihu", "Licensor"). By downloading, accessing, or otherwise using the Materials, you
        ("Licensee") accept and agree to be bound by this License.
        
        1. DEFINITIONS
           1.1 "Materials" — the turkish-stt model weights, model card, and any
               accompanying code, documentation, or related artifacts released under this License.
           1.2 "Outputs" — anything produced by running the Materials.
           1.3 "Derivative" — any work created from, adapted from, or built upon the Materials.
           1.4 "Annual Revenue" — the combined worldwide gross revenue of Licensee together with
               its affiliates over the preceding twelve months.
        
        2. COMMUNITY GRANT
           Provided Licensee's Annual Revenue stays below USD 500,000, and subject to every term
           below, Licensor grants Licensee a worldwide, non-exclusive, non-transferable,
           royalty-free, no-cost right to use, reproduce, and make Derivatives of the Materials.
           This covers, without limitation:
             (a) research and academic work;
             (b) personal and other non-commercial use;
             (c) commercial use within the revenue limit above, once any commercial-use
                 registration that Licensor requires has been completed.
        
        3. ABOVE THE THRESHOLD
           Once Licensee's Annual Revenue reaches USD 500,000 or more, no use is permitted under
           the Community Grant. Licensee must first secure a separate commercial agreement from
           mihu. Write to support@mihu.ai to arrange terms.
        
        4. ATTRIBUTION
           Licensee shall (a) keep this License intact, together with any copyright or attribution
           notices, in a "NOTICE" file shipped alongside the Materials or any Derivative, and
           (b) show "Powered by mihu" clearly in any product, service, interface, or documentation
           that builds on the Materials or their Outputs.
        
        5. RESTRICTIONS
           Licensee shall not:
             (a) use the Materials or Outputs to train, build, or refine any competing speech,
                 foundational, or general-purpose AI model;
             (b) strip, hide, or modify any attribution or proprietary notice;
             (c) use the mihu name, logo, or marks beyond the attribution required in Section 4
                 (no trademark rights are granted here);
             (d) use the Materials unlawfully or contrary to any Acceptable Use Policy that
                 Licensor may publish;
             (e) sublicense, sell, or redistribute the Materials except where this License
                 expressly allows it.
        
        6. OWNERSHIP
           Between the parties, Licensor keeps all right, title, and interest in the Materials.
           Licensee holds the Derivatives it lawfully makes and the Outputs it generates, always
           subject to Licensor's rights in the underlying Materials. Nothing beyond the rights
           stated here is granted, by implication or otherwise.
        
        7. NO WARRANTY
           THE MATERIALS ARE SUPPLIED "AS IS", WITH NO WARRANTY OF ANY KIND, WHETHER EXPRESS OR
           IMPLIED, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
           PURPOSE, OR NON-INFRINGEMENT.
        
        8. LIMITATION OF LIABILITY
           TO THE FULLEST EXTENT THE LAW ALLOWS, LICENSOR IS NOT LIABLE FOR ANY INDIRECT,
           INCIDENTAL, SPECIAL, CONSEQUENTIAL, OR EXEMPLARY DAMAGES CONNECTED TO THE MATERIALS OR
           THIS LICENSE.
        
        9. TERMINATION
           This License ends automatically if (a) Licensee's Annual Revenue reaches or passes
           USD 500,000 without a commercial agreement in place, (b) Licensee breaches any term, or
           (c) Licensee brings litigation or a patent claim against Licensor over the Materials.
           On termination, Licensee must stop all use and delete every copy of the Materials. To
           keep using them, arrange a commercial agreement via support@mihu.ai.
        
        10. GENERAL
           This License is the complete agreement covering the Materials. It is governed by the
           laws of Licensor's principal place of business, disregarding conflict-of-law rules.
        
        © mihu. All rights reserved.
        
        turkish-stt and the mihu Community License are provided by Hunters AI, operating
        under the mihu brand. "mihu" is a trademark of Hunters AI.
        
Project-URL: Model weights, https://huggingface.co/mihuai/turkish-stt
Keywords: speech-recognition,asr,streaming,turkish,on-device,cpu,voice-agent
Classifier: Programming Language :: Python :: 3
Classifier: License :: Other/Proprietary License
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: sherpa-onnx
Requires-Dist: numpy
Requires-Dist: soundfile
Requires-Dist: soxr
Requires-Dist: huggingface_hub
Provides-Extra: eval
Requires-Dist: jiwer; extra == "eval"
Requires-Dist: num2words; extra == "eval"
Dynamic: license-file

# turkish-stt

**Real-time, low-latency speech-to-text (STT) for Turkish — on the CPU.**

Turkish-only · streaming · CPU-native · runs on the edge. A compact **66 M-parameter** causal streaming model,
built for voice agents, call centers, and on-device transcription where a GPU is not an option — no API key, no
cloud, no GPU.

- 🇹🇷 **Turkish-first** — every parameter serves one language, not ~100
- ⚡ **Streaming** — partial results as you speak (~320 ms), no 30-second windows
- 🖥️ **CPU-native** — **RTF 0.128** on a single CPU thread (~8× faster than real time)
- 🔌 **Tiny** — ~68 MB; runs on a Raspberry-Pi-class device
- 🏷️ **Entity/brand aware** — tuned for Turkish brands, models, and numbers

## Installation

```bash
pip install turkish-stt
```

## Usage

```python
import mihu_stt

# one-shot: transcribe a file (16 kHz mono, or anything soundfile reads)
text = mihu_stt.transcribe("audio.wav")
print(text)

# timed segments, cut at detected turn ends — for subtitles or a searchable transcript
for seg in mihu_stt.transcribe_segments("audio.wav"):
    print(seg["start"], seg["end"], seg["text"])
```

Streaming — feed audio as it arrives and read an updating transcript, with turn-end detection built in:

```python
import mihu_stt

stt = mihu_stt.StreamingSTT()
# pcm16 = 16-bit PCM bytes from your mic / phone line
text, is_final = stt.accept_pcm16(pcm16, sample_rate=16000)
# `text` updates while speech continues; `is_final` turns True at end-of-utterance
```

Model weights download automatically from Hugging Face
([`mihuai/turkish-stt`](https://huggingface.co/mihuai/turkish-stt)) the first time and are cached.

## Try it on your microphone

[`examples/microphone.py`](examples/microphone.py) is a ~60-line live transcriber — partial text updates as
you speak, each turn commits with a `✓` when the model detects end-of-utterance:

```bash
pip install turkish-stt sounddevice
python examples/microphone.py                 # default input device
python examples/microphone.py --list-devices  # or pick one:  --device 1
```

## Transcribe a file, export the transcript

[`examples/export_transcript.py`](examples/export_transcript.py) turns any audio file into a plain-text
transcript or timed subtitles — the format follows the output extension:

```bash
python examples/export_transcript.py meeting.wav              # -> meeting.txt
python examples/export_transcript.py meeting.wav -o subs.srt  # .srt / .vtt / .json
```

```srt
1
00:00:00,000 --> 00:00:05,280
Aracınızın periyodik bakımı tamamlandı. Dilerseniz kapınıza teslim ediyoruz
```

## Integrations

Drop-in adapters for the common voice-agent stacks (see [`examples/`](examples)):

**LiveKit Agents** — [`examples/livekit_stt.py`](examples/livekit_stt.py):
```python
from livekit.agents import AgentSession
from livekit_stt import MihuSTT
session = AgentSession(stt=MihuSTT(), llm=..., tts=...)
```

**Pipecat** — [`examples/pipecat_stt.py`](examples/pipecat_stt.py):
```python
from pipecat_stt import MihuSTTService
pipeline = Pipeline([transport.input(), vad, MihuSTTService(), llm, tts, transport.output()])
```

## Benchmarks

Measured in-house under one matched Turkish normalization. Real-human held-out **FLEURS-TR** (743 clips) and a
second real-human set **MediaSpeech-TR** (200-clip subset), both audited absent from training. Latency on a
single CPU thread (AMD EPYC 7282).

| System | Class | Params | FLEURS WER | MediaSpeech WER | CPU RTF |
|---|---|---:|---:|---:|---:|
| **turkish-stt** | **streaming · CPU** | **66 M** | **13.90%** | **15.89%** | **0.128** |
| Vosk-TR | streaming · CPU | ~50 M | 34.09% | 31.02% | 0.138 |
| Whisper small | offline · GPU | 244 M | 15.12% | — | 1.098 |
| Whisper large-v3 | offline · GPU | 1.5 B | 7.08% | — | 6.095 |

Among **streaming, CPU-deployable** systems turkish-stt more than halves Vosk's error on both real-human sets,
matches the four-times-larger offline Whisper-small, and is the only option that is real-time on CPU — it also
degrades more gracefully than Vosk under additive noise. A detailed technical report — full methodology, ablations,
latency/concurrency study, and the leakage audits — is being prepared and will be shared.

## Reproduce the numbers

The evaluation set, references, and scripts are in [`eval/`](eval) — including the text (n-gram) and acoustic
(chromaprint) contamination audits used to verify the held-out sets are absent from training.

```bash
pip install "turkish-stt[eval]"
python eval/run_eval.py --data-dir eval/tts-synthetic
```

## License

**mihu Community License** — free for research, personal, and limited commercial use. See [`LICENSE`](LICENSE)
for the full terms. Weights are released under the same license on Hugging Face.
