@decartai/sdk 0.2.1 → 0.2.2

package/README.md

@@ -82,6 +82,27 @@ Options:
 - `"auto"` — mirror when the input track reports `facingMode: "user"` (mobile front cameras).
 - `true` — always mirror (e.g. desktop webcams).
 
+#### Fast mode
+
+Fast mode (`speed: "fast"`) serves the session from a higher-compute tier for lower latency and higher throughput; output quality is unchanged. It is currently available for `lucy-2.5` / `lucy-latest` and `lucy-vton-3.5` / `lucy-vton-latest`, in the US region only, and is billed at 2x the standard realtime rate for those models. Other models ignore the option. Omit it (the default) for standard mode.
+
+```ts
+const realtimeClient = await client.realtime.connect(stream, {
+  model: models.realtime("lucy-2.5"),
+  speed: "fast",
+  // ...
+});
+```
+
+Models that offer fast mode list it in their definition's `supportedSpeeds`:
+
+```ts
+models.realtime("lucy-2.5").supportedSpeeds; // ["fast"]
+models.realtime("lucy-2.1").supportedSpeeds; // undefined
+```
+
+Passing `speed` for a model without the capability logs a warning through the client's logger and the session runs at standard speed.
+
 ### Watch a Stream
 
 A connected realtime session exposes an SDK `subscribeToken` once it reaches a

package/dist/files/types.d.ts

@@ -12,6 +12,7 @@ import { ReactNativeFile } from "../process/types.js";
 interface FileReference {
   id: string;
   filename: string | null;
+  /** Type of the stored file. The API re-encodes non-JPEG images to JPEG, so a PNG upload reports `image/jpeg`. */
   mime_type: string;
   size_bytes: number;
   /**

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { CanonicalModel, CustomModelDefinition, ImageModelDefinition, ImageModels, ListedModelDefinition, Model, ModelDefinition, ModelFps, ModelKind, RealTimeModels, VideoModelDefinition, VideoModels, isCanonicalModel, isImageModel, isModel, isRealtimeModel, isVideoModel, listModels, modelAliases, models, resolveCanonicalModelAlias, resolveFpsNumber, resolveModelAlias } from "./shared/model.js";
+import { CanonicalModel, CustomModelDefinition, ImageModelDefinition, ImageModels, ListedModelDefinition, Model, ModelDefinition, ModelFps, ModelKind, RealTimeModels, RealtimeSpeed, VideoModelDefinition, VideoModels, isCanonicalModel, isImageModel, isModel, isRealtimeModel, isVideoModel, listModels, modelAliases, models, resolveCanonicalModelAlias, resolveFpsNumber, resolveModelAlias } from "./shared/model.js";
 import { FileInput, ProcessOptions, ReactNativeFile } from "./process/types.js";
 import { FileReference, FileUploadInput } from "./files/types.js";
 import { FilesClient, UploadFileOptions } from "./files/client.js";
@@ -33,4 +33,4 @@ declare const createDecartClient: (options?: DecartClientOptions) => {
   files: FilesClient;
 };
 //#endregion
-export { CanonicalModel, CheckConnectivityOptions, ClientSessionConnectionBreakdownEvent, ClientSessionConnectionBreakdownPhase, ConnectionQuality, ConnectionQualityLimitingFactor, ConnectionQualityMetrics, ConnectionQualityReport, ConnectionState, ConnectivityMetrics, ConnectivityReport, ConnectivityTransport, CreateTokenOptions, CreateTokenResponse, CustomModelDefinition, type DecartClientOptions, DecartSDKError, DiagnosticEvent, DiagnosticEventName, DiagnosticEvents, ERROR_CODES, FileInput, FileReference, FileUploadInput, FilesClient, G2GMetrics, GenerationEndedMessage, ImageModelDefinition, ImageModels, JobStatus, JobStatusResponse, JobSubmitResponse, ListedModelDefinition, LogLevel, Logger, Model, ModelDefinition, ModelFps, ModelKind, ModelState, ProcessClient, ProcessOptions, QueueClient, QueueJobResult, QueuePosition, QueuePositionMessage, QueueSubmitAndPollOptions, QueueSubmitOptions, ReactNativeFile, RealTimeClient, RealTimeClientConnectOptions, RealTimeClientInitialState, Events as RealTimeEvents, RealTimeModels, RealTimeSubscribeClient, RealtimeMediaStream, ReconnectEvent, SessionEnded, SetInput, SubscribeEvents, SubscribeOptions, TokensClient, UploadFileOptions, VideoModelDefinition, VideoModels, VideoStallEvent, WebRTCStats, createConsoleLogger, createDecartClient, isCanonicalModel, isImageModel, isModel, isRealtimeModel, isVideoModel, listModels, modelAliases, models, noopLogger, resolveCanonicalModelAlias, resolveFpsNumber, resolveModelAlias };
+export { CanonicalModel, CheckConnectivityOptions, ClientSessionConnectionBreakdownEvent, ClientSessionConnectionBreakdownPhase, ConnectionQuality, ConnectionQualityLimitingFactor, ConnectionQualityMetrics, ConnectionQualityReport, ConnectionState, ConnectivityMetrics, ConnectivityReport, ConnectivityTransport, CreateTokenOptions, CreateTokenResponse, CustomModelDefinition, type DecartClientOptions, DecartSDKError, DiagnosticEvent, DiagnosticEventName, DiagnosticEvents, ERROR_CODES, FileInput, FileReference, FileUploadInput, FilesClient, G2GMetrics, GenerationEndedMessage, ImageModelDefinition, ImageModels, JobStatus, JobStatusResponse, JobSubmitResponse, ListedModelDefinition, LogLevel, Logger, Model, ModelDefinition, ModelFps, ModelKind, ModelState, ProcessClient, ProcessOptions, QueueClient, QueueJobResult, QueuePosition, QueuePositionMessage, QueueSubmitAndPollOptions, QueueSubmitOptions, ReactNativeFile, RealTimeClient, RealTimeClientConnectOptions, RealTimeClientInitialState, Events as RealTimeEvents, RealTimeModels, RealTimeSubscribeClient, RealtimeMediaStream, RealtimeSpeed, ReconnectEvent, SessionEnded, SetInput, SubscribeEvents, SubscribeOptions, TokensClient, UploadFileOptions, VideoModelDefinition, VideoModels, VideoStallEvent, WebRTCStats, createConsoleLogger, createDecartClient, isCanonicalModel, isImageModel, isModel, isRealtimeModel, isVideoModel, listModels, modelAliases, models, noopLogger, resolveCanonicalModelAlias, resolveFpsNumber, resolveModelAlias };

package/dist/index.react-native.d.ts

@@ -1,4 +1,4 @@
-import { CanonicalModel, CustomModelDefinition, ImageModelDefinition, ImageModels, ListedModelDefinition, Model, ModelDefinition, ModelFps, ModelKind, RealTimeModels, VideoModelDefinition, VideoModels, isCanonicalModel, isImageModel, isModel, isRealtimeModel, isVideoModel, listModels, modelAliases, models, resolveCanonicalModelAlias, resolveFpsNumber, resolveModelAlias } from "./shared/model.js";
+import { CanonicalModel, CustomModelDefinition, ImageModelDefinition, ImageModels, ListedModelDefinition, Model, ModelDefinition, ModelFps, ModelKind, RealTimeModels, RealtimeSpeed, VideoModelDefinition, VideoModels, isCanonicalModel, isImageModel, isModel, isRealtimeModel, isVideoModel, listModels, modelAliases, models, resolveCanonicalModelAlias, resolveFpsNumber, resolveModelAlias } from "./shared/model.js";
 import { FileInput, ProcessOptions, ReactNativeFile } from "./process/types.js";
 import { FileReference, FileUploadInput } from "./files/types.js";
 import { FilesClient, UploadFileOptions } from "./files/client.js";
@@ -33,4 +33,4 @@ declare const createDecartClient: (options?: DecartClientOptions) => {
   files: FilesClient;
 };
 //#endregion
-export { CanonicalModel, CheckConnectivityOptions, ClientSessionConnectionBreakdownEvent, ClientSessionConnectionBreakdownPhase, ConnectionQuality, ConnectionQualityLimitingFactor, ConnectionQualityMetrics, ConnectionQualityReport, ConnectionState, ConnectivityMetrics, ConnectivityReport, ConnectivityTransport, CreateTokenOptions, CreateTokenResponse, CustomModelDefinition, type DecartClientOptions, DecartSDKError, DiagnosticEvent, DiagnosticEventName, DiagnosticEvents, ERROR_CODES, FileInput, FileReference, FileUploadInput, FilesClient, G2GMetrics, GenerationEndedMessage, ImageModelDefinition, ImageModels, JobStatus, JobStatusResponse, JobSubmitResponse, ListedModelDefinition, LogLevel, Logger, Model, ModelDefinition, ModelFps, ModelKind, ModelState, ProcessClient, ProcessOptions, QueueClient, QueueJobResult, QueuePosition, QueuePositionMessage, QueueSubmitAndPollOptions, QueueSubmitOptions, ReactNativeFile, RealTimeClient, RealTimeClientConnectOptions, RealTimeClientInitialState, Events as RealTimeEvents, RealTimeModels, RealTimeSubscribeClient, RealtimeMediaStream, ReconnectEvent, SessionEnded, SetInput, SubscribeEvents, SubscribeOptions, TokensClient, UploadFileOptions, VideoModelDefinition, VideoModels, VideoStallEvent, WebRTCStats, createConsoleLogger, createDecartClient, isCanonicalModel, isImageModel, isModel, isRealtimeModel, isVideoModel, listModels, modelAliases, models, noopLogger, resolveCanonicalModelAlias, resolveFpsNumber, resolveModelAlias };
+export { CanonicalModel, CheckConnectivityOptions, ClientSessionConnectionBreakdownEvent, ClientSessionConnectionBreakdownPhase, ConnectionQuality, ConnectionQualityLimitingFactor, ConnectionQualityMetrics, ConnectionQualityReport, ConnectionState, ConnectivityMetrics, ConnectivityReport, ConnectivityTransport, CreateTokenOptions, CreateTokenResponse, CustomModelDefinition, type DecartClientOptions, DecartSDKError, DiagnosticEvent, DiagnosticEventName, DiagnosticEvents, ERROR_CODES, FileInput, FileReference, FileUploadInput, FilesClient, G2GMetrics, GenerationEndedMessage, ImageModelDefinition, ImageModels, JobStatus, JobStatusResponse, JobSubmitResponse, ListedModelDefinition, LogLevel, Logger, Model, ModelDefinition, ModelFps, ModelKind, ModelState, ProcessClient, ProcessOptions, QueueClient, QueueJobResult, QueuePosition, QueuePositionMessage, QueueSubmitAndPollOptions, QueueSubmitOptions, ReactNativeFile, RealTimeClient, RealTimeClientConnectOptions, RealTimeClientInitialState, Events as RealTimeEvents, RealTimeModels, RealTimeSubscribeClient, RealtimeMediaStream, RealtimeSpeed, ReconnectEvent, SessionEnded, SetInput, SubscribeEvents, SubscribeOptions, TokensClient, UploadFileOptions, VideoModelDefinition, VideoModels, VideoStallEvent, WebRTCStats, createConsoleLogger, createDecartClient, isCanonicalModel, isImageModel, isModel, isRealtimeModel, isVideoModel, listModels, modelAliases, models, noopLogger, resolveCanonicalModelAlias, resolveFpsNumber, resolveModelAlias };

package/dist/package.js

@@ -1,4 +1,4 @@
 //#region package.json
-var version = "0.2.1";
+var version = "0.2.2";
 //#endregion
 export { version };

package/dist/realtime/client.d.ts

@@ -36,6 +36,9 @@ declare const realTimeClientConnectOptionsSchema: z.ZodObject<{
     width: z.ZodNumber;
     height: z.ZodNumber;
     inputSchema: z.ZodOptional<z.ZodAny>;
+    supportedSpeeds: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodEnum<{
+      fast: "fast";
+    }>>>>;
   }, z.core.$strip>;
   onRemoteStream: z.ZodCustom<OnRemoteStreamFn, OnRemoteStreamFn>;
   onConnectionChange: z.ZodOptional<z.ZodCustom<OnConnectionChangeFn, OnConnectionChangeFn>>;
@@ -55,6 +58,9 @@ declare const realTimeClientConnectOptionsSchema: z.ZodObject<{
     "720p": "720p";
     "1080p": "1080p";
   }>>;
+  speed: z.ZodOptional<z.ZodEnum<{
+    fast: "fast";
+  }>>;
   preferredVideoCodec: z.ZodOptional<z.ZodEnum<{
     h264: "h264";
     vp8: "vp8";

package/dist/realtime/client.js

@@ -1,7 +1,7 @@
 import { classifyWebrtcError } from "../utils/errors.js";
 import { createConsoleLogger } from "../utils/logger.js";
 import { isFileRefId } from "../files/types.js";
-import { modelDefinitionSchema, resolveFpsNumber } from "../shared/model.js";
+import { modelDefinitionSchema, realtimeSpeedSchema, resolveFpsNumber } from "../shared/model.js";
 import { modelStateSchema } from "../shared/types.js";
 import { imageToBase64 } from "../utils/media.js";
 import { createEventBuffer } from "./event-buffer.js";
@@ -20,6 +20,14 @@ const realTimeClientConnectOptionsSchema = z.object({
 	queryParams: z.record(z.string(), z.string()).optional(),
 	mirror: z.union([z.literal("auto"), z.boolean()]).optional(),
 	resolution: z.enum(["720p", "1080p"]).optional(),
+	/**
+	* Realtime speed tier. Fast mode (`"fast"`) serves the session from a higher-compute tier for lower
+	* latency and higher throughput; output quality is unchanged. It is currently available for `lucy-2.5` /
+	* `lucy-latest` and `lucy-vton-3.5` / `lucy-vton-latest`, in the US region only, and is billed at 2x the
+	* standard realtime rate for those models. Other models ignore the option (the SDK logs a warning when the
+	* model does not list it in `supportedSpeeds`). Omit it (the default) for standard mode.
+	*/
+	speed: realtimeSpeedSchema.optional(),
 	/** Local track publish codec. Desktop Safari is always pinned to vp8 and ignores this value. */
 	preferredVideoCodec: z.enum([
 		"h264",
@@ -39,7 +47,7 @@ const createRealTimeClient = (opts) => {
 	const connect = async (stream, options) => {
 		const parsedOptions = realTimeClientConnectOptionsSchema.safeParse(options);
 		if (!parsedOptions.success) throw parsedOptions.error;
-		const { onRemoteStream, onConnectionChange, onConnectionQuality, onQueuePosition, initialState, resolution, preferredVideoCodec } = parsedOptions.data;
+		const { onRemoteStream, onConnectionChange, onConnectionQuality, onQueuePosition, initialState, resolution, speed, preferredVideoCodec } = parsedOptions.data;
 		const mirror = parsedOptions.data.mirror ?? false;
 		let session;
 		let observability;
@@ -74,13 +82,19 @@ const createRealTimeClient = (opts) => {
 				}
 			});
 			observability = preparedConnection.observability;
+			if (speed && !options.model.supportedSpeeds?.includes(speed)) logger.warn("realtime: model does not support the requested speed tier; the server serves it at standard speed", {
+				model: options.model.name,
+				speed,
+				supportedSpeeds: options.model.supportedSpeeds ?? []
+			});
 			session = new StreamSession({
 				url: `${url}?${new URLSearchParams({
 					...preparedConnection.queryParams ?? {},
 					...options.queryParams ?? {},
 					api_key: apiKey,
 					model: options.model.name,
-					...resolution ? { resolution } : {}
+					...resolution ? { resolution } : {},
+					...speed ? { speed } : {}
 				}).toString()}`,
 				integration,
 				observability,

package/dist/shared/model.d.ts

@@ -289,6 +289,14 @@ type ModelFps = number | {
   ideal?: number;
   exact?: number;
 };
+/**
+ * Realtime speed tiers selectable with the `speed` connect option.
+ * `"fast"` is the only tier today; the standard tier has no value (omit the option).
+ */
+declare const realtimeSpeedSchema: z.ZodEnum<{
+  fast: "fast";
+}>;
+type RealtimeSpeed = z.infer<typeof realtimeSpeedSchema>;
 type ModelDefinition<T extends Model = Model> = {
   name: T;
   urlPath: string;
@@ -297,6 +305,11 @@ type ModelDefinition<T extends Model = Model> = {
   width: number;
   height: number;
   inputSchema: T extends keyof ModelInputSchemas ? ModelInputSchemas[T] : z.ZodTypeAny;
+  /**
+   * Realtime speed tiers this model can be served from via the `speed` connect option.
+   * Absent when the model only offers the standard tier (the server ignores `speed` for it).
+   */
+  supportedSpeeds?: readonly RealtimeSpeed[];
 };
 declare function resolveFpsNumber(fps: ModelFps, fallback?: number): number;
 /**
@@ -375,4 +388,4 @@ declare const models: {
   };
 };
 //#endregion
-export { CanonicalModel, CustomModelDefinition, ImageModelDefinition, ImageModels, ListedModelDefinition, Model, ModelDefinition, ModelFps, ModelInputSchemas, ModelKind, RealTimeModels, VideoModelDefinition, VideoModels, canonicalModelSchema, imageModels, isCanonicalModel, isImageModel, isModel, isRealtimeModel, isVideoModel, listModels, modelAliases, modelInputSchemas, modelSchema, models, realtimeModels, resolveCanonicalModelAlias, resolveFpsNumber, resolveModelAlias, videoModels };
+export { CanonicalModel, CustomModelDefinition, ImageModelDefinition, ImageModels, ListedModelDefinition, Model, ModelDefinition, ModelFps, ModelInputSchemas, ModelKind, RealTimeModels, RealtimeSpeed, VideoModelDefinition, VideoModels, canonicalModelSchema, imageModels, isCanonicalModel, isImageModel, isModel, isRealtimeModel, isVideoModel, listModels, modelAliases, modelInputSchemas, modelSchema, models, realtimeModels, realtimeSpeedSchema, resolveCanonicalModelAlias, resolveFpsNumber, resolveModelAlias, videoModels };

package/dist/shared/model.js

@@ -185,6 +185,11 @@ const modelInputSchemas = {
 	"lucy-pro-i2i": imageEditSchema,
 	"lucy-restyle-v2v": restyleSchema
 };
+/**
+* Realtime speed tiers selectable with the `speed` connect option.
+* `"fast"` is the only tier today; the standard tier has no value (omit the option).
+*/
+const realtimeSpeedSchema = z.enum(["fast"]);
 function resolveFpsNumber(fps, fallback = 30) {
 	if (typeof fps === "number") return fps;
 	return fps.ideal ?? fps.max ?? fps.exact ?? fps.min ?? fallback;
@@ -201,7 +206,8 @@ const modelDefinitionSchema = z.object({
 	})]),
 	width: z.number().min(1),
 	height: z.number().min(1),
-	inputSchema: z.any().optional()
+	inputSchema: z.any().optional(),
+	supportedSpeeds: z.array(realtimeSpeedSchema).readonly().optional()
 });
 const _models = {
 	realtime: {
@@ -225,7 +231,8 @@ const _models = {
 			},
 			width: 1280,
 			height: 720,
-			inputSchema: z.object({})
+			inputSchema: z.object({}),
+			supportedSpeeds: ["fast"]
 		},
 		"lucy-vton-3.5": {
 			urlPath: "/v1/stream",
@@ -236,7 +243,8 @@ const _models = {
 			},
 			width: 1280,
 			height: 720,
-			inputSchema: z.object({})
+			inputSchema: z.object({}),
+			supportedSpeeds: ["fast"]
 		},
 		"lucy-restyle-2": {
 			urlPath: "/v1/stream",
@@ -258,7 +266,8 @@ const _models = {
 			},
 			width: 1088,
 			height: 624,
-			inputSchema: z.object({})
+			inputSchema: z.object({}),
+			supportedSpeeds: ["fast"]
 		},
 		"lucy-vton-latest": {
 			urlPath: "/v1/stream",
@@ -269,7 +278,8 @@ const _models = {
 			},
 			width: 1280,
 			height: 720,
-			inputSchema: z.object({})
+			inputSchema: z.object({}),
+			supportedSpeeds: ["fast"]
 		},
 		"lucy-restyle-latest": {
 			urlPath: "/v1/stream",
@@ -483,4 +493,4 @@ const models = {
 	}
 };
 //#endregion
-export { canonicalImageModels, canonicalModelSchema, canonicalRealtimeModels, canonicalVideoModels, imageModels, isCanonicalModel, isImageModel, isModel, isRealtimeModel, isVideoModel, listModels, modelAliases, modelDefinitionSchema, modelInputSchemas, modelSchema, models, realtimeModels, resolveCanonicalModelAlias, resolveFpsNumber, resolveModelAlias, videoModels };
+export { canonicalImageModels, canonicalModelSchema, canonicalRealtimeModels, canonicalVideoModels, imageModels, isCanonicalModel, isImageModel, isModel, isRealtimeModel, isVideoModel, listModels, modelAliases, modelDefinitionSchema, modelInputSchemas, modelSchema, models, realtimeModels, realtimeSpeedSchema, resolveCanonicalModelAlias, resolveFpsNumber, resolveModelAlias, videoModels };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decartai/sdk",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Decart's JavaScript SDK",
   "type": "module",
   "license": "MIT",