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 with glibc 2.17 or later
  • Officially supported and tested: Ubuntu 22.04 LTS and 24.04 LTS
  • Older Ubuntu releases and other glibc-based Linux distributions may work, but are not currently covered by KoreanFA's official test matrix
• 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.

If an engine download or checksum verification fails, see the engine installation troubleshooting guide. KoreanFA never installs an engine whose SHA-256 checksum does not match the published manifest.

Citation

If you use KoreanFA in academic work, please cite the specific version used in your research. Citation metadata is provided in CITATION.cff and through the Cite this repository menu on GitHub.

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.