react-native-misaki

react-native-misaki

React Native bindings for MisakiSwift, a Swift G2P (grapheme-to-phoneme) library for converting English text to IPA phonemes. Designed for text-to-speech applications such as Kokoro TTS.

Requirements

Requirement	Details
Platform	iOS only (physical device required)
iOS Version	18.0+
React Native	0.75+

Note: This library uses a static fork of MisakiSwift which eliminates the need for use_frameworks! :linkage => :dynamic in your Podfile.

Simulator Limitation: This library uses MLX under the hood, which does not run on iOS Simulator. Testing requires a physical device.

Installation

npm install react-native-misaki react-native-nitro-modules

react-native-nitro-modules is required as this library uses Nitro Modules for native bindings.

iOS Setup

1. Set minimum deployment target to iOS 18.0

In your ios/Podfile, add or update:

platform :ios, '18.0'

2. Install pods

cd ios && pod install

No additional framework configuration is required.

Expo Setup

This library requires a development build and is not compatible with Expo Go.

1. Install dependencies

npx expo install react-native-misaki react-native-nitro-modules expo-build-properties

2. Configure app.json

Add the config plugin to set iOS 18.0 deployment target:

{
  "expo": {
    "plugins": [
      [
        "expo-build-properties",
        {
          "ios": {
            "deploymentTarget": "18.0"
          }
        }
      ]
    ]
  }
}

3. Generate native project and build

# Generate the ios folder
npx expo prebuild --platform ios --clean

# Build and run on physical device
npx expo run:ios --device

The --device flag is required as the iOS Simulator is not supported due to MLX limitations.

Usage

import { EnglishG2P } from 'react-native-misaki';

// American English (default)
const g2p = new EnglishG2P();
const result = g2p.phonemize('Hello world!');

console.log(result.phonemes);
// Output: "həlˈO wˈɜɹld!"

console.log(result.tokens);
// Output: [
//   { text: "Hello", phonemes: "həlˈO", whitespace: " ", start: undefined, end: undefined },
//   { text: "world", phonemes: "wˈɜɹld", whitespace: "", start: undefined, end: undefined },
//   { text: "!", phonemes: "!", whitespace: "", start: undefined, end: undefined }
// ]

// British English
const g2pBritish = new EnglishG2P({ british: true });
const resultBritish = g2pBritish.phonemize('Hello world!');

// Async version (runs on background thread)
const resultAsync = await g2p.phonemizeAsync('Hello world!');

API

EnglishG2P

Constructor

new EnglishG2P(options?: EnglishG2POptions)

Option	Type	Default	Description
british	boolean	false	Use British English pronunciation

Methods

Method	Returns	Description
phonemize(text: string)	PhonemizeResult	Convert text to IPA phonemes synchronously
phonemizeAsync(text: string)	Promise<PhonemizeResult>	Convert text to IPA phonemes asynchronously

PhonemizeResult

The result object returned by phonemize() and phonemizeAsync():

Property	Type	Description
phonemes	string	The complete IPA phoneme string for the input
tokens	Token[]	Array of tokens with individual phoneme mappings

Token

Each token represents a word or punctuation from the input text:

Property	Type	Description
text	string	The original text of the token
phonemes	string | undefined	The IPA phonemes for this token
whitespace	string	Whitespace following this token in original text
start	number | undefined	Start timestamp for audio alignment (seconds)
end	number | undefined	End timestamp for audio alignment (seconds)

Limitations

Constraint	Reason
iOS 18.0+ only	MisakiSwift requires iOS 18 APIs
Physical device only	MLX framework does not run on iOS Simulator
No Android support	MisakiSwift is a Swift-only library with no Android equivalent

Troubleshooting

App crashes on simulator

This library does not support the iOS Simulator. MLX, which powers MisakiSwift, requires Apple Silicon and does not run in the simulated environment. A physical iOS device is required for testing.

Build fails with deployment target error

Bare React Native:

Ensure your Podfile specifies iOS 18.0:

platform :ios, '18.0'

Then run pod install again.

Expo:

Ensure expo-build-properties is configured in your app.json:

{
  "expo": {
    "plugins": [
      [
        "expo-build-properties",
        {
          "ios": {
            "deploymentTarget": "18.0"
          }
        }
      ]
    ]
  }
}

Then regenerate the native project:

npx expo prebuild --platform ios --clean

Expo Go is not supported

This library includes native code and requires a development build. Expo Go cannot load native modules. Use:

npx expo run:ios --device

Code signing error

If you encounter code signing issues during development:

# Bare React Native
npx react-native run-ios -- CODE_SIGNING_ALLOWED=NO

# Expo
npx expo run:ios --device -- CODE_SIGNING_ALLOWED=NO

See IMPLEMENTATION.md for additional details.

Contributing

• Development workflow
• Sending a pull request
• Code of conduct

License

MIT

Made with create-react-native-library