Metadata-Version: 2.4
Name: balbal
Version: 0.1.1
Summary: Open Turkish speech recognition on CPU: balbal-v2 and balbal-v2-manas, weights fetched from Hugging Face on first use.
Author: Eray Yapağcı
License-Expression: Apache-2.0
Project-URL: Homepage, https://erayy.com/balbal
Project-URL: Source, https://github.com/erayyap/balbal
Project-URL: Model: balbal-v2, https://huggingface.co/erayyapagci/balbal-v2
Project-URL: Model: balbal-v2-manas, https://huggingface.co/erayyapagci/balbal-v2-manas
Keywords: speech recognition,asr,stt,turkish,onnx,cpu
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Natural Language :: Turkish
Classifier: Natural Language :: English
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: <3.13,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: scipy>=1.10
Requires-Dist: soundfile>=0.12
Requires-Dist: sentencepiece>=0.2.0
Requires-Dist: onnxruntime>=1.30.0
Requires-Dist: flashlight-text==0.0.7
Requires-Dist: huggingface_hub>=0.23
Dynamic: license-file

# balbal

Open Turkish speech recognition that runs on a CPU.

```bash
pip install balbal
balbal run speech.wav
```

The first run downloads the model from Hugging Face (balbal-v2: ~590 MB, once); later runs start from the local cache.

| Model | Parameters | Languages | Mu-Bench WER / sigWER | Speed (8 CPU threads) |
|---|---|---|---|---|
| **balbal-v2** (default) | 45.4M | Turkish | 9.46% / 18.44% | 236x real time |
| **balbal-v2-manas** | 313.3M | Turkish, English | 8.20% / 14.89% | 123x real time |

Output: cased, punctuated text with per-word timestamps; spoken numbers come out as digits.

## Command line

```bash
balbal run speech.wav                         # text
balbal run --model manas a.wav b.mp3          # balbal-v2-manas; MP3 / M4A / video through FFmpeg
balbal run --json speech.wav                  # one JSON line per file: text, words with start / end seconds, timings
balbal run --hotwords "Eray,Hasan" call.wav   # favour names / words you expect in the audio
balbal run --no-itn speech.wav                # keep numbers as spoken words
balbal download --model manas                 # fetch the model files now
```

`--threads` sets the CPU threads (default `BALBAL_THREADS`, else up to 8).

## Python

```python
import balbal

print(balbal.transcribe('speech.wav')['text'])

model = balbal.load('balbal-v2-manas')          # load once, reuse
result = model.transcribe('call.wav', hotwords=['Eray'])
for w in result['words']:
    print(w['start'], w['end'], w['word'])

model.transcribe(samples, sample_rate=8000)      # a NumPy waveform at any sample rate
```

`transcribe` returns `text`, `words` (`word`, `start`, `end` in seconds), `duration_seconds`, `inference_seconds` and
`realtime_factor`. Audio longer than 30 s is read in overlapping windows whose CTC frames are stitched into one sequence and
decoded in one KenLM pass, so no word is cut at a window edge. One `Model` per thread.

## Platform

Linux x86-64, Python 3.11 or 3.12. The wheel carries the native beam-search decoder and the custom onnxruntime operators of the
fast graph (built for x86-64-v2, AVX2 and AVX-512 CPUs, chosen at run time). `runtime='onnx'` (`--runtime onnx`) runs the
standard-operator graph instead.

Files go to `~/.cache/huggingface/balbal/` (`HF_HOME`, `BALBAL_CACHE` or `cache_dir=` move it). The model revisions are pinned to the ones this release was tested
with; `revision='main'` takes the latest upload.

## Links

- Model page: https://erayy.com/balbal
- Weights: [erayyapagci/balbal-v2](https://huggingface.co/erayyapagci/balbal-v2), [erayyapagci/balbal-v2-manas](https://huggingface.co/erayyapagci/balbal-v2-manas)
- Code (inference, streaming, training): https://github.com/erayyap/balbal

The code is Apache-2.0. The model weights have their own license (balbal Community License 1.0, on the model pages).
