ボイス検索とプレビュー

このドキュメントは英語の原文から自動翻訳されています。表現に不自然な箇所がある場合があります。正確な内容は英語の原文もあわせてご確認ください。

ユーザーがボイスを選択できるプロダクトでは、検索可能なリストとオーディオプレビューを表示したくなるはずです。Supertone APIはこれを直接サポートしています。search_voicesはフィルター条件に一致するボイスに加えて、ブラウザでそのまま再生できる事前生成済みのサンプルクリップを返します。

Python — フィルター指定してサンプルを表示する

import os
from supertone import Supertone

with Supertone(api_key=os.environ["SUPERTONE_API_KEY"]) as client:
    result = client.voices.search_voices(
        language="en,ko",
        style="happy,neutral",
        gender="female",
        age="young-adult",
        page_size=20,
    )

    for voice in result.items or []:
        sample = next(
            (s for s in (voice.samples or []) if s.language == "en"),
            None,
        )
        print(f"{voice.voice_id}\t{voice.name}\t{sample.url if sample else '(no en sample)'}")

TypeScript — ピッカーを描画する

import { Supertone } from "@supertone/supertone";

const client = new Supertone({ apiKey: process.env.SUPERTONE_API_KEY });

async function loadVoices() {
  return client.voices.searchVoices({
    language: "en,ko",
    style: "happy,neutral",
    gender: "female",
    age: "young-adult",
    pageSize: 20,
  });
}

const result = await loadVoices();

for (const voice of result.items ?? []) {
  const sample = voice.samples?.find((s) => s.language === "en");
  console.log(
    voice.voiceId,
    voice.name,
    sample?.url ?? "(no en sample)",
  );
}

ブラウザでピッカーを描画する

WebのUIにボイスを表示する場合は、リストはバックエンド経由で取得してください（ブラウザから自分のキーで直接Supertone APIを呼び出してはいけません）。その上で、サンプルURLを<audio>要素として描画します。

<!-- After your backend returns the search result as JSON -->
<ul id="voice-picker"></ul>

<script>
  async function renderVoices() {
    const res = await fetch("/api/voices?language=en&style=happy");
    const { items } = await res.json();
    const ul = document.getElementById("voice-picker");

    for (const voice of items) {
      const sample = voice.samples?.find((s) => s.language === "en");
      const li = document.createElement("li");
      li.innerHTML = `
        <button data-voice-id="${voice.voiceId}">${voice.name}</button>
        ${sample ? `<audio controls src="${sample.url}"></audio>` : ""}
      `;
      ul.appendChild(li);
    }
  }

  renderVoices();
</script>

ヒント: samplesフィールドは(language, style, model)の組み合わせをキーとしています。実際にアプリで使う組み合わせに一致するサンプルを選ぶことで、プレビューと本番出力を一致させられます。

ページネーション

search_voicesはpage_size件まで（デフォルト20、最大100）のボイスを返し、続きがある場合はnext_page_tokenを一緒に返します。そのトークンを再度渡せば次のページを取得できます。

Python
TypeScript

page = client.voices.search_voices(language="en", page_size=50)
while True:
    for voice in page.items or []:
        handle(voice)
    if not page.next_page_token:
        break
    page = client.voices.search_voices(
        language="en",
        page_size=50,
        next_page_token=page.next_page_token,
    )

let page = await client.voices.searchVoices({ language: "en", pageSize: 50 });
while (true) {
  for (const voice of page.items ?? []) {
    handle(voice);
  }
  if (!page.nextPageToken) break;
  page = await client.voices.searchVoices({
    language: "en",
    pageSize: 50,
    nextPageToken: page.nextPageToken,
  });
}

ヒント

複数値はORで評価されます。 language=ko,enはいずれかをサポートするボイスを返します。複数のフィルターを組み合わせるとAND的に絞り込めます。
sortパラメータはありません。 結果は自然な順序で返ります。独自の並び順が必要な場合はクライアント側でソートしてください。
レスポンスをキャッシュしましょう。 ボイスライブラリの内容は頻繁には変わりません。バックエンドでリストをキャッシュ（15〜60分程度が目安）すると、呼び出し回数を減らしつつピッカーのレイテンシも改善できます。

ボイス

ボイスIDとボイスオブジェクトの概念的な解説です。