@trtc/calls-uikit-react 4.5.11 → 4.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trtc/calls-uikit-react",
-  "version": "4.5.11",
+  "version": "4.6.0",
   "main": "./tuicall-uikit-react.umd.js",
   "module": "./tuicall-uikit-react.es.js",
   "types": "./types/index.d.ts",
@@ -14,7 +14,7 @@
   },
   "dependencies": {
     "@tencentcloud/tui-core-lite": "~1.0.1",
-    "@trtc/call-engine-lite-js": "~4.0.10",
+    "@trtc/call-engine-lite-js": "~4.1.0",
     "@tencentcloud/lite-chat": "^1.6.3",
     "@trtc/call-engine-lite-wx": "~5.0.6"
 },

package/src/Components/TUICallKit/TUICallKit.tsx

@@ -16,6 +16,7 @@ import SingleCall from '../components/SingleCall/SingleCall';
 import GroupCall from '../components/GroupCall/GroupCall';
 import { AISubtitle } from '../components/common/AIAssistant';
 import AutoPlayDialog from '../components/common/AutoPlayDialog';
+import DevicePermissionBanner from '../components/common/PermissionDialog';
 import { classNames } from '../util/classnames';
 import {
   CallInfoContext,
@@ -338,6 +339,7 @@ export default function TUICallKit(props: ITUICallKitProps) {
                 {!isMultiUserLayout && <SingleCall />}
                 {isMultiUserLayout && <GroupCall />}
                 <AutoPlayDialog />
+                <DevicePermissionBanner />
                 <AISubtitle />
               </div>
               <Portal attach="body">

package/src/Components/components/common/ButtonPanel/button/Camera.tsx

@@ -1,6 +1,7 @@
 import React, {
   useCallback,
   useContext,
+  useEffect,
   useMemo,
   useState,
 } from 'react';
@@ -9,9 +10,11 @@ import Icon from '../../../base/Icon/Icon';
 import { classNames } from '../../../../util/classnames';
 import Popup from '../../../base/Popup/Popup';
 import DeviceSelector from '../../DeviceSelector/DeviceSelector';
-import { DeviceType } from '../../../../../TUICallService/const';
+import { DeviceType, NAME } from '../../../../../TUICallService/const';
 import { UserInfoContext } from '../../../../context';
-import { TUICallKitAPI, TUIGlobal } from '../../../../../TUICallService';
+import {
+  TUICallKitAPI, TUIGlobal, TUIStore, StoreName,
+} from '../../../../../TUICallService';
 import { useTranslate } from '../../../../hooks';
 import CameraOpenSrc from '../../../../assets/button/camera-open.svg';
 import CameraCloseSrc from '../../../../assets/button/camera-close.svg';
@@ -32,8 +35,42 @@ export default function Camera(props: ICameraProps) {
   const [isClickable, setIsClickable] = useState(true);
   const { t } = useTranslate();
   const [{ deviceList }] = useDeviceList(DeviceType.CAMERA);
+
+  // Subscribe to the unavailable-device reasons so the camera button can show a
+  // red badge and intercept clicks when the camera is unavailable.
+  const [
+    deviceUnavailableReasons,
+    setDeviceUnavailableReasons,
+  ] = useState(TUIStore.getData(StoreName.CALL, NAME.DEVICE_UNAVAILABLE_REASONS));
+  useEffect(() => {
+    const handleChange = (value) => setDeviceUnavailableReasons(value);
+    TUIStore.watch(StoreName.CALL, {
+      [NAME.DEVICE_UNAVAILABLE_REASONS]: handleChange,
+    }, { notifyRangeWhenWatch: NAME.MYSELF });
+    return () => {
+      TUIStore.unwatch(StoreName.CALL, {
+        [NAME.DEVICE_UNAVAILABLE_REASONS]: handleChange,
+      });
+    };
+  }, []);
+  const cameraReason = deviceUnavailableReasons?.camera;
+  const isDeviceUnavailable = !!cameraReason;
+  const isMobile = !TUIGlobal.isPC;
+
   const handleClick = useCallback(
     async () => {
+      // When the camera is unavailable, intercept the click and show a toast
+      // guiding the user instead of toggling the camera.
+      if (isDeviceUnavailable) {
+        let tipKey = 'permission-btn-cam-no-device';
+        if (cameraReason === 'no-permission') {
+          tipKey = isMobile ? 'permission-btn-cam-no-perm-h5' : 'permission-btn-cam-no-perm';
+        } else if (cameraReason === 'device-occupied') {
+          tipKey = 'permission-btn-cam-occupied';
+        }
+        TUIStore.update(StoreName.CALL, NAME.TOAST_INFO, { content: tipKey, type: NAME.ERROR });
+        return;
+      }
       setIsClickable(false);
 
       if (isCameraOpen) {
@@ -44,7 +81,7 @@ export default function Camera(props: ICameraProps) {
 
       setIsClickable(true);
     },
-    [isCameraOpen],
+    [isCameraOpen, isDeviceUnavailable, cameraReason, isMobile],
   );
   const iconClassName = classNames([
     commonStyle['btn-icon-container'],
@@ -56,12 +93,18 @@ export default function Camera(props: ICameraProps) {
     },
   ]);
   const CameraIcon = <Icon url={isCameraOpen ? CameraOpenSrc : CameraCloseSrc} className={commonStyle['btn-icon']} />;
-  const btnText = isCameraOpen ? t('camera enabled') : t('camera disabled');
+  let btnText = isCameraOpen ? t('camera enabled') : t('camera disabled');
+  if (isDeviceUnavailable) {
+    btnText = cameraReason === 'no-permission' ? t('no cam permission') : t('no cam device');
+  }
+  const btnTextNode = isDeviceUnavailable
+    ? <span style={{ color: '#FE3C44' }}>{btnText}</span>
+    : btnText;
 
   return (
     <Popup
       content={<DeviceSelector deviceType={DeviceType.CAMERA} />}
-      disabled={!TUIGlobal.isPC || !(deviceList?.length > 0)}
+      disabled={!TUIGlobal.isPC || isDeviceUnavailable || !(deviceList?.length > 0)}
       teleported={false}
     >
       <div style={{ display: 'flex' }}>
@@ -73,7 +116,7 @@ export default function Camera(props: ICameraProps) {
           onClick={handleClick}
           {...props}
         >
-          {btnText}
+          {btnTextNode}
         </Button>
       </div>
     </Popup>

package/src/Components/components/common/ButtonPanel/button/Microphone.tsx

@@ -1,18 +1,21 @@
 import React, {
   useCallback,
   useContext,
+  useEffect,
   useMemo,
   useState,
 } from 'react';
 import Button from '../../../base/Button';
 import Icon from '../../../base/Icon/Icon';
-import { TUICallKitAPI, TUIGlobal } from '../../../../../TUICallService';
+import {
+  TUICallKitAPI, TUIGlobal, TUIStore, StoreName,
+} from '../../../../../TUICallService';
 import { UserInfoContext } from '../../../../context';
 import { classNames } from '../../../../util/classnames';
 import Popup from '../../../base/Popup/Popup';
 import DeviceSelector from '../../DeviceSelector/DeviceSelector';
 import { useTranslate, useDeviceList } from '../../../../hooks';
-import { DeviceType } from '../../../../../TUICallService/const';
+import { DeviceType, NAME } from '../../../../../TUICallService/const';
 import MicrophoneOpenSrc from '../../../../assets/button/microphone-open.svg';
 import MicrophoneCloseSrc from '../../../../assets/button/microphone-close.svg';
 import { classPrefix } from '../../../base/common';
@@ -29,8 +32,41 @@ export default function Microphone(props: IMicrophoneProps) {
   const [isClickable, setIsClickable] = useState(true);
   const { t } = useTranslate();
 
+  // Subscribe to the unavailable-device reasons so the microphone button can show
+  // a red badge and intercept clicks when the microphone is unavailable.
+  const [
+    deviceUnavailableReasons,
+    setDeviceUnavailableReasons,
+  ] = useState(TUIStore.getData(StoreName.CALL, NAME.DEVICE_UNAVAILABLE_REASONS));
+  useEffect(() => {
+    const handleChange = (value) => setDeviceUnavailableReasons(value);
+    TUIStore.watch(StoreName.CALL, {
+      [NAME.DEVICE_UNAVAILABLE_REASONS]: handleChange,
+    }, { notifyRangeWhenWatch: NAME.MYSELF });
+    return () => {
+      TUIStore.unwatch(StoreName.CALL, {
+        [NAME.DEVICE_UNAVAILABLE_REASONS]: handleChange,
+      });
+    };
+  }, []);
+  const microphoneReason = deviceUnavailableReasons?.microphone;
+  const isDeviceUnavailable = !!microphoneReason;
+  const isMobile = !TUIGlobal.isPC;
+
   const handleClick = useCallback(
     async () => {
+      // When the microphone is unavailable, intercept the click and show a toast
+      // guiding the user instead of toggling the microphone.
+      if (isDeviceUnavailable) {
+        let tipKey = 'permission-btn-mic-no-device';
+        if (microphoneReason === 'no-permission') {
+          tipKey = isMobile ? 'permission-btn-mic-no-perm-h5' : 'permission-btn-mic-no-perm';
+        } else if (microphoneReason === 'device-occupied') {
+          tipKey = 'permission-btn-mic-occupied';
+        }
+        TUIStore.update(StoreName.CALL, NAME.TOAST_INFO, { content: tipKey, type: NAME.ERROR });
+        return;
+      }
       setIsClickable(false);
 
       if (isOpen) {
@@ -41,7 +77,7 @@ export default function Microphone(props: IMicrophoneProps) {
 
       setIsClickable(true);
     },
-    [isOpen, setIsClickable],
+    [isOpen, setIsClickable, isDeviceUnavailable, microphoneReason, isMobile],
   );
   const iconClassName = classNames([
     commonStyle['btn-icon-container'],
@@ -52,13 +88,19 @@ export default function Microphone(props: IMicrophoneProps) {
       disabled: !isClickable,
     },
   ]);
-  const btnText = isOpen ? t('microphone enabled') : t('microphone disabled');
+  let btnText = isOpen ? t('microphone enabled') : t('microphone disabled');
+  if (isDeviceUnavailable) {
+    btnText = microphoneReason === 'no-permission' ? t('no mic permission') : t('no mic device');
+  }
+  const btnTextNode = isDeviceUnavailable
+    ? <span style={{ color: '#FE3C44' }}>{btnText}</span>
+    : btnText;
   const MicrophoneIcon = <Icon className={commonStyle['btn-icon']} url={isOpen ? MicrophoneOpenSrc : MicrophoneCloseSrc}/>;
 
   return (
     <Popup
       content={<DeviceSelector deviceType={DeviceType.MICROPHONE} />}
-      disabled={!TUIGlobal.isPC || !(deviceList?.length > 0)}
+      disabled={!TUIGlobal.isPC || isDeviceUnavailable || !(deviceList?.length > 0)}
       teleported={false}
     >
       <div style={{ display: 'flex' }}>
@@ -70,7 +112,7 @@ export default function Microphone(props: IMicrophoneProps) {
           onClick={handleClick}
           {...props}
         >
-          {btnText}
+          {btnTextNode}
         </Button>
       </div>
     </Popup>

package/src/Components/components/common/PermissionDialog/DevicePermissionBanner.module.scss

@@ -0,0 +1,55 @@
+.device-permission-banner {
+  position: absolute;
+  top: 50px;
+  left: 50%;
+  transform: translateX(-50%);
+  z-index: 40;
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  background: rgba(0, 0, 0, 0.75);
+  backdrop-filter: blur(6px);
+  color: #fff;
+  border-radius: 6px;
+  padding: 6px 28px 6px 10px;
+  font-size: 12px;
+  line-height: 1.5;
+  max-width: 80%;
+  pointer-events: auto;
+
+  .banner-dot {
+    width: 5px;
+    height: 5px;
+    border-radius: 50%;
+    background: #e6a23c;
+    flex: 0 0 auto;
+  }
+
+  .banner-text {
+    flex: 1;
+    min-width: 0;
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+  }
+
+  .banner-close {
+    position: absolute;
+    top: 50%;
+    right: 5px;
+    transform: translateY(-50%);
+    cursor: pointer;
+    color: rgba(255, 255, 255, 0.45);
+    font-size: 11px;
+    line-height: 1;
+    width: 14px;
+    height: 14px;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+
+    &:hover {
+      color: #fff;
+    }
+  }
+}

package/src/Components/components/common/PermissionDialog/DevicePermissionBanner.tsx

@@ -0,0 +1,78 @@
+import React, { useEffect, useState } from 'react';
+import {
+  TUIStore,
+  StoreName,
+  NAME,
+  TUIGlobal,
+  CallStatus,
+  buildDeviceUnavailableText,
+} from '../../../../TUICallService';
+import type { DeviceUnavailableReasons } from '../../../../TUICallService/const';
+import bannerStyle from './DevicePermissionBanner.module.scss';
+
+// Top banner that surfaces unavailable-device reasons (no permission / no device /
+// occupied) during a call. Driven by the DEVICE_UNAVAILABLE_REASONS store written
+// by the service layer after calls/accept.
+export default function DevicePermissionBanner() {
+  const isMobile = !TUIGlobal.isPC;
+  const [
+    deviceUnavailableReasons,
+    setDeviceUnavailableReasons,
+  ] = useState<DeviceUnavailableReasons | null>(TUIStore.getData(StoreName.CALL, NAME.DEVICE_UNAVAILABLE_REASONS));
+  const [
+    visible,
+    setVisible,
+  ] = useState<boolean>(!!TUIStore.getData(StoreName.CALL, NAME.DEVICE_UNAVAILABLE_REASONS));
+
+  const handleDeviceUnavailableReasonsChange = (value: DeviceUnavailableReasons | null) => {
+    setDeviceUnavailableReasons(value);
+    if (value) {
+      setVisible(true);
+    }
+  };
+
+  // Reset banner when the call ends.
+  const handleCallStatusChange = (value) => {
+    if (value === CallStatus.IDLE) {
+      setVisible(false);
+      setDeviceUnavailableReasons(null);
+    }
+  };
+
+  useEffect(() => {
+    TUIStore.watch(StoreName.CALL, {
+      [NAME.DEVICE_UNAVAILABLE_REASONS]: handleDeviceUnavailableReasonsChange,
+      [NAME.CALL_STATUS]: handleCallStatusChange,
+    }, {
+      notifyRangeWhenWatch: NAME.MYSELF,
+    });
+
+    return () => {
+      TUIStore.unwatch(StoreName.CALL, {
+        [NAME.DEVICE_UNAVAILABLE_REASONS]: handleDeviceUnavailableReasonsChange,
+        [NAME.CALL_STATUS]: handleCallStatusChange,
+      });
+    };
+  }, []);
+
+  if (!visible || !deviceUnavailableReasons) {
+    return null;
+  }
+
+  // Group devices per reason so mixed cases (e.g. mic no-permission + camera
+  // no-device) describe each device accurately instead of a single wrong sentence.
+  const bannerText = buildDeviceUnavailableText(
+    deviceUnavailableReasons.microphone,
+    deviceUnavailableReasons.camera,
+    'banner',
+    isMobile,
+  );
+
+  return (
+    <div className={bannerStyle['device-permission-banner']}>
+      <span className={bannerStyle['banner-dot']} />
+      <span className={bannerStyle['banner-text']}>{bannerText}</span>
+      <span className={bannerStyle['banner-close']} onClick={() => setVisible(false)}>✕</span>
+    </div>
+  );
+}

package/src/Components/components/common/PermissionDialog/index.ts

@@ -0,0 +1,3 @@
+import DevicePermissionBanner from './DevicePermissionBanner';
+
+export default DevicePermissionBanner;

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.11';
+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;