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