realtime-avatar 0.37.0 → 0.39.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -259,6 +259,24 @@ and fetch, including a pending `next()`. The smaller of `timeoutMs` and `totalTi
259
259
  covers the entire request/body, including pauses between iterations. **Never automatically
260
260
  retry** an ambiguous paid request. Cancellation does not prove that billing stopped.
261
261
 
262
+ ### Live speech session
263
+
264
+ `openSpeechSession(voiceId, { maxTextBytes, latency?, chunkLength?, language? }, { signal? })`
265
+ opens `GET /voices/{voiceId}/speech/live` as a WebSocket and resolves once the platform admitted
266
+ the session, so every refusal rejects the promise. Send `text(utterance, text)` (utterance 0 first,
267
+ at most `chunkLength` characters each), `flush(utterance)` to speak it and open the next, `end()`
268
+ and `cancel()`. Iterate it once for `started`, per-utterance `audio` (`sampleOffset` from the
269
+ utterance's start), `alignment` (replaces that utterance's snapshot, may arrive late) and
270
+ `utterance-end`, then one `completed` or `failed`. Frames are validated by the generated
271
+ `speechLiveClientMessageSchema` and `speechLiveServerMessageSchema` in both directions;
272
+ non-contiguous audio or a skipped utterance fails the session.
273
+
274
+ Billing is for the UTF-8 bytes sent: cancel, disconnect, `break` and abort still bill them, and a
275
+ provider failure refunds. Never retried. In Workers the upgrade is a `fetch` with the
276
+ `Authorization` header and a refusal is a `RealtimeAvatarHttpError`; in Node 22 it is the global
277
+ `WebSocket`, which reports no status, so a refusal is a `RealtimeAvatarError`. `timeoutMs` bounds
278
+ opening and `totalTimeoutMs`, if set, the whole session.
279
+
262
280
  ## Custom voice (webhook)
263
281
 
264
282
  Speak a call in your own voice. Each sentence she is about to say is POSTed, signed, to an
@@ -482,6 +500,8 @@ rta.getConnectionHistory(sessionId) // bounded LiveKit observations; requires
482
500
  rta.createSpeech(voiceId, { text, format?, speed?, language? }, { signal? })
483
501
  // unreleased streaming candidate; generated SSE events, never retried
484
502
  rta.createSpeechStream(voiceId, { text, speed?, language? }, { signal? })
503
+ // live session: text in while it is written, PCM + alignment per utterance; WebSocket, never retried
504
+ rta.openSpeechSession(voiceId, { maxTextBytes, latency?, chunkLength?, language? }, { signal? })
485
505
 
486
506
  // pre-rendered video (MP4, no live call); server only, requires renders:write / renders:read
487
507
  rta.createRender({ avatarId, voiceId? | voice?, lipGain?, shots }) // 202 queued; one Idempotency-Key across retries
@@ -492,7 +512,7 @@ rta.iterateRenders({ limit? }) // every render, paging handled
492
512
  rta.getRenderAccess(renderId) // { id, url, expiresAt }; signed for an hour, renew when needed
493
513
 
494
514
  // avatars
495
- rta.createLive2dAvatar({ displayName, voice, settings?, metadata? }) // app-owned rig, explicit voice, no assets
515
+ rta.createAnimaAvatar({ displayName, voice, settings?, metadata? }) // app-owned rig and rendering, explicit voice, no assets
496
516
  rta.createAvatarFromImage({ displayName, imageUrl, motionPrompt?, voice? }) // platform-rendered video
497
517
  rta.createAvatarFromVideo({ displayName, videoUrl, voice? }) // DEPRECATED — closed, 422
498
518
  rta.listAvatars()
@@ -544,10 +564,10 @@ const voice: VoiceSpecInput = {
544
564
  };
545
565
  ```
546
566
 
547
- ### Register an app-owned Live2D rig
567
+ ### Register an Anima avatar (your app owns the rig and the rendering)
548
568
 
549
569
  ```ts
550
- const avatar = await rta.createLive2dAvatar({
570
+ const avatar = await rta.createAnimaAvatar({
551
571
  displayName: "Rin",
552
572
  voice: { provider: "fish", voice_id: "your-provider-voice-id", model: "s2-pro" },
553
573
  metadata: { characterId: "your-character-id" },
@@ -556,18 +576,21 @@ const avatar = await rta.createLive2dAvatar({
556
576
  const call = await rta.startCall({ avatarId: avatar.id, mode: "voice" });
557
577
  ```
558
578
 
559
- Requires the platform's Live2D identity support. One `POST /avatars` sends `renderer: "live2d"`,
579
+ Requires the platform's `anima` renderer. One `POST /avatars` sends `renderer: "anima"`,
560
580
  `sourceKind: "image"` and an explicit voice selector; no assets, automatic casting, clips or
561
- resting-loop generation are requested. Your app owns the rig. Source fields, motion prompts,
581
+ resting-loop generation are requested. Your app owns the rig and the rendering. Source fields, motion prompts,
562
582
  renderer overrides and automatic voice descriptions are refused before network I/O.
563
583
  `settings` and `metadata` are optional records and are omitted unless provided.
564
584
 
565
- The exported `CreateLive2dAvatarInput` and complete `RegisteredAvatar` response derive from
585
+ The exported `CreateAnimaAvatarInput` and complete `RegisteredAvatar` response derive from
566
586
  canonical generated schemas. The response is parsed once; malformed successful responses throw
567
587
  `RealtimeAvatarError` without the rejected body. Existing image/video creation requests are
568
588
  unchanged. Existing avatar methods retain `renderer`, defaulting older responses that omit it to
569
589
  `"video"`.
570
590
 
591
+ `renderer: "anima"` replaced `live2d` in 0.38.0 with no alias: the platform refuses `live2d` and
592
+ SDK 0.37.0 and earlier cannot parse an `anima` avatar, so upgrade once the platform serves `anima`.
593
+
571
594
  ### Validate persisted grants and proxy requests
572
595
 
573
596
  The server root (`realtime-avatar` or `realtime-avatar/server`) exports the existing
@@ -1,4 +1,4 @@
1
- import { RealtimeAvatar, ROUTE_TIMEOUT_MS, proxyEndRequestSchema, proxyConnectRequestSchema, isQueued, RealtimeAvatarHttpError, RealtimeAvatarError } from './chunk-RBK6EHVH.js';
1
+ import { RealtimeAvatar, ROUTE_TIMEOUT_MS, proxyEndRequestSchema, proxyConnectRequestSchema, isQueued, RealtimeAvatarHttpError, RealtimeAvatarError } from './chunk-YBKE7SDI.js';
2
2
 
3
3
  // ../http-client/src/generated/error-semantics.ts
4
4
  var ERROR_SEMANTICS = {