TTS: Matcha (Chinese)

Generate speech with the Matcha Chinese (baker) model. This model requires a vocoder and rule FSTs for Chinese text normalization. It supports both synchronous and asynchronous generation.

For model documentation, see Matcha Chinese.

Source files

Synchronous generation

// Copyright (c)  2025  Xiaomi Corporation
//
// Text-to-speech with the Matcha Chinese (baker) model.
// Requires a separate vocoder model (vocos-22khz-univ.onnx) and
// rule FSTs for phone, date, and number normalization.
//
// Usage:
//   node tts_matcha_zh.js
//
const sherpa_onnx = require('sherpa-onnx-node');

function createOfflineTts() {
  const config = {
    model: {
      matcha: {
        acousticModel: './matcha-icefall-zh-baker/model-steps-3.onnx',
        vocoder: './vocos-22khz-univ.onnx',
        lexicon: './matcha-icefall-zh-baker/lexicon.txt',
        tokens: './matcha-icefall-zh-baker/tokens.txt',
      },
      debug: true,
      numThreads: 1,
      provider: 'cpu',
    },
    maxNumSentences: 1,
    // Rule FSTs for Chinese text normalization (phone, date, number).
    ruleFsts:
        './matcha-icefall-zh-baker/phone.fst,./matcha-icefall-zh-baker/date.fst,./matcha-icefall-zh-baker/number.fst',
  };
  return new sherpa_onnx.OfflineTts(config);
}

const tts = createOfflineTts();

const text =
    '当夜幕降临，星光点点，伴随着微风拂面，我在静谧中感受着时光的流转，思念如涟漪荡漾，梦境如画卷展开，我与自然融为一体，沉静在这片宁静的美丽之中，感受着生命的奇迹与温柔. 某某银行的副行长和一些行政领导表示，他们去过长江和长白山; 经济不断增长。2024年12月31号，拨打110或者18920240511。123456块钱。';

const generationConfig = new sherpa_onnx.GenerationConfig({
  sid: 0,
  speed: 1.0,
  silenceScale: 0.2,
});

let start = Date.now();
const audio = tts.generate({text, generationConfig});
let stop = Date.now();
const elapsed_seconds = (stop - start) / 1000;
const duration = audio.samples.length / audio.sampleRate;
const real_time_factor = elapsed_seconds / duration;
console.log('Wave duration', duration.toFixed(3), 'seconds');
console.log('Elapsed', elapsed_seconds.toFixed(3), 'seconds');
console.log(
    `RTF = ${elapsed_seconds.toFixed(3)}/${duration.toFixed(3)} =`,
    real_time_factor.toFixed(3));

const filename = 'test-matcha-zh.wav';
sherpa_onnx.writeWave(
    filename, {samples: audio.samples, sampleRate: audio.sampleRate});

console.log(`Saved to ${filename}`);

Asynchronous generation

// Copyright (c)  2026  Xiaomi Corporation
//
// Asynchronous text-to-speech with the Matcha Chinese model.
//
// Usage:
//   node tts_matcha_zh_async.js
//
const sherpa_onnx = require('sherpa-onnx-node');

async function createOfflineTts() {
  const config = {
    model: {
      matcha: {
        acousticModel: './matcha-icefall-zh-baker/model-steps-3.onnx',
        vocoder: './vocos-22khz-univ.onnx',
        lexicon: './matcha-icefall-zh-baker/lexicon.txt',
        tokens: './matcha-icefall-zh-baker/tokens.txt',
      },
      debug: false,
      numThreads: 1,
      provider: 'cpu',
    },
    maxNumSentences: 1,
    ruleFsts:
        './matcha-icefall-zh-baker/phone.fst,./matcha-icefall-zh-baker/date.fst,./matcha-icefall-zh-baker/number.fst',
  };
  return await sherpa_onnx.OfflineTts.createAsync(config);
}

async function main() {
  const tts = await createOfflineTts();

  const text =
      '当夜幕降临，星光点点，伴随着微风拂面，我在静谧中感受着时光的流转，思念如涟漪荡漾，梦境如画卷展开，我与自然融为一体，沉静在这片宁静的美丽之中，感受着生命的奇迹与温柔. 某某银行的副行长和一些行政领导表示，他们去过长江和长白山; 经济不断增长。2024年12月31号，拨打110或者18920240511。123456块钱。';

  const generationConfig = new sherpa_onnx.GenerationConfig({
    sid: 0,
    speed: 1.0,
    silenceScale: 0.2,
  });

  const start = Date.now();
  const audio = await tts.generateAsync({
    text,
    enableExternalBuffer: true,
    generationConfig,
    onProgress: ({samples, progress}) => {
      process.stdout.write(
          `Progress: ${(progress * 100).toFixed(1)}%, ` +
          `Samples: ${samples.length}\r`);
      return 1;
    },
  });

  console.log('');
  const stop = Date.now();
  const elapsed_seconds = (stop - start) / 1000;
  const duration = audio.samples.length / audio.sampleRate;
  const real_time_factor = elapsed_seconds / duration;
  console.log('Wave duration', duration.toFixed(3), 'seconds');
  console.log('Elapsed', elapsed_seconds.toFixed(3), 'seconds');
  console.log(
      `RTF = ${elapsed_seconds.toFixed(3)}/${duration.toFixed(3)} =`,
      real_time_factor.toFixed(3));

  const filename = 'test-matcha-zh-async.wav';
  sherpa_onnx.writeWave(
      filename, {samples: audio.samples, sampleRate: audio.sampleRate});
  console.log(`Saved to ${filename}`);
}

main().catch((err) => {
  console.error('Error:', err);
});

How to run

Install the package:
```
npm install sherpa-onnx-node
```

Download the model, vocoder, and rule FSTs:

curl -SL -O https://github.com/k2-fsa/sherpa-onnx/releases/download/tts-models/matcha-icefall-zh-baker.tar.bz2
tar xvf matcha-icefall-zh-baker.tar.bz2
rm matcha-icefall-zh-baker.tar.bz2

curl -SL -O https://github.com/k2-fsa/sherpa-onnx/releases/download/vocoder-models/vocos-22khz-univ.onnx

Set the library path and run:

# macOS
export DYLD_LIBRARY_PATH=$(npm root)/sherpa-onnx-node/lib:$DYLD_LIBRARY_PATH

# Linux
export LD_LIBRARY_PATH=$(npm root)/sherpa-onnx-node/lib:$LD_LIBRARY_PATH

# Choose one:
node tts_matcha_zh.js
node tts_matcha_zh_async.js

Notes

In addition to the matcha config fields, the Chinese model uses: - lexicon: Maps Chinese characters to phonemes. - ruleFsts: Comma-separated FST files for phone, date, and number

normalization (e.g., phone.fst,date.fst,number.fst).
The text contains dates, phone numbers, and monetary amounts that are normalized by the rule FSTs before synthesis.
The sync API uses new sherpa_onnx.OfflineTts(config) and tts.generate({text, generationConfig}).
The async API uses OfflineTts.createAsync() and tts.generateAsync() with an onProgress callback.
For English, see TTS: Matcha (English).