Muestra la mascota de tu agente en Flutter con Wixzel Voice

¿Qué necesitas antes de empezar?

• Un agente de Wixzel Voice y una clave de API con crédito, guardada en tu servidor. Sirve cualquier agente: todos tienen una mascota, empezando por la verde predeterminada.
• Flutter 3.27 o posterior.
• Un servidor que controles y que pueda llamar a la API. El ejemplo usa Node.js y el SDK de TypeScript.
• Un plugin de grabación que transmita PCM de 16 bits, idealmente a 8 kHz mono con cancelación de eco, y un reproductor que acepte PCM sin procesar, como record y flutter_pcm_sound.

¿Cómo construyes esto en Wixzel Voice, paso a paso?

1. 01Añade los paquetes

   wixzel_voice_flutter dibuja la mascota; wixzel_voice es el SDK de Dart sobre el que se construye:

   pubspec.yamlCopiar

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

   El paquete depende de sensors_plus, para que los ojos de la mascota sigan la inclinación del teléfono, y de visibility_detector, para que solo se anime mientras está en pantalla. No graba ni reproduce audio.

2. 02Dale a la app el agente y una sesión, desde tu servidor

   Tu clave de API nunca va en la app. Tu servidor obtiene el agente y crea una sesión de un solo uso válida durante un minuto, y la app le pide ambas cosas a tu servidor:

   server.mjsCopiar

   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);

   El JSON del agente incluye mascot.spec, la pequeña especificación a partir de la cual se dibuja la mascota. Crear una sesión no cuesta nada; la facturación empieza cuando la app se conecta.

3. 03Dibuja la mascota

   Agent.fromJson lee lo que envió tu servidor, y AgentMascotView lo dibuja:

   agent_face.dartCopiar

   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);

   Un agente sin spec recibe el aspecto predeterminado. Una mascota casi negra o casi blanca se coloca sobre un fondo de su propio color, para que no desaparezca en una pantalla oscura o clara; desactívalo con stage: false. Un toque reproduce una expresión, y MascotController reproduce movimientos por nombre, como mascot.play('hello').

4. 04Vincula la mascota a una llamada

   Conéctate con RealtimeConnection del SDK de Dart y pásaselo a MascotRealtimeLink. El vínculo hace que la mascota piense mientras la llamada se conecta, salude, escuche mientras el usuario habla y mueva la boca con el audio del agente:

   talk.dartCopiar

   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;
     }
   }

   Muéstrala con AgentMascotView(agent: agent, controller: mascot), el mismo controlador que maneja la llamada. Libera el controlador cuando la pantalla desaparezca.

   Activa la cancelación de eco de la plataforma en tu grabadora, o el agente se oirá a sí mismo por el altavoz y se interrumpirá.

5. 05Haz exacta la sincronización labial, si tu reproductor programa el audio

   Por defecto, el vínculo supone que tu reproductor empieza cada fragmento unos 120 ms después de recibirlo. Si tu reproductor sabe exactamente cuándo suena un fragmento, díselo al vínculo:

   exact_timing.dartCopiar

   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);
   }

¿Cuánto cuesta esto en Wixzel Voice?

¿Qué límites de Wixzel Voice se aplican a esto?

• El paquete no graba ni reproduce audio. Tu app aporta ambas cosas mediante los plugins que elija.
• Audio de calidad telefónica: G.711 µ-law a 8 kHz en ambas direcciones.
• Las sesiones cuentan para el límite de llamadas simultáneas de la cuenta, cinco por defecto.
• Flutter 3.27 o posterior. La inclinación necesita un acelerómetro; sin él, la mascota mira a su alrededor por sí sola.
• Cambiar el aspecto de una mascota es una llamada a la API desde tu servidor (agents.updateMascot), no desde la app, porque necesita tu clave de API.