Communitygithub.com

TTS (Texto para Fala)

Implemente funcionalidades de texto para fala (TTS) usando o z-ai-web-dev-sdk. Use esta skill quando o usuário precisar converter texto em fala com som natural, criar conteúdo de áudio, construir aplicações habilitadas por voz ou gerar arquivos de áudio falados. Suporta múltiplas vozes, velocidade ajustável e vários formatos de áudio.

O que é TTS (Texto para Fala)?

Esta skill fornece uma implementação abrangente de conversão de texto para fala (TTS) utilizando o pacote z-ai-web-dev-sdk. Ela permite que desenvolvedores convertam texto em áudio com som natural com suporte para múltiplas vozes (tongtong, chuichui, xiaochen, jam, kazi, douji, luodo), velocidade ajustável (0.5 a 2.0) e volume (0 a 10), e vários formatos de saída como wav, mp3 e pcm. A skill inclui exemplos detalhados de código para uso básico de TTS, processamento em lote, geração de conteúdo dinâmico e integração com frameworks web como Next.js e Express.js. Também aborda as melhores práticas para preparação de texto, tratamento de erros e reutilização da instância do SDK. Importante: a skill enfatiza que o SDK deve ser usado apenas no backend, com um limite de 1024 caracteres por requisição e streaming suportado apenas no formato pcm. Exemplos de uso via CLI e SDK são fornecidos, com orientações sobre quando usar cada abordagem.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/AiCurv/ADBCommander/tree/HEAD/skills/TTS

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Skill TTS (Texto para Fala)

Esta skill orienta a implementação de funcionalidade de texto para fala (TTS) usando o pacote z-ai-web-dev-sdk, permitindo a conversão de texto em áudio de fala com som natural.

Caminho da Skill

Localização da Skill: {project_path}/skills/TTS

Esta skill está localizada no caminho acima em seu projeto.

Scripts de Referência: Scripts de exemplo de teste estão disponíveis no diretório {Skill Location}/scripts/ para testes e referência rápidos. Veja {Skill Location}/scripts/tts.ts para um exemplo funcional.

Visão Geral

Texto para Fala permite que você construa aplicações que geram áudio falado a partir de entrada de texto, suportando várias vozes, velocidades e formatos de saída para diversos casos de uso.

IMPORTANTE: z-ai-web-dev-sdk DEVE ser usado apenas em código backend. Nunca o use em código do lado do cliente.

Limitações e Restrições da API

Antes de implementar a funcionalidade TTS, esteja ciente destas limitações importantes:

Restrições do Texto de Entrada

  • Comprimento máximo: 1024 caracteres por requisição
  • Texto que exceda este limite deve ser dividido em partes menores

Parâmetros de Áudio

  • Faixa de velocidade: 0.5 a 2.0
    • 0.5 = metade da velocidade (mais lento)
    • 1.0 = velocidade normal (padrão)
    • 2.0 = velocidade dupla (mais rápido)
  • Faixa de volume: Maior que 0, até 10
    • Padrão: 1.0
    • Os valores devem ser maiores que 0 (exclusivo) e até 10 (inclusivo)

Formato e Streaming

  • Limitação de streaming: Quando stream: true estiver ativado, apenas o formato pcm é suportado
  • Sem streaming: Suporta formatos wav, pcm e mp3
  • Taxa de amostragem: 24000 Hz (recomendado)

Melhor Prática para Texto Longo

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

Pré-requisitos

O pacote z-ai-web-dev-sdk já está instalado. Importe-o conforme mostrado nos exemplos abaixo.

Uso via CLI (Para Tarefas Simples)

Para conversões simples de texto para fala, você pode usar a CLI do z-ai em vez de escrever código. Isso é ideal para geração rápida de áudio, teste de vozes ou automação simples.

TTS Básico

# Converter texto para fala (formato WAV padrão)
z-ai tts --input "Olá, mundo" --output ./ola.wav

# Usando opções curtas
z-ai tts -i "Olá, mundo" -o ./ola.wav

Diferentes Vozes e Velocidade

# Usar voz específica
z-ai tts -i "Bem-vindo ao nosso serviço" -o ./bemvindo.wav --voice tongtong

# Ajustar velocidade da fala (0.5-2.0)
z-ai tts -i "Esta é uma fala mais rápida" -o ./rapido.wav --speed 1.5

# Fala mais lenta
z-ai tts -i "Esta é uma fala mais lenta" -o ./lento.wav --speed 0.8

Diferentes Formatos de Saída

# Formato MP3
z-ai tts -i "Olá Mundo" -o ./ola.mp3 --format mp3

# Formato WAV (padrão)
z-ai tts -i "Olá Mundo" -o ./ola.wav --format wav

# Formato PCM
z-ai tts -i "Olá Mundo" -o ./ola.pcm --format pcm

Saída com Streaming

# Geração de áudio com streaming
z-ai tts -i "Este é um texto mais longo que será transmitido" -o ./stream.wav --stream

Parâmetros da CLI

  • --input, -i <texto>: Obrigatório - Texto para converter em fala (máx. 1024 caracteres)
  • --output, -o <caminho>: Obrigatório - Caminho do arquivo de áudio de saída
  • --voice, -v <voz>: Opcional - Tipo de voz (padrão: tongtong)
  • --speed, -s <número>: Opcional - Velocidade da fala, 0.5-2.0 (padrão: 1.0)
  • --format, -f <formato>: Opcional - Formato de saída: wav, mp3, pcm (padrão: wav)
  • --stream: Opcional - Ativar saída com streaming (suporta apenas formato pcm)

Quando Usar CLI vs SDK

Use CLI para:

  • Conversões rápidas de texto para fala
  • Testar diferentes vozes e velocidades
  • Geração de áudio em lote simples
  • Scripts de automação de linha de comando

Use SDK para:

  • Geração dinâmica de áudio em aplicações
  • Integração com serviços web
  • Pipelines personalizados de processamento de áudio
  • Aplicações de produção com requisitos complexos

Implementação Básica de TTS

Texto para Fala Simples

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

  // Obter array buffer do objeto Response
  const arrayBuffer = await response.arrayBuffer();
  const buffer = Buffer.from(new Uint8Array(arrayBuffer));

  fs.writeFileSync(outputPath, buffer);
  console.log(`Áudio salvo em ${outputPath}`);
  return outputPath;
}

// Uso
await textToSpeech('Olá, mundo!', './output.wav');

Múltiplas Opções de Voz

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, // Vozes disponíveis: tongtong, chuichui, xiaochen, jam, kazi, douji, luodo
    speed: 1.0,
    response_format: 'wav',
    stream: false
  });

  // Obter array buffer do objeto Response
  const arrayBuffer = await response.arrayBuffer();
  const buffer = Buffer.from(new Uint8Array(arrayBuffer));

  fs.writeFileSync(outputPath, buffer);
  return outputPath;
}

// Uso
await generateWithVoice('Bem-vindo ao nosso serviço', 'tongtong', './bemvindo.wav');

Velocidade Ajustável

import ZAI from 'z-ai-web-dev-sdk';
import fs from 'fs';

async function generateWithSpeed(text, speed, outputPath) {
  const zai = await ZAI.create();

  // Faixa de velocidade: 0.5 a 2.0 (restrição da API)
  // 0.5 = metade da velocidade (mais lento)
  // 1.0 = velocidade normal (padrão)
  // 2.0 = velocidade dupla (mais rápido)
  // Valores fora deste intervalo causarão erros da API

  const response = await zai.audio.tts.create({
    input: text,
    voice: 'tongtong',
    speed: speed,
    response_format: 'wav',
    stream: false
  });

  // Obter array buffer do objeto Response
  const arrayBuffer = await response.arrayBuffer();
  const buffer = Buffer.from(new Uint8Array(arrayBuffer));

  fs.writeFileSync(outputPath, buffer);
  return outputPath;
}

// Uso - narração mais lenta
await generateWithSpeed('Este é um anúncio importante', 0.8, './lento.wav');

// Uso - narração mais rápida
await generateWithSpeed('Atualização rápida', 1.3, './rapido.wav');

Volume Ajustável

import ZAI from 'z-ai-web-dev-sdk';
import fs from 'fs';

async function generateWithVolume(text, volume, outputPath) {
  const zai = await ZAI.create();

  // Faixa de volume: maior que 0, até 10 (restrição da API)
  // Os valores devem ser > 0 (exclusivo) e <= 10 (inclusivo)
  // Padrão: 1.0 (volume normal)

  const response = await zai.audio.tts.create({
    input: text,
    voice: 'tongtong',
    speed: 1.0,
    volume: volume, // Parâmetro opcional
    response_format: 'wav',
    stream: false
  });

  // Obter array buffer do objeto Response
  const arrayBuffer = await response.arrayBuffer();
  const buffer = Buffer.from(new Uint8Array(arrayBuffer));

  fs.writeFileSync(outputPath, buffer);
  return outputPath;
}

// Uso - áudio mais alto
await generateWithVolume('Este é um anúncio', 5.0, './alto.wav');

// Uso - áudio mais baixo
await generateWithVolume('Mensagem sussurrada', 0.5, './baixo.wav');

Casos de Uso Avançados

Processamento em Lote

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 = [];

  // Garantir que o diretório de saída exista
  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
      });

      // Obter array buffer do objeto 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;
}

// Uso
const texts = [
  'Bem-vindo ao capítulo um',
  'Bem-vindo ao capítulo dois',
  'Bem-vindo ao capítulo três'
];

const results = await batchTextToSpeech(texts, './audio-output');
console.log('Gerados:', results.length, 'arquivos de áudio');

Geração de Conteúdo Dinâmico

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

    // Obter array buffer do objeto 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;
  }
}

// Uso
const generator = new TTSGenerator();
await generator.initialize();

await generator.saveAudio(
  'Olá, isto é um teste',
  './output.wav',
  { speed: 1.2 }
);

Exemplo de Rota de API Next.js

import { NextRequest, NextResponse } from 'next/server';

export async function POST(req: NextRequest) {
  try {
    const { text, voice = 'tongtong', speed = 1.0 } = await req.json();

    // Importar SDK ZAI
    const ZAI = (await import('z-ai-web-dev-sdk')).default;

    // Criar instância do SDK
    const zai = await ZAI.create();

    // Gerar áudio TTS
    const response = await zai.audio.tts.create({
      input: text.trim(),
      voice: voice,
      speed: speed,
      response_format: 'wav',
      stream: false,
    });

    // Obter array buffer do objeto Response
    const arrayBuffer = await response.arrayBuffer();
    const buffer = Buffer.from(new Uint8Array(arrayBuffer));

    // Retornar áudio como resposta
    return new NextResponse(buffer, {
      status: 200,
      headers: {
        'Content-Type': 'audio/wav',
        'Content-Length': buffer.length.toString(),
        'Cache-Control': 'no-cache',
      },
    });
  } catch (error) {
    console.error('Erro na API TTS:', error);

    return NextResponse.json(
      {
        error: error instanceof Error ? error.message : 'Falha ao gerar fala. Tente novamente mais tarde.',
      },
      { status: 500 }
    );
  }
}

Melhores Práticas

1. Preparação de Texto

function prepareTextForTTS(text) {
  // Remover espaços em branco excessivos
  text = text.replace(/\s+/g, ' ').trim();

  // Expandir abreviações comuns para melhor pronúncia
  const abbreviations = {
    'Dr.': 'Doutor',
    'Sr.': 'Senhor',
    'Sra.': 'Senhora',
    'etc.': 'et cetera'
  };

  for (const [abbr, full] of Object.entries(abbreviations)) {
    text = text.replace(new RegExp(abbr, 'g'), full);
  }

  return text;
}

2. Tratamento de Erros

import ZAI from 'z-ai-web-dev-sdk';
import fs from 'fs';

async function safeTTS(text, outputPath) {
  try {
    // Validar entrada
    if (!text || text.trim().length === 0) {
      throw new Error('A entrada de texto não pode estar vazia');
    }

    if (text.length > 1024) {
      throw new Error('A entrada de texto excede o comprimento máximo de 1024 caracteres');
    }

    const zai = await ZAI.create();

    const response = await zai.audio.tts.create({
      input: text,
      voice: 'tongtong',
      speed: 1.0,
      response_format: 'wav',
      stream: false
    });

    // Obter array buffer do objeto 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('Erro TTS:', error);
    return {
      success: false,
      error: error.message
    };
  }
}

3. Reutilização da Instância do SDK

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

// Criar uma instância singleton
let zaiInstance = null;

async function getZAIInstance() {
  if (!zaiInstance) {
    zaiInstance = await ZAI.create();
  }
  return zaiInstance;
}

// Uso
const zai = await getZAIInstance();
const response = await zai.audio.tts.create({ ... });

Casos de Uso Comuns

  1. Audiobooks e Podcasts: Converter conteúdo escrito em formato de áudio
  2. E-learning: Criar narração para conteúdo educacional
  3. Acessibilidade: Fornecer versões em áudio de conteúdo textual
  4. Assistentes de Voz: Gerar respostas dinâmicas
  5. Anúncios: Criar notificações de áudio automatizadas
  6. Sistemas IVR: Gerar prompts de sistema telefônico
  7. Localização de Conteúdo: Criar áudio em diferentes idiomas

Exemplos de Integração

Endpoint de API Express.js

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('/api/tts', async (req, res) => {
  try {
    const { text, voice, speed, format } = req.body;
    
    if (!text) {
      return res.status(400).json({ error: 'Texto é obrigatório' });
    }

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

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

    res.setHeader('Content-Type', `audio/${format || 'wav'}`);
    res.send(buffer);
  } catch (error) {
    console.error('Erro TTS:', error);
    res.status(500).json({ error: error.message });
  }
});

app.listen(3000, () => console.log('Servidor rodando na porta 3000'));

Suporte a Vozes

Atualmente, as seguintes vozes estão disponíveis:

VozDescriçãoMelhor Para
tongtongVoz feminina padrãoUso geral, narração
chuichuiVoz feminina suaveConteúdo calmante, histórias infantis
xiaochenVoz masculinaNarração, anúncios
jamVoz masculina jovemConteúdo casual, moderno
kaziVoz masculina profissionalConteúdo empresarial, apresentações
doujiVoz feminina enérgicaPromoções, conteúdo animado
luodoVoz masculina profundaTrailers, anúncios dramáticos

Parâmetros de Áudio

ParâmetroTipoPadrãoFaixaDescrição
inputstring-1-1024 caracteresO texto para converter em fala
voicestring'tongtong'Ver tabela de vozesO tipo de voz a usar
speednumber1.00.5-2.0Velocidade da fala
volumenumber1.00 < volume <= 10Volume do áudio
response_formatstring'wav''wav', 'mp3', 'pcm'Formato do áudio de saída
streambooleanfalsetrue/falseAtivar saída com streaming

Resolução de Problemas

Problemas Comuns

  1. Texto muito longo (erro: "Entrada de texto muito longa")

    • Use a função auxiliar splitTextIntoChunks() para dividir o texto
  2. Velocidade fora do intervalo (erro: "Velocidade inválida")

    • Certifique-se de que a velocidade esteja entre 0.5 e 2.0
  3. Streaming sem PCM (erro: "Formato não suportado para streaming")

    • Ao usar streaming, defina response_format: 'pcm'
  4. Taxa de limite excedida (erro: "Muitas requisições")

    • Implemente intervalos entre requisições consecutivas

Dicas de Depuração

  • Sempre registre as respostas da API para rastreamento de erros
  • Teste com texto curto primeiro antes de processar documentos longos
  • Verifique os caminhos dos arquivos de saída e permissões
  • Monitore o uso da API para evitar exceder limites de taxa

Individual skills in this repo

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

AiCurv/ADBCommander

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.

AiCurv/ADBCommander

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.

AiCurv/ADBCommander

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.

AiCurv/ADBCommander

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.

AiCurv/ADBCommander

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

AiCurv/ADBCommander

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.

AiCurv/ADBCommander

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.

Habilidades Relacionadas