KoreanFA

한국어

KoreanFA creates Praat TextGrid files from Korean or Japanese WAV audio and a matching UTF-8 transcript. It provides both a Python API and a command-line interface, with automatic Korean/Japanese model selection by default.

Features

• Align one WAV/TXT pair or an entire directory of pairs
• Select Korean or Japanese automatically, or choose a model explicitly
• Produce word and phone tiers in a Praat TextGrid
• Use a managed Kaldi-based engine; Docker and a web server are not required

Requirements

• Linux x86_64
• macOS 12 or later on Apple Silicon (arm64) or Intel (x86_64)
• Python 3.12 or 3.13
• WAV audio and UTF-8 text transcripts

Windows is not supported yet. KoreanFA automatically downloads the native engine matching a supported Linux or macOS system.

Installation

Install KoreanFA from PyPI, then install the native alignment engine matching the current system once:

python -m pip install koreanfa
koreanfa engine install

To use the latest development source from the default branch instead:

git clone --depth 1 https://github.com/hyung8758/Korean_FA.git
cd Korean_FA
python -m pip install .
koreanfa engine install

Check the engine status at any time:

koreanfa engine status

If the engine is missing, an alignment command explains how to install it.

Command line

Align one WAV/TXT pair:

koreanfa align recording.wav recording.txt

This creates recording.TextGrid beside the input audio by default.

Align every matching pair in a directory:

koreanfa align corpus
koreanfa align corpus -r -o aligned

Files are paired by their relative stem: for example, session_01.wav is matched with session_01.txt. Unmatched files are skipped by default and a warning identifies them.

The CLI reports each file's preparation/decode stage, a directory progress bar, and a final total / success / failed summary. Successful files keep their TextGrids even if other files fail; the CLI then exits with status 2 and prints each rejected file's reason. Add --keep-workdir to retain logs/summary.tsv and per-file Kaldi logs for diagnosis.

Language selection

-l auto / --lang auto is the default. Hangul selects the Korean model, while Hiragana, Katakana, or Kanji selects the Japanese model. Choose a model explicitly for mixed-script transcripts. In a directory, a transcript that has neither script (for example, <laugh> or English-only text) is reported in batch.failures; other files continue to run.

koreanfa align recording.wav recording.txt -l kor
koreanfa align recording.wav recording.txt -l jap

Run koreanfa align --help for all options.

Alignment options

• -nj N, --num-jobs N: align up to N files concurrently; the default is 4. In Python, use num_jobs=N.
• -o DIR, --output-dir DIR: write TextGrids under DIR (output_dir=DIR).
• -kd DIR, --kaldi-dir DIR: use an external Kaldi runtime (kaldi_dir=DIR).
• -l {auto,kor,jap}, --lang ...: choose a language adapter (lang=...).
• -r, --recursive: include subdirectories when aligning a directory (recursive=True).
• -iu, --ignore-unmatched [true|false]: skip WAV/TXT files without a same-stem counterpart and issue a warning; this is the default (ignore_unmatched=True). Set it to false to stop before alignment when an unmatched file is found.
• -nw, --no-word; -np, --no-phone: omit the corresponding TextGrid tier (word_tier=False / phone_tier=False).
• -kw, --keep-workdir: retain successful-run Kaldi logs and staged diagnostics (keep_workdir=True).

Use -h / --help for command help and -v / --version for the package version.

Python API

Install the engine once, then align a pair:

from koreanfa import align, install_engine

install_engine()
result = align("recording.wav", "recording.txt", lang="auto")
print(result.textgrid)
print(result.language)  # "kor" or "jap"

For a directory, use Aligner:

from koreanfa import Aligner

aligner = Aligner(lang="auto", num_jobs=4)
batch = aligner.align("corpus", recursive=True)
for result in batch.results:
    print(result.textgrid)
for failure in batch.failures:
    print(f"rejected: {failure.audio} ({failure.reason})")

Library calls do not print progress by default; unmatched input files are reported through Python's warning system. Pass a progress callback when the host application wants structured progress events, and use keep_workdir=True when it needs to retain logs/summary.tsv. Directory alignment returns successful files in batch.results and controlled per-file rejections in batch.failures.

Input notes

• Each WAV file needs a matching UTF-8 .txt transcript.
• One sentence per transcript is recommended.
• Audio is normalized to mono 16 kHz PCM WAV in a temporary workspace.
• Korean pronunciation conversion is provided by the package dependency ko-speech-tools and its Korean MeCab dictionary; no separate Korean G2P installation is required.
• Japanese support includes the required MeCab and IPADIC resources in the managed engine.

Engine management

koreanfa engine install
koreanfa engine status
koreanfa engine install -f
koreanfa engine remove -y

Set KOREANFA_ENGINE_HOME to choose the engine cache location. Advanced users can set KOREANFA_KALDI_DIR or pass kaldi_dir= to use an externally managed Kaldi runtime instead.

License

KoreanFA code and the Japanese acoustic model are licensed under Apache-2.0. The Korean acoustic model is proprietary to Mediazen and may be used for commercial or non-commercial purposes only as part of KoreanFA; modification or separate redistribution requires prior written permission. See the Korean model notice, the example-data notice, and the third-party notices for bundled source material and the separately downloaded engine.