Wixzel VoiceのエージェントのマスコットをFlutterアプリに表示する

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

• Wixzel Voiceのエージェントと、クレジットのあるAPIキー（サーバーに保管）。どのエージェントでも使えます。すべてのエージェントにマスコットがあり、最初はデフォルトの緑色のマスコットです。
• Flutter 3.27以降。
• APIを呼び出せる、ご自身で管理するサーバー。例ではNode.jsとTypeScript SDKを使います。
• 16ビットPCMをストリーミングできる録音プラグイン（できれば8 kHzモノラルでエコーキャンセル付き）と、生のPCMを再生できるプレーヤー。たとえばrecordとflutter_pcm_soundです。

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

1. 01パッケージを追加する

   wixzel_voice_flutterがマスコットを描画し、wixzel_voiceはその土台となるDart SDKです。

   pubspec.yamlコピー

   dependencies:
     wixzel_voice: ^0.8.0
     wixzel_voice_flutter: ^0.1.0
     http: ^1.2.0

   このパッケージはsensors_plusに依存しており、マスコットの目がスマートフォンの傾きを追えるようになっています。またvisibility_detectorにも依存しており、画面に表示されている間だけアニメーションします。音声の録音や再生は行いません。

2. 02サーバーからアプリにエージェントとセッションを渡す

   APIキーはアプリに入れません。サーバーがエージェントを取得し、1分間有効な使い捨てのセッションを発行し、アプリはその両方をサーバーに要求します。

   server.mjsコピー

   import express from 'express';
   import { WixzelVoice } from 'wixzel-voice';
   
   const wixzel = new WixzelVoice({ apiKey: process.env.WIXZEL_API_KEY });
   const app = express();
   const AGENT_ID = process.env.AGENT_ID;
   
   // Put your own sign-in check in front of both routes.
   app.get('/agent', async (req, res) => {
     res.json(await wixzel.agents.retrieve(AGENT_ID));
   });
   
   app.post('/session', async (req, res) => {
     res.json(await wixzel.realtime.createSession({ agent_id: AGENT_ID, max_duration_seconds: 300 }));
   });
   
   app.listen(3000);

   エージェントのJSONには、マスコットを描画するための小さな仕様であるmascot.specが含まれます。セッションの発行は無料で、課金はアプリが接続した時点から始まります。

3. 03マスコットを描画する

   Agent.fromJsonがサーバーから送られた内容を読み込み、AgentMascotViewが描画します。

   agent_face.dartコピー

   import 'dart:convert';
   
   import 'package:flutter/widgets.dart';
   import 'package:http/http.dart' as http;
   import 'package:wixzel_voice/wixzel_voice.dart';
   import 'package:wixzel_voice_flutter/wixzel_voice_flutter.dart';
   
   const backendUrl = 'https://api.example.com';
   
   Future<Agent> loadAgent() async {
     final res = await http.get(Uri.parse('$backendUrl/agent'));
     return Agent.fromJson(jsonDecode(res.body) as Map<String, dynamic>);
   }
   
   Widget agentFace(Agent agent, MascotController controller) =>
       AgentMascotView(agent: agent, controller: controller, size: 220);
   
   // In a list, draw one frame and run no animation:
   Widget agentRow(Agent agent) => AgentMascotView(agent: agent, size: 40, still: true);

   specのないエージェントにはデフォルトの見た目が使われます。黒に近い、または白に近いマスコットは、暗い画面や明るい画面に埋もれないよう、自分の色のステージの上に表示されます。これはstage: falseでオフにできます。タップすると表情が再生され、MascotControllerではmascot.play('hello')のように名前を指定して動きを再生できます。

4. 04マスコットを通話につなぐ

   Dart SDKのRealtimeConnectionで接続し、それをMascotRealtimeLinkに渡します。このリンクにより、マスコットは通話の接続中は考え、あいさつで手を振り、ユーザーが話している間は聞き、エージェントの音声に合わせて口を動かします。

   talk.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';
   import 'package:wixzel_voice_flutter/wixzel_voice_flutter.dart';
   
   /// Your audio plugins, behind a small interface.
   abstract class PcmPlayer {
     void add(Int16List samples); // 16-bit PCM, 8 kHz mono
     void clear();
   }
   
   class MascotCall {
     MascotCall(this.mascot, this.player);
   
     final MascotController mascot;
     final PcmPlayer player;
     RealtimeConnection? _conn;
     MascotRealtimeLink? _link;
     StreamSubscription<Int16List>? _mic;
   
     /// [micFrames] is 16-bit PCM at 8 kHz in 160-sample (20 ms) frames.
     Future<void> start(Stream<Int16List> micFrames) async {
       final res = await http.post(Uri.parse('https://api.example.com/session'));
       final session = RealtimeSession.fromJson(jsonDecode(res.body) as Map<String, dynamic>);
   
       final conn = RealtimeConnection.forSession(session);
       _conn = conn;
       _link = MascotRealtimeLink(mascot, conn);
       conn.events.listen((event) {
         switch (event) {
           case RealtimeAudio(:final mulaw):
             player.add(mulawToPcm16(mulaw)); // the mouth follows this audio through the link
           case RealtimeAudioClear():
             player.clear(); // the user spoke over the agent
           case RealtimeEnded():
             unawaited(end());
           default:
         }
       });
       await conn.ready;
       _mic = micFrames.listen((frame) {
         conn.sendAudio(pcm16ToMulaw(frame));
         _link?.micAudio(frame); // it leans in while the user talks
       });
     }
   
     Future<void> end() async {
       await _mic?.cancel();
       await _link?.dispose(); // leaves the mascot idle; does not end the call
       await _conn?.end();
       _mic = null;
       _link = null;
       _conn = null;
     }
   }

   表示にはAgentMascotView(agent: agent, controller: mascot)を使います。通話が動かすのと同じコントローラーです。画面を閉じるときはコントローラーを破棄してください。

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

5. 05プレーヤーが音声をスケジュールするなら、口の動きを正確に合わせる

   デフォルトでは、リンクはプレーヤーが各チャンクを受け取ってから約120 ms後に再生を始めると想定しています。プレーヤーが各チャンクの再生時刻を正確に把握している場合は、代わりにそれをリンクに伝えます。

   exact_timing.dartコピー

   import 'dart:typed_data';
   
   import 'package:wixzel_voice/wixzel_voice.dart';
   import 'package:wixzel_voice_flutter/wixzel_voice_flutter.dart';
   
   MascotRealtimeLink exactLink(MascotController mascot, RealtimeConnection conn) =>
       MascotRealtimeLink(mascot, conn, estimatePlayback: false);
   
   // In your player, each time it schedules a chunk, on the player's own clock:
   void scheduled(MascotRealtimeLink link, Int16List pcm, double playAt, double now) {
     link.agentAudio(pcm, playAt: playAt, currentTime: now, sampleRate: 8000);
   }

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

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

• このパッケージは音声の録音や再生を行いません。どちらもアプリが任意のプラグインで用意します。
• 電話並みの音質です。双方向ともG.711 µ-law、8 kHzです。
• セッションは、アカウントの同時通話数の上限（デフォルトは5件）に数えられます。
• Flutter 3.27以降が必要です。傾きの追従には加速度センサーが必要で、ない場合はマスコットが自分であたりを見回します。
• マスコットの見た目の変更は、APIキーが必要なため、アプリからではなくサーバーからのAPI呼び出し（agents.updateMascot）で行います。