Communitygithub.com

Cetc2211/AcTR-app

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

O que é AcTR-app?

Esta habilidade implementa conversão de texto para fala (TTS) utilizando o pacote z-ai-web-dev-sdk, permitindo que desenvolvedores gerem áudio de fala natural a partir de entradas de texto. Ela suporta múltiplas vozes (como 'tongtong', 'chuichui', 'xiaochen'), velocidade ajustável (0.5 a 2.0), volume (até 10) e formatos de saída como wav, mp3 e pcm, com capacidade de streaming para formato pcm. É ideal para construir aplicações como audiolivros, e-learning, ferramentas de acessibilidade e assistentes de voz. A habilidade inclui orientações para uso via CLI para tarefas rápidas e via SDK para integração programática em aplicações, com exemplos em JavaScript/Node.js, incluindo rota de API Next.js e endpoint Express.js. Destaca-se a importância de usar o SDK apenas no backend (nunca no frontend) e as limitações de 1024 caracteres por requisição, fornecendo um método de divisão de texto longo em partes menores.

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

Perguntar na sua IA favorita

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

Documentação

Habilidade de TTS (Texto para Fala)

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

Caminho da Habilidade

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

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

Scripts de Referência: Scripts de teste de exemplo estão disponíveis no diretório {Skill Location}/scripts/ para teste e referência rápidos. Consulte {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: O z-ai-web-dev-sdk DEVE ser usado apenas em código backend. Nunca o use em código lado cliente.

Limitações e Restrições da API

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

Restrições de Texto de Entrada

  • Comprimento máximo: 1024 caracteres por requisição
  • Texto que exceder 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
    • Valores devem ser maiores que 0 (exclusivo) e até 10 (inclusivo)

Formato e Streaming

  • Limitação de streaming: Quando stream: true está habilitado, 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 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 em 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 ./bem-vindo.wav --voice tongtong

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

# Fala mais lenta
z-ai tts -i "Esta é uma fala mais lenta" -o ./lenta.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 por Streaming

# Geração de áudio por 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 a ser convertido 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 - Habilitar saída por 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 simples de áudio em lote
  • 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 de processamento de áudio personalizados
  • 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', './bem-vindo.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 na 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)
  // 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 Dinâmica de Conteúdo

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 áudio, 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. Audiolivros 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 });
  }
}

app.post('/api/tts', async (req, res) => {
  try {
    const { text, voice, speed } = req.body;
    const timestamp = Date.now();
    const outputPath = path.join(outputDir, `tts_${timestamp}.wav`);

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

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

    fs.writeFileSync(outputPath, buffer);

    res.json({
      success: true,
      path: outputPath,
      size: buffer.length
    });
  } catch (error) {
    res.status(500).json({ success: false, error: error.message });
  }
});

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

Referência de API

Método zai.audio.tts.create(options)

ParâmetroTipoObrigatórioPadrãoDescrição
inputstringSim-Texto para converter em fala (máx. 1024 caracteres)
voicestringSim-Voz a ser usada (tongtong, chuichui, xiaochen, jam, kazi, douji, luodo)
speednumberNão1.0Velocidade da fala (0.5 a 2.0)
volumenumberNão1.0Volume do áudio (> 0 e <= 10)
response_formatstringNão'wav'Formato de saída (wav, mp3, pcm)
streambooleanNãofalseHabilitar saída por streaming (apenas pcm)

Solução de Problemas

Problemas Comuns

  1. Erro de validação de comprimento do texto: O texto de entrada excede o limite máximo de 1024 caracteres. Divida o texto em partes menores.

  2. Erro de parâmetro de velocidade inválido: O valor da velocidade está fora da faixa permitida (0.5-2.0). Certifique-se de que a velocidade está dentro do intervalo especificado.

  3. Erro de formato de streaming: Quando stream: true está definido, apenas o formato pcm é suportado. Altere o formato para pcm ou desabilite o streaming.

  4. Instância do SDK não inicializada: Certifique-se de que ZAI.create() é chamado antes de usar qualquer funcionalidade TTS.

  5. Erro de caminho de saída: Certifique-se de que o diretório de saída existe ou seja criado com fs.mkdirSync com a opção recursive: true.

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.

Habilidades Relacionadas