用 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 金鑰絕不放進應用程式。由您的伺服器取得代理並建立一個有效一分鐘、只能使用一次的工作階段，應用程式再向您的伺服器索取這兩者：

   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) 顯示它，使用與通話驅動的同一個控制器。畫面關閉時請釋放（dispose）該控制器。

   在錄音器中開啟平台的回音消除，否則代理會透過喇叭聽到自己的聲音並打斷自己。

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 限制？

• 這個套件不會錄製或播放音訊。兩者都由您的應用程式透過自選的外掛提供。
• 電話等級音質：雙向皆為 8 kHz 的 G.711 µ-law。
• 工作階段計入帳號的同時通話上限，預設五通。
• 需要 Flutter 3.27 或更新版本。傾斜功能需要加速度計；沒有的話，吉祥物會自己四處張望。
• 更改吉祥物外觀需要從您的伺服器呼叫 API（agents.updateMascot），而不是從應用程式，因為這需要您的 API 金鑰。