Communitygithub.com

TTS (텍스트 음성 변환) 스킬

z-ai-web-dev-sdk를 사용하여 텍스트 음성 변환(TTS) 기능을 구현합니다. 사용자가 텍스트를 자연스러운 음성으로 변환하거나, 오디오 콘텐츠를 만들고, 음성 기반 애플리케이션을 구축하거나, 음성 오디오 파일을 생성해야 할 때 이 스킬을 사용하세요. 여러 음성, 조절 가능한 속도 및 다양한 오디오 형식을 지원합니다.

TTS (텍스트 음성 변환) 스킬란 무엇인가요?

이 스킬은 z-ai-web-dev-sdk 패키지를 사용하여 텍스트 음성 변환(TTS) 기능을 구현하는 방법을 설명합니다. 텍스트를 자연스러운 음성 오디오로 변환하여 오디오북, 전자 학습, 음성 비서, IVR 시스템 등 다양한 애플리케이션에 활용할 수 있습니다. 지원하는 플랫폼은 Node.js 기반의 백엔드 환경이며, CLI와 SDK 두 가지 방식으로 사용할 수 있습니다. CLI는 빠른 테스트나 단순 자동화에 적합하고, SDK는 동적 오디오 생성, 웹 서비스 통합, 복잡한 파이프라인 구축에 유용합니다. API의 주요 제약 사항으로는 요청당 최대 1024자, 속도 0.5~2.0, 볼륨 0~10, 스트리밍 시 PCM 형식만 지원 등이 있습니다. 스킬 문서에는 기본 TTS, 다양한 음성 옵션, 속도 및 볼륨 조절, 배치 처리, 동적 콘텐츠 생성, Next.js 및 Express.js API 라우트 예제, 에러 처리, 텍스트 전처리, SDK 인스턴스 재사용 등 모범 사례가 포함되어 있습니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ARYAN2302/liquid_researcher/tree/HEAD/skills/TTS

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

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({ ... });

일반적인 사용 사례

  1. 오디오북 및 팟캐스트: 작성된 콘텐츠를 오디오 형식으로 변환
  2. 전자 학습: 교육 콘텐츠에 대한 내레이션 생성
  3. 접근성: 텍스트 콘텐츠의 오디오 버전 제공
  4. 음성 비서: 동적 응답 생성
  5. 공지사항: 자동화된 오디오 알림 생성
  6. IVR 시스템: 전화 시스템 프롬프트 생성
  7. 콘텐츠 현지화: 다양한 언어로 오디오 생성

통합 예제

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에서 실행 중입니다.');
});

문제 해결

일반적인 문제

  1. API 오류 "요청이 너무 깁니다"

    • 텍스트가 1024자를 초과하는지 확인하고 필요한 경우 분할하세요.
  2. 오디오 품질 저하

    • 더 나은 결과를 위해 입력 텍스트를 준비하세요 (특수 문자 제거, 약어 확장).
  3. 파일 크기가 너무 큼

    • 스토리지 요구 사항을 줄이려면 mp3 형식을 사용하세요.
  4. 스트리밍이 작동하지 않음

    • stream: true를 사용할 때는 pcm 형식만 지원됩니다.

보안 고려 사항

  1. API 키 관리: API 키를 안전하게 보관하고 클라이언트 측 코드에 노출하지 마십시오.
  2. 속도 제한: 과도한 사용을 방지하기 위해 애플리케이션 수준에서 속도 제한을 구현하십시오.
  3. 입력 유효성 검사: 텍스트 입력의 길이와 내용을 항상 검증하십시오.
  4. 보안 헤더: 프로덕션에서 오디오 파일을 제공할 때 적절한 CORS 헤더를 설정하십시오.

결론

이 스킬은 z-ai-web-dev-sdk를 사용하여 TTS 기능을 구현하기 위한 포괄적인 가이드를 제공합니다. 기본 텍스트-음성 변환에서 배치 처리 및 동적 콘텐츠 생성과 같은 고급 사용 사례까지 모든 것을 다룹니다. 제공된 예제와 모범 사례를 따라 다양한 애플리케이션 요구 사항에 맞는 강력한 TTS 솔루션을 구축할 수 있습니다.

Individual skills in this repo

This repo contains 8 individual skills — each has its own dedicated page.

ARYAN2302/liquid_researcher

Generate a single-file Chinese atelier-style portfolio website (horizontal-row list + hover-reveal thumb interaction, art lishu typography "Alimama DaoLiTi" via CDN, light/dark theme, hash-routed detail pages). Takes a natural-language description of the studio (name, director, discipline, works) and outputs ONE working .html file. Runs in BOTH Claude Code (writes to ~/Desktop) and GLM / online chat (outputs HTML inline). Trigger phrases include "做个中式工作室作品集", "做个隶书作品集", "lishu-portfolio-gen ...", "做个白屋风格的作品集", or when user drags this skill folder into chat asking for an atelier-style site.

ARYAN2302/liquid_researcher

Chinese-market SaaS pricing page template — soft sky-blue glass-morphism, 4-tier card grid with one elevated "recommended" tier, monthly/annual toggle, FAQ accordion, ¥ pricing with Inter numerals, careful CJK linebreaking, ICP filing footer.

ARYAN2302/liquid_researcher

Premium calm-tech SaaS landing template — bilingual (CN/EN) literary voice over a dark forest-night palette with warm gold accent, Cormorant + Noto Serif SC, Three.js procedural forest hero, station-based scrolling narrative, custom cursor. Built for ambient-AI / creative-tool / philosophical SaaS, not loud commercial launch.

ARYAN2302/liquid_researcher

Pro-camera HUD mockup template — full-viewport black canvas wrapping a real video with monospace overlays (corner brackets, top status bar, side AF/exposure columns, bottom timecode + aperture/shutter/ISO row, vertical 8-filter wheel, animated reticle). For cinematographer portfolios, camera-app demos, LUT pack previews, filter-look auditions. NOT a TikTok/Reels mockup, NOT a storyboard, NOT a shot list, NOT a script document. The chrome wraps real footage — never a div placeholder.

ARYAN2302/liquid_researcher

Premium pre-launch waitlist page template — dark charcoal canvas with subtle vignette, drifting portrait video-thumbnail cards, fade-up cascades, glass nav, live-updating join counter, single email form with success/error states. Built for creative-tool / AI / niche-SaaS invite-only launches with hushed exclusive tone, not loud growth-marketing.

ARYAN2302/liquid_researcher

Route design-related HTML artifact tasks to the right artifact skill, reference, design system generation, or export skill.

ARYAN2302/liquid_researcher

Implement AI-powered video generation capabilities using the z-ai-web-dev-sdk. Use this skill when the user needs to generate videos from text prompts or images, create video content programmatically, or build applications that produce video outputs. Supports asynchronous task management with status polling and result retrieval.

ARYAN2302/liquid_researcher

Implement specialized video understanding capabilities using the z-ai-web-dev-sdk. Use this skill when the user needs to analyze video content, understand motion and temporal sequences, extract information from video frames, describe video scenes, or perform video-based AI analysis. Optimized for MP4, AVI, MOV, and other common video formats.

관련 스킬