realtime-avatar 0.29.0 → 0.31.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 +123 -1
- package/dist/{chunk-MMO5AQN4.js → chunk-LRGQKZFB.js} +178 -38
- package/dist/{chunk-HC7O44WE.js → chunk-TJM53JXR.js} +1 -1
- package/dist/express.d.ts +2 -2
- package/dist/express.js +2 -2
- package/dist/hono.d.ts +2 -2
- package/dist/hono.js +2 -2
- package/dist/index.d.ts +195 -12
- package/dist/index.js +1 -1
- package/dist/nextjs.d.ts +2 -2
- package/dist/nextjs.js +2 -2
- package/dist/{proxy-client-BJQxlVHz.d.ts → proxy-client-BlaFxR6S.d.ts} +4 -2
- package/dist/react-native.d.ts +2 -2
- package/dist/react-native.js +1 -1
- package/dist/react.d.ts +2 -2
- package/dist/react.js +1 -1
- package/dist/server.d.ts +2 -2
- package/dist/server.js +1 -1
- package/dist/tanstack-start.d.ts +2 -2
- package/dist/tanstack-start.js +2 -2
- package/dist/{types-Bv29uEAs.d.ts → types-DOFXGl7G.d.ts} +518 -5
- package/dist/{types-CgAEmIVE.d.ts → types-Du6T6XQB.d.ts} +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -243,6 +243,98 @@ return new Response(await myTts(text, voice_id), { headers: { "content-type": "a
|
|
|
243
243
|
Working endpoints: `apps/quickstart/nextjs-app-router/app/api/voice/route.ts` and `POST /api/voice`
|
|
244
244
|
in `apps/quickstart/python-fastapi/main.py`.
|
|
245
245
|
|
|
246
|
+
## Pre-rendered video
|
|
247
|
+
|
|
248
|
+
**Everything in one shot happens at the same time; shots play one after another.**
|
|
249
|
+
|
|
250
|
+
```ts
|
|
251
|
+
const render = await rta.createRender({
|
|
252
|
+
avatarId: "ava_0123456789abcdef0123456789abcdef",
|
|
253
|
+
shots: [
|
|
254
|
+
{ clipId: "gesture_send_flower", say: "你终于来了。今天……我有话想对你说。" },
|
|
255
|
+
{ clipId: "idle_touch_collar", say: "别笑,我是认真的。", pauseAfterMs: 800 },
|
|
256
|
+
{ say: "所以,今晚留下来。" },
|
|
257
|
+
],
|
|
258
|
+
});
|
|
259
|
+
const done = await rta.waitForRender(render.id);
|
|
260
|
+
if (done.status === "failed") throw new Error(done.error?.message);
|
|
261
|
+
const { url, expiresAt } = await rta.getRenderAccess(done.id); // <video src={url}> plays it
|
|
262
|
+
```
|
|
263
|
+
|
|
264
|
+
She sends the flower while she says the first line, touches her collar while she says the
|
|
265
|
+
second and then stays quiet for 800 ms, and says the last line without a new clip. The result is
|
|
266
|
+
an MP4 (H.264 + AAC, 25 fps) with the same face, clips, voice and lip-sync as a call, made
|
|
267
|
+
offline with no call and no LiveKit room. The avatar id is a placeholder: use your own
|
|
268
|
+
`avatarId`, and clip ids from `listClips(avatarId)`.
|
|
269
|
+
|
|
270
|
+
| Field | What it is |
|
|
271
|
+
| --- | --- |
|
|
272
|
+
| `avatarId` | The avatar. |
|
|
273
|
+
| `voiceId` | A voice from your workspace's voice library. |
|
|
274
|
+
| `voice` | An inline Fish voice, the same object a call takes: `{ provider: "fish", voice_id, model?, speed?, emotion?, language? }`. |
|
|
275
|
+
| `lipGain` | Mouth-motion amplitude, as on a call. Omit it for the default. |
|
|
276
|
+
| `shots` | The script: 1 to 50 shots, played one after another. |
|
|
277
|
+
| `shots[].clipId` | What she does: a ready clip from the avatar's clip library, or `"primary"` for the avatar's own video. Omit it to keep the current loop clip. |
|
|
278
|
+
| `shots[].say` | What she says, 1 to 1,000 characters after trimming whitespace; a blank `say` is refused. Speech starts when the shot starts. |
|
|
279
|
+
| `shots[].pauseAfterMs` | How long she stays silent after speaking, 0 to 10,000 ms. Default 0. |
|
|
280
|
+
|
|
281
|
+
**How long a shot lasts.** Its speech plus `pauseAfterMs`, or its clip's action if that is
|
|
282
|
+
longer, rounded up to 200 ms. A loop clip does not set a shot's length: a shot with only a loop
|
|
283
|
+
clip lasts 200 ms, so add `pauseAfterMs` to hold it.
|
|
284
|
+
|
|
285
|
+
**Which clips loop.** A clip loops if it is `"primary"` or in the avatar's idle pool
|
|
286
|
+
(`listClips(avatarId).behavior.idle.clips`); every other clip plays once, so a listening clip
|
|
287
|
+
or an action that is not also in the idle pool plays once. The clip list has no per-clip
|
|
288
|
+
`playback`; read `behavior.idle.clips` from it.
|
|
289
|
+
|
|
290
|
+
- **once**, an action: it plays exactly once from its first frame and is never cut. If the shot
|
|
291
|
+
runs longer, she continues on the loop clip from before the shot. The same clip in two shots
|
|
292
|
+
in a row plays twice.
|
|
293
|
+
- **loop**: it fills the shot, and the same loop clip in shots in a row continues without
|
|
294
|
+
restarting.
|
|
295
|
+
|
|
296
|
+
The video opens with about 400 ms and closes with about 600 ms on the current loop clip.
|
|
297
|
+
|
|
298
|
+
**Where each shot landed.** A `ready` render carries `timeline`, one entry per shot, in order.
|
|
299
|
+
Every time is milliseconds from the start of the video.
|
|
300
|
+
|
|
301
|
+
| Field | What it is |
|
|
302
|
+
| --- | --- |
|
|
303
|
+
| `index` | The shot's position in your `shots`, from 0. |
|
|
304
|
+
| `startMs` · `endMs` | When the shot starts and ends; the next shot starts at `endMs`. |
|
|
305
|
+
| `clipId` | The clip the shot played: the one you named, else the loop clip it kept, else `"primary"`. |
|
|
306
|
+
| `playback` | `"once"` or `"loop"`. |
|
|
307
|
+
| `speechStartMs` · `speechEndMs` | When she starts and stops speaking. `null` when the shot has no `say`. |
|
|
308
|
+
| `clipEndMs` | When the action finished. Once clips only, else `null`. |
|
|
309
|
+
| `afterClipId` | The loop clip shown after the action, when the shot outlasts it. Once clips only, else `null`. |
|
|
310
|
+
|
|
311
|
+
- **The key needs `renders:write` to create and `renders:read` to read.** Both are off on a new
|
|
312
|
+
key until you tick them; a key without the scope answers `403 insufficient_scope`.
|
|
313
|
+
- **`createRender` returns on acceptance.** A render is `queued`, then `rendering`, then `ready`
|
|
314
|
+
or `failed`. `waitForRender` returns a failed render rather than throwing, so `error.code`
|
|
315
|
+
(`asset_unavailable`, `tts_failed`, `too_long`, `render_failed`) stays a value you can branch
|
|
316
|
+
on. It throws only when its timeout (30 minutes by default) runs out, and that is not a
|
|
317
|
+
failure.
|
|
318
|
+
- **A `clipId` must be a READY clip of the avatar, or `"primary"`.** Otherwise the create is
|
|
319
|
+
refused with `422 render_clip_unavailable` before anything is charged. Run `waitForClips`
|
|
320
|
+
after changing the library.
|
|
321
|
+
- **The voice is `voiceId`, or `voice`, or neither for the avatar's own.** Sending both does not
|
|
322
|
+
compile, and the platform refuses it with `422`. Only a Fish voice renders: a `voiceId` the
|
|
323
|
+
workspace cannot see is `404 voice_not_found`, and an inline voice of another provider, a
|
|
324
|
+
`voiceId` that is not Fish, or, when neither was sent, an avatar whose own voice is not Fish
|
|
325
|
+
is `422 voice_unavailable`, refused before anything is charged. A render is never quietly
|
|
326
|
+
spoken in another voice. `render.voiceId` is the library voice it spoke with, `null` for an
|
|
327
|
+
inline `voice`.
|
|
328
|
+
- **Keep the render id, not the URL.** The URL is signed for an hour; ask `getRenderAccess`
|
|
329
|
+
again for a fresh one. The file itself is kept until you delete the account.
|
|
330
|
+
- **Limits.** Every shot sets at least one field (`pauseAfterMs: 0` alone does not count), at
|
|
331
|
+
least one shot has `say`, at most 4,000 characters of `say` in total and 16 different clips
|
|
332
|
+
besides `"primary"`. A script whose video would run past 180 seconds is refused with
|
|
333
|
+
`400 render_too_long` before any credits are held. A workspace may have 4 renders queued or rendering at once; the
|
|
334
|
+
next is `429 concurrency_limit_reached`, which clears when one settles.
|
|
335
|
+
- **Billing.** Per second of rendered video at the live per-second rate. A failed render is not
|
|
336
|
+
charged.
|
|
337
|
+
|
|
246
338
|
## Input source on room messages
|
|
247
339
|
|
|
248
340
|
On React and React Native, `session.sendTurn(text)` automatically observes text.
|
|
@@ -304,6 +396,14 @@ rta.getRecording(recordingId)
|
|
|
304
396
|
rta.getRecordingAccess(recordingId)
|
|
305
397
|
rta.getConnectionHistory(sessionId) // bounded LiveKit observations; requires usage:read
|
|
306
398
|
|
|
399
|
+
// pre-rendered video (MP4, no live call); server only, requires renders:write / renders:read
|
|
400
|
+
rta.createRender({ avatarId, voiceId? | voice?, lipGain?, shots }) // 202 queued; one Idempotency-Key across retries
|
|
401
|
+
rta.waitForRender(renderId) // block until ready | failed; RETURNS a failed render, throws only on timeout
|
|
402
|
+
rta.getRender(renderId)
|
|
403
|
+
rta.listRenders({ limit?, cursor? })
|
|
404
|
+
rta.iterateRenders({ limit? }) // every render, paging handled
|
|
405
|
+
rta.getRenderAccess(renderId) // { id, url, expiresAt }; signed for an hour, renew when needed
|
|
406
|
+
|
|
307
407
|
// avatars
|
|
308
408
|
rta.createAvatarFromImage({ displayName, imageUrl, motionPrompt?, voice? }) // the only lane
|
|
309
409
|
rta.createAvatarFromVideo({ displayName, videoUrl, voice? }) // DEPRECATED — closed, 422
|
|
@@ -333,6 +433,27 @@ rta.iterateSessions({ from, to }) // the same, paging handled
|
|
|
333
433
|
// webhooks
|
|
334
434
|
verifyTranscript(rawBytes, headers, secret)
|
|
335
435
|
verifyVoiceWebhook(rawBytes, headers, secret) // one sentence to speak, typed; see "Custom voice (webhook)"
|
|
436
|
+
|
|
437
|
+
// contract values; also exported by realtime-avatar/react and /react-native
|
|
438
|
+
fishTtsModelSchema.safeParse(storedModelId) // a Fish model id you stored -> FishTtsModel, or a failure
|
|
439
|
+
DEFAULT_FISH_TTS_MODEL // the platform's Fish default model
|
|
440
|
+
```
|
|
441
|
+
|
|
442
|
+
**A Fish model id you stored is validated once, with the SDK's own list.** Both values are
|
|
443
|
+
generated from the platform's contract: every live and deprecated id it accepts, and its
|
|
444
|
+
default. `fishTtsModelSchema.safeParse(row.model)` returns the public `FishTtsModel` on success,
|
|
445
|
+
so the voice you build needs no cast and your code keeps no copy of the list. Do it where the
|
|
446
|
+
stored string enters your server, and decide there what a refused id falls back to.
|
|
447
|
+
|
|
448
|
+
```ts
|
|
449
|
+
import { DEFAULT_FISH_TTS_MODEL, fishTtsModelSchema, type VoiceSpecInput } from "realtime-avatar/react";
|
|
450
|
+
|
|
451
|
+
const parsed = fishTtsModelSchema.safeParse(row.model);
|
|
452
|
+
const voice: VoiceSpecInput = {
|
|
453
|
+
provider: "fish",
|
|
454
|
+
voice_id: row.voiceId,
|
|
455
|
+
model: parsed.success ? parsed.data : DEFAULT_FISH_TTS_MODEL,
|
|
456
|
+
};
|
|
336
457
|
```
|
|
337
458
|
|
|
338
459
|
### Session page validation
|
|
@@ -624,7 +745,8 @@ a useful order from outside, and every one was a name we would have had to keep
|
|
|
624
745
|
|
|
625
746
|
What stayed: the components and hooks, the `DEFAULT_*` constants (so you can read the timings
|
|
626
747
|
rather than guess them), the two capacity mappers `capacityErrorFromBusy` / `capacityStateFromGrant`
|
|
627
|
-
for building your own queue UI,
|
|
748
|
+
for building your own queue UI, the zod schemas `sessionBehaviorSchema` / `sessionClipSchema`, and
|
|
749
|
+
the Fish model validator `fishTtsModelSchema` with its `DEFAULT_FISH_TTS_MODEL`.
|
|
628
750
|
|
|
629
751
|
|
|
630
752
|
---
|
|
@@ -297,6 +297,61 @@ var recordingAccessResponseSchema = z.object({
|
|
|
297
297
|
url: z.string().url(),
|
|
298
298
|
expiresAt: z.string().datetime({ offset: true })
|
|
299
299
|
}).strict();
|
|
300
|
+
var RENDER_ID_PATTERN = /^rnd_[0-9a-f]{32}$/;
|
|
301
|
+
var renderIdSchema = z.string().regex(RENDER_ID_PATTERN, "render id must be rnd_ followed by 32 lowercase hex");
|
|
302
|
+
var RENDER_STATUSES = ["queued", "rendering", "ready", "failed"];
|
|
303
|
+
var renderStatusSchema = z.enum(RENDER_STATUSES);
|
|
304
|
+
var RENDER_FAILURE_CODES = ["asset_unavailable", "tts_failed", "too_long", "render_failed"];
|
|
305
|
+
var renderFailureCodeSchema = z.enum(RENDER_FAILURE_CODES);
|
|
306
|
+
var RENDER_PLAYBACKS = ["once", "loop"];
|
|
307
|
+
var renderPlaybackSchema = z.enum(RENDER_PLAYBACKS);
|
|
308
|
+
var renderErrorSchema = z.object({
|
|
309
|
+
code: renderFailureCodeSchema,
|
|
310
|
+
message: z.string().min(1)
|
|
311
|
+
}).strict();
|
|
312
|
+
var shotTimingSchema = z.object({
|
|
313
|
+
index: z.number().int().nonnegative().describe("The shot's position in your shots list, from 0."),
|
|
314
|
+
startMs: z.number().int().nonnegative().describe("When the shot starts."),
|
|
315
|
+
endMs: z.number().int().positive().describe("When the shot ends; the next shot starts here."),
|
|
316
|
+
clipId: z.string().min(1).describe('The clip the shot played: the one you named, else the loop clip it kept, else "primary".'),
|
|
317
|
+
playback: renderPlaybackSchema.describe("once: the clip's action played one time. loop: the clip filled the shot."),
|
|
318
|
+
speechStartMs: z.number().int().nonnegative().nullable().describe("When she starts speaking. Null when the shot has no say."),
|
|
319
|
+
speechEndMs: z.number().int().nonnegative().nullable().describe("When she stops speaking. Null when the shot has no say."),
|
|
320
|
+
clipEndMs: z.number().int().nonnegative().nullable().describe("When the action finished. Once clips only; null for a loop clip."),
|
|
321
|
+
afterClipId: z.string().min(1).nullable().describe("The loop clip shown after the action finished, when the shot outlasts it. Once clips only; otherwise null.")
|
|
322
|
+
}).strict();
|
|
323
|
+
var renderSchema = z.object({
|
|
324
|
+
id: renderIdSchema,
|
|
325
|
+
object: z.literal("render"),
|
|
326
|
+
status: renderStatusSchema,
|
|
327
|
+
avatarId: z.string().min(1),
|
|
328
|
+
voiceId: z.string().min(1).nullable().describe("The library voice the render speaks with: the voiceId you sent, else the avatar's own voice. Null when it speaks with the inline voice you sent."),
|
|
329
|
+
durationMs: z.number().int().positive().nullable().describe("Length of the rendered video. Set once status is ready."),
|
|
330
|
+
width: z.number().int().positive().nullable(),
|
|
331
|
+
height: z.number().int().positive().nullable(),
|
|
332
|
+
timeline: z.array(shotTimingSchema).nullable().describe("One entry per shot, in order. Set once status is ready."),
|
|
333
|
+
error: renderErrorSchema.nullable().describe("Set only when status is failed."),
|
|
334
|
+
createdAt: z.string().datetime({ offset: true }),
|
|
335
|
+
completedAt: z.string().datetime({ offset: true }).nullable()
|
|
336
|
+
}).strict();
|
|
337
|
+
var listRendersQuerySchema = z.object({
|
|
338
|
+
limit: z.coerce.number().int().min(1).max(100).default(50),
|
|
339
|
+
cursor: z.string().min(1).optional()
|
|
340
|
+
}).strict();
|
|
341
|
+
var listRendersResponseSchema = z.object({
|
|
342
|
+
data: z.array(renderSchema),
|
|
343
|
+
nextCursor: z.string().nullable()
|
|
344
|
+
}).strict();
|
|
345
|
+
var renderAccessResponseSchema = z.object({
|
|
346
|
+
id: renderIdSchema,
|
|
347
|
+
url: z.string().url(),
|
|
348
|
+
expiresAt: z.string().datetime({ offset: true })
|
|
349
|
+
}).strict();
|
|
350
|
+
var schema02 = z.enum(["s1", "s2-pro", "s2.1-pro", "drama-3"]);
|
|
351
|
+
var schema110 = z.enum(["speech-1.6", "speech-1.5", "s1-mini"]);
|
|
352
|
+
var schema27 = z.union([schema02, schema110]);
|
|
353
|
+
var fishTtsModelSchema = schema27;
|
|
354
|
+
var DEFAULT_FISH_TTS_MODEL = "s2.1-pro";
|
|
300
355
|
|
|
301
356
|
// ../http-client/src/retry.ts
|
|
302
357
|
var RETRYABLE_STATUS = /* @__PURE__ */ new Set([408, 500, 502, 503, 504]);
|
|
@@ -312,6 +367,13 @@ function backoffMs(attempt, retryAfter) {
|
|
|
312
367
|
return Math.random() * Math.min(500 * 2 ** attempt, 8e3);
|
|
313
368
|
}
|
|
314
369
|
var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
|
|
370
|
+
function pollBudget(options, defaults) {
|
|
371
|
+
const finite = (value, fallback) => typeof value === "number" && Number.isFinite(value) ? value : fallback;
|
|
372
|
+
return {
|
|
373
|
+
timeoutMs: finite(options.timeoutMs, defaults.timeoutMs),
|
|
374
|
+
pollMs: Math.max(1e3, finite(options.pollMs, defaults.pollMs))
|
|
375
|
+
};
|
|
376
|
+
}
|
|
315
377
|
var PROXY_CLIENT_TIMEOUT_MS = 6e4;
|
|
316
378
|
var ROUTE_TIMEOUT_MS = PROXY_CLIENT_TIMEOUT_MS - 1e4;
|
|
317
379
|
function retryFits(attemptStartedAt, waitMs, deadline) {
|
|
@@ -322,12 +384,12 @@ function isTransient(cause) {
|
|
|
322
384
|
const name = cause?.name;
|
|
323
385
|
return name === "TimeoutError" || name === "TypeError" || name === "FetchError";
|
|
324
386
|
}
|
|
325
|
-
var
|
|
326
|
-
var
|
|
327
|
-
var
|
|
328
|
-
var schema32 = z.array(
|
|
387
|
+
var schema03 = z.string().min(2).max(64);
|
|
388
|
+
var schema111 = z.array(schema03);
|
|
389
|
+
var schema28 = z.string().regex(new RegExp("\\S")).min(1).max(160);
|
|
390
|
+
var schema32 = z.array(schema28).max(1e3);
|
|
329
391
|
var schema42 = z.strictObject({
|
|
330
|
-
"language_codes":
|
|
392
|
+
"language_codes": schema111.optional(),
|
|
331
393
|
"custom_vocabulary": schema32.optional()
|
|
332
394
|
});
|
|
333
395
|
var transcriptionWireSchema = schema42;
|
|
@@ -342,27 +404,22 @@ function transcriptionToWire(input) {
|
|
|
342
404
|
...options.customVocabulary !== void 0 ? { custom_vocabulary: options.customVocabulary } : {}
|
|
343
405
|
};
|
|
344
406
|
}
|
|
345
|
-
var
|
|
346
|
-
var contentPolicySchema =
|
|
347
|
-
var
|
|
348
|
-
var
|
|
349
|
-
var
|
|
407
|
+
var schema04 = z.enum(["minor-sexual-content-v1", "safe-content-v1"]);
|
|
408
|
+
var contentPolicySchema = schema04;
|
|
409
|
+
var schema05 = z.literal("voice_error");
|
|
410
|
+
var schema112 = z.enum(["voice_webhook_url_not_allowed", "voice_webhook_unauthorized", "voice_webhook_unreachable", "voice_webhook_timeout", "voice_webhook_http_error", "voice_webhook_unsupported_audio", "voice_webhook_empty_audio"]);
|
|
411
|
+
var schema29 = z.string();
|
|
350
412
|
var schema33 = z.int().min(-9007199254740991).max(9007199254740991);
|
|
351
413
|
var schema43 = z.boolean();
|
|
352
414
|
var schema52 = z.object({
|
|
353
|
-
"kind":
|
|
354
|
-
"code":
|
|
355
|
-
"message":
|
|
415
|
+
"kind": schema05,
|
|
416
|
+
"code": schema112,
|
|
417
|
+
"message": schema29,
|
|
356
418
|
"status": schema33.optional(),
|
|
357
419
|
"fatal": schema43,
|
|
358
|
-
"request_id":
|
|
420
|
+
"request_id": schema29.optional()
|
|
359
421
|
});
|
|
360
422
|
var voiceErrorFrameSchema = schema52;
|
|
361
|
-
var schema05 = z.enum(["s1", "s2-pro", "s2.1-pro", "drama-3"]);
|
|
362
|
-
var schema112 = z.enum(["speech-1.6", "speech-1.5", "s1-mini"]);
|
|
363
|
-
var schema29 = z.union([schema05, schema112]);
|
|
364
|
-
var fishTtsModelSchema = schema29;
|
|
365
|
-
var DEFAULT_FISH_TTS_MODEL = "s2.1-pro";
|
|
366
423
|
|
|
367
424
|
// ../client/src/wire.ts
|
|
368
425
|
var DEFAULT_AVATAR_ID = "maria";
|
|
@@ -861,7 +918,8 @@ function toSessionsPage(page) {
|
|
|
861
918
|
|
|
862
919
|
// ../http-client/src/client.ts
|
|
863
920
|
var DEFAULT_BASE_URL = "https://realtimeavatar.ai/api/v1";
|
|
864
|
-
var
|
|
921
|
+
var RENDER_MISMATCH = "Render response did not match the SDK contract";
|
|
922
|
+
var SDK_VERSION = "0.31.0";
|
|
865
923
|
var RealtimeAvatar = class {
|
|
866
924
|
#apiKey;
|
|
867
925
|
#baseUrl;
|
|
@@ -1186,8 +1244,7 @@ var RealtimeAvatar = class {
|
|
|
1186
1244
|
* failed render and on timeout; a timeout is not a failure, so re-poll or call again.
|
|
1187
1245
|
*/
|
|
1188
1246
|
async waitForLoop(avatarId, options = {}) {
|
|
1189
|
-
const timeoutMs = options
|
|
1190
|
-
const pollMs = Math.max(1e3, options.pollMs ?? 1e4);
|
|
1247
|
+
const { timeoutMs, pollMs } = pollBudget(options, { timeoutMs: 20 * 6e4, pollMs: 1e4 });
|
|
1191
1248
|
const deadline = Date.now() + timeoutMs;
|
|
1192
1249
|
for (; ; ) {
|
|
1193
1250
|
const avatar = await this.getAvatar(avatarId);
|
|
@@ -1217,8 +1274,7 @@ var RealtimeAvatar = class {
|
|
|
1217
1274
|
* Throws only on timeout.
|
|
1218
1275
|
*/
|
|
1219
1276
|
async waitForClips(avatarId, options = {}) {
|
|
1220
|
-
const timeoutMs = options
|
|
1221
|
-
const pollMs = Math.max(1e3, options.pollMs ?? 1e4);
|
|
1277
|
+
const { timeoutMs, pollMs } = pollBudget(options, { timeoutMs: 20 * 6e4, pollMs: 1e4 });
|
|
1222
1278
|
const deadline = Date.now() + timeoutMs;
|
|
1223
1279
|
for (; ; ) {
|
|
1224
1280
|
const library = await this.listClips(avatarId);
|
|
@@ -1284,19 +1340,11 @@ var RealtimeAvatar = class {
|
|
|
1284
1340
|
const response = await this.#request("GET", `/usage/sessions${suffix}`, {
|
|
1285
1341
|
headers: options.speechDiagnostics === true ? { "X-RTA-Speech-Diagnostics": "1" } : void 0
|
|
1286
1342
|
});
|
|
1287
|
-
|
|
1288
|
-
|
|
1289
|
-
|
|
1290
|
-
|
|
1291
|
-
|
|
1292
|
-
if (error instanceof SyntaxError) throw new RealtimeAvatarError(mismatch);
|
|
1293
|
-
throw error;
|
|
1294
|
-
}
|
|
1295
|
-
const page = listUsageSessionsResponseSchema.safeParse(raw);
|
|
1296
|
-
if (!page.success) {
|
|
1297
|
-
throw new RealtimeAvatarError(mismatch);
|
|
1298
|
-
}
|
|
1299
|
-
return toSessionsPage(page.data);
|
|
1343
|
+
return toSessionsPage(await this.#contract(
|
|
1344
|
+
response,
|
|
1345
|
+
listUsageSessionsResponseSchema,
|
|
1346
|
+
"Usage sessions response did not match the SDK contract"
|
|
1347
|
+
));
|
|
1300
1348
|
}
|
|
1301
1349
|
/**
|
|
1302
1350
|
* Every session in a window, following the cursor for you.
|
|
@@ -1330,6 +1378,82 @@ var RealtimeAvatar = class {
|
|
|
1330
1378
|
async getRecordingAccess(recordingId) {
|
|
1331
1379
|
return recordingAccessResponseSchema.parse(await this.#json(await this.#request("GET", `/recordings/${encodeURIComponent(recordingId)}/access`)));
|
|
1332
1380
|
}
|
|
1381
|
+
// ── renders (pre-rendered video) ─────────────────────────────────────────
|
|
1382
|
+
/**
|
|
1383
|
+
* Render an MP4 of the avatar performing a script of `shots`, offline, with no live call.
|
|
1384
|
+
* Everything in one shot happens at the same time; shots play one after another. Requires
|
|
1385
|
+
* `renders:write`, which a new key does not carry unless you tick it.
|
|
1386
|
+
*
|
|
1387
|
+
* `202` is acceptance: the render is `queued`, and `waitForRender` follows it to the end.
|
|
1388
|
+
* Every `clipId` must be a READY clip of this avatar or `"primary"`, or the request is refused
|
|
1389
|
+
* with `422 render_clip_unavailable` before anything is charged. The retry carries the same
|
|
1390
|
+
* `Idempotency-Key`, so a lost response never starts, or bills, a second render.
|
|
1391
|
+
*/
|
|
1392
|
+
async createRender(input) {
|
|
1393
|
+
return this.#contract(await this.#request("POST", "/renders", { json: input }), renderSchema, RENDER_MISMATCH);
|
|
1394
|
+
}
|
|
1395
|
+
/** One render's status. Requires `renders:read`. */
|
|
1396
|
+
async getRender(renderId) {
|
|
1397
|
+
return this.#contract(await this.#request("GET", `/renders/${encodeURIComponent(renderId)}`), renderSchema, RENDER_MISMATCH);
|
|
1398
|
+
}
|
|
1399
|
+
/** This workspace's renders, newest first, one page. Requires `renders:read`. */
|
|
1400
|
+
async listRenders(options = {}) {
|
|
1401
|
+
const checked = listRendersQuerySchema.safeParse(options);
|
|
1402
|
+
if (!checked.success) {
|
|
1403
|
+
const issues = checked.error.issues.map((issue) => `${issue.path.join(".")} ${issue.message}`).join("; ");
|
|
1404
|
+
throw new RealtimeAvatarError(`Invalid listRenders options: ${issues}`);
|
|
1405
|
+
}
|
|
1406
|
+
const parsed = checked.data;
|
|
1407
|
+
const query = new URLSearchParams();
|
|
1408
|
+
if (options.limit !== void 0) query.set("limit", String(parsed.limit));
|
|
1409
|
+
if (parsed.cursor !== void 0) query.set("cursor", parsed.cursor);
|
|
1410
|
+
const suffix = query.size ? `?${query}` : "";
|
|
1411
|
+
return this.#contract(await this.#request("GET", `/renders${suffix}`), listRendersResponseSchema, RENDER_MISMATCH);
|
|
1412
|
+
}
|
|
1413
|
+
/** Every render, following `nextCursor` for you. */
|
|
1414
|
+
async *iterateRenders(options = {}) {
|
|
1415
|
+
let cursor = options.cursor;
|
|
1416
|
+
do {
|
|
1417
|
+
const page = await this.listRenders({ ...options, cursor });
|
|
1418
|
+
yield* page.data;
|
|
1419
|
+
cursor = page.nextCursor ?? void 0;
|
|
1420
|
+
} while (cursor);
|
|
1421
|
+
}
|
|
1422
|
+
/**
|
|
1423
|
+
* A signed download URL for a ready render. It expires at `expiresAt` (an hour); keep the
|
|
1424
|
+
* render id and ask again rather than storing the URL. `409 render_not_ready` before the
|
|
1425
|
+
* render is ready, `410 render_gone` if the file is no longer stored.
|
|
1426
|
+
*/
|
|
1427
|
+
async getRenderAccess(renderId) {
|
|
1428
|
+
return this.#contract(
|
|
1429
|
+
await this.#request("GET", `/renders/${encodeURIComponent(renderId)}/access`),
|
|
1430
|
+
renderAccessResponseSchema,
|
|
1431
|
+
RENDER_MISMATCH
|
|
1432
|
+
);
|
|
1433
|
+
}
|
|
1434
|
+
/**
|
|
1435
|
+
* Block until a render settles, and return it: `ready` with its `timeline`, or `failed` with
|
|
1436
|
+
* `error.code`.
|
|
1437
|
+
*
|
|
1438
|
+
* A failed render is returned, not thrown, so its code stays a typed value you can branch on
|
|
1439
|
+
* (`too_long` means shorten the script; `tts_failed` and `render_failed` are worth one retry).
|
|
1440
|
+
* Throws only on timeout, which is not a failure: the render may still land, so poll again.
|
|
1441
|
+
* The default timeout is 30 minutes, the platform's own budget for one render.
|
|
1442
|
+
*/
|
|
1443
|
+
async waitForRender(renderId, options = {}) {
|
|
1444
|
+
const { timeoutMs, pollMs } = pollBudget(options, { timeoutMs: 30 * 6e4, pollMs: 5e3 });
|
|
1445
|
+
const deadline = Date.now() + timeoutMs;
|
|
1446
|
+
for (; ; ) {
|
|
1447
|
+
const render = await this.getRender(renderId);
|
|
1448
|
+
if (render.status === "ready" || render.status === "failed") return render;
|
|
1449
|
+
if (Date.now() >= deadline) {
|
|
1450
|
+
throw new RealtimeAvatarError(
|
|
1451
|
+
`Render ${renderId} was still ${render.status} after ${Math.round(timeoutMs / 1e3)}s. This is a timeout, not a failure \u2014 the render may still land.`
|
|
1452
|
+
);
|
|
1453
|
+
}
|
|
1454
|
+
await sleep(pollMs);
|
|
1455
|
+
}
|
|
1456
|
+
}
|
|
1333
1457
|
/** Read one session's bounded LiveKit connection history. Requires `usage:read`. */
|
|
1334
1458
|
async getConnectionHistory(sessionId) {
|
|
1335
1459
|
if (!sessionId) throw new RealtimeAvatarError("sessionId is required");
|
|
@@ -1391,6 +1515,22 @@ var RealtimeAvatar = class {
|
|
|
1391
1515
|
}
|
|
1392
1516
|
throw new RealtimeAvatarHttpError(response.status, code, text, response.headers.get("x-request-id") ?? void 0);
|
|
1393
1517
|
}
|
|
1518
|
+
/**
|
|
1519
|
+
* A 2xx body validated against its contract schema. A mismatch, malformed JSON included,
|
|
1520
|
+
* throws one fixed message with no cause, so the rejected body never reaches a log.
|
|
1521
|
+
*/
|
|
1522
|
+
async #contract(response, schema, mismatch) {
|
|
1523
|
+
let raw;
|
|
1524
|
+
try {
|
|
1525
|
+
raw = await this.#json(response);
|
|
1526
|
+
} catch (error) {
|
|
1527
|
+
if (error instanceof SyntaxError) throw new RealtimeAvatarError(mismatch);
|
|
1528
|
+
throw error;
|
|
1529
|
+
}
|
|
1530
|
+
const parsed = schema.safeParse(raw);
|
|
1531
|
+
if (!parsed.success) throw new RealtimeAvatarError(mismatch);
|
|
1532
|
+
return parsed.data;
|
|
1533
|
+
}
|
|
1394
1534
|
};
|
|
1395
1535
|
function isRecord(value) {
|
|
1396
1536
|
return typeof value === "object" && value !== null && !Array.isArray(value);
|
|
@@ -1519,4 +1659,4 @@ function isQueued(result) {
|
|
|
1519
1659
|
return "queued" in result;
|
|
1520
1660
|
}
|
|
1521
1661
|
|
|
1522
|
-
export { ROUTE_TIMEOUT_MS, RealtimeAvatar, RealtimeAvatarError, RealtimeAvatarHttpError, RealtimeAvatarWebhookError, clipLibraryDeclarationSchema, isQueued, listRecordingsResponseSchema, liveKitSessionReleaseReasonSchema, recordingAccessResponseSchema, recordingArtifactSchema, recordingModeSchema, sessionModeSchema, verifyTranscript, verifyVoiceWebhook };
|
|
1662
|
+
export { DEFAULT_FISH_TTS_MODEL, ROUTE_TIMEOUT_MS, RealtimeAvatar, RealtimeAvatarError, RealtimeAvatarHttpError, RealtimeAvatarWebhookError, clipLibraryDeclarationSchema, fishTtsModelSchema, isQueued, listRecordingsResponseSchema, listRendersResponseSchema, liveKitSessionReleaseReasonSchema, recordingAccessResponseSchema, recordingArtifactSchema, recordingModeSchema, renderAccessResponseSchema, renderSchema, sessionModeSchema, verifyTranscript, verifyVoiceWebhook };
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { sessionModeSchema, liveKitSessionReleaseReasonSchema, RealtimeAvatar, ROUTE_TIMEOUT_MS, isQueued, RealtimeAvatarHttpError, RealtimeAvatarError } from './chunk-
|
|
1
|
+
import { sessionModeSchema, liveKitSessionReleaseReasonSchema, RealtimeAvatar, ROUTE_TIMEOUT_MS, isQueued, RealtimeAvatarHttpError, RealtimeAvatarError } from './chunk-LRGQKZFB.js';
|
|
2
2
|
import { z } from 'zod';
|
|
3
3
|
|
|
4
4
|
// ../http-client/src/generated/error-semantics.ts
|
package/dist/express.d.ts
CHANGED
package/dist/express.js
CHANGED
package/dist/hono.d.ts
CHANGED
package/dist/hono.js
CHANGED