Communitygithub.com

TTS(文本转语音)技能

使用 z-ai-web-dev-sdk 实现文本转语音(TTS)功能。当用户需要将文本转换为自然语音、创建音频内容、构建语音应用或生成语音音频文件时使用此技能。支持多种语音、可调速度和各种音频格式。

TTS(文本转语音)技能 是什么?

该技能指导开发者在项目中使用 z-ai-web-dev-sdk 包来实现文本转语音(TTS)功能。它支持将文本转换为自然语音音频,提供多种语音选项(如 tongtong、chuichui、xiaochen 等)、可调速度(0.5-2.0)、音量控制(0-10)以及多种输出格式(wav、mp3、pcm)。核心限制包括每次请求最多1024个字符,流式输出仅支持 pcm 格式。该技能同时提供 CLI 和 SDK 两种使用方式:CLI 适合快速转换和测试,SDK 则用于动态音频生成和集成到应用中。详细文档涵盖了从基础实现、批量处理、动态内容生成到 Next.js 和 Express.js 的集成示例,并提供了文本准备、错误处理和 SDK 实例复用的最佳实践。该技能适用于语音助手、有声读物、电子学习、无障碍功能等多种场景。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Cetc2211/AcTR-app/tree/HEAD/skills/TTS

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

TTS(文本转语音)技能 是做什么的?

此技能指导使用 z-ai-web-dev-sdk 包实现文本转语音(TTS)功能,可将文本转换为自然的语音音频。

技能路径

技能位置:{project_path}/skills/TTS

该技能位于项目中的上述路径。

参考脚本:示例测试脚本位于 {Skill Location}/scripts/ 目录中,用于快速测试和参考。请参阅 {Skill Location}/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 适用于:

  • 应用程序中的动态音频生成
  • 与 Web 服务集成
  • 自定义音频处理管道
  • 具有复杂需求的生产级应用程序

基本 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(`音频已保存至 ${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('已生成:', results.length, '个音频文件');

动态内容生成

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);

    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);
    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, format = 'wav' } = req.body;

    if (!text || text.trim().length === 0) {
      return res.status(400).json({ error: '文本输入不能为空' });
    }

    if (text.length > 1024) {
      return res.status(400).json({ error: '文本输入超过最大长度 1024 个字符' });
    }

    const filename = `tts-${Date.now()}.${format}`;
    const outputPath = path.join(outputDir, filename);

    const response = await zaiInstance.audio.tts.create({
      input: text,
      voice: voice,
      speed: speed,
      response_format: format,
      stream: false
    });

    const arrayBuffer = await response.arrayBuffer();
    const buffer = Buffer.from(new Uint8Array(arrayBuffer));

    fs.writeFileSync(outputPath, buffer);

    res.json({
      success: true,
      filename: filename,
      path: outputPath,
      size: buffer.length
    });
  } catch (error) {
    console.error('TTS 错误:', error);
    res.status(500).json({ error: '生成语音失败' });
  }
});

app.get('/tts/:filename', (req, res) => {
  const filePath = path.join(outputDir, req.params.filename);
  if (fs.existsSync(filePath)) {
    res.sendFile(filePath);
  } else {
    res.status(404).json({ error: '文件未找到' });
  }
});

app.listen(3000, () => {
  console.log('TTS 服务运行在端口 3000');
});

WebSocket 实时音频流

import WebSocket from 'ws';
import ZAI from 'z-ai-web-dev-sdk';

const wss = new WebSocket.Server({ port: 8080 });

wss.on('connection', (ws) => {
  console.log('客户端已连接');

  ws.on('message', async (message) => {
    try {
      const { text, voice = 'tongtong', speed = 1.0 } = JSON.parse(message);

      const zai = await ZAI.create();

      const response = await zai.audio.tts.create({
        input: text,
        voice: voice,
        speed: speed,
        response_format: 'pcm', // 流式必须使用 pcm
        stream: true
      });

      // 使用 ReadableStream 处理流式响应
      const reader = response.body.getReader();
      while (true) {
        const { done, value } = await reader.read();
        if (done) break;

        // 将音频块发送给客户端
        ws.send(value);
      }

      ws.send(JSON.stringify({ type: 'end' }));
    } catch (error) {
      ws.send(JSON.stringify({ type: 'error', message: error.message }));
    }
  });

  ws.on('close', () => {
    console.log('客户端已断开连接');
  });
});

console.log('WebSocket 服务器运行在 ws://localhost:8080');

Individual skills in this repo

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

Cetc2211/AcTR-app

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.

Cetc2211/AcTR-app

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.

Cetc2211/AcTR-app

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.

Cetc2211/AcTR-app

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.

Cetc2211/AcTR-app

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

Cetc2211/AcTR-app

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.

Cetc2211/AcTR-app

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.

相关技能