Communitygithub.com

AiCurv/ADBCommander

Implementieren Sie Text-to-Speech (TTS)-Funktionen mit dem z-ai-web-dev-sdk. Verwenden Sie diesen Skill, wenn der Benutzer Text in natürlich klingende Sprache umwandeln, Audioinhalte erstellen, sprachgesteuerte Anwendungen entwickeln oder gesprochene Audiodateien generieren muss. Unterstützt mehrere Stimmen, anpassbare Geschwindigkeit und verschiedene Audioformate.

Was ist ADBCommander?

Dieser Skill beschreibt die Implementierung von Text-to-Speech (TTS) mit dem z-ai-web-dev-sdk. Er wandelt Text in natürlich klingende Audiodateien um und bietet Flexibilität durch mehrere Stimmen sowie einstellbare Geschwindigkeit (0,5 bis 2,0) und Lautstärke (bis 10). Der Skill unterstützt sowohl CLI-Befehle für schnelle Tests als auch SDK-Integrationen für Produktionsanwendungen (z. B. in Next.js oder Express.js). Er behandelt wichtige API-Einschränkungen wie die maximale Eingabelänge von 1024 Zeichen und die Beschränkung auf PCM-Format beim Streaming. Mit praktischen Codebeispielen, bewährten Methoden zur Fehlerbehandlung und dynamischen Generierung ist dieser Skill ideal für Audiobücher, Sprachassistenten, E-Learning und Barrierefreiheit.

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

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

TTS (Text-to-Speech) Skill

Dieser Skill führt durch die Implementierung der Text-to-Speech (TTS)-Funktionalität mit dem z-ai-web-dev-sdk-Paket und ermöglicht die Umwandlung von Text in natürlich klingende Sprachausgabe.

Skills-Pfad

Skill-Speicherort: {project_path}/skills/TTS

Dieser Skill befindet sich unter dem oben genannten Pfad in Ihrem Projekt.

Referenzskripte: Beispieltestskripte finden Sie im Verzeichnis {Skill-Speicherort}/scripts/ zum schnellen Testen und als Referenz. Siehe {Skill-Speicherort}/scripts/tts.ts für ein funktionierendes Beispiel.

Überblick

Text-to-Speech ermöglicht es Ihnen, Anwendungen zu entwickeln, die aus Texteingaben gesprochene Audiodateien generieren, und unterstützt verschiedene Stimmen, Geschwindigkeiten und Ausgabeformate für unterschiedliche Anwendungsfälle.

WICHTIG: z-ai-web-dev-sdk darf NUR im Backend-Code verwendet werden. Verwenden Sie es niemals im clientseitigen Code.

API-Beschränkungen und -Einschränkungen

Bevor Sie die TTS-Funktionalität implementieren, beachten Sie diese wichtigen Einschränkungen:

Eingabetext-Einschränkungen

  • Maximale Länge: 1024 Zeichen pro Anfrage
  • Text, der diese Grenze überschreitet, muss in kleinere Teile aufgeteilt werden

Audio-Parameter

  • Geschwindigkeitsbereich: 0,5 bis 2,0
    • 0,5 = halbe Geschwindigkeit (langsamer)
    • 1,0 = normale Geschwindigkeit (Standard)
    • 2,0 = doppelte Geschwindigkeit (schneller)
  • Lautstärkebereich: Größer als 0, bis 10
    • Standard: 1,0
    • Werte müssen größer als 0 (exklusiv) und bis einschließlich 10 (inklusive) sein

Format und Streaming

  • Streaming-Einschränkung: Wenn stream: true aktiviert ist, wird nur das pcm-Format unterstützt
  • Nicht-Streaming: Unterstützt die Formate wav, pcm und mp3
  • Abtastrate: 24000 Hz (empfohlen)

Bewährte Methode für langen Text

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

Voraussetzungen

Das z-ai-web-dev-sdk-Paket ist bereits installiert. Importieren Sie es wie in den folgenden Beispielen gezeigt.

CLI-Verwendung (für einfache Aufgaben)

Für einfache Text-to-Speech-Umwandlungen können Sie die z-ai-CLI anstelle des Schreibens von Code verwenden. Dies ist ideal für schnelle Audioerstellung, das Testen von Stimmen oder einfache Automatisierung.

Einfaches TTS

# Text in Sprache umwandeln (Standard-WAV-Format)
z-ai tts --input "Hallo, Welt" --output ./hallo.wav

# Mit kurzen Optionen
z-ai tts -i "Hallo, Welt" -o ./hallo.wav

Verschiedene Stimmen und Geschwindigkeit

# Bestimmte Stimme verwenden
z-ai tts -i "Willkommen bei unserem Service" -o ./willkommen.wav --voice tongtong

# Sprachgeschwindigkeit anpassen (0,5-2,0)
z-ai tts -i "Dies ist schnellere Sprache" -o ./schnell.wav --speed 1.5

# Langsamere Sprache
z-ai tts -i "Dies ist langsamere Sprache" -o ./langsam.wav --speed 0.8

Verschiedene Ausgabeformate

# MP3-Format
z-ai tts -i "Hallo Welt" -o ./hallo.mp3 --format mp3

# WAV-Format (Standard)
z-ai tts -i "Hallo Welt" -o ./hallo.wav --format wav

# PCM-Format
z-ai tts -i "Hallo Welt" -o ./hallo.pcm --format pcm

Streaming-Ausgabe

# Stream-Audioerstellung
z-ai tts -i "Dies ist ein längerer Text, der gestreamt wird" -o ./stream.wav --stream

CLI-Parameter

  • --input, -i <text>: Erforderlich - Text, der in Sprache umgewandelt werden soll (max. 1024 Zeichen)
  • --output, -o <pfad>: Erforderlich - Ausgabedateipfad für die Audiodatei
  • --voice, -v <stimme>: Optional - Stimmtyp (Standard: tongtong)
  • --speed, -s <zahl>: Optional - Sprachgeschwindigkeit, 0,5-2,0 (Standard: 1,0)
  • --format, -f <format>: Optional - Ausgabeformat: wav, mp3, pcm (Standard: wav)
  • --stream: Optional - Streaming-Ausgabe aktivieren (unterstützt nur pcm-Format)

Wann CLI vs. SDK verwenden

CLI verwenden für:

  • Schnelle Text-to-Speech-Umwandlungen
  • Testen verschiedener Stimmen und Geschwindigkeiten
  • Einfache Batch-Audioerstellung
  • Befehlszeilen-Automatisierungsskripte

SDK verwenden für:

  • Dynamische Audioerstellung in Anwendungen
  • Integration mit Webservices
  • Benutzerdefinierte Audioverarbeitungspipelines
  • Produktionsanwendungen mit komplexen Anforderungen

Einfache TTS-Implementierung

Einfache Text-to-Speech-Ausgabe

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

  // ArrayBuffer aus dem Response-Objekt holen
  const arrayBuffer = await response.arrayBuffer();
  const buffer = Buffer.from(new Uint8Array(arrayBuffer));

  fs.writeFileSync(outputPath, buffer);
  console.log(`Audio gespeichert unter ${outputPath}`);
  return outputPath;
}

// Verwendung
await textToSpeech('Hallo, Welt!', './output.wav');

Mehrere Stimmenoptionen

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, // Verfügbare Stimmen: tongtong, chuichui, xiaochen, jam, kazi, douji, luodo
    speed: 1.0,
    response_format: 'wav',
    stream: false
  });

  // ArrayBuffer aus dem Response-Objekt holen
  const arrayBuffer = await response.arrayBuffer();
  const buffer = Buffer.from(new Uint8Array(arrayBuffer));

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

// Verwendung
await generateWithVoice('Willkommen bei unserem Service', 'tongtong', './willkommen.wav');

Anpassbare Geschwindigkeit

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

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

  // Geschwindigkeitsbereich: 0,5 bis 2,0 (API-Einschränkung)
  // 0,5 = halbe Geschwindigkeit (langsamer)
  // 1,0 = normale Geschwindigkeit (Standard)
  // 2,0 = doppelte Geschwindigkeit (schneller)
  // Werte außerhalb dieses Bereichs führen zu API-Fehlern

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

  // ArrayBuffer aus dem Response-Objekt holen
  const arrayBuffer = await response.arrayBuffer();
  const buffer = Buffer.from(new Uint8Array(arrayBuffer));

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

// Verwendung - langsamere Erzählung
await generateWithSpeed('Dies ist eine wichtige Ankündigung', 0.8, './langsam.wav');

// Verwendung - schnellere Erzählung
await generateWithSpeed('Schnelles Update', 1.3, './schnell.wav');

Anpassbare Lautstärke

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

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

  // Lautstärkebereich: größer als 0, bis 10 (API-Einschränkung)
  // Werte müssen > 0 (exklusiv) und <= 10 (inklusiv) sein
  // Standard: 1.0 (normale Lautstärke)

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

  // ArrayBuffer aus dem Response-Objekt holen
  const arrayBuffer = await response.arrayBuffer();
  const buffer = Buffer.from(new Uint8Array(arrayBuffer));

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

// Verwendung - lauteres Audio
await generateWithVolume('Dies ist eine Ankündigung', 5.0, './laut.wav');

// Verwendung - leiseres Audio
await generateWithVolume('Geflüsterte Nachricht', 0.5, './leise.wav');

Fortgeschrittene Anwendungsfälle

Batch-Verarbeitung

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

  // Sicherstellen, dass das Ausgabeverzeichnis existiert
  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
      });

      // ArrayBuffer aus dem Response-Objekt holen
      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;
}

// Verwendung
const texts = [
  'Willkommen zu Kapitel eins',
  'Willkommen zu Kapitel zwei',
  'Willkommen zu Kapitel drei'
];

const results = await batchTextToSpeech(texts, './audio-output');
console.log('Erstellt:', results.length, 'Audiodateien');

Dynamische Inhaltserstellung

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

    // ArrayBuffer aus dem Response-Objekt holen
    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;
  }
}

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

await generator.saveAudio(
  'Hallo, dies ist ein Test',
  './output.wav',
  { speed: 1.2 }
);

Next.js-API-Routenbeispiel

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

    // SDK-Instanz erstellen
    const zai = await ZAI.create();

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

    // ArrayBuffer aus dem Response-Objekt holen
    const arrayBuffer = await response.arrayBuffer();
    const buffer = Buffer.from(new Uint8Array(arrayBuffer));

    // Audio als Antwort zurückgeben
    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-Fehler:', error);

    return NextResponse.json(
      {
        error: error instanceof Error ? error.message : 'Spracherzeugung fehlgeschlagen, bitte versuchen Sie es später erneut',
      },
      { status: 500 }
    );
  }
}

Bewährte Methoden

1. Textvorbereitung

function prepareTextForTTS(text) {
  // Übermäßige Leerzeichen entfernen
  text = text.replace(/\s+/g, ' ').trim();

  // Häufige Abkürzungen für bessere Aussprache erweitern
  const abbreviations = {
    'Dr.': 'Doktor',
    '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. Fehlerbehandlung

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

async function safeTTS(text, outputPath) {
  try {
    // Eingabe validieren
    if (!text || text.trim().length === 0) {
      throw new Error('Texteingabe darf nicht leer sein');
    }

    if (text.length > 1024) {
      throw new Error('Texteingabe überschreitet die maximale Länge von 1024 Zeichen');
    }

    const zai = await ZAI.create();

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

    // ArrayBuffer aus dem Response-Objekt holen
    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-Fehler:', error);
    return {
      success: false,
      error: error.message
    };
  }
}

3. Wiederverwendung der SDK-Instanz

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

// Singleton-Instanz erstellen
let zaiInstance = null;

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

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

Häufige Anwendungsfälle

  1. Hörbücher & Podcasts: Schriftliche Inhalte in Audioformat umwandeln
  2. E-Learning: Erstellung einer Erzählung für Bildungsinhalte
  3. Barrierefreiheit: Bereitstellung von Audioversionen von Textinhalten
  4. Sprachassistenten: Generieren dynamischer Antworten
  5. Ankündigungen: Erstellung automatisierter Audio-Benachrichtigungen
  6. IVR-Systeme: Generierung von Telefonansagen
  7. Inhaltslokalisierung: Erstellung von Audio in verschiedenen Sprachen

Integrationsbeispiele

Express.js-API-Endpunkt

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

// ... (weiterer Code folgt)

// Endpunkt zur TTS-Generierung
app.post('/api/tts', async (req, res) => {
  try {
    const { text, voice = 'tongtong', speed = 1.0, format = 'wav' } = req.body;

    if (!text || text.length > 1024) {
      return res.status(400).json({ error: 'Ungültige Eingabe: Text muss zwischen 1 und 1024 Zeichen liegen' });
    }

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

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

    // Optional: In Datei speichern
    const fileName = `tts-${Date.now()}.${format}`;
    const filePath = path.join(outputDir, fileName);
    fs.writeFileSync(filePath, buffer);

    res.set('Content-Type', `audio/${format}`);
    res.send(buffer);
  } catch (error) {
    console.error('Fehler bei TTS-Generierung:', error);
    res.status(500).json({ error: 'Fehler bei der Spracherzeugung' });
  }
});

initZAI().then(() => {
  app.listen(3000, () => console.log('Server läuft auf Port 3000'));
});

Fehlerbehebung (Troubleshooting)

Häufige Fehler

FehlerUrsacheLösung
Eingabe zu langText überschreitet 1024 ZeichenText in kleinere Teile aufteilen
Ungültige GeschwindigkeitGeschwindigkeit außerhalb von 0,5-2,0Geschwindigkeit auf 0,5-2,0 beschränken
Ungültige LautstärkeLautstärke außerhalb von 0 bis 10Lautstärke auf 0-10 beschränken
Nicht unterstütztes Format beim StreamingStreaming mit nicht-PCM-FormatBei aktiviertem Streaming auf PCM-Format ändern

Debugging-Tipps

# Testen mit kurzer Eingabe
z-ai tts -i "Test" -o ./test.wav

# Lautstärke explizit angeben
z-ai tts -i "Test" -o ./test.wav --volume 1.0

# Ausgabeverzeichnis überprüfen
ls -la ./test.wav

Referenzen

Lizenz

Dieser Skill wird unter der MIT-Lizenz bereitgestellt. Siehe LICENSE-Datei für Details.

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.

Verwandte Skills