korean-pronunciation

Korean grapheme-to-phoneme converter for Node.js. Converts written Korean (Hangul) into its pronunciation.

This is a Node.js port of g2pK by Kyubyong Park.

Features

• Implements all 30 Korean Standard Pronunciation Rules
• English word transliteration (using CMU Pronouncing Dictionary)
• Arabic numeral to Korean conversion (Sino-Korean & Pure Korean)
• Idiom/exception handling
• Descriptive (colloquial) pronunciation mode
• Zero runtime dependencies - pure JavaScript

Installation

npm install korean-pronunciation

Usage

const { G2p } = require('korean-pronunciation');

const g2p = new G2p();

// Basic conversion
console.log(g2p.convert('있다'));       // 읻따
console.log(g2p.convert('먹는'));       // 멍는
console.log(g2p.convert('좋다'));       // 조타
console.log(g2p.convert('같이'));       // 가치
console.log(g2p.convert('합니다'));     // 함니다

// English words are automatically converted to Hangul
console.log(g2p.convert('mp3'));        // 엠피쓰리
console.log(g2p.convert('file'));       // 파일
console.log(g2p.convert('game'));       // 게임

// Numbers before counter words use pure Korean
console.log(g2p.convert('3개'));        // 세개

// Mixed text
console.log(g2p.convert('나의 친구가 mp3 file 3개를 다운받고 있다'));
// 나의 친구가 엠피쓰리 파일 세개를 다운받꼬 읻따

TypeScript

import { G2p, G2pOptions } from 'korean-pronunciation';

const g2p = new G2p();

const options: G2pOptions = {
  descriptive: true,  // colloquial pronunciation
  verbose: false,     // show conversion steps
  groupVowels: false, // normalize similar vowels
  toSyl: true,        // assemble jamo into syllables
};

console.log(g2p.convert('나의 친구', options));
// 나에 친구 (descriptive: 의 as particle → 에)

API

new G2p()

Creates a new G2p instance. Loads the pronunciation rule table, CMU dictionary, and idiom list.

g2p.convert(text, options?)

Converts Korean text to its pronunciation.

Parameters:

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | text | string | | Input Korean text | | options.descriptive | boolean | false | Use colloquial pronunciation rules | | options.verbose | boolean | false | Print conversion process to console | | options.groupVowels | boolean | false | Normalize similar vowels (ㅐ→ㅔ, ㅒ→ㅖ) | | options.toSyl | boolean | true | Assemble jamo into syllable blocks |

Returns: string - The pronunciation of the input text.

Pronunciation Rules Implemented

The converter implements all 30 rules of Korean Standard Pronunciation:

• Rules 5.1-5.4: Vowel rules (ㅖ, ㅢ)
• Rule 9: Final consonant neutralization (ㄲ,ㅋ→ㄱ; ㅅ,ㅆ,ㅈ,ㅊ,ㅌ→ㄷ; ㅍ→ㅂ)
• Rules 10-11: Compound coda simplification
• Rule 12: ㅎ aspiration
• Rules 13-15: Consonant linking
• Rule 16: Hangul letter names
• Rule 17: Palatalization (ㄷ+ㅣ→ㅈ)
• Rule 18: Nasal assimilation
• Rules 19-20: ㄹ assimilation
• Rules 23-27: Consonant hardening (tensification)
• Rules 28-30: Sai-siot rules

Additional Exports

const { h2j, j2h, compose, processNum, convertNum, convertEng } = require('korean-pronunciation');

// Hangul decomposition/composition
h2j('한글');     // '한글' (decompose to jamo)
j2h('ᄒ','ᅡ','ᆫ'); // '한' (compose jamo to syllable)

// Number conversion
processNum('123', true);   // '백이십삼' (Sino-Korean)
processNum('3', false);    // '세' (Pure Korean)

License

Apache License 2.0 (same as original g2pK)

Credits

• Original Python library by Kyubyong Park
• CMU Pronouncing Dictionary by Carnegie Mellon University