pyopenjtalk

The pyopenjtalk module provides a high-level functional interface for text processing and waveform synthesis. Most common tasks can be performed using these top-level functions, which internally manage global instances of pyopenjtalk.openjtalk.OpenJTalk and pyopenjtalk.htsengine.HTSEngine for ease of use.

Key high-level functions include:

• tts: Performs Text-to-Speech synthesis.
• g2p: Performs Grapheme-to-Phoneme conversion.
• extract_fullcontext: Extracts full context information from text.
• synthesize: Synthesizes audio from text.

While the high-level API uses global instances for convenience, you should manually instantiate pyopenjtalk.openjtalk.OpenJTalk and pyopenjtalk.htsengine.HTSEngine if you require advanced control, such as:

• Using an external dictionary.
• Using a specific htsvoice.

If you have installed pyopenjtalk[marine], you can use the run_marine=True flag to estimate Japanese accent using a DNN-based method. This can be applied to both TTS and text processing:

import pyopenjtalk

# For TTS
x, sr = pyopenjtalk.tts("おめでとうございます", run_marine=True)

# For text processing
labels = pyopenjtalk.extract_fullcontext("こんにちは", run_marine=True)

import pyopenjtalk

x, sr = pyopenjtalk.tts("おめでとうございます", run_marine=True)
label = pyopenjtalk.extract_fullcontext("こんにちは", run_marine=True)

The latest release of pyopenjtalk is available on PyPI. You can install it using the standard pip command.

pip install pyopenjtalk

To use the run_marine option for estimating Japanese accent using the DNN-based method (based on marine), install the package with the marine extra:

pip install pyopenjtalk[marine]

You can add custom words to the dictionary to improve pronunciation and recognition.

1. Prepare a CSV file (e.g., user.csv) with the custom word entry following the MeCab dictionary format:

   ＧＮＵ,,,1,名詞,一般,*,*,*,*,ＧＮＵ,グヌー,グヌー,2/3,*

2. Compile the CSV into a dictionary file using mecab_dict_index():

   import pyopenjtalk
   pyopenjtalk.mecab_dict_index("user.csv", "user.dic")

3. Apply the dictionary using update_global_jtalk_with_user_dict():

   import pyopenjtalk
   pyopenjtalk.update_global_jtalk_with_user_dict("user.dic")

import pyopenjtalk

# 1. Compile
pyopenjtalk.mecab_dict_index("user.csv", "user.dic")

# 2. Apply
pyopenjtalk.update_global_jtalk_with_user_dict("user.dic")

Install the standard version of pyopenjtalk using pip:

pip install pyopenjtalk

Build Requirements

Because the package uses Cython to create Python bindings for open_jtalk and hts_engine_API, you must have the following installed on your system:

• C/C++ compilers
• cmake
• cython

Supported Platforms

• Linux
• Mac OSX
• Windows (MSVC)

If you encounter a ValueError: numpy.ndarray size changed, may indicate binary incompatibility (e.g., Expected 96 from C header, got 88 from PyObject), it is due to NumPy's ABI breaking changes.

To resolve this, ensure numpy is installed in your environment first, then install pyopenjtalk using the --no-build-isolation flag. This prevents pip from creating a separate build environment and forces it to use your pre-installed NumPy version during the build process.

# Install numpy first
pip install numpy

# Then install pyopenjtalk without build isolation
pip install pyopenjtalk --no-build-isolation

# Or install directly from the GitHub repository
pip install git+https://github.com/r9y9/pyopenjtalk --no-build-isolation

Convert text to its phonetic representation using pyopenjtalk.g2p(). You can optionally pass kana=True to get the output in Katakana.

import pyopenjtalk

# Default output (Latin characters)
print(pyopenjtalk.g2p("こんにちは")) # 'k o N n i ch i w a'

# Kana output
print(pyopenjtalk.g2p("こんにちは", kana=True)) # 'コンニチワ'

Use pyopenjtalk.tts() to synthesize speech from text. It returns a tuple containing the audio waveform (as a NumPy array) and the sampling rate.

import pyopenjtalk
import numpy as np
from scipy.io import wavfile

# Synthesize audio
x, sr = pyopenjtalk.tts("おめでとうございます")

# Save to a WAV file
wavfile.write("test.wav", sr, x.astype(np.int16))

If you only need the text processing capabilities (without speech synthesis), use pyopenjtalk.extract_fullcontext(). This returns a list of full-context labels used for linguistic analysis.

import pyopenjtalk

labels = pyopenjtalk.extract_fullcontext("こんにちは")
print(labels)