Wixzel Voice로 Flutter 앱에 에이전트 마스코트 표시하기

시작하기 전에 무엇이 필요한가요?

• Wixzel Voice 에이전트와 크레딧이 있는 API 키(서버에 보관). 모든 에이전트에 마스코트가 있으므로(처음에는 기본 초록색 마스코트) 어떤 에이전트든 됩니다.
• Flutter 3.27 이상.
• API를 호출할 수 있는, 직접 관리하는 서버. 예제는 Node.js와 TypeScript SDK를 사용합니다.
• 16비트 PCM을 스트리밍하는 녹음 플러그인(가능하면 8 kHz 모노, 에코 제거 지원)과 raw 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);

   사양이 없는 에이전트는 기본 모습으로 그려집니다. 검은색이나 흰색에 가까운 마스코트는 자기 색의 배경(stage) 위에 놓이므로 어둡거나 밝은 화면에 묻히지 않습니다. 이 기능은 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입니다.
• 세션은 계정의 동시 통화 한도(기본 5건)에 포함됩니다.
• Flutter 3.27 이상이 필요합니다. 기울기 반응에는 가속도계가 필요하며, 가속도계가 없으면 마스코트가 스스로 주위를 둘러봅니다.
• 마스코트 모습 변경은 API 키가 필요하므로 앱이 아니라 서버에서 하는 API 호출(agents.updateMascot)입니다.