Communitygithub.com

ARYAN2302/liquid_researcher

Implementa capacidades de conversão de texto em fala (TTS) usando o z-ai-web-dev-sdk. Use esta skill quando o usuário precisar converter texto em áudio com som natural, criar conteúdo de áudio, construir aplicativos habilitados por voz ou gerar arquivos de áudio falados. Suporta múltiplas vozes, velocidade ajustável e vários formatos de áudio.

O que é liquid_researcher?

Esta skill fornece uma implementação abrangente de conversão de texto em fala (TTS) usando o pacote z-ai-web-dev-sdk. Ela permite que desenvolvedores gerem áudio de fala com som natural a partir de entrada de texto, suportando várias vozes (como tongtong, chuichui, xiaochen), velocidades ajustáveis (0.5 a 2.0) e múltiplos formatos de saída de áudio (wav, mp3, pcm). A skill inclui tanto uso via CLI para conversões rápidas e testes, quanto uso via SDK para integração em aplicações maiores. Limitações importantes são destacadas, como o limite de 1024 caracteres por requisição e a restrição de formato pcm ao usar streaming. A documentação também fornece práticas recomendadas para preparação de texto, tratamento de erros, processamento em lote e reutilização de instâncias do SDK, além de exemplos de integração com Express.js e Next.js API Routes.

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

Perguntar na sua IA favorita

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

Documentação

Skill de TTS (Text-to-Speech)

Esta skill orienta a implementação da funcionalidade de conversão de texto em 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 no seu projeto.

Scripts de Referência: Scripts de teste de exemplo estão disponíveis no diretório {Skill Location}/scripts/ para testes rápidos e referência. 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 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 esse limite deve ser dividido em pedaços 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 = dobro da velocidade (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 está ativado, apenas o formato pcm é suportado
  • Sem streaming: Suporta os 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 em 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

# Converte 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

Vozes e Velocidades Diferentes

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

# Ajusta a 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 em Streaming

# Geração de áudio em 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 - Ativa saída em streaming (suporta apenas formato pcm)

Quando Usar CLI vs SDK

Use CLI para:

  • Conversões rápidas de texto em 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 personalizados de processamento de áudio
  • Aplicações de produção com requisitos complexos

Implementação Básica de TTS

Conversão Simples de Texto em Fala

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

  // Obtém o 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
  });

  // Obtém o 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 = dobro da velocidade (mais rápido)
  // Valores fora desta faixa causarão erros na API

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

  // Obtém o 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
  });

  // Obtém o 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 = [];

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

      // Obtém o 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
    });

    // Obtém o 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();

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

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

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

    // Obtém o array buffer do objeto Response
    const arrayBuffer = await response.arrayBuffer();
    const buffer = Buffer.from(new Uint8Array(arrayBuffer));

    // Retorna o á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) {
  // Remove espaços em branco excessivos
  text = text.replace(/\s+/g, ' ').trim();

  // Expande 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 {
    // Valida 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
    });

    // Obtém o 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 de Instância do SDK

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

// Cria 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 para sistemas telefônicos
  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 = 'tongtong', speed = 1.0 } = req.body;

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

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

    const timestamp = Date.now();
    const outputPath = path.join(outputDir, `tts-${timestamp}.wav`);
    fs.writeFileSync(outputPath, buffer);

    res.json({
      success: true,
      audioPath: outputPath,
      size: buffer.length
    });
  } catch (error) {
    console.error('Erro TTS:', error);
    res.status(500).json({
      success: false,
      error: error instanceof Error ? error.message : 'Erro interno do servidor'
    });
  }
});

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

Conclusão

A skill TTS fornece capacidades robustas de conversão de texto em fala via CLI para tarefas rápidas e SDK para aplicações complexas. Siga as limitações da API, use as práticas recomendadas para tratamento de erros e preparação de texto, e reutilize instâncias do SDK para desempenho ideal. A flexibilidade em vozes, velocidade e formatos a torna adequada para diversos casos de uso, desde audiolivros até assistentes de voz.

Próximos Passos

  • Experimente com diferentes vozes e velocidades
  • Implemente tratamento de erros e validação
  • Processe textos longos dividindo-os em pedaços
  • Reutilize instâncias do SDK para melhor desempenho

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.

Habilidades Relacionadas