اعرض الشخصية التعريفية لوكيلك في تطبيق Flutter مع Wixzel Voice

ما الذي تحتاجه قبل أن تبدأ؟

• وكيل على Wixzel Voice ومفتاح API مع رصيد، محفوظ على خادمك. أي وكيل يصلح: لكل وكيل شخصية تعريفية، بدءًا من الشخصية الخضراء الافتراضية.
• Flutter 3.27 أو أحدث.
• خادم تتحكم فيه ويمكنه استدعاء الـ API. يستخدم المثال Node.js وTypeScript SDK.
• إضافة تسجيل تبث PCM بدقة 16 بت، ويُفضَّل بتردد 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);

   الوكيل الذي لا مواصفة له يحصل على المظهر الافتراضي. الشخصية التعريفية القريبة من الأسود أو الأبيض تقف على خلفية بلونها الخاص، حتى لا تختفي في شاشة داكنة أو فاتحة؛ أوقف ذلك عبر stage: false. اللمسة تُشغّل تعبيرًا، ويشغّل MascotController الحركات بالاسم، مثل mascot.play('hello').

4. 04اربط الشخصية التعريفية بمكالمة

   اتصل عبر RealtimeConnection من Dart SDK وسلّمه إلى 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 التي تنطبق على هذا البناء؟

• لا تسجّل الحزمة الصوت ولا تشغّله. يوفّر تطبيقك كليهما عبر الإضافات التي يختارها.
• صوت بجودة الهاتف: G.711 µ-law بتردد 8 kHz في الاتجاهين.
• تُحتسب الجلسات ضمن حد المكالمات المتزامنة للحساب، خمس افتراضيًا.
• Flutter 3.27 أو أحدث. يحتاج الميلان إلى مقياس تسارع؛ وبدونه تتلفّت الشخصية التعريفية من تلقاء نفسها.
• تغيير مظهر الشخصية التعريفية استدعاء API من خادمك (agents.updateMascot)، لا من التطبيق، لأنه يحتاج إلى مفتاح API الخاص بك.