@trtc/calls-uikit-react 4.5.10 → 4.6.0

package/src/TUICallService/CallService/index.ts

@@ -4,13 +4,13 @@ import {
 import {
   StoreName, CallStatus, CallMediaType, NAME, CALL_DATA_KEY, LanguageType, CallRole, LOG_LEVEL, VideoDisplayMode,
   VideoResolution, StatusChange, AudioPlayBackDevice, CameraPosition, COMPONENT, FeatureButton, ButtonState,
-  LayoutMode, DEFAULT_BLUR_LEVEL,
+  LayoutMode, DEFAULT_BLUR_LEVEL, DEVICE_ERROR_CODE, DeviceErrorReason, DeviceUnavailableReasons,
 } from '../const/index';
 // @ts-ignore
 import { TUICallEngine } from '@trtc/call-engine-lite-js';
 import { checkLocalMP3FileExists } from '../utils/index';
 import { handleModalError } from './UIKitModal';
-import { CallTips, t } from '../locales/index';
+import { CallTips, t, buildDeviceUnavailableText } from '../locales/index';
 import { BellContext } from './bellContext';
 import { avoidRepeatedCall } from '../utils/validate/index';
 import { handleRepeatedCallError, formatTime, performanceNow, initBrowserCloseDetection } from '../utils/common-utils';
@@ -27,7 +27,7 @@ const TUIGlobal: ITUIGlobal = TuiGlobal.getInstance();
 const TUIStore: ITUIStore = TuiStore.getInstance();
 const uiDesign = UIDesign.getInstance();
 uiDesign.setTUIStore(TUIStore);
-const version = '4.5.10';
+const version = '4.6.0';
 import AIAssistant from './AIAssistant'; // 仅 web 支持 AI 实时字幕
 const frameWork = 'react';
 export { TUIGlobal, TUIStore, uiDesign };
@@ -45,6 +45,11 @@ export default class TUICallService {
   private _currentGroupId: string = ''; // The currentGroupId of the group chat that the user is currently in
   private _offlinePushInfo = null;
   private _permissionCheckTimer: any = null;
+  // Device permission error codes maintained by the service layer (0 = no error).
+  // Populated by catching the error thrown from engine's device permission check,
+  // replacing the removed engine-side audioErrorName/videoErrorName fields.
+  private _deviceErrorCodes = { audio: DEVICE_ERROR_CODE.NONE, video: DEVICE_ERROR_CODE.NONE };
+
   private _chatCombine: any = null;
   private _engineEventHandler: any = null;
   // wasm ready
@@ -217,6 +222,10 @@ export default class TUICallService {
       const { userIDList, type, chatGroupID, offlinePushInfo } = callsParams;
       if (TUIStore.getData(StoreName.CALL, NAME.CALL_STATUS) !== CallStatus.IDLE) return;
       const remoteUserInfoList = userIDList.map(userId => ({ userId }));
+      // Engine no longer probes device permission internally, so the service layer
+      // must do it before the call. This keeps updateDeviceList and the post-call
+      // permission dialog working against the real device state.
+      await this.probeDevicePermission({ audio: true, video: type === CallMediaType.VIDEO });
       await this._updateCallStoreBeforeCall(type, remoteUserInfoList, chatGroupID);
       this.executeExternalBeforeCalling();
       callsParams.offlinePushInfo = { ...this.getDefaultOfflinePushInfo(), ...offlinePushInfo };
@@ -240,18 +249,25 @@ export default class TUICallService {
       };
       TUIStore.updateStore(updateStoreParams, StoreName.CALL);
 
+      // Engine no longer probes device permission internally; probe here so the
+      // following updateDeviceList and audio availability read the real state.
+      await this.probeDevicePermission({
+        audio: true,
+        video: updateStoreParams[NAME.CALL_MEDIA_TYPE] === CallMediaType.VIDEO,
+      });
       const response = await this._tuiCallEngine.join(params);
       TUIStore.update(StoreName.CALL, NAME.IS_CLICKABLE, true);
       this.startTimer();
 
-      updateDeviceList(this._tuiCallEngine);;
+      updateDeviceList(this._tuiCallEngine);
       await this._tuiCallEngine.setVideoQuality(TUIStore.getData(StoreName.CALL, NAME.VIDEO_RESOLUTION));
       const localUserInfo = TUIStore.getData(StoreName.CALL, NAME.LOCAL_USER_INFO);
       TUIStore.update(StoreName.CALL, NAME.LOCAL_USER_INFO, { ...localUserInfo, isEnter: true });
       TUIStore.update(StoreName.CALL, NAME.LOCAL_USER_INFO_EXCLUDE_VOLUMN, { ...localUserInfo, isEnter: true });
 
       await this.openMicrophone();
-      setLocalUserInfoAudioVideoAvailable(true, NAME.AUDIO);
+      const joinPermission = this._tuiCallEngine?.getDevicePermission();
+      setLocalUserInfoAudioVideoAvailable(!!joinPermission?.audio, NAME.AUDIO);
 
       // // Current policy: By default, the camera remains off when joining GroupCall
       // if (TUIStore.getData(StoreName.CALL, NAME.CALL_MEDIA_TYPE) === CallMediaType.VIDEO) {
@@ -377,11 +393,29 @@ export default class TUICallService {
       data: { callStatus },
     });
     if (callStatus === CallStatus.CONNECTED) return; // avoid double click when application stuck, especially for miniProgram
+
+    // Probe device permission so the following accept flow (updateDeviceList /
+    // openMicrophone / unavailable hints) runs against the real device state.
+    // Unavailable devices no longer block accept: we connect directly and surface
+    // a toast + banner afterwards instead of popping a confirm dialog.
+    const acceptMediaType = TUIStore.getData(StoreName.CALL, NAME.CALL_MEDIA_TYPE);
+    await this.probeDevicePermission({
+      audio: true,
+      video: acceptMediaType === CallMediaType.VIDEO,
+    });
+
+    await this._doAccept();
+  }
+
+  // Perform the actual accept (called directly or after the accept-permission dialog)
+  public async _doAccept() {
     try {
       TUIStore.update(StoreName.CALL, NAME.CALL_STATUS, CallStatus.CONNECTED);
-      updateDeviceList(this._tuiCallEngine);;
+      updateDeviceList(this._tuiCallEngine);
       const response = await this._tuiCallEngine.accept();
       await this._handleAcceptResponse(response);
+      const acceptCallMediaType = TUIStore.getData(StoreName.CALL, NAME.CALL_MEDIA_TYPE);
+      this._updateDeviceUnavailableHints(acceptCallMediaType);
     } catch (error) {
       this._tuiCallEngine?.reportLog?.({
         name: 'TUICallKit.accept.fail',
@@ -406,7 +440,8 @@ export default class TUICallService {
       const localUserInfo = TUIStore.getData(StoreName.CALL, NAME.LOCAL_USER_INFO);
       TUIStore.update(StoreName.CALL, NAME.LOCAL_USER_INFO, { ...localUserInfo, isEnter: true });
       TUIStore.update(StoreName.CALL, NAME.LOCAL_USER_INFO_EXCLUDE_VOLUMN, { ...localUserInfo, isEnter: true });
-      setLocalUserInfoAudioVideoAvailable(true, NAME.AUDIO); // web && mini default open audio
+      const acceptPermission = this._tuiCallEngine?.getDevicePermission();
+      setLocalUserInfoAudioVideoAvailable(!!acceptPermission?.audio, NAME.AUDIO);
     }
   }
   @avoidRepeatedCall()
@@ -441,6 +476,11 @@ export default class TUICallService {
   }
   @avoidRepeatedCall()
   public async openCamera(videoViewDomID: string) {
+    // Skip opening camera if video permission is already known to be unavailable
+    if (this.isDeviceKnownUnavailable(NAME.VIDEO as 'video')) {
+      console.warn(`${NAME.PREFIX}openCamera skipped: video device unavailable (code ${this._deviceErrorCodes.video}).`);
+      return;
+    }
     try {
       if (TUIGlobal.isH5 || TUIGlobal.isWeChat) {
         const currentPosition = TUIStore.getData(StoreName.CALL, NAME.CAMERA_POSITION);
@@ -466,6 +506,11 @@ export default class TUICallService {
   }
   @avoidRepeatedCall()
   public async openMicrophone() {
+    // Skip opening microphone if audio permission is already known to be unavailable
+    if (this.isDeviceKnownUnavailable(NAME.AUDIO as 'audio')) {
+      console.warn(`${NAME.PREFIX}openMicrophone skipped: audio device unavailable (code ${this._deviceErrorCodes.audio}).`);
+      return;
+    }
     try {
       await this._tuiCallEngine.openMicrophone();
       setLocalUserInfoAudioVideoAvailable(true, NAME.AUDIO);
@@ -659,6 +704,102 @@ export default class TUICallService {
     }
   }
   // =========================【private methods for service use】=========================
+  /**
+   * Check device permissions after call/accept succeeds.
+   * 1. Show an error toast summarizing unavailable devices.
+   * 2. Store the unavailable-device reasons so the banner bar and button badges
+   *    can render accordingly (aligned with interaction design).
+   */
+  private _updateDeviceUnavailableHints(callMediaType: CallMediaType): void {
+    const deviceUnavailableReasons = this._resolveUnavailableDevices(callMediaType);
+    if (!deviceUnavailableReasons) {
+      TUIStore.update(StoreName.CALL, NAME.DEVICE_UNAVAILABLE_REASONS, null);
+      return;
+    }
+
+    // Build toast message by grouping devices per reason so mixed cases
+    // (e.g. mic no-permission + camera no-device) are described accurately.
+    const toastText = buildDeviceUnavailableText(deviceUnavailableReasons.microphone, deviceUnavailableReasons.camera, 'toast');
+    TUIStore.update(StoreName.CALL, NAME.TOAST_INFO, {
+      content: { key: 'permission-toast-raw', options: { text: toastText } },
+      type: NAME.ERROR,
+    });
+
+    // Store the unavailable-device reasons for banner bar + button badges
+    TUIStore.update(StoreName.CALL, NAME.DEVICE_UNAVAILABLE_REASONS, deviceUnavailableReasons);
+  }
+
+  /**
+   * Resolve the classified reasons for currently unavailable devices from the engine's
+   * cached permission. Returns null when all required devices are available; otherwise
+   * returns the per-device reason. Derived values (whether it is a permission issue,
+   * device-name text) are computed by the UI from these reasons.
+   */
+  private _resolveUnavailableDevices(callMediaType: CallMediaType): DeviceUnavailableReasons | null {
+    const permission = this._tuiCallEngine?.getDevicePermission();
+    if (!permission) return null;
+
+    const noMicrophone = !permission.audio;
+    const noCamera = callMediaType === CallMediaType.VIDEO && !permission.video;
+    if (!noMicrophone && !noCamera) return null;
+
+    // Map the engine's audio/video permission to device-named reasons for the UI.
+    return {
+      microphone: noMicrophone ? this._classifyDeviceErrorReason(this._deviceErrorCodes.audio) : null,
+      camera: noCamera ? this._classifyDeviceErrorReason(this._deviceErrorCodes.video) : null,
+    };
+  }
+
+  private _classifyDeviceErrorReason(errorCode: number): DeviceErrorReason {
+    switch (errorCode) {
+      case DEVICE_ERROR_CODE.PERMISSION_DENIED: return 'no-permission';
+      case DEVICE_ERROR_CODE.NO_MICROPHONE:
+      case DEVICE_ERROR_CODE.NO_CAMERA: return 'no-device';
+      case DEVICE_ERROR_CODE.MICROPHONE_NOT_READABLE:
+      case DEVICE_ERROR_CODE.CAMERA_NOT_READABLE: return 'device-occupied';
+      default: return 'unknown';
+    }
+  }
+
+  /**
+   * Probe device permission by reusing engine's device permission check, which
+   * triggers getUserMedia and classifies the failure (incl. iOS repeated-call and
+   * http protocol handling). The thrown error's code is cached per device so the
+   * service layer can decide device availability without engine-side errorName.
+   * Audio and video are probed separately because engine aborts on the first failure.
+   */
+  public async probeDevicePermission(opts: { audio?: boolean; video?: boolean }): Promise<void> {
+    if (opts.audio) {
+      try {
+        await this._tuiCallEngine?._checkDevicePermission({ audio: true });
+        this._deviceErrorCodes.audio = DEVICE_ERROR_CODE.NONE;
+      } catch (error: any) {
+        this._deviceErrorCodes.audio = error?.code ?? DEVICE_ERROR_CODE.NONE;
+      }
+    }
+    if (opts.video) {
+      try {
+        // isThrowVideoError is required, otherwise engine swallows the video error.
+        await this._tuiCallEngine?._checkDevicePermission({ video: true, isThrowVideoError: true });
+        this._deviceErrorCodes.video = DEVICE_ERROR_CODE.NONE;
+      } catch (error: any) {
+        this._deviceErrorCodes.video = error?.code ?? DEVICE_ERROR_CODE.NONE;
+      }
+    }
+  }
+
+  // Clear the cached device error so the next probe re-triggers the browser prompt.
+  public resetDeviceError(type: 'audio' | 'video'): void {
+    if (type === NAME.AUDIO) this._deviceErrorCodes.audio = DEVICE_ERROR_CODE.NONE;
+    if (type === NAME.VIDEO) this._deviceErrorCodes.video = DEVICE_ERROR_CODE.NONE;
+  }
+
+  // Whether a device is known to be unavailable (permission off / no device / occupied).
+  public isDeviceKnownUnavailable(type: 'audio' | 'video'): boolean {
+    const permission = this._tuiCallEngine?.getDevicePermission();
+    if (type === NAME.AUDIO) return !permission?.audio && this._deviceErrorCodes.audio !== DEVICE_ERROR_CODE.NONE;
+    return !permission?.video && this._deviceErrorCodes.video !== DEVICE_ERROR_CODE.NONE;
+  }
   // 处理 "呼叫" 抛出的异常
   private _handleCallError(error: any, methodName?: string) {
     this._permissionCheckTimer && clearInterval(this._permissionCheckTimer);
@@ -691,7 +832,7 @@ export default class TUICallService {
       oldStatus: StatusChange.IDLE,
       newStatus: (groupID || remoteUserInfoList.length > 1) ? StatusChange.DIALING_GROUP : StatusChange.DIALING_C2C,
     });
-    updateDeviceList(this._tuiCallEngine);;
+    updateDeviceList(this._tuiCallEngine);
     const remoteUserInfoLists = await getRemoteUserProfile(remoteUserInfoList.map(obj => obj.userId), this.getTim());
 
     if (remoteUserInfoLists.length > 0) {
@@ -721,7 +862,10 @@ export default class TUICallService {
       const localUserInfo = TUIStore.getData(StoreName.CALL, NAME.LOCAL_USER_INFO);
       TUIStore.update(StoreName.CALL, NAME.LOCAL_USER_INFO, { ...localUserInfo, isEnter: true });
       TUIStore.update(StoreName.CALL, NAME.LOCAL_USER_INFO_EXCLUDE_VOLUMN, { ...localUserInfo, isEnter: true });
-      setLocalUserInfoAudioVideoAvailable(true, NAME.AUDIO); // web && mini, default open audio
+      const callPermission = this._tuiCallEngine?.getDevicePermission();
+      setLocalUserInfoAudioVideoAvailable(!!callPermission?.audio, NAME.AUDIO);
+      // Show device-unavailable hints (banner / button badges / toast) once the call is established.
+      this._updateDeviceUnavailableHints(callMediaType);
     } else {
       this._permissionCheckTimer && clearInterval(this._permissionCheckTimer);
       this._permissionCheckTimer = null;

package/src/TUICallService/CallService/utils.ts

@@ -200,19 +200,29 @@ export function deleteRemoteUser(userIdList: string[]): void {
   TUIStore.update(StoreName.CALL, NAME.REMOTE_USER_INFO_EXCLUDE_VOLUMN_LIST, remoteUserInfoList);
 }
 export function updateDeviceList(tuiCallEngine) {
-  tuiCallEngine?.getDeviceList('speaker').then((result)=>{
-    const deviceList = TUIStore.getData(StoreName.CALL, NAME.DEVICE_LIST);
-    const currentSpeaker = result?.[0] || {};
-    TUIStore.update(
-      StoreName.CALL,
-      NAME.DEVICE_LIST,
-      { ...deviceList, speakerList: result, currentSpeaker },
-    );
-  }).catch(error =>{
-    console.error(`${NAME.PREFIX}updateSpeakerList failed, error: ${JSON.stringify(error)}.`);
-  });
+  // Check current permission state to avoid triggering getUserMedia prompts.
+  // getDeviceList internally calls _checkDevicePermission which fires getUserMedia
+  // when the permission has not been checked yet (permission.audio/video is false).
+  // This races with Engine.calls() and causes duplicate browser prompts.
+  const permission = tuiCallEngine?.getDevicePermission?.();
+  const hasAudioPermission = permission?.audio === true;
+  const hasVideoPermission = permission?.video === true;
+
+  if (hasAudioPermission) {
+    tuiCallEngine?.getDeviceList('speaker').then((result)=>{
+      const deviceList = TUIStore.getData(StoreName.CALL, NAME.DEVICE_LIST);
+      const currentSpeaker = result?.[0] || {};
+      TUIStore.update(
+        StoreName.CALL,
+        NAME.DEVICE_LIST,
+        { ...deviceList, speakerList: result, currentSpeaker },
+      );
+    }).catch(error =>{
+      console.error(`${NAME.PREFIX}updateSpeakerList failed, error: ${JSON.stringify(error)}.`);
+    });
+  }
   const callMediaType = TUIStore.getData(StoreName.CALL, NAME.CALL_MEDIA_TYPE);
-  if (callMediaType === CallMediaType.VIDEO) {
+  if (callMediaType === CallMediaType.VIDEO && hasVideoPermission) {
     tuiCallEngine?.getDeviceList('camera').then((result) => {
       const deviceList = TUIStore.getData(StoreName.CALL, NAME.DEVICE_LIST);
       const currentCamera = result?.[0] || {};
@@ -225,17 +235,19 @@ export function updateDeviceList(tuiCallEngine) {
       console.error(`${NAME.PREFIX}updateCameraList failed, error: ${error}.`);
     });
   }
-  tuiCallEngine?.getDeviceList('microphones').then((result) => {
-    const deviceList = TUIStore.getData(StoreName.CALL, NAME.DEVICE_LIST);
-    const currentMicrophone = result?.[0] || {};
-    TUIStore.update(
-      StoreName.CALL,
-      NAME.DEVICE_LIST,
-      { ...deviceList, microphoneList: result, currentMicrophone },
-    );
-  }).catch(error => {
-    console.error(`${NAME.PREFIX}updateMicrophoneList failed, error: ${error}.`);
-  });
+  if (hasAudioPermission) {
+    tuiCallEngine?.getDeviceList('microphones').then((result) => {
+      const deviceList = TUIStore.getData(StoreName.CALL, NAME.DEVICE_LIST);
+      const currentMicrophone = result?.[0] || {};
+      TUIStore.update(
+        StoreName.CALL,
+        NAME.DEVICE_LIST,
+        { ...deviceList, microphoneList: result, currentMicrophone },
+      );
+    }).catch(error => {
+      console.error(`${NAME.PREFIX}updateMicrophoneList failed, error: ${error}.`);
+    });
+  }
 }
 /**
  * update the no device permission toast

package/src/TUICallService/TUIStore/callStore.ts

@@ -60,6 +60,7 @@ export default class CallStore {
     realtimeMessageList: [],
     isAITranscriberEnabled: false,
     isAITranscriberRunning: false,
+    deviceUnavailableReasons: null, // per-device unavailable reasons (null = available)
   };
   public store: ICallStore = deepClone(this.defaultStore);
   public prevStore: ICallStore = deepClone(this.defaultStore);

package/src/TUICallService/const/index.ts

@@ -40,6 +40,7 @@ export const CALL_DATA_KEY: any = {
   PUSHER_ID: 'pusherId',
   IS_FORCE_USE_V2_API: 'isForceUseV2API',
   MODAL_ERROR: 'modalError',
+  DEVICE_UNAVAILABLE_REASONS: 'deviceUnavailableReasons',
   TRANSCRIBER_ROBOT_ID: 'transcriberRobotId',
   REALTIME_MESSAGE_LIST: 'realtimeMessageList',
   IS_AI_TRANSCRIBER_ENABLED: 'isAITranscriberEnabled', // Controls UI visibility
@@ -84,6 +85,32 @@ export const NAME = {
   ...CHAT_DATA_KEY,
 };
 
+// Stable device error codes exposed by TUICallEngine (kept in sync with the
+// engine's public ERROR_CODE). Used by the service layer to classify device
+// failures caught from engine's device permission check, instead of relying on
+// engine-internal errorName fields.
+// Classified reason why a device is unavailable, shared by the service layer and UI.
+export type DeviceErrorReason = 'no-permission' | 'no-device' | 'device-occupied' | 'unknown' | null;
+
+// Per-device reason why a device is currently unavailable. The value is the classified
+// reason (e.g. 'no-permission' / 'no-device' / 'device-occupied'); null means that device
+// is available. The keys follow the engine's audio/video wording:
+//   - microphone (audio input)
+//   - camera (video input)
+export interface DeviceUnavailableReasons {
+  microphone: DeviceErrorReason;
+  camera: DeviceErrorReason;
+}
+
+export const DEVICE_ERROR_CODE = {
+  NONE: 0, // no error
+  PERMISSION_DENIED: -1101, // NotAllowedError, permission refused
+  NO_MICROPHONE: 60003, // NotFoundError, no microphone device
+  NO_CAMERA: 60004, // NotFoundError, no camera device
+  MICROPHONE_NOT_READABLE: 60007, // NotReadableError, mic occupied / hardware error
+  CAMERA_NOT_READABLE: 60008, // NotReadableError, camera occupied / hardware error
+};
+
 export const AudioCallIcon = 'https://web.sdk.qcloud.com/component/TUIKit/assets/call.png';
 export const VideoCallIcon = 'https://web.sdk.qcloud.com/component/TUIKit/assets/call-video-reverse.svg';
 export const MAX_NUMBER_ROOM_ID = 2147483647;

package/src/TUICallService/index.ts

@@ -13,7 +13,7 @@ import {
   LayoutMode,
   CloudRecordPolicy,
 } from './const/index';
-import { t } from './locales/index';
+import { t, buildDeviceUnavailableText } from './locales/index';
 
 // 实例化
 const TUICallKitAPI = TUICallService.getInstance();
@@ -32,6 +32,7 @@ export {
   VideoDisplayMode,
   AudioPlayBackDevice,
   t,
+  buildDeviceUnavailableText,
   uiDesign,
   FeatureButton,
   LayoutMode,

package/src/TUICallService/interface/ICallStore.ts

@@ -1,4 +1,4 @@
-import { CallStatus, CallRole, CallMediaType, VideoDisplayMode, VideoResolution, TDeviceList, CameraPosition, ICustomUIConfig } from '../const/index';
+import { CallStatus, CallRole, CallMediaType, VideoDisplayMode, VideoResolution, TDeviceList, CameraPosition, ICustomUIConfig, DeviceUnavailableReasons } from '../const/index';
 import { IUserInfo, INetWorkQuality } from './index';
 
 export interface IToastInfo {
@@ -58,4 +58,5 @@ export interface ICallStore {
   realtimeMessageList: [], // 实时转写消息列表
   isAITranscriberEnabled: boolean, // AI 转写UI是否显示
   isAITranscriberRunning: boolean, // AI transcriber running state
+  deviceUnavailableReasons: DeviceUnavailableReasons | null, // Per-device unavailable reason (null = available); drives banner/button badges & toast
 }

package/src/TUICallService/locales/en.ts

@@ -49,6 +49,10 @@ export const en = {
   'camera disabled': 'Camera Off',
   'microphone enabled': 'Unmuted',
   'microphone disabled': 'Muted',
+  'no mic permission': 'No Mic Access',
+  'no mic device': 'No Mic Found',
+  'no cam permission': 'No Cam Access',
+  'no cam device': 'No Cam Found',
   'speaker enabled': 'Speaker On',
   'speaker disabled': 'Speaker Off',
   'open speaker': 'Turn on speaker',
@@ -152,6 +156,28 @@ export const en = {
   'error.10017': "Failed to start the call: the callee userID cannot be the current logged-in user. Please check the callee userID you passed in.",
   'error.10018': "Failed to start the call: the number of callees in a single call must be between 1 and 8. Please check the userIDList you passed in.",
   'error': 'Error',
+  // Permission / device unavailability texts
+  'permission-device-separator': ' and ',
+  'permission-phrase-separator': '; ',
+  'permission-sentence-separator': '. ',
+  'permission-phrase-perm': '{{ devices }} access denied',
+  'permission-phrase-no-device': '{{ devices }} not detected',
+  'permission-phrase-occupied': '{{ devices }} is in use by another app',
+  'permission-phrase-unknown': '{{ devices }} unavailable',
+  'permission-toast-suffix': ', cannot be used during the call.',
+  'permission-toast-raw': '{{ text }}',
+  'permission-banner-guide-perm': 'Please allow access in the browser address bar.',
+  'permission-banner-guide-perm-h5': 'Please enable in system settings.',
+  'permission-banner-guide-no-device': 'Please connect device and try again.',
+  'permission-banner-guide-no-device-h5': 'Please connect device.',
+  'permission-btn-mic-no-perm': 'Microphone access denied. Please click the lock icon in the address bar to allow.',
+  'permission-btn-mic-no-device': 'No microphone detected. Please connect a microphone.',
+  'permission-btn-mic-occupied': 'Microphone is in use by another app. Please close that app.',
+  'permission-btn-cam-no-perm': 'Camera access denied. Please click the lock icon in the address bar to allow.',
+  'permission-btn-cam-no-device': 'No camera detected. Please connect a camera.',
+  'permission-btn-cam-occupied': 'Camera is in use by another app. Please close that app.',
+  'permission-btn-mic-no-perm-h5': 'Microphone access denied. Please allow browser microphone access in system settings.',
+  'permission-btn-cam-no-perm-h5': 'Camera access denied. Please allow browser camera access in system settings.',
   // AI Subtitle Settings
   'ai-subtitle': 'AI Subtitle',
   'ai-subtitle-settings': 'AI Subtitle Settings',

package/src/TUICallService/locales/index.ts

@@ -59,3 +59,69 @@ interface languageItemType {
 interface languageDataType {
   [key: string]: languageItemType;
 }
+
+// Map a classified device error reason to its phrase translation key.
+const DEVICE_REASON_PHRASE_KEY: { [reason: string]: string } = {
+  'no-permission': 'permission-phrase-perm',
+  'no-device': 'permission-phrase-no-device',
+  'device-occupied': 'permission-phrase-occupied',
+};
+
+/**
+ * Build a device-unavailability message by grouping devices by their error reason,
+ * so each reason is described accurately. For example, when the microphone has no
+ * permission and the camera has no device, it produces
+ * "麦克风权限未开启，未检测到摄像头" instead of wrongly saying both lack permission.
+ *
+ * @param audioReason classified reason for the microphone, or null if available
+ * @param videoReason classified reason for the camera, or null if available
+ * @param scene 'plain' returns the grouped description only; 'toast' appends the
+ *        in-call suffix; 'banner' appends the guidance sentence
+ * @param isMobile selects PC vs H5 guidance text (banner only)
+ * @returns the composed localized text, or '' when no device is unavailable
+ */
+export function buildDeviceUnavailableText(
+  audioReason: string | null,
+  videoReason: string | null,
+  scene: 'plain' | 'toast' | 'banner',
+  isMobile = false,
+): string {
+  const reasonToDevices: { [reason: string]: string[] } = {};
+  const collect = (reason: string | null, deviceName: string) => {
+    if (!reason) return;
+    (reasonToDevices[reason] = reasonToDevices[reason] || []).push(deviceName);
+  };
+  collect(audioReason, t('microphone'));
+  collect(videoReason, t('camera'));
+
+  const reasons = Object.keys(reasonToDevices);
+  if (reasons.length === 0) return '';
+
+  const deviceSep = t('permission-device-separator');
+  const phraseSep = t('permission-phrase-separator');
+  const phrases = reasons.map((reason) => {
+    const deviceNameText = reasonToDevices[reason].join(deviceSep);
+    const phraseKey = DEVICE_REASON_PHRASE_KEY[reason] || 'permission-phrase-unknown';
+    return t({ key: phraseKey, options: { devices: deviceNameText } });
+  });
+  const description = phrases.join(phraseSep);
+
+  if (scene === 'plain') {
+    return description;
+  }
+
+  if (scene === 'toast') {
+    return `${description}${t('permission-toast-suffix')}`;
+  }
+
+  // Banner: permission issues take priority since the user must actively grant
+  // access; otherwise guide the user to connect a device.
+  const hasPermIssue = reasons.includes('no-permission');
+  let guideKey: string;
+  if (hasPermIssue) {
+    guideKey = isMobile ? 'permission-banner-guide-perm-h5' : 'permission-banner-guide-perm';
+  } else {
+    guideKey = isMobile ? 'permission-banner-guide-no-device-h5' : 'permission-banner-guide-no-device';
+  }
+  return `${description}${t('permission-sentence-separator')}${t(guideKey)}`;
+}

package/src/TUICallService/locales/ja_JP.ts

@@ -60,6 +60,10 @@ export const ja_JP = {
   'camera disabled': 'カメラオフ',
   'microphone enabled': 'マイクオン',
   'microphone disabled': 'マイクオフ',
+  'no mic permission': 'マイク権限なし',
+  'no mic device': 'マイク未検出',
+  'no cam permission': 'カメラ権限なし',
+  'no cam device': 'カメラ未検出',
   'speaker enabled': 'スピーカーオン',
   'speaker disabled': 'スピーカーオフ',
   'open speaker': 'スピーカーをオンにする',
@@ -150,6 +154,28 @@ export const ja_JP = {
   'error.10017': "通話の発信に失敗しました：着信側 userID を現在ログイン中のユーザー自身に指定することはできません。渡した着信側 userID を確認してください。",
   'error.10018': "通話の発信に失敗しました：1 回の通話で指定できる着信側ユーザー数は 1〜8 人である必要があります。渡した userIDList を確認してください。",
   'error': 'エラー',
+  // Permission / device unavailability texts
+  'permission-device-separator': '、',
+  'permission-phrase-separator': '、',
+  'permission-sentence-separator': '。',
+  'permission-phrase-perm': '{{ devices }}のアクセス許可が未設定です',
+  'permission-phrase-no-device': '{{ devices }}が検出されません',
+  'permission-phrase-occupied': '{{ devices }}が他のアプリで使用中です',
+  'permission-phrase-unknown': '{{ devices }}は使用できません',
+  'permission-toast-suffix': '。通話中は使用できません。',
+  'permission-toast-raw': '{{ text }}',
+  'permission-banner-guide-perm': 'ブラウザのアドレスバーでアクセスを許可してください。',
+  'permission-banner-guide-perm-h5': 'システム設定で有効にしてください。',
+  'permission-banner-guide-no-device': 'デバイスを接続して再試行してください。',
+  'permission-banner-guide-no-device-h5': 'デバイスを接続してください。',
+  'permission-btn-mic-no-perm': 'マイクのアクセス許可が未設定です。アドレスバーのロックアイコンをクリックして許可してください。',
+  'permission-btn-mic-no-device': 'マイクが検出されません。マイクを接続してください。',
+  'permission-btn-mic-occupied': 'マイクが他のアプリで使用中です。他のアプリを閉じてください。',
+  'permission-btn-cam-no-perm': 'カメラのアクセス許可が未設定です。アドレスバーのロックアイコンをクリックして許可してください。',
+  'permission-btn-cam-no-device': 'カメラが検出されません。カメラを接続してください。',
+  'permission-btn-cam-occupied': 'カメラが他のアプリで使用中です。他のアプリを閉じてください。',
+  'permission-btn-mic-no-perm-h5': 'マイクのアクセス許可が未設定です。システム設定でブラウザのマイクを許可してください。',
+  'permission-btn-cam-no-perm-h5': 'カメラのアクセス許可が未設定です。システム設定でブラウザのカメラを許可してください。',
   // AI Subtitle Settings
   'ai-subtitle': 'AI字幕',
   'ai-subtitle-settings': 'AI字幕設定',

package/src/TUICallService/locales/zh-cn.ts

@@ -49,6 +49,10 @@ export const zh = {
   'camera disabled': '摄像头已关',
   'microphone enabled': '麦克风已开',
   'microphone disabled': '麦克风已关',
+  'no mic permission': '无麦克风权限',
+  'no mic device': '无麦克风设备',
+  'no cam permission': '无摄像头权限',
+  'no cam device': '无摄像头设备',
   'speaker enabled': '扬声器已开',
   'speaker disabled': '扬声器已关',
   'open speaker': '开启扬声器',
@@ -147,6 +151,37 @@ export const zh = {
   'error.10017': "发起通话失败：被叫 userID 不能是当前登录用户自己，请检查传入的被叫 userID。",
   'error.10018': "发起通话失败：单次呼叫的被叫用户数量需在 1 到 8 之间，请检查传入的 userIDList。",
   'error': '错误',
+  // Permission / device unavailability texts
+  // Separator used when joining multiple device names sharing the same reason (e.g. microphone、camera)
+  'permission-device-separator': '、',
+  // Separator used when joining phrases of different reasons
+  'permission-phrase-separator': '，',
+  // Separator between the device description and the guidance sentence (banner)
+  'permission-sentence-separator': '，',
+  // Device unavailability phrases (grouped by reason, combined dynamically)
+  'permission-phrase-perm': '{{ devices }}权限未开启',
+  'permission-phrase-no-device': '未检测到{{ devices }}',
+  'permission-phrase-occupied': '{{ devices }}被其他应用占用',
+  'permission-phrase-unknown': '{{ devices }}不可用',
+  // Toast: suffix appended after the combined device phrases
+  'permission-toast-suffix': '，通话中将无法使用',
+  // Toast: raw passthrough template for pre-composed text
+  'permission-toast-raw': '{{ text }}',
+  // Banner: guidance appended after the device phrases (PC / H5)
+  'permission-banner-guide-perm': '请在浏览器地址栏允许访问',
+  'permission-banner-guide-perm-h5': '请前往系统设置开启',
+  'permission-banner-guide-no-device': '请连接设备后重试',
+  'permission-banner-guide-no-device-h5': '请连接设备',
+  // Button click toast (PC)
+  'permission-btn-mic-no-perm': '麦克风权限未开启，请在浏览器地址栏点击锁定图标允许使用',
+  'permission-btn-mic-no-device': '未检测到麦克风设备，请连接麦克风后重试',
+  'permission-btn-mic-occupied': '麦克风被其他应用占用，请关闭占用应用后重试',
+  'permission-btn-cam-no-perm': '摄像头权限未开启，请在浏览器地址栏点击锁定图标允许使用',
+  'permission-btn-cam-no-device': '未检测到摄像头设备，请连接摄像头后重试',
+  'permission-btn-cam-occupied': '摄像头被其他应用占用，请关闭占用应用后重试',
+  // Button click toast (H5)
+  'permission-btn-mic-no-perm-h5': '麦克风权限未开启，请在手机系统设置中允许浏览器使用麦克风',
+  'permission-btn-cam-no-perm-h5': '摄像头权限未开启，请在手机系统设置中允许浏览器使用摄像头',
   // AI Subtitle Settings
   'ai-subtitle': 'AI 字幕',
   'ai-subtitle-settings': 'AI 字幕设置',

package/src/index.ts

@@ -35,7 +35,7 @@ const TUICallType = {
   AUDIO_CALL: 1,
   VIDEO_CALL: 2,
 };
-const Version = '4.5.10'; // basic-demo 原来上报使用
+const Version = '4.6.0'; // basic-demo 原来上报使用
 
 // 输出产物
 export {