Communitygithub.com

ARYAN2302/liquid_researcher

Implementa capacidades de texto a voz (TTS) usando el z-ai-web-dev-sdk. Usa esta habilidad cuando el usuario necesite convertir texto en voz natural, crear contenido de audio, construir aplicaciones con voz, o generar archivos de audio hablado. Soporta múltiples voces, velocidad ajustable y varios formatos de audio.

¿Qué es liquid_researcher?

Esta habilidad guía la implementación de funcionalidad de texto a voz (TTS) utilizando el paquete `z-ai-web-dev-sdk`, permitiendo la conversión de texto en audio de voz con sonido natural. Es útil para desarrolladores que construyen aplicaciones de audio, asistentes de voz, audiolibros, contenido de e-learning y sistemas de accesibilidad. La habilidad proporciona documentación completa, incluyendo ejemplos para la línea de comandos (CLI) y el SDK, casos de uso avanzados como procesamiento por lotes y generación dinámica de contenido, y prácticas recomendadas para manejo de errores y optimización. Soporta múltiples voces (tongtong, chuichui, xiaochen, jam, kazi, douji, luodo), velocidad ajustable (0.5 a 2.0), volumen ajustable (mayor que 0 hasta 10), y formatos de salida como wav, mp3 y pcm. Incluye limitaciones importantes: máximo 1024 caracteres por solicitud y restricciones de streaming (solo formato pcm cuando stream está activado). La habilidad está diseñada para usarse exclusivamente en el backend y se integra con frameworks como Next.js y Express.js.

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

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Habilidad de TTS (Texto a Voz)

Esta habilidad guía la implementación de funcionalidad de texto a voz (TTS) usando el paquete z-ai-web-dev-sdk, permitiendo convertir texto en audio de voz con sonido natural.

Ruta de la Habilidad

Ubicación de la Habilidad: {project_path}/skills/TTS

Esta habilidad se encuentra en la ruta anterior dentro de tu proyecto.

Scripts de Referencia: Hay scripts de prueba de ejemplo disponibles en el directorio {Skill Location}/scripts/ para pruebas rápidas y referencia. Consulta {Skill Location}/scripts/tts.ts para un ejemplo funcional.

Resumen

El texto a voz te permite crear aplicaciones que generan audio hablado a partir de entrada de texto, soportando diversas voces, velocidades y formatos de salida para diferentes casos de uso.

IMPORTANTE: z-ai-web-dev-sdk DEBE usarse solo en código del backend. Nunca lo uses en código del lado del cliente.

Limitaciones y Restricciones de la API

Antes de implementar la funcionalidad TTS, ten en cuenta estas limitaciones importantes:

Restricciones del Texto de Entrada

  • Longitud máxima: 1024 caracteres por solicitud
  • El texto que exceda este límite debe dividirse en fragmentos más pequeños

Parámetros de Audio

  • Rango de velocidad: 0.5 a 2.0
    • 0.5 = mitad de velocidad (más lento)
    • 1.0 = velocidad normal (predeterminada)
    • 2.0 = velocidad doble (más rápido)
  • Rango de volumen: Mayor que 0, hasta 10
    • Predeterminado: 1.0
    • Los valores deben ser mayores que 0 (exclusivo) y hasta 10 (inclusive)

Formato y Transmisión

  • Limitación de transmisión: Cuando stream: true está habilitado, solo se admite el formato pcm
  • Sin transmisión: Soporta formatos wav, pcm y mp3
  • Frecuencia de muestreo: 24000 Hz (recomendada)

Mejor Práctica para Texto Largo

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

Prerrequisitos

El paquete z-ai-web-dev-sdk ya está instalado. Impórtalo como se muestra en los ejemplos a continuación.

Uso de la CLI (Para Tareas Simples)

Para conversiones simples de texto a voz, puedes usar la CLI de z-ai en lugar de escribir código. Esto es ideal para generación rápida de audio, prueba de voces o automatización simple.

TTS Básico

# Convertir texto a voz (formato WAV predeterminado)
z-ai tts --input "Hola, mundo" --output ./hola.wav

# Usando opciones cortas
z-ai tts -i "Hola, mundo" -o ./hola.wav

Diferentes Voces y Velocidad

# Usar voz específica
z-ai tts -i "Bienvenido a nuestro servicio" -o ./bienvenido.wav --voice tongtong

# Ajustar velocidad del habla (0.5-2.0)
z-ai tts -i "Este es un discurso más rápido" -o ./rapido.wav --speed 1.5

# Discurso más lento
z-ai tts -i "Este es un discurso más lento" -o ./lento.wav --speed 0.8

Diferentes Formatos de Salida

# Formato MP3
z-ai tts -i "Hola Mundo" -o ./hola.mp3 --format mp3

# Formato WAV (predeterminado)
z-ai tts -i "Hola Mundo" -o ./hola.wav --format wav

# Formato PCM
z-ai tts -i "Hola Mundo" -o ./hola.pcm --format pcm

Salida en Transmisión

# Generación de audio en transmisión
z-ai tts -i "Este es un texto más largo que se transmitirá" -o ./transmision.wav --stream

Parámetros de la CLI

  • --input, -i <texto>: Requerido - Texto a convertir a voz (máximo 1024 caracteres)
  • --output, -o <ruta>: Requerido - Ruta del archivo de audio de salida
  • --voice, -v <voz>: Opcional - Tipo de voz (predeterminado: tongtong)
  • --speed, -s <número>: Opcional - Velocidad del habla, 0.5-2.0 (predeterminado: 1.0)
  • --format, -f <formato>: Opcional - Formato de salida: wav, mp3, pcm (predeterminado: wav)
  • --stream: Opcional - Habilitar salida en transmisión (solo admite formato pcm)

Cuándo Usar la CLI vs el SDK

Usa la CLI para:

  • Conversiones rápidas de texto a voz
  • Probar diferentes voces y velocidades
  • Generación simple de audio por lotes
  • Scripts de automatización de línea de comandos

Usa el SDK para:

  • Generación dinámica de audio en aplicaciones
  • Integración con servicios web
  • Tuberías de procesamiento de audio personalizadas
  • Aplicaciones de producción con requisitos complejos

Implementación Básica de TTS

Texto a Voz Simple

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

async function textoAVoz(texto, rutaSalida) {
  const zai = await ZAI.create();

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

  // Obtener array buffer del objeto Response
  const arrayBuffer = await respuesta.arrayBuffer();
  const buffer = Buffer.from(new Uint8Array(arrayBuffer));

  fs.writeFileSync(rutaSalida, buffer);
  console.log(`Audio guardado en ${rutaSalida}`);
  return rutaSalida;
}

// Uso
await textoAVoz('¡Hola, mundo!', './salida.wav');

Múltiples Opciones de Voz

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

async function generarConVoz(texto, voz, rutaSalida) {
  const zai = await ZAI.create();

  const respuesta = await zai.audio.tts.create({
    input: texto,
    voice: voz, // Voces disponibles: tongtong, chuichui, xiaochen, jam, kazi, douji, luodo
    speed: 1.0,
    response_format: 'wav',
    stream: false
  });

  // Obtener array buffer del objeto Response
  const arrayBuffer = await respuesta.arrayBuffer();
  const buffer = Buffer.from(new Uint8Array(arrayBuffer));

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

// Uso
await generarConVoz('Bienvenido a nuestro servicio', 'tongtong', './bienvenido.wav');

Velocidad Ajustable

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

async function generarConVelocidad(texto, velocidad, rutaSalida) {
  const zai = await ZAI.create();

  // Rango de velocidad: 0.5 a 2.0 (restricción de la API)
  // 0.5 = mitad de velocidad (más lento)
  // 1.0 = velocidad normal (predeterminada)
  // 2.0 = velocidad doble (más rápido)
  // Valores fuera de este rango causarán errores de la API

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

  // Obtener array buffer del objeto Response
  const arrayBuffer = await respuesta.arrayBuffer();
  const buffer = Buffer.from(new Uint8Array(arrayBuffer));

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

// Uso - narración más lenta
await generarConVelocidad('Este es un anuncio importante', 0.8, './lento.wav');

// Uso - narración más rápida
await generarConVelocidad('Actualización rápida', 1.3, './rapido.wav');

Volumen Ajustable

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

async function generarConVolumen(texto, volumen, rutaSalida) {
  const zai = await ZAI.create();

  // Rango de volumen: mayor que 0, hasta 10 (restricción de la API)
  // Los valores deben ser > 0 (exclusivo) y <= 10 (inclusive)
  // Predeterminado: 1.0 (volumen normal)

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

  // Obtener array buffer del objeto Response
  const arrayBuffer = await respuesta.arrayBuffer();
  const buffer = Buffer.from(new Uint8Array(arrayBuffer));

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

// Uso - audio más fuerte
await generarConVolumen('Este es un anuncio', 5.0, './fuerte.wav');

// Uso - audio más bajo
await generarConVolumen('Mensaje susurrado', 0.5, './bajo.wav');

Casos de Uso Avanzados

Procesamiento por Lotes

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

async function textoAVozPorLotes(matrizTexto, directorioSalida) {
  const zai = await ZAI.create();
  const resultados = [];

  // Asegurar que el directorio de salida exista
  if (!fs.existsSync(directorioSalida)) {
    fs.mkdirSync(directorioSalida, { recursive: true });
  }

  for (let i = 0; i < matrizTexto.length; i++) {
    try {
      const texto = matrizTexto[i];
      const rutaSalida = path.join(directorioSalida, `audio_${i + 1}.wav`);

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

      // Obtener array buffer del objeto Response
      const arrayBuffer = await respuesta.arrayBuffer();
      const buffer = Buffer.from(new Uint8Array(arrayBuffer));

      fs.writeFileSync(rutaSalida, buffer);
      resultados.push({
        success: true,
        texto,
        path: rutaSalida
      });
    } catch (error) {
      resultados.push({
        success: false,
        texto: matrizTexto[i],
        error: error.message
      });
    }
  }

  return resultados;
}

// Uso
const textos = [
  'Bienvenido al capítulo uno',
  'Bienvenido al capítulo dos',
  'Bienvenido al capítulo tres'
];

const resultados = await textoAVozPorLotes(textos, './salida-audio');
console.log('Generados:', resultados.length, 'archivos de audio');

Generación Dinámica de Contenido

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

class GeneradorTTS {
  constructor() {
    this.zai = null;
  }

  async inicializar() {
    this.zai = await ZAI.create();
  }

  async generarAudio(texto, opciones = {}) {
    const {
      voice = 'tongtong',
      speed = 1.0,
      format = 'wav'
    } = opciones;

    const respuesta = await this.zai.audio.tts.create({
      input: texto,
      voice: voice,
      speed: speed,
      response_format: format,
      stream: false
    });

    // Obtener array buffer del objeto Response
    const arrayBuffer = await respuesta.arrayBuffer();
    return Buffer.from(new Uint8Array(arrayBuffer));
  }

  async guardarAudio(texto, rutaSalida, opciones = {}) {
    const buffer = await this.generarAudio(texto, opciones);
    if (buffer) {
      fs.writeFileSync(rutaSalida, buffer);
      return rutaSalida;
    }
    return null;
  }
}

// Uso
const generador = new GeneradorTTS();
await generador.inicializar();

await generador.guardarAudio(
  'Hola, esto es una prueba',
  './salida.wav',
  { speed: 1.2 }
);

Ejemplo de Ruta de API de 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 de ZAI
    const ZAI = (await import('z-ai-web-dev-sdk')).default;

    // Crear instancia del SDK
    const zai = await ZAI.create();

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

    // Obtener array buffer del objeto Response
    const arrayBuffer = await respuesta.arrayBuffer();
    const buffer = Buffer.from(new Uint8Array(arrayBuffer));

    // Devolver audio como respuesta
    return new NextResponse(buffer, {
      status: 200,
      headers: {
        'Content-Type': 'audio/wav',
        'Content-Length': buffer.length.toString(),
        'Cache-Control': 'no-cache',
      },
    });
  } catch (error) {
    console.error('Error de API TTS:', error);

    return NextResponse.json(
      {
        error: error instanceof Error ? error.message : 'Error al generar audio, inténtalo de nuevo más tarde',
      },
      { status: 500 }
    );
  }
}

Mejores Prácticas

1. Preparación del Texto

function prepararTextoParaTTS(texto) {
  // Eliminar espacios en blanco excesivos
  texto = texto.replace(/\s+/g, ' ').trim();

  // Expandir abreviaturas comunes para mejor pronunciación
  const abreviaturas = {
    'Dr.': 'Doctor',
    'Sr.': 'Señor',
    'Sra.': 'Señora',
    'etc.': 'etcétera'
  };

  for (const [abrev, completo] of Object.entries(abreviaturas)) {
    texto = texto.replace(new RegExp(abrev, 'g'), completo);
  }

  return texto;
}

2. Manejo de Errores

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

async function TTS_seguro(texto, rutaSalida) {
  try {
    // Validar entrada
    if (!texto || texto.trim().length === 0) {
      throw new Error('La entrada de texto no puede estar vacía');
    }

    if (texto.length > 1024) {
      throw new Error('La entrada de texto supera la longitud máxima de 1024 caracteres');
    }

    const zai = await ZAI.create();

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

    // Obtener array buffer del objeto Response
    const arrayBuffer = await respuesta.arrayBuffer();
    const buffer = Buffer.from(new Uint8Array(arrayBuffer));

    fs.writeFileSync(rutaSalida, buffer);

    return {
      success: true,
      path: rutaSalida,
      size: buffer.length
    };
  } catch (error) {
    console.error('Error TTS:', error);
    return {
      success: false,
      error: error.message
    };
  }
}

3. Reutilización de la Instancia del SDK

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

// Crear una instancia singleton
let instanciaZAI = null;

async function obtenerInstanciaZAI() {
  if (!instanciaZAI) {
    instanciaZAI = await ZAI.create();
  }
  return instanciaZAI;
}

// Uso
const zai = await obtenerInstanciaZAI();
const respuesta = await zai.audio.tts.create({ ... });

Casos de Uso Comunes

  1. Audiolibros y Podcasts: Convertir contenido escrito a formato de audio
  2. E-learning: Crear narración para contenido educativo
  3. Accesibilidad: Proporcionar versiones de audio del contenido textual
  4. Asistentes de Voz: Generar respuestas dinámicas
  5. Anuncios: Crear notificaciones de audio automatizadas
  6. Sistemas IVR: Generar mensajes de sistemas telefónicos
  7. Localización de Contenido: Crear audio en diferentes idiomas

Ejemplos de Integración

Endpoint de API de 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 instanciaZAI;
const directorioSalida = './salida-audio';

async function initZAI() {
  instanciaZAI = await ZAI.create();
  if (!fs.existsSync(directorioSalida)) {
    fs.mkdirSync(directorioSalida, { recursive: true });
  }
}

app.post('/tts', async (req, res) => {
  try {
    const { text, voice = 'tongtong', speed = 1.0 } = req.body;

    if (!text || text.length > 1024) {
      return res.status(400).json({ error: 'Texto inválido o demasiado largo' });
    }

    const nombreArchivo = `audio_${Date.now()}.wav`;
    const rutaSalida = path.join(directorioSalida, nombreArchivo);

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

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

    fs.writeFileSync(rutaSalida, buffer);

    res.json({
      success: true,
      path: rutaSalida,
      size: buffer.length
    });
  } catch (error) {
    console.error('Error de TTS:', error);
    res.status(500).json({ error: error.message });
  }
});

app.listen(3000, async () => {
  await initZAI();
  console.log('Servidor TTS iniciado en el puerto 3000');
});

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.

Skills relacionados