Metadata-Version: 2.5
Name: bareum
Version: 0.1.0
Summary: Korean pronunciation scoring: segmentals and standard pronunciation rules.
Project-URL: Homepage, https://github.com/dungca1512/bareum
Project-URL: Source, https://github.com/dungca1512/bareum
Project-URL: Issues, https://github.com/dungca1512/bareum/issues
Project-URL: Changelog, https://github.com/dungca1512/bareum/blob/main/CHANGELOG.md
Author: Công Anh Dũng
License-Expression: MIT
License-File: LICENSE
Keywords: gop,hangul,korean,phonology,pronunciation,speech
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Natural Language :: Korean
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Requires-Python: >=3.10
Requires-Dist: numpy>=1.24
Provides-Extra: all
Requires-Dist: kiwipiepy>=0.18; extra == 'all'
Requires-Dist: librosa>=0.10; extra == 'all'
Requires-Dist: onnxruntime>=1.17; extra == 'all'
Requires-Dist: soundfile>=0.12; extra == 'all'
Provides-Extra: audio
Requires-Dist: librosa>=0.10; extra == 'audio'
Requires-Dist: soundfile>=0.12; extra == 'audio'
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Requires-Dist: twine>=5; extra == 'dev'
Provides-Extra: export
Requires-Dist: onnx>=1.15; extra == 'export'
Requires-Dist: torch>=2.2; extra == 'export'
Requires-Dist: transformers>=4.40; extra == 'export'
Provides-Extra: frontend
Requires-Dist: kiwipiepy>=0.18; extra == 'frontend'
Provides-Extra: onnx
Requires-Dist: onnxruntime>=1.17; extra == 'onnx'
Description-Content-Type: text/markdown

# bareum

Korean pronunciation scoring for read-aloud speech, on the CPU. It scores
consonants and vowels per syllable, and whether the standard pronunciation rules
(표준 발음법: liaison, nasalization, lateralization…) were applied.

> Status: **alpha (0.1)**. All thresholds were tuned on native read speech only
> (Zeroth-Korean, 10 speakers), and no L2 learner data has been used yet. Treat
> the scores as feedback, not as a grade. Design and tuning records:
> [docs/SPEC.md](docs/SPEC.md) and
> [`calibration/default.json`](src/bareum/calibration/default.json).

Sibling of [hatsuon](https://github.com/dungca1512/hatsuon) (Japanese). The audio,
alignment and GOP modules are shared with it.

## Install

```bash
pip install "bareum[all]"
```

The acoustic model is **not** shipped in the package. Convert it once on your
machine. This step needs PyTorch and transformers only for the conversion itself:

```bash
pip install "bareum[export]"
bareum-export            # writes ~/.cache/bareum/models/... (ONNX, int8)
```

`bareum-export --out DIR` writes the model elsewhere; set `BAREUM_MODEL_DIR=DIR`
to use it. `--no-quantize` keeps FP32 weights. The default model is
[slplab/wav2vec2-xls-r-300m_phone-mfa_korean](https://huggingface.co/slplab/wav2vec2-xls-r-300m_phone-mfa_korean)
(Apache-2.0), pinned to one revision.

## Use

```python
import bareum

r = bareum.score("learner.wav", "국물이 맛있어요")
print(r.overall, r.accuracy, r.rules, r.completeness, r.fluency, r.confidence)
for w in r.words:
    print(w.surface, w.pronunciation, w.score, w.rules_score)
    for s in w.syllables:
        print("  ", s.spelling, s.pronounced, s.status.value, round(s.score))
        for p in s.phones:
            print("     ", p.role, p.phone, p.status.value, p.substituted_by)
    for site in w.rules:
        print("   rule:", site.rule, site.standard_form, site.observed.value)
print([x.value for x in r.warnings])
```

- `audio` can be a path, encoded bytes, or a `(samples, sample_rate)` tuple.
- The expected pronunciation comes from the built-in rule engine. Override it with
  `pronunciation="궁무리 마시써요"` (whole text) or `pronunciation={"국물": "궁물"}`.
  A list (`{"맛있어요": ["마시써요", "마디써요"]}`) accepts any of the forms.
- A rule site is `applied`, `not_applied` or `unknown`. Only obligatory rules
  within a word count towards `r.rules`. Optional and cross-word rules accept
  either form and are reported but not scored.
- `rules=False` or `fluency=False` skips those stages. A skipped or abstaining
  sub-score is `None`, and `overall` is renormalized over the rest.
- `debug=True` attaches the free decode, per-phone GOP and rule-site margins to
  `r.debug`.
- Soft problems such as `no_speech`, `content_mismatch` or `truncated` come back
  in `r.warnings` and lower `r.confidence`.
- Hard errors raise `bareum.AudioError` or `bareum.TextError`.

## Known limitations (0.1)

All figures are on 5 held-out native speakers (Zeroth-Korean test, about 200
utterances). The other 5 speakers were used for tuning.

- **Native-only calibration.** We have not yet measured mispronunciation recall
  on learners.
  - 0.35% of correct native syllables fall below the `mispronounced` threshold.
    On a 10-syllable sentence, about 1 native reading in 30 gets one false flag.
  - Synthetic one-phone substitutions (the expected pronunciation is changed, the
    audio is not) are caught 59% of the time: 74% for vowels, 60% for
    lenis/aspirated/tense swaps and 42% for codas. The 5 tuning speakers give
    48%, so expect a wide margin of error. Real learner errors are often subtler
    than these.
  - Synthetic deleted syllables are caught 59% of the time (76% for the last
    syllable of the utterance).
- **Rules that are not judged yet.** These rules are always reported `unknown`,
  and both forms are accepted:
  - **Tensification (경음화).** On native speech, the acoustic model prefers the
    lenis form at 32% of sites.
  - Rules with fewer than 8 native examples in the tuning data: ㅎ-tensification
    and ㅎ-nasalization, palatalization, ㄴ-insertion, 사이시옷, place
    assimilation, the 의 / 져 / 예 vowel rules, and a few others. The full list
    is under `rules_disabled` in the calibration file.

  The judged rules are liaison, nasalization, lateralization, ㄹ-nasalization,
  aspiration, cluster simplification and ㅎ-deletion. Natives apply them at
  99.3% of sites and miss them at 0.5%.
- **Cross-word rules** (liaison or nasalization across a word boundary) are not
  scored. Natives often pause between words and apply them only about 30% of the
  time.
- **ㅐ / ㅔ are one unit**, as in most contemporary Seoul speech. The default model
  cannot separate them.
- **The rule engine can be wrong** on loanwords, proper nouns and lexical
  exceptions. A correct reading then shows up as mispronounced syllables. Pass
  `pronunciation={...}` in those cases.
- Read speech only, one sentence at a time. Not for spontaneous speech or singing.
  Recordings cut tightly at the end get a `truncated` warning. Leave about 0.3 s
  of silence on each side.
- `intonation=True` is not available yet and raises `NotImplementedError`.

## Development

```bash
pip install -e ".[all,dev]"
pytest && ruff check .
# Zeroth-Korean test split (see DATA_SOURCES.md for the source and revision)
python -I tools/prepare_zeroth.py data/zeroth/kresnik/test.parquet data/zeroth/test
python tools/eval_per.py data/zeroth/test/manifest.tsv   # phone error rate
python tools/calibrate.py collect --strict && python tools/calibrate.py collect
python tools/calibrate.py synth && python tools/calibrate.py fit --write
```

## License

MIT. Corpora and the acoustic model have their own licences and are never
redistributed. See [DATA_SOURCES.md](DATA_SOURCES.md).
