Wixzel VoiceでWebSocket経由のFlutter音声エージェントを追加する

始める前に何が必要ですか？

• クレジットのあるWixzel VoiceのAPIキー。サーバーに保管します。
• セッションを発行するための、ご自身で管理するサーバー。例ではNode.jsとExpressを使いますが、HTTPSリクエストを送れる言語なら何でも使えます。
• 16ビットPCMをストリーミングできる録音プラグイン（できれば8 kHzモノラルでエコーキャンセル付き）と、生のPCMを再生できるプレーヤーを使うFlutterアプリ。

Wixzel Voiceでこれを構築する手順は？

1. 01エージェントを一度だけ作成する

   このエージェントはGemini Liveを使います。聞く、考える、話すを1つでこなすリアルタイムモデルです。

   shellコピー

   curl https://api.voice.wixzel.com/v1/agents \
     -H "Authorization: Bearer $WIXZEL_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "In-app assistant",
       "system_prompt": "You are the voice assistant inside the Acme app. Answer in one or two short sentences.",
       "opening_message": "Hi, what can I help you with?",
       "voice": {
         "realtime": { "model": "google/gemini-live", "voice": "Kore" }
       }
     }'

   このエージェントにはアプリ固有の設定はありません。同じエージェントが電話番号に応答することもできます。idはサーバーにAGENT_IDとして保管しておきます。

2. 02サーバーでセッションを発行する

   アプリがAPIキーを持つことはありません。アプリはサーバーに依頼し、サーバーがPOST /v1/realtime/sessionsでAPIにセッションを要求します。ここではTypeScript SDKを使います。

   server.mjsコピー

   import express from 'express';
   import { WixzelVoice } from 'wixzel-voice';
   
   const wixzel = new WixzelVoice({ apiKey: process.env.WIXZEL_API_KEY });
   const app = express();
   
   // Replace with your own authentication. It must set req.userId.
   function requireUser(req, res, next) {
     req.userId = 'demo-user';
     next();
   }
   
   app.post('/voice/session', requireUser, async (req, res) => {
     const session = await wixzel.realtime.createSession({
       agent_id: process.env.AGENT_ID,
       max_duration_seconds: 300,
       metadata: { user_id: req.userId },
     });
     res.json(session);
   });
   
   app.listen(3000);

   レスポンスには、ソケットのurl、このエージェントに対して1分間に1回だけ使えるclient_secret、audio_format: "mulaw_8000"が含まれます。発行は無料で、課金はアプリが接続した時点から始まります。max_duration_secondsは会話の長さの上限で、10〜3600秒の範囲で指定でき、デフォルトは600秒です。metadataは通話記録にそのまま返され、モデルに送られることはありません。allowed_originsはブラウザでのみ意味があるため、ネイティブアプリでは省略します。

3. 03アプリから接続する

   flutter pub add wixzel_voice httpでSDKを追加し、サーバーが返したセッションを開きます。

   voice_call.dartコピー

   import 'dart:async';
   import 'dart:convert';
   import 'dart:typed_data';
   
   import 'package:http/http.dart' as http;
   import 'package:wixzel_voice/wixzel_voice.dart';
   
   /// Whatever your playback plugin offers, behind a small interface.
   abstract class PcmPlayer {
     void add(Int16List samples);
     void clear();
   }
   
   class VoiceCall {
     VoiceCall({required this.player, required this.onLine});
   
     final PcmPlayer player;
     final void Function(String role, String text) onLine;
   
     RealtimeConnection? _conn;
     StreamSubscription<Uint8List>? _mic;
     final List<int> _pending = [];
   
     /// [micBytes] is 16-bit little-endian PCM, 8 kHz mono, from your recording plugin.
     Future<void> start(Stream<Uint8List> micBytes) async {
       final res = await http.post(Uri.parse('https://api.example.com/voice/session'));
       final status = res.statusCode;
       if (status != 200) throw Exception('Could not start a voice session: HTTP $status');
       final session = RealtimeSession.fromJson(jsonDecode(res.body) as Map<String, dynamic>);
   
       final conn = RealtimeConnection.forSession(session);
       _conn = conn;
       conn.events.listen((event) {
         switch (event) {
           case RealtimeAudio(:final mulaw):
             player.add(mulawToPcm16(mulaw));
           case RealtimeAudioClear():
             player.clear(); // the user interrupted: drop queued audio
           case RealtimeTranscript(:final role, :final text):
             onLine(role, text);
           case RealtimeError(:final code, :final message):
             onLine('error', '$code: $message');
           case RealtimeEnded(:final reason):
             onLine('system', 'ended: $reason');
             _mic?.cancel();
           default:
         }
       });
       await conn.ready;
       _mic = micBytes.listen(_send);
     }
   
     void _send(Uint8List bytes) {
       final data = ByteData.sublistView(bytes);
       for (var i = 0; i + 1 < bytes.length; i += 2) {
         _pending.add(data.getInt16(i, Endian.little));
       }
       // 160 samples is 20 ms at 8 kHz, the frame size the server expects.
       while (_pending.length >= 160) {
         final frame = Int16List.fromList(_pending.sublist(0, 160));
         _pending.removeRange(0, 160);
         _conn?.sendAudio(pcm16ToMulaw(frame));
       }
     }
   
     Future<void> end() async {
       await _mic?.cancel();
       await _conn?.end();
     }
   }

   RealtimeConnectionが扱うのはプロトコルだけです。マイクやスピーカーは開かないため、SDKはプラグインに依存せず、すでに使っている音声プラグインをそのまま使えます。pcm16ToMulawとmulawToPcm16は、16ビットPCMと通信で送る形式を相互に変換します。

   先にマイクの権限を求めてください。AndroidではRECORD_AUDIO、iOSではNSMicrophoneUsageDescriptionです。

4. 04エコーキャンセルを有効にし、電話並みの音質を前提にする

   録音プラグインで、プラットフォームのエコーキャンセルを有効にしてください。これがないと、エージェントがスピーカーから自分の声を聞いて、自分の発話を遮ってしまいます。

   音声は双方向ともG.711 µ-law、8 kHzで、電話回線と同じです。セッションが通話と同じメディア経路を通るためです。会話には十分ですが、広帯域の音声より帯域は狭くなります。プラグインが対応していれば8 kHzで録音し、そうでなければpcm16ToMulawの前にリサンプリングして、エージェントの音声は8 kHzモノラルで再生してください。

5. 05セッションの記録を確認する

   すべてのセッションは、channel: "web"の通話記録になります。

   shellコピー

   curl "https://api.voice.wixzel.com/v1/calls?channel=web&limit=5" \
     -H "Authorization: Bearer $WIXZEL_API_KEY"

   Webセッションは着信として記録され、fromとtoはなく、通話時間、cost_micros、指定したmetadataを含みます。GET /v1/calls/{id}では文字起こしも取得できます。終了時には電話と同じcallCompleted Webhookが送信されます。Webセッションは録音されません。

Wixzel Voiceでこの構築にかかる費用は？

この構築に関係するWixzel Voiceの制限は？

• 電話並みの音質です。双方向ともG.711 µ-law、8 kHzで、広帯域ではありません。
• Dart SDKは音声の録音や再生を行いません。マイクとスピーカーは、アプリが任意のプラグインで用意します。
• セッションは電話と合わせて、アカウントの同時通話数の上限（デフォルトは5件）に数えられます。上限は申請により引き上げられます。
• セッションの長さはデフォルトで10分、最長で1時間で、2分間無音が続くと終了します。
• Webセッションは録音されず、ユーザーを人間の担当者に引き継ぐための別回線もありません。