TTS (텍스트 음성 변환) 스킬은(는) 무엇을 하나요?
이 스킬은 z-ai-web-dev-sdk 패키지를 사용하여 텍스트 음성 변환(TTS) 기능을 구현하는 방법을 안내합니다. 텍스트를 자연스러운 음성 오디오로 변환할 수 있습니다.
스킬 경로
스킬 위치: {project_path}/skills/TTS
이 스킬은 프로젝트의 위 경로에 있습니다.
참조 스크립트: 빠른 테스트 및 참조를 위해 {스킬 위치}/scripts/ 디렉토리에 예제 테스트 스크립트가 있습니다. 작동 예제는 {스킬 위치}/scripts/tts.ts를 참조하세요.
개요
텍스트 음성 변환을 사용하면 텍스트 입력에서 음성 오디오를 생성하는 애플리케이션을 구축할 수 있으며, 다양한 음성, 속도 및 출력 형식을 지원하여 다양한 사용 사례에 대응할 수 있습니다.
중요: z-ai-web-dev-sdk는 백엔드 코드에서만 사용해야 합니다. 클라이언트 측 코드에서는 절대 사용하지 마십시오.
API 제한 사항 및 제약 조건
TTS 기능을 구현하기 전에 다음의 중요한 제한 사항을 알아두십시오.
입력 텍스트 제약 조건
- 최대 길이: 요청당 1024자
- 이 제한을 초과하는 텍스트는 더 작은 청크로 분할해야 합니다.
오디오 매개변수
- 속도 범위: 0.5 ~ 2.0
- 0.5 = 절반 속도 (느리게)
- 1.0 = 일반 속도 (기본값)
- 2.0 = 두 배 속도 (빠르게)
- 볼륨 범위: 0보다 크고 10까지
- 기본값: 1.0
- 값은 0(제외)보다 크고 10(포함)까지여야 합니다.
형식 및 스트리밍
- 스트리밍 제한:
stream: true가 활성화되면pcm형식만 지원됩니다. - 비스트리밍:
wav,pcm,mp3형식을 지원합니다. - 샘플 레이트: 24000 Hz (권장)
긴 텍스트에 대한 모범 사례
function splitTextIntoChunks(text, maxLength = 1000) {
const chunks = [];
const sentences = text.match(/[^.!?]+[.!?]+/g) || [text];
let currentChunk = '';
for (const sentence of sentences) {
if ((currentChunk + sentence).length <= maxLength) {
currentChunk += sentence;
} else {
if (currentChunk) chunks.push(currentChunk.trim());
currentChunk = sentence;
}
}
if (currentChunk) chunks.push(currentChunk.trim());
return chunks;
}
사전 요구 사항
z-ai-web-dev-sdk 패키지는 이미 설치되어 있습니다. 아래 예제와 같이 가져오십시오.
CLI 사용법 (간단한 작업용)
간단한 텍스트 음성 변환의 경우 코드를 작성하는 대신 z-ai CLI를 사용할 수 있습니다. 빠른 오디오 생성, 음성 테스트 또는 간단한 자동화에 적합합니다.
기본 TTS
# 텍스트를 음성으로 변환 (기본 WAV 형식)
z-ai tts --input "Hello, world" --output ./hello.wav
# 짧은 옵션 사용
z-ai tts -i "Hello, world" -o ./hello.wav
다양한 음성 및 속도
# 특정 음성 사용
z-ai tts -i "Welcome to our service" -o ./welcome.wav --voice tongtong
# 음성 속도 조절 (0.5-2.0)
z-ai tts -i "This is faster speech" -o ./fast.wav --speed 1.5
# 느린 음성
z-ai tts -i "This is slower speech" -o ./slow.wav --speed 0.8
다양한 출력 형식
# MP3 형식
z-ai tts -i "Hello World" -o ./hello.mp3 --format mp3
# WAV 형식 (기본값)
z-ai tts -i "Hello World" -o ./hello.wav --format wav
# PCM 형식
z-ai tts -i "Hello World" -o ./hello.pcm --format pcm
스트리밍 출력
# 오디오 스트리밍 생성
z-ai tts -i "This is a longer text that will be streamed" -o ./stream.wav --stream
CLI 매개변수
--input, -i <text>: 필수 - 음성으로 변환할 텍스트 (최대 1024자)--output, -o <path>: 필수 - 출력 오디오 파일 경로--voice, -v <voice>: 선택 사항 - 음성 유형 (기본값: tongtong)--speed, -s <number>: 선택 사항 - 음성 속도, 0.5-2.0 (기본값: 1.0)--format, -f <format>: 선택 사항 - 출력 형식: wav, mp3, pcm (기본값: wav)--stream: 선택 사항 - 스트리밍 출력 활성화 (pcm 형식만 지원)
CLI 사용 시기와 SDK 사용 시기
CLI 사용:
- 빠른 텍스트 음성 변환
- 다양한 음성 및 속도 테스트
- 간단한 배치 오디오 생성
- 명령줄 자동화 스크립트
SDK 사용:
- 애플리케이션에서 동적 오디오 생성
- 웹 서비스와의 통합
- 사용자 지정 오디오 처리 파이프라인
- 복잡한 요구 사항이 있는 프로덕션 애플리케이션
기본 TTS 구현
간단한 텍스트 음성 변환
import ZAI from 'z-ai-web-dev-sdk';
import fs from 'fs';
async function textToSpeech(text, outputPath) {
const zai = await ZAI.create();
const response = await zai.audio.tts.create({
input: text,
voice: 'tongtong',
speed: 1.0,
response_format: 'wav',
stream: false
});
// Response 객체에서 배열 버퍼 가져오기
const arrayBuffer = await response.arrayBuffer();
const buffer = Buffer.from(new Uint8Array(arrayBuffer));
fs.writeFileSync(outputPath, buffer);
console.log(`Audio saved to ${outputPath}`);
return outputPath;
}
// 사용법
await textToSpeech('Hello, world!', './output.wav');
여러 음성 옵션
import ZAI from 'z-ai-web-dev-sdk';
import fs from 'fs';
async function generateWithVoice(text, voice, outputPath) {
const zai = await ZAI.create();
const response = await zai.audio.tts.create({
input: text,
voice: voice, // 사용 가능한 음성: tongtong, chuichui, xiaochen, jam, kazi, douji, luodo
speed: 1.0,
response_format: 'wav',
stream: false
});
// Response 객체에서 배열 버퍼 가져오기
const arrayBuffer = await response.arrayBuffer();
const buffer = Buffer.from(new Uint8Array(arrayBuffer));
fs.writeFileSync(outputPath, buffer);
return outputPath;
}
// 사용법
await generateWithVoice('Welcome to our service', 'tongtong', './welcome.wav');
속도 조절
import ZAI from 'z-ai-web-dev-sdk';
import fs from 'fs';
async function generateWithSpeed(text, speed, outputPath) {
const zai = await ZAI.create();
// 속도 범위: 0.5 ~ 2.0 (API 제약 조건)
// 0.5 = 절반 속도 (느리게)
// 1.0 = 일반 속도 (기본값)
// 2.0 = 두 배 속도 (빠르게)
// 이 범위를 벗어난 값은 API 오류를 발생시킵니다.
const response = await zai.audio.tts.create({
input: text,
voice: 'tongtong',
speed: speed,
response_format: 'wav',
stream: false
});
// Response 객체에서 배열 버퍼 가져오기
const arrayBuffer = await response.arrayBuffer();
const buffer = Buffer.from(new Uint8Array(arrayBuffer));
fs.writeFileSync(outputPath, buffer);
return outputPath;
}
// 사용법 - 느린 내레이션
await generateWithSpeed('This is an important announcement', 0.8, './slow.wav');
// 사용법 - 빠른 내레이션
await generateWithSpeed('Quick update', 1.3, './fast.wav');
볼륨 조절
import ZAI from 'z-ai-web-dev-sdk';
import fs from 'fs';
async function generateWithVolume(text, volume, outputPath) {
const zai = await ZAI.create();
// 볼륨 범위: 0보다 크고 10까지 (API 제약 조건)
// 값은 > 0 (제외) 및 <= 10 (포함)이어야 합니다.
// 기본값: 1.0 (일반 볼륨)
const response = await zai.audio.tts.create({
input: text,
voice: 'tongtong',
speed: 1.0,
volume: volume, // 선택적 매개변수
response_format: 'wav',
stream: false
});
// Response 객체에서 배열 버퍼 가져오기
const arrayBuffer = await response.arrayBuffer();
const buffer = Buffer.from(new Uint8Array(arrayBuffer));
fs.writeFileSync(outputPath, buffer);
return outputPath;
}
// 사용법 - 더 큰 오디오
await generateWithVolume('This is an announcement', 5.0, './loud.wav');
// 사용법 - 더 작은 오디오
await generateWithVolume('Whispered message', 0.5, './quiet.wav');
고급 사용 사례
배치 처리
import ZAI from 'z-ai-web-dev-sdk';
import fs from 'fs';
import path from 'path';
async function batchTextToSpeech(textArray, outputDir) {
const zai = await ZAI.create();
const results = [];
// 출력 디렉토리 확인
if (!fs.existsSync(outputDir)) {
fs.mkdirSync(outputDir, { recursive: true });
}
for (let i = 0; i < textArray.length; i++) {
try {
const text = textArray[i];
const outputPath = path.join(outputDir, `audio_${i + 1}.wav`);
const response = await zai.audio.tts.create({
input: text,
voice: 'tongtong',
speed: 1.0,
response_format: 'wav',
stream: false
});
// Response 객체에서 배열 버퍼 가져오기
const arrayBuffer = await response.arrayBuffer();
const buffer = Buffer.from(new Uint8Array(arrayBuffer));
fs.writeFileSync(outputPath, buffer);
results.push({
success: true,
text,
path: outputPath
});
} catch (error) {
results.push({
success: false,
text: textArray[i],
error: error.message
});
}
}
return results;
}
// 사용법
const texts = [
'Welcome to chapter one',
'Welcome to chapter two',
'Welcome to chapter three'
];
const results = await batchTextToSpeech(texts, './audio-output');
console.log('Generated:', results.length, 'audio files');
동적 콘텐츠 생성
import ZAI from 'z-ai-web-dev-sdk';
import fs from 'fs';
class TTSGenerator {
constructor() {
this.zai = null;
}
async initialize() {
this.zai = await ZAI.create();
}
async generateAudio(text, options = {}) {
const {
voice = 'tongtong',
speed = 1.0,
format = 'wav'
} = options;
const response = await this.zai.audio.tts.create({
input: text,
voice: voice,
speed: speed,
response_format: format,
stream: false
});
// Response 객체에서 배열 버퍼 가져오기
const arrayBuffer = await response.arrayBuffer();
return Buffer.from(new Uint8Array(arrayBuffer));
}
async saveAudio(text, outputPath, options = {}) {
const buffer = await this.generateAudio(text, options);
if (buffer) {
fs.writeFileSync(outputPath, buffer);
return outputPath;
}
return null;
}
}
// 사용법
const generator = new TTSGenerator();
await generator.initialize();
await generator.saveAudio(
'Hello, this is a test',
'./output.wav',
{ speed: 1.2 }
);
Next.js API 라우트 예제
import { NextRequest, NextResponse } from 'next/server';
export async function POST(req: NextRequest) {
try {
const { text, voice = 'tongtong', speed = 1.0 } = await req.json();
// ZAI SDK 가져오기
const ZAI = (await import('z-ai-web-dev-sdk')).default;
// SDK 인스턴스 생성
const zai = await ZAI.create();
// TTS 오디오 생성
const response = await zai.audio.tts.create({
input: text.trim(),
voice: voice,
speed: speed,
response_format: 'wav',
stream: false,
});
// Response 객체에서 배열 버퍼 가져오기
const arrayBuffer = await response.arrayBuffer();
const buffer = Buffer.from(new Uint8Array(arrayBuffer));
// 오디오를 응답으로 반환
return new NextResponse(buffer, {
status: 200,
headers: {
'Content-Type': 'audio/wav',
'Content-Length': buffer.length.toString(),
'Cache-Control': 'no-cache',
},
});
} catch (error) {
console.error('TTS API Error:', error);
return NextResponse.json(
{
error: error instanceof Error ? error.message : '음성 생성에 실패했습니다. 잠시 후 다시 시도해주세요.',
},
{ status: 500 }
);
}
}
모범 사례
1. 텍스트 준비
function prepareTextForTTS(text) {
// 과도한 공백 제거
text = text.replace(/\s+/g, ' ').trim();
// 발음을 위해 일반적인 약어 확장
const abbreviations = {
'Dr.': 'Doctor',
'Mr.': 'Mister',
'Mrs.': 'Misses',
'etc.': 'et cetera'
};
for (const [abbr, full] of Object.entries(abbreviations)) {
text = text.replace(new RegExp(abbr, 'g'), full);
}
return text;
}
2. 오류 처리
import ZAI from 'z-ai-web-dev-sdk';
import fs from 'fs';
async function safeTTS(text, outputPath) {
try {
// 입력 유효성 검사
if (!text || text.trim().length === 0) {
throw new Error('텍스트 입력이 비어 있을 수 없습니다.');
}
if (text.length > 1024) {
throw new Error('텍스트 입력이 최대 길이 1024자를 초과했습니다.');
}
const zai = await ZAI.create();
const response = await zai.audio.tts.create({
input: text,
voice: 'tongtong',
speed: 1.0,
response_format: 'wav',
stream: false
});
// Response 객체에서 배열 버퍼 가져오기
const arrayBuffer = await response.arrayBuffer();
const buffer = Buffer.from(new Uint8Array(arrayBuffer));
fs.writeFileSync(outputPath, buffer);
return {
success: true,
path: outputPath,
size: buffer.length
};
} catch (error) {
console.error('TTS Error:', error);
return {
success: false,
error: error.message
};
}
}
3. SDK 인스턴스 재사용
import ZAI from 'z-ai-web-dev-sdk';
// 싱글톤 인스턴스 생성
let zaiInstance = null;
async function getZAIInstance() {
if (!zaiInstance) {
zaiInstance = await ZAI.create();
}
return zaiInstance;
}
// 사용법
const zai = await getZAIInstance();
const response = await zai.audio.tts.create({ ... });
일반적인 사용 사례
- 오디오북 및 팟캐스트: 작성된 콘텐츠를 오디오 형식으로 변환
- 전자 학습: 교육 콘텐츠에 대한 내레이션 생성
- 접근성: 텍스트 콘텐츠의 오디오 버전 제공
- 음성 비서: 동적 응답 생성
- 공지사항: 자동화된 오디오 알림 생성
- IVR 시스템: 전화 시스템 프롬프트 생성
- 콘텐츠 현지화: 다양한 언어로 오디오 생성
통합 예제
Express.js API 엔드포인트
import express from 'express';
import ZAI from 'z-ai-web-dev-sdk';
import fs from 'fs';
import path from 'path';
const app = express();
app.use(express.json());
let zaiInstance;
const outputDir = './audio-output';
async function initZAI() {
zaiInstance = await ZAI.create();
if (!fs.existsSync(outputDir)) {
fs.mkdirSync(outputDir, { recursive: true });
}
}
initZAI();
app.post('/tts', async (req, res) => {
try {
const { text, voice = 'tongtong', speed = 1.0 } = req.body;
if (!text || text.length > 1024) {
return res.status(400).json({
error: '텍스트는 필수이며 1024자를 초과할 수 없습니다.'
});
}
const response = await zaiInstance.audio.tts.create({
input: text,
voice,
speed,
response_format: 'wav',
stream: false
});
const arrayBuffer = await response.arrayBuffer();
const buffer = Buffer.from(new Uint8Array(arrayBuffer));
const fileName = `tts-${Date.now()}.wav`;
const filePath = path.join(outputDir, fileName);
fs.writeFileSync(filePath, buffer);
res.json({
success: true,
url: `/audio/${fileName}`,
filePath
});
} catch (error) {
console.error('TTS Error:', error);
res.status(500).json({
success: false,
error: '음성 생성 실패'
});
}
});
app.listen(3000, () => {
console.log('TTS API 서버가 포트 3000에서 실행 중입니다.');
});
문제 해결
일반적인 문제
-
API 오류 "요청이 너무 깁니다"
- 텍스트가 1024자를 초과하는지 확인하고 필요한 경우 분할하세요.
-
오디오 품질 저하
- 더 나은 결과를 위해 입력 텍스트를 준비하세요 (특수 문자 제거, 약어 확장).
-
파일 크기가 너무 큼
- 스토리지 요구 사항을 줄이려면 mp3 형식을 사용하세요.
-
스트리밍이 작동하지 않음
- stream: true를 사용할 때는 pcm 형식만 지원됩니다.
보안 고려 사항
- API 키 관리: API 키를 안전하게 보관하고 클라이언트 측 코드에 노출하지 마십시오.
- 속도 제한: 과도한 사용을 방지하기 위해 애플리케이션 수준에서 속도 제한을 구현하십시오.
- 입력 유효성 검사: 텍스트 입력의 길이와 내용을 항상 검증하십시오.
- 보안 헤더: 프로덕션에서 오디오 파일을 제공할 때 적절한 CORS 헤더를 설정하십시오.
결론
이 스킬은 z-ai-web-dev-sdk를 사용하여 TTS 기능을 구현하기 위한 포괄적인 가이드를 제공합니다. 기본 텍스트-음성 변환에서 배치 처리 및 동적 콘텐츠 생성과 같은 고급 사용 사례까지 모든 것을 다룹니다. 제공된 예제와 모범 사례를 따라 다양한 애플리케이션 요구 사항에 맞는 강력한 TTS 솔루션을 구축할 수 있습니다.