1.0.10

What's New

• SDK 视频组件在远端首帧后进行 1000 ms 渲染预热，再以 300 ms 渐入展示画面；系统开启减少动态效果时不执行渐入。
• 启动耗时拆分展示创建会话、RTC 进房、发布、首帧及渲染预热，便于定位启动瓶颈。
• 调整动态码率策略及质量档位，质量历史记录保留一小时；移除 X-Lab 临时调试控件。
• 内置模型精简为 CN / US 两个模型，移除旧开发环境模型配置。
• 自动化验证覆盖 SDK、示例、类型检查、构建及独立消费端；不代表真实 RTC 网络及所有浏览器均已人工验收。渲染预热仅延迟首次展示，不能消除持续网络卡顿。

API Changes

• 状态语义变更：新增 RealtimeConnectionState.starting。startGeneration() 返回可挂载的远端流后，只有生成任务已确认且 SDK 视频组件预热完成，状态才进入 generating。接入方应先挂载 SDK 视频组件，并通过 generating 结束 loading；未挂载组件时将保持 starting。
• 启动统计变更：RealtimeLaunchTiming.connectionMs 移除，新增 sessionMs、rtcJoinMs 和 renderWarmupMs。totalMs 统计至渲染预热完成，不包含后续渐入动画时间。
• 模型枚举变更：RealtimeModel 仅保留 x2_1_1_preview_cn 和 x2_1_1_preview_us，分别对应 x2.1.1-preview-cn 和 x2.1.1-preview-us。使用旧枚举的接入方需要迁移；自定义模型字符串仍可透传。
• 质量历史记录增加保存时间；旧格式历史记录不再复用。

1.0.9

What's New

• Added local image streams for TRTC, Agora, and VeRTC. Images are fitted without cropping and continuously published as silent video input.
• Added drag interaction on generated video, with coordinate mapping, multi-touch support, and customizable glowing trajectory effects.
• Added opt-in recording of approximately 20 seconds of original remote video and audio. Recordings preserve video frames while shortening long frame gaps and removing matching audio intervals without re-encoding; processing failures fall back to the original clip.
• Extended adaptive uplink and downlink quality controls to TRTC, with frame-rate-only uplink adjustment for the current TRTC implementation.
• Added the Agora-based x2.1.1-preview-cn and x2.1.1-preview-us models. X-Lab now lists all built-in models and offers recorded clips for download.
• Moved README media assets to materials and disabled temporary X-Lab quality-debug controls.

API Changes

• Added createLocalImageStream({ file, videoFormat }).
• Added restart, extraParams, and record options to startGeneration(). Extra parameters extend the signaling params without overriding SDK fields, apply to the current call only, and are not cached for automatic recovery. Restart creates a new generation task while retaining the RTC connection.
• Added setRecordingListener() and recording event/result types for completed, interrupted, and failed recordings. Recording is disabled by default; condition updates ignore record, and recording a restarted task is not supported yet.
• Video views expose isInteractionEnabled and trajectoryRenderer for interaction control and custom visual effects.
• No breaking API changes.

Limitations

• Recording formats depend on browser support. TRTC recording on mobile Safari is unsupported. Recording excludes client-side interpolation and overlays; trimmed clips can be shorter than 20 seconds, and removed audio or missing motion is not reconstructed.
• Automated release checks cover tests, types, builds, and installed-package consumers; they do not replace live RTC and cross-browser device testing.

1.0.8

What's New

• Added external video track input for applications that manage their own capture, processing, and preview.
• Added optional face restoration for generation start and condition updates. X-Lab enables it in clothing mode.
• Added the x2.1-preview-1014 model using the development endpoint, and restored x2.0 in the X-Lab model list.
• Removed verbose sender-parameter debug logging and clarified API parameter documentation.

API Changes

• Added createExternalVideoStream({ videoTrack, videoFormat }). This video-only input accepts a live MediaStreamTrack; the caller retains ownership of the original track. External input uses mirror: false.
• startGeneration() accepts optional faceRestoration, defaulting to false. It maps to face_replace in both start and change_condition signals.
• No breaking API changes.

1.0.7

What's New

• Added optional local camera rotation for Agora sessions. Preview and published video share the corrected frames.
• X-Lab keeps camera rotation disabled by default.
• Simplified the README to focus on getting started.

API Changes

• createLocalCameraStream() accepts an optional rotation value of 0, 90, 180, or 270 degrees clockwise. The default is 0, preserving the existing capture path.
• videoFormat describes the target dimensions after rotation. For portrait output, keep width: 1024 and height: 1920 when setting rotation: 90.
• Exported the CameraRotation type. No breaking API changes.

Limitations

• Nonzero rotation currently requires Agora; other RTC providers reject it explicitly.
• Rotation uses local Canvas processing and may add rendering overhead. Browser/device performance still requires live-session validation.
• Do not apply an additional CSS rotation to the corrected preview. Mirroring remains independent of rotation.

1.0.6

What's New

• Added independent Agora uplink and downlink adaptive quality with five tiers, fast downgrade and gradual recovery. Downlink adaptation requests server output resolution changes through change_target_size.
• Remember the last successful target tier per model and direction in localStorage; use L2 when no valid history is available. L4 now uses 512 × 960 at 20 fps for the standard portrait source.
• Agora camera quality updates now use WebRTC sender scaling, frame-rate caps and maximum bitrate instead of reapplying camera capture constraints. File video and other RTC providers retain their existing configuration paths.
• Improved Safari frame-timestamp handling and added video-view render frame-rate statistics.
• X-Lab now defaults to x2.1-preview, with microphone and frame interpolation disabled by default. Frame interpolation can still be toggled during a session; temporary quality-debug buttons have been removed.

API Changes

• Renamed the realtime manager's updateVideoFormat() to updateUplinkVideoFormat(); callers must update method references.
• Added updateUplinkFrameRate(fps) and adjustDownlinkQuality("upgrade" | "downgrade").
• Added VideoRenderStatistics, the video view's renderStatisticsHandler, and the React video's onRenderStatistics callback.
• Removed the built-in RealtimeModel.x2_0_agora preset. Use RealtimeModel.x2_1_preview, which now defaults to Agora and the production endpoint https://cloud.xmax.22duck.cn/open/api/v1.
• Unknown model identifiers inherit the updated x2.1-preview defaults while retaining their original server model name; explicit RTC-provider overrides remain supported for custom models.

Requirements and Known Limitations

• Adaptive quality is currently implemented for Agora. Downlink target changes update resolution only; sending the signal does not confirm server application.
• Camera sender-only configuration requires browser support for the relevant WebRTC sender parameters. Minimum bitrate is not applied, and initial frames may be published before the target limits are installed.
• Stored quality history has no expiry or network-identity matching. Actual resolution, frame rate and bitrate still depend on the browser, device, RTC implementation and network conditions.
• Manual frame-rate switching was verified by the maintainer. Automated release checks do not replace cross-browser live-session testing.

1.0.5

What's New

• Added local-file video generation for TRTC, Agora and VeRTC. Files are decoded through Canvas and Web Audio without requesting camera or microphone access; audio and looping are enabled by default.
• Local-file input sizes automatically fit the nearest model resolution by aspect ratio, with proportional scaling and letterboxing. Camera and network-video size validation are unchanged.
• Added network-video generation: the server reads a video URL while the client receives generated media without publishing local audio or video.
• Added non-realtime video tasks, ordinary video uploads and browser video downloads.
• Reference selection in X-Lab no longer dims and disables the entire reference area during generation-condition updates; consecutive selections use the existing selection queue.

API Changes

• Added createLocalVideoStream({ file, videoFormat, loop?, includeAudio? }) and createNetworkVideoStream({ url, videoFormat, sampleMethod?, onFinish? }) to the realtime manager.
• Added RealtimeContext.referenceVideo and RealtimeVideoSampleMethod for network-video sources.
• Added createNonRealtimeManager() for task submission, querying, listing and completion polling. Task submission requires an explicit model.
• Non-realtime tasks use dedicated China/global endpoints: https://api.xmaxai.com/open/api/v1/offline-task and https://api.xmax.ai/open/api/v1/offline-task.
• Added storage-service uploadVideo() and downloadVideo() methods.
• Added RealtimeModelName for custom server model identifiers. Unknown models retain their original name and use the local defaults of x2.1-preview, unless an RTC provider is explicitly selected.
• The default RTC provider for x2.0 is VeRTC. Removed the built-in x2_0_pro and x2_1_preview_1005 enum members and their preset configuration; migrate enum references before upgrading.

Requirements and Known Limitations

• Local-file decoding depends on browser codec support, Canvas capture and Web Audio. Invoke source creation from a user gesture and keep the page foregrounded for stable frame delivery.
• Playback starts after the generation start signal is sent, not after a server input-readiness acknowledgement; processing every initial frame is not guaranteed. Local preview remains silent while file audio is published.
• Network video URLs must be accessible to the server; browser preview and download additionally depend on browser media and CORS restrictions.
• Actual RTC resolution, frame rate and bitrate can vary with device, browser and network conditions. The new TRTC and VeRTC file-source paths have automated coverage but have not been verified against live generation services in this release workflow.
• Full release CI and isolated consumer build validation were skipped at the maintainer's request. The release package was built with version 1.0.5 and its contents and checksums were inspected; this is not a full release-validation pass.

1.0.4

What's New

• Added Agora and Volcengine VeRTC alongside the existing TRTC transport, with shared mobile video-orientation handling.
• Added runtime uplink video-format updates: change encoding resolution, frame rate and bitrate without reconnecting or restarting generation. Successful settings are reused on reconnect; generation and remote interpolation retain the original format.
• X-Lab now keeps each reference category mounted with an independent scroll position on mobile and desktop. Reference selection is global, and submitting a free-mode prompt clears selections from other categories.
• X-Lab model labels are now X2.1-preview-trtc, X2.1-preview-agora and X2.1-preview-vertc; API model identifiers and routing are unchanged.

API Changes

• Added RealtimeConfiguration.provider with RtcProvider.trtc, RtcProvider.agora and RtcProvider.vertc. TRTC remains the default; the provider is fixed for a manager's lifetime.
• Added RealtimeModel.x2_0_agora (x2.0-agora) and RealtimeModel.x2_1_preview (x2.1-preview). Both currently use the model-specific dev session API at https://dev.xmaxai.com/open/api/v1.
• Added XmaxRealtimeManaging.updateVideoFormat(videoFormat). Call after creating the local camera stream and await completion before another configuration or lifecycle operation. Supply a complete format; omitted optional values use SDK defaults.
• Video-format validation now rejects non-finite frame rates and bitrate values.
• Removed RealtimeModel.x2_0_pro (x2.0-pro). Applications referencing this enum member must select a supported model and the matching RTC provider before upgrading.

Requirements and Known Limitations

• Camera and microphone require an HTTPS or localhost secure context and user permission. Audio playback remains subject to browser autoplay policies.
• Actual sent resolution, frame rate and bitrate depend on the device, browser, RTC provider and network. Use statistics callbacks to observe the effective values.
• Interpolation requires WebGPU, shader-f16 and requestVideoFrameCallback; support and performance vary by browser and device.
• Automated validation does not substitute for live camera, RTC, audio, interpolation and reconnect testing on target devices. The release process does not run live service sessions.

1.0.3

What's New

• Uplink video now targets the smooth-priority bitrate (minimumBitrate from the encoding configuration) as the single TRTC target bitrate instead of the quality-first maximum, trading peak quality for steadier frame delivery on weak networks.
• On iOS Safari and WKWebView, where remote volume cannot be scaled, setRemoteAudioVolume now degrades to mute/unmute control, and a stored volume of 0 survives remote audio subscription instead of playing sound.
• Fixed uplink orientation on mobile portrait devices: the TRTC capture and encoding profiles are transposed so the published stream matches the requested orientation.
• Camera startup no longer waits for exposure validation; a fixed 200 ms warmup replaces the frame-quality probe, shortening the time to a publishable stream.
• The realtime session is now cleaned up on pagehide, and the session close request uses keepalive so it still reaches the server while the page unloads.
• X-Lab example: the session page adapts to mobile with a picture-in-picture layout and single-line prompt input, input focus no longer triggers page zoom on iOS, the reference list is fixed at two scrollable rows, and assorted mobile/desktop polish.

API Changes

• RealtimeLaunchTiming breaking change: frameValidationMs is removed; permissionMs (camera/microphone permission confirmation) and publishMs (local stream publish) are added, and connectionMs now includes the camera warmup wait while excluding publishing. Code referencing frameValidationMs fails to compile and must be migrated.
• XmaxRealtimeManager.setRemoteAudioVolume on iOS Safari and WKWebView is effectively binary: 0 mutes remote audio and any positive value restores it; intermediate volume levels have no effect on those platforms.
• No other API changes.

Requirements and Known Limitations

• Camera and microphone require an HTTPS or localhost secure context and user permission. Audio playback remains subject to browser autoplay policies.
• On iOS Safari and WKWebView, remote audio volume cannot be scaled per user; only mute/unmute is available.
• Interpolation requires WebGPU, shader-f16, and requestVideoFrameCallback; at most one frame is inserted per source pair with a 60fps ceiling, and the target rate is not guaranteed on all devices and resolutions.
• The remote frame rate depends on server send pacing and network jitter; interpolation cannot compensate for burst-delivered source frames, so overall smoothness relies on server-side pacing.
• RTC statistics frame rate reflects the raw received stream, and E2E is an RTC-provided estimate; neither represents full end-to-end latency including generation and client-side interpolation.

1.0.2

What's New

• Adds the x2.0-trtc realtime generation model and makes it the default everywhere: MediaService, XmaxClient.createMediaService, and the X-Lab example.
• Removes the x2-fast-1080p model. The x2.0-trtc model keeps the same input constraints: 1024×1920 / 1920×1024 resolution buckets and a 2.1M-pixel input cap.
• The china environment now points to the production base URL https://cloud.xmax.22duck.cn/open/api/v1 instead of the temporary integration environment.

API Changes

• RealtimeModel.x2_fast_1080p is removed; use RealtimeModel.x2_0_trtc (x2.0-trtc) instead. Code referencing the removed member fails to compile and must be migrated.
• Default model for createMediaService and new MediaService() changed from x2-fast-1080p to x2.0-trtc.
• No other API changes.

Requirements and Known Limitations

• Camera and microphone require an HTTPS or localhost secure context and user permission. Audio playback remains subject to browser autoplay policies.
• Interpolation requires WebGPU, shader-f16, and requestVideoFrameCallback; at most one frame is inserted per source pair with a 60fps ceiling, and the target rate is not guaranteed on all devices and resolutions.
• The remote frame rate depends on server send pacing and network jitter; interpolation cannot compensate for burst-delivered source frames, so overall smoothness relies on server-side pacing.
• RTC statistics frame rate reflects the raw received stream, and E2E is an RTC-provided estimate; neither represents full end-to-end latency including generation and client-side interpolation.

1.0.1

What's New

• Interpolated playback is now paced on a queued vsync-driven timeline, producing more even output cadence and reducing visible stutter.
• The camera publishes as soon as the first valid frame passes validation, shortening time-to-first-image. Frame brightness validation is now bounded to two seconds and only warns on timeout instead of stalling startup.
• Remote frame interpolation is now off by default. Enable it via frameInterpolation.enabled or setFrameInterpolationEnabled(true) at runtime; unsupported devices and processing failures still fall back to the original video.
• The X-Lab example removes the interpolation toggle and model picker and pins x2-fast-1080p. The statistics panel is grouped, and frame validation time is reported separately in launch timing.

API Changes

• RealtimeConfiguration interpolation defaults changed from on to off: both frameInterpolation.enabled and isFrameInterpolationEnabled now default to false. Integrations that relied on the previous default must set frameInterpolation: { enabled: true } explicitly.
• createLocalCameraStream adds an enableFrameValidation option (default true); set it to false to skip the startup brightness check and its wait.
• RealtimeLaunchTiming adds frameValidationMs, reported separately from session and room connection timing; the field is absent when validation is skipped.

Requirements and Known Limitations

• Camera and microphone require an HTTPS or localhost secure context and user permission. Audio playback remains subject to browser autoplay policies.
• Interpolation requires WebGPU, shader-f16, and requestVideoFrameCallback; at most one frame is inserted per source pair with a 60fps ceiling, and the target rate is not guaranteed on all devices and resolutions.
• The remote frame rate depends on server send pacing and network jitter; interpolation cannot compensate for burst-delivered source frames, so overall smoothness relies on server-side pacing.
• The frame rate in RTC statistics reflects the raw received stream, and E2E is an RTC-provided estimate; neither represents full end-to-end latency including generation and client-side interpolation.