Web SDK

@sorisdk/web-audio は、Webサービスやブラウザベースの製品にSORI音声認識を組み込むためのブラウザSDKです。

Beta

Web SDK は現在 Beta 段階です。実装はまだ発展途上のため、一部の API や連携フローは変更される可能性があります。

前提条件

https:// または http://localhost などのsecure context
AudioContext と MediaDevices.getUserMedia をサポートする最新ブラウザ
SORIが提供するephemeral keyフローへのアクセス
ユーザーが許可したマイク権限

npm・バンドラー連携

npmとバンドラーを使用するアプリケーションでは、バージョンを指定してパッケージをインストールします。

bash

npm install @sorisdk/web-audio@0.6.10

Viteベースのアプリケーションでは vite-plugin-wasm も必要です。

bash

npm install --save-dev vite-plugin-wasm

import wasm from "vite-plugin-wasm";

export default {
  plugins: [wasm()]
};

AudioRecognizer は、認証の初期化、セッション管理、パックのキャッシュ、マイクによる認識を処理します。ephemeral keyは、アプリケーションのバックエンドまたはサーバーレスエンドポイントから取得してください。

import { AudioRecognizer } from "@sorisdk/web-audio";

const recognizer = new AudioRecognizer({
  appId: "YOUR_APP_ID",
  ephemeralKey: async () => {
    const response = await fetch("/api/ephemeral-key", {
      method: "POST"
    });

    if (!response.ok) {
      throw new Error(`Ephemeral key request failed: HTTP ${response.status}`);
    }

    const { ephemeral_key } = await response.json();
    return ephemeral_key;
  }
});

recognizer.on("campaign", (event) => {
  console.log(event.campaign);
});

recognizer.on("error", ({ error }) => {
  console.error(error);
});

await recognizer.start();

認識を終了するときやページを破棄するときは、stop() または destroy() を呼び出してください。

ブラウザ向けスタンドアロンモジュール

npmやバンドラーを使用しないブラウザアプリケーションでは、正確なバージョン URLからスタンドアロンESMモジュールを直接インポートします。これはブラウザ標準のモジュールインポートであり、グローバルAPIは作成されません。

html

<script type="module">
  import { AudioRecognizer } from
    "https://cdn.iplateia.com/web/sorisdk/v0.6.10/sori-web-audio.mjs";

  const recognizer = new AudioRecognizer({
    appId: "YOUR_APP_ID",
    ephemeralKey: async () => {
      const response = await fetch("/api/ephemeral-key", {
        method: "POST"
      });

      if (!response.ok) {
        throw new Error(`Ephemeral key request failed: HTTP ${response.status}`);
      }

      const { ephemeral_key } = await response.json();
      return ephemeral_key;
    }
  });

  recognizer.on("campaign", (event) => {
    console.log(event.campaign);
  });

  recognizer.on("error", ({ error }) => {
    console.error(error);
  });

  await recognizer.start();
</script>

本番環境では正確なバージョンを固定し、可変の latest URLに置き換えないでください。

Ephemeral Keyエンドポイントの保護

スタンドアロンモジュールを使うとフロントエンドのビルドは不要になりますが、信頼できるサーバーは引き続き必要です。有効期間の長いアプリケーションシークレットをブラウザコードに埋め込まないでください。

アプリケーション運営者は、製品に適した認証または匿名セッション検証に加え、ユーザー、IP、セッション単位のレート制限、発行クォータ、不正利用の監視によって、ephemeralKey が利用するエンドポイントを保護する責任があります。エンドポイントが別オリジンにある場合はCORSヘッダーが必要になることがありますが、CORSは認証ではなく、スクリプト、ボット、ブラウザ以外のクライアントからの呼び出しを防ぐものではありません。

キー発行とrelayパターンは Ephemeral Key を参照してください。

Content Security Policy

厳格なContent Security Policy（CSP）を使用する場合は、 'wasm-unsafe-eval' でWebAssemblyのコンパイルを許可します。 https://cdn.iplateia.com を script-src と connect-src の両方に追加し、 SORI APIとephemeral keyエンドポイントのオリジンも connect-src に追加してください。例：

text

script-src 'self' 'wasm-unsafe-eval' https://cdn.iplateia.com;
connect-src 'self' https://cdn.iplateia.com https://console.soriapi.com;

ephemeral keyエンドポイントが別のオリジンを使用する場合は、そのオリジンを connect-src に追加します。スタンドアロンの例ではインラインモジュールスクリプトを使用しているため、CSP nonceまたはhashで許可するか、許可済みの外部スクリプトへ移動してください。この連携のためだけに 'unsafe-inline' を有効にしないでください。

Web SDK ​

前提条件 ​

npm・バンドラー連携 ​

ブラウザ向けスタンドアロンモジュール ​

Ephemeral Keyエンドポイントの保護 ​

Content Security Policy ​