Edge TTS for Node.js

Common errors

• Error: Network request failed

  cause The module could not connect to the Microsoft Edge TTS service endpoint due to network issues, firewall restrictions, an incorrect proxy configuration, or a timeout.
  fix Verify your internet connection, check firewall settings, ensure any specified `proxy` option is correct and reachable, and consider increasing the `timeout` option for slower networks.

• Error: Invalid voice or language parameter

  cause The `voice` or `lang` specified in the configuration is not recognized or supported by the Microsoft Edge TTS service, or it uses an incorrect format.
  fix Refer to Microsoft's documentation for supported voices and languages (linked in the README) and ensure the exact string is used. Test with common, well-known voices first (e.g., 'en-US-AriaNeural').

• ENOENT: no such file or directory, open './output.mp3'

  cause The directory specified in the `filepath` for the output audio does not exist, and the library does not automatically create it.
  fix Before calling `ttsPromise`, ensure the directory for the output file exists. Use `fs.mkdirSync(path.dirname(audioFilePath), { recursive: true });` if the directory might not exist.

Warnings

• gotcha Some advanced speech configuration options (pitch, rate, volume) listed in Microsoft's official documentation might not be fully supported by the underlying Edge online TTS service this library uses, leading to unexpected behavior or ignored settings.
  Fix: Test specific pitch/rate/volume settings thoroughly. For critical applications requiring precise control, consider official Azure Cognitive Services Speech SDKs.
• gotcha The library relies on an unofficial interface to Microsoft Edge's online TTS service. This means its functionality can be broken by undocumented changes to Edge's service or internal APIs, which are outside the control of the library maintainers.
  Fix: Regularly test the library's functionality, especially after major Edge browser updates or if speech generation starts failing unexpectedly. Consider contributing to the project or having a fallback TTS solution for mission-critical use cases.
• gotcha Saving subtitles generates a JSON file with the same base name as the audio file in the specified output directory. Ensure your application handles both files appropriately, especially for cleanup or relocation.
  Fix: Always expect both an audio and a `.json` subtitle file if `saveSubtitles` is enabled. Implement logic to manage or delete both files together.

Install

• npm install node-edge-tts npm
• yarn add node-edge-tts yarn
• pnpm add node-edge-tts pnpm

Imports

• EdgeTTS
  wrong:

  const EdgeTTS = require('node-edge-tts')

  correct:

  import { EdgeTTS } from 'node-edge-tts'

  Use named import for ESM. For CommonJS, use `const { EdgeTTS } = require('node-edge-tts')`.
• EdgeTTS
  wrong:

  import EdgeTTS from 'node-edge-tts'

  correct:

  const { EdgeTTS } = require('node-edge-tts')

  This is the correct CommonJS `require` syntax. The package does not provide a default export.
• EdgeTTSOptions

  import type { EdgeTTSOptions } from 'node-edge-tts'

  Import the type definition for configuration options when using TypeScript.

Quickstart

Demonstrates how to instantiate EdgeTTS, configure it with a voice and output format, and generate an audio file with corresponding subtitles.

import { EdgeTTS } from 'node-edge-tts';
import * as path from 'path';
import * as fs from 'fs';

async function generateSpeech() {
  const outputDir = './audio_output';
  if (!fs.existsSync(outputDir)) {
    fs.mkdirSync(outputDir, { recursive: true });
  }
  const audioFilePath = path.join(outputDir, 'hello_world.mp3');

  const tts = new EdgeTTS({
    voice: 'en-US-AriaNeural',
    lang: 'en-US',
    outputFormat: 'audio-24khz-96kbitrate-mono-mp3',
    saveSubtitles: true,
    // proxy: 'http://localhost:7890', // Uncomment and configure if behind a proxy
    // timeout: 15000 // Increase timeout if network is slow
  });

  try {
    console.log(`Generating speech to ${audioFilePath}...`);
    await tts.ttsPromise('Hello world, this is a test from node-edge-tts!', audioFilePath);
    console.log('Speech generated successfully!');
    console.log(`Subtitles saved to ${audioFilePath.replace('.mp3', '.json')}`);
  } catch (error) {
    console.error('Failed to generate speech:', error);
  }
}

generateSpeech();