Communitygithub.com

ARYAN2302/liquid_researcher

z-ai-web-dev-sdk を使用してテキスト読み上げ(TTS)機能を実装します。ユーザーがテキストを自然な音声に変換したり、オーディオコンテンツを作成したり、音声対応アプリケーションを構築したり、音声ファイルを生成したりする必要がある場合にこのスキルを使用してください。複数の音声、調整可能な速度、さまざまなオーディオ形式をサポートしています。

liquid_researcher とは?

このスキルは、z-ai-web-dev-sdk パッケージを使用してテキスト読み上げ(TTS)機能を実装するための包括的なガイドを提供します。音声選択、再生速度の調整(0.5~2.0)、音量制御(0~10)、出力形式(wav、pcm、mp3)など、主要な機能をカバーしています。CLI と SDK の両方の使用方法を提供し、簡単な変換から Next.js や Express.js とのアプリケーション統合まで対応可能です。また、1024 文字の文字数制限やストリーミング時の形式制限などの API 制約も詳しく説明しています。このスキルは z-ai-web-dev-sdk と互換性があり、複数の音声オプションをサポートし、バッチ処理や動的コンテンツ生成のための高度なユースケースも提供します。また、SDK インスタンスの再利用やエラーハンドリングなどのベストプラクティスも紹介し、開発者が音声生成を確実かつ効率的に実装できるようにします。

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

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

TTS(テキスト読み上げ)スキル

このスキルは、z-ai-web-dev-sdk パッケージを使用してテキスト読み上げ(TTS)機能を実装するためのガイドです。テキストを自然な音声に変換できます。

スキルパス

スキルの場所: {project_path}/skills/TTS

このスキルは、上記のプロジェクトパスにあります。

リファレンススクリプト: テストと参考用のスクリプト例が {スキルの場所}/scripts/ ディレクトリにあります。動作例については {スキルの場所}/scripts/tts.ts を参照してください。

概要

テキスト読み上げを使用すると、テキスト入力から音声を生成するアプリケーションを構築でき、さまざまな音声、速度、出力形式をサポートして、多様なユースケースに対応できます。

重要: z-ai-web-dev-sdk はバックエンドコードでのみ使用してください。クライアントサイドコードでは絶対に使用しないでください。

API の制限と制約

TTS 機能を実装する前に、以下の重要な制限に注意してください。

入力テキストの制約

  • 最大長: リクエストあたり 1024 文字
  • この制限を超えるテキストは、より小さなチャンクに分割する必要があります

オーディオパラメータ

  • 速度範囲: 0.5 ~ 2.0
    • 0.5 = 半速(遅い)
    • 1.0 = 通常速度(デフォルト)
    • 2.0 = 倍速(速い)
  • 音量範囲: 0 より大きく、10 まで
    • デフォルト: 1.0
    • 値は 0 より大きく(排他的)、10 以下(包括的)である必要があります

形式とストリーミング

  • ストリーミングの制限: stream: true が有効な場合、pcm 形式のみがサポートされます
  • 非ストリーミング: wav、pcm、mp3 形式をサポート
  • サンプルレート: 24000 Hz(推奨)

長いテキストのベストプラクティス

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

前提条件

z-ai-web-dev-sdk パッケージはすでにインストールされています。以下の例に示すようにインポートしてください。

CLI の使用(簡単なタスク向け)

簡単なテキスト読み上げ変換には、コードを書く代わりに z-ai CLI を使用できます。これは、クイックな音声生成、音声のテスト、簡単な自動化に最適です。

基本的な TTS

# テキストを音声に変換(デフォルトは WAV 形式)
z-ai tts --input "Hello, world" --output ./hello.wav

# 短いオプションを使用
z-ai tts -i "Hello, world" -o ./hello.wav

さまざまな音声と速度

# 特定の音声を使用
z-ai tts -i "Welcome to our service" -o ./welcome.wav --voice tongtong

# 速度を調整(0.5~2.0)
z-ai tts -i "This is faster speech" -o ./fast.wav --speed 1.5

# 遅い音声
z-ai tts -i "This is slower speech" -o ./slow.wav --speed 0.8

さまざまな出力形式

# MP3 形式
z-ai tts -i "Hello World" -o ./hello.mp3 --format mp3

# WAV 形式(デフォルト)
z-ai tts -i "Hello World" -o ./hello.wav --format wav

# PCM 形式
z-ai tts -i "Hello World" -o ./hello.pcm --format pcm

ストリーミング出力

# 音声生成をストリーミング
z-ai tts -i "This is a longer text that will be streamed" -o ./stream.wav --stream

CLI パラメータ

  • --input, -i <text>: 必須 - 音声に変換するテキスト(最大 1024 文字)
  • --output, -o <path>: 必須 - 出力オーディオファイルのパス
  • --voice, -v <voice>: オプション - 音声タイプ(デフォルト: tongtong)
  • --speed, -s <number>: オプション - 音声速度、0.5~2.0(デフォルト: 1.0)
  • --format, -f <format>: オプション - 出力形式: wav、mp3、pcm(デフォルト: wav)
  • --stream: オプション - ストリーミング出力を有効にする(pcm 形式のみサポート)

CLI と SDK の使い分け

CLI を使用する場合:

  • クイックなテキスト読み上げ変換
  • さまざまな音声と速度のテスト
  • 簡単なバッチ音声生成
  • コマンドライン自動化スクリプト

SDK を使用する場合:

  • アプリケーション内での動的音声生成
  • Web サービスとの統合
  • カスタム音声処理パイプライン
  • 複雑な要件を持つ本番アプリケーション

基本的な TTS 実装

シンプルなテキスト読み上げ

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

  // Response オブジェクトから ArrayBuffer を取得
  const arrayBuffer = await response.arrayBuffer();
  const buffer = Buffer.from(new Uint8Array(arrayBuffer));

  fs.writeFileSync(outputPath, buffer);
  console.log(`オーディオを ${outputPath} に保存しました`);
  return outputPath;
}

// 使用例
await textToSpeech('Hello, world!', './output.wav');

複数の音声オプション

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, // 利用可能な音声: tongtong, chuichui, xiaochen, jam, kazi, douji, luodo
    speed: 1.0,
    response_format: 'wav',
    stream: false
  });

  // Response オブジェクトから ArrayBuffer を取得
  const arrayBuffer = await response.arrayBuffer();
  const buffer = Buffer.from(new Uint8Array(arrayBuffer));

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

// 使用例
await generateWithVoice('Welcome to our service', 'tongtong', './welcome.wav');

速度の調整

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

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

  // 速度範囲: 0.5 ~ 2.0(API 制約)
  // 0.5 = 半速(遅い)
  // 1.0 = 通常速度(デフォルト)
  // 2.0 = 倍速(速い)
  // この範囲外の値は API エラーになります

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

  // Response オブジェクトから ArrayBuffer を取得
  const arrayBuffer = await response.arrayBuffer();
  const buffer = Buffer.from(new Uint8Array(arrayBuffer));

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

// 使用例 - 遅いナレーション
await generateWithSpeed('This is an important announcement', 0.8, './slow.wav');

// 使用例 - 速いナレーション
await generateWithSpeed('Quick update', 1.3, './fast.wav');

音量の調整

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

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

  // 音量範囲: 0 より大きく、10 まで(API 制約)
  // 値は > 0(排他的)かつ <= 10(包括的)である必要があります
  // デフォルト: 1.0(通常の音量)

  const response = await zai.audio.tts.create({
    input: text,
    voice: 'tongtong',
    speed: 1.0,
    volume: volume, // オプションのパラメータ
    response_format: 'wav',
    stream: false
  });

  // Response オブジェクトから ArrayBuffer を取得
  const arrayBuffer = await response.arrayBuffer();
  const buffer = Buffer.from(new Uint8Array(arrayBuffer));

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

// 使用例 - 大きな音声
await generateWithVolume('This is an announcement', 5.0, './loud.wav');

// 使用例 - 小さな音声
await generateWithVolume('Whispered message', 0.5, './quiet.wav');

高度なユースケース

バッチ処理

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

  // 出力ディレクトリが存在することを確認
  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
      });

      // Response オブジェクトから ArrayBuffer を取得
      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;
}

// 使用例
const texts = [
  'Welcome to chapter one',
  'Welcome to chapter two',
  'Welcome to chapter three'
];

const results = await batchTextToSpeech(texts, './audio-output');
console.log('生成されたファイル数:', results.length);

動的コンテンツ生成

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

    // Response オブジェクトから ArrayBuffer を取得
    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;
  }
}

// 使用例
const generator = new TTSGenerator();
await generator.initialize();

await generator.saveAudio(
  'Hello, this is a test',
  './output.wav',
  { speed: 1.2 }
);

Next.js API ルートの例

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 をインポート
    const ZAI = (await import('z-ai-web-dev-sdk')).default;

    // SDK インスタンスを作成
    const zai = await ZAI.create();

    // TTS オーディオを生成
    const response = await zai.audio.tts.create({
      input: text.trim(),
      voice: voice,
      speed: speed,
      response_format: 'wav',
      stream: false,
    });

    // Response オブジェクトから ArrayBuffer を取得
    const arrayBuffer = await response.arrayBuffer();
    const buffer = Buffer.from(new Uint8Array(arrayBuffer));

    // 音声をレスポンスとして返す
    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 エラー:', error);

    return NextResponse.json(
      {
        error: error instanceof Error ? error.message : '音声の生成に失敗しました。後でもう一度お試しください',
      },
      { status: 500 }
    );
  }
}

ベストプラクティス

1. テキストの準備

function prepareTextForTTS(text) {
  // 過剰な空白を削除
  text = text.replace(/\s+/g, ' ').trim();

  // 一般的な略語を展開して発音を改善
  const abbreviations = {
    'Dr.': 'Doctor',
    '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. エラーハンドリング

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

async function safeTTS(text, outputPath) {
  try {
    // 入力を検証
    if (!text || text.trim().length === 0) {
      throw new Error('テキスト入力は空にできません');
    }

    if (text.length > 1024) {
      throw new Error('テキスト入力が最大長の 1024 文字を超えています');
    }

    const zai = await ZAI.create();

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

    // Response オブジェクトから ArrayBuffer を取得
    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 エラー:', error);
    return {
      success: false,
      error: error.message
    };
  }
}

3. SDK インスタンスの再利用

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

// シングルトンインスタンスを作成
let zaiInstance = null;

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

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

一般的なユースケース

  1. オーディオブック & ポッドキャスト: 書かれたコンテンツを音声形式に変換
  2. E-ラーニング: 教育コンテンツのナレーションを作成
  3. アクセシビリティ: テキストコンテンツの音声版を提供
  4. 音声アシスタント: 動的な応答を生成
  5. アナウンス: 自動化された音声通知を作成
  6. IVR システム: 電話システムのプロンプトを生成
  7. コンテンツのローカリゼーション: さまざまな言語で音声を作成

統合例

Express.js API エンドポイント

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('/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: '無効なテキスト入力' });
    }

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

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

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

    res.json({
      success: true,
      url: `/audio/${filename}`,
      size: buffer.length
    });
  } catch (error) {
    console.error('TTS エラー:', error);
    res.status(500).json({ error: error.message });
  }
});

initZAI().then(() => {
  app.listen(3000, () => console.log('TTS サーバーが起動しました '));
});

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.

関連スキル