Communitygithub.com

ARYAN2302/liquid_researcher

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

liquid_researcher 是什么?

此技能引导开发者使用 z-ai-web-dev-sdk 包实现文本转语音(TTS)功能。它提供了从简单命令行工具到高级集成的完整指南,包括批量处理、动态内容生成和 Next.js API 路由示例。该技能详细说明了API限制和约束,例如每请求最多1024个字符的文本长度、0.5到2.0之间的速度范围、以及大于0到10之间的音量范围。在流式传输模式下,仅支持PCM格式;非流式传输则支持WAV、PCM和MP3。最佳实践部分包括文本预处理、错误处理以及SDK实例的复用。该技能主要面向在Node.js后端环境中使用SDK的开发者,并提供了多种实际应用场景,如有声书、电子学习和语音助手。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ARYAN2302/liquid_researcher/tree/HEAD/skills/TTS

在你喜欢的 AI 中提问

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

文档

TTS(文本转语音)技能

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

技能路径

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

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

参考脚本:{技能位置}/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(o

…

[截断以进行翻译]

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.

相关技能