녹음에서
음성으로.

pipertts로 Node.js 프로젝트에 Piper 연동하기

pipertts는 Piper를 Node.js에서 쓸 수 있게 하며 파일 출력과 메모리 내 오디오를 지원해요. 권장 방식은 PiperNativeTTS예요. 프로세스 안에서 동작하는 100% 네이티브 추론(ONNX + 컴파일된 espeak 브리지)으로 Python이 필요 없고 래퍼보다 약 10배 빨라요. 음성(.onnx + .onnx.json)은 별도 파일로 유지돼요.

1. 01

   종속 항목 설치

   문서에서는 Node.js 18 이상과 TypeScript 5 이상을 요구해요. 네이티브 방식은 추가로 필요 없이 일반 npm install이면 돼요. 기존 래퍼 방식(python3 -m piper 경유의 PiperTTS)은 Python과 Piper 모듈이 별도로 필요해요. 카탈로그 식별자를 지정하면 모델과 설정을 models/에 다운로드할 수 있어요.

   npm install pipertts
   # mode wrapper uniquement : python3 -m pip install piper-tts

2. 02

   카탈로그 음성으로 시작하기

   import { PiperNativeTTS, resolveModelPathFromOptions } from "pipertts";
   import * as fs from "node:fs";
   
   const modelPath = await resolveModelPathFromOptions({
     model: "en_US-lessac-medium",
     modelsDir: "./models",
   });
   const tts = await PiperNativeTTS.load({ modelPath });
   
   const { audio } = await tts.synthesize("Hello from Piper.");
   fs.writeFileSync("./hello.wav", audio);

3. 03

   로컬 모델 사용하기

   직접 다운로드한 음성은 ONNX 파일 경로를 전달하세요. 대응하는 .onnx.json 파일은 같은 위치에 두세요. 설정 위치가 다르면 configPath를 지정하세요.

   import { PiperNativeTTS } from "pipertts";
   
   const tts = await PiperNativeTTS.load({
     modelPath: "./models/my-voice.onnx",
   });
   const { audio, sampleRate } = await tts.synthesize("Hello.", { speakerId: 0 });

4. 04

   API와 출력 형식

   synthesize()는 audio(Buffer), sampleRate, text를 반환해요. outputFile은 디스크에도 써요. 옵션: speakerId(다중 음성·다중 스타일), lengthScale(1보다 크면 느려지고 1보다 작으면 빨라짐), noiseScale, noiseWScale, sentenceSilence, normalizeAudio, volume, outputFormat(wav, raw, mp3, ogg, opus). mp3와 opus는 순수 JS 대체가 있으며 ogg는 FFmpeg이 필요해요. phonemize()와 synthesizeChunks()로 문장 단위의 저수준 접근이 가능해요.

5. 05

   기존 래퍼(PiperTTS)

   PiperTTS는 python3 -m piper를 실행하며 합성마다 프로세스 1개를 써요. 약 10배 느리며 네이티브 엔진이 동작하지 않는 환경용이에요. Python과 Piper 모듈이 필요해요.

   import { PiperTTS } from "pipertts";
   
   const tts = await PiperTTS.create({
     modelPath: "./models/en_US-lessac-medium.onnx",
   });
   await tts.synthesizeToFile("Hello from the legacy wrapper.", "./hello.wav");

   npm의 pipertts 페이지 ↗pipertts GitHub 저장소 ↗pipertts 문서 및 예제 ↗