Skip to main content

Frequently Asked Questions (FAQ)

This document collects common questions and solutions encountered during the use of AaaS Pilot Kit.

Q: Why do I need user-triggered clicks or other actions to enable sound?​

A: Modern browsers implement autoplay restriction policies to prevent malicious websites from automatically playing audio and disturbing users. The Digital Human's voice playback function is affected by this limitation, and audio playback is only allowed in the following situations:

  • User has interacted with the page (click, touch, key press, etc.)
  • Audio is muted or volume is 0
  • Website has been trusted by user (browser automatically judges based on visit frequency)
  • Explicitly authorized through browser permission policies

Solution: When initializing the Digital Employee, you need to provide a user activation button to guide the user to actively click to start the audio function (the button can be called "Start the Conversation Journey"). This is a requirement of browser security mechanisms and must be activated through user's active operation.

Q: What should I do if the Digital Human cannot be displayed in iPhone WeChat browser?​

A: Some mobile browsers have media playback restrictions that require manual activation for normal playback.

Solution: Call the activateManually() method for manual activation, see API Documentation for details.

Q: Why does the Digital Human fail to render or not work properly?​

A: WebRTC technology requires running in HTTPS environment and cannot work properly in HTTP environment.

Solution: Ensure your application is deployed in HTTPS environment. For local development, you can use localhost or configure local HTTPS certificates.

Q: What should I do if subtitle display and Digital Human broadcast are out of sync?​

A: After setting typeDelay and enTypeDelay, subtitles display at a fixed speed, but Digital Human broadcast has natural tone pauses and rhythm changes, so they cannot be fully synchronized.

Solution: This is normal behavior. If you need better synchronization, you can appropriately adjust the typeDelay parameter, or consider using event listeners to optimize subtitle display timing.

Q: I cannot perform voice input, microphone is not working?​

A: Browser requires user explicit authorization to access microphone device.

Solution:

  1. Check if there is a microphone permission prompt in the browser address bar
  2. Confirm in browser settings that the website is allowed to access microphone
  3. Ensure device microphone function is normal
// Listen for microphone permission errors
controller.emitter.on('error', (error) => {
    if (error.code === '3103') {  // Updated to new permission error code (old version 3008 deprecated)
        showMessage('Please allow microphone permission to use voice function');
    }
});

Q: What should I do if Digital Human has no action in Android browser?​

A: Some Android browsers have incomplete WebRTC support, or require user interaction to activate media playback.

Solution:

  1. Use activateManually() method for manual activation
  2. Recommend users to use mainstream browsers like Chrome, Edge
  3. Ensure browser version is recent enough, supporting complete WebRTC functionality

Q: What should I do if Digital Human cannot display or appears black screen?​

A: Possible causes and solutions:

  1. Network connection issue - Check network connection status
  2. figureId configuration error - Confirm figureId parameter is correct
  3. Container element issue - Confirm mounting container exists and is visible
  4. Browser compatibility - Confirm browser supports WebRTC functionality

Q: How to optimize performance?​

  1. Adjust resolution:
figureResolutionWidth: 720,  // Reduce resolution to improve performance
figureResolutionHeight: 1280
  1. Reasonable audio sample rate:
ttsSample: 16000  // Balance audio quality and performance
  1. Call dispose() for cleanup when ending
// Taking React tech stack as example
useEffect(
    () => {
        const cleanup = () => {
            controller.dispose();
        };
        return cleanup;
    },
    []
);

Q: What should I do if custom content layer is covered by Digital Human image when rendererMode is cloud-native?​

A: When rendererMode is set to 'cloud-native', the Digital Human image uses position: absolute positioning with z-index: 1. If you need to implement subtitles or other custom elements above the Digital Human image, you need to manually adjust the positioning (position) and z-index values of these custom elements to ensure their layer is higher than the Digital Human image (i.e., z-index value greater than 1).

Q: How to debug issues?​

Enable debug mode to get detailed logs:

const controller = createAaaSPilotKit({
    token: 'your-auth-token-here',
    // ... other configurations
    env: 'development',
    enableDebugMode: true,
});

// Listen for all errors
controller.emitter.on('error', (error) => {
    console.group('AaaS Kit Error Details');
    console.error('Error Code:', error.code);
    console.error('Error Message:', error.message);
    console.error('Severity:', error.severity);
    console.error('Metadata:', error.metadata);
    if (error.stack) {
        console.error('Error Stack:', error.stack);
    }
    console.groupEnd();
});

Q: Common error codes and solutions​

General Errors (1000-1999)​

Error CodeError DescriptionSolution
1001Network connection errorCheck network connection status, ensure network is smooth before retrying
1002Request timeoutCheck network latency, increase timeout configuration
1003Invalid configuration parameterCheck if configuration parameters like figureId, token, robotId are correct
1004Authentication failedCheck if token is valid, contact technical support to confirm permissions

Agent Service Errors (2000-2999)​

Error CodeError DescriptionSolution
2001Agent query failedCheck robotId configuration, confirm Agent service status
2002Agent response parsing errorCheck Agent returned data format, contact technical support
2003Agent request timeoutCheck network connection, appropriately increase timeout
2005Agent connection failedConfirm Agent service address and network connectivity

Speech Recognition Errors (3000-3999)​

Error CodeError DescriptionSolution
3001ASR initialization failedCheck browser compatibility, confirm audio device available
3002ASR startup failedCheck microphone permissions, ensure device is working properly
3007ASR network errorCheck network connection, confirm speech service is accessible
3008ASR permission denied⚠️ Deprecated, please use 3103 instead
3009ASR device not foundConfirm audio input device is connected and working properly
3100Browser doesn't support MediaDevices APIUpgrade browser or use modern browser (Chrome 53+, Firefox 36+, Safari 11+)
3101HTTPS security context requiredUse HTTPS protocol to access, or use localhost during development
3102Audio device enumeration failedCheck device connection, re-plug microphone
3103User denied permission requestGuide user to enable microphone permissions in browser settings (see "Microphone Device Troubleshooting" below)
3104Device occupied or not readableClose other applications using microphone
3105Audio device check timeoutCheck network connection, retry operation

Digital Human Service Errors (4000-4999)​

Error CodeError DescriptionSolution
4001Digital Human mount failedCheck if container element exists, confirm page DOM structure
4003Digital Human rendering errorCheck figureId configuration, confirm browser supports WebRTC
4005Digital Human RTC errorEnsure HTTPS environment, check browser WebRTC support
4006Digital Human authentication errorVerify token validity, check Digital Human service permissions
4007Session count limit reachedWait for existing session to end or contact technical support to increase quota
4012Digital Human image ID invalidConfirm figureId parameter is correct, contact technical support to confirm available image
4013Digital Human token invalidCheck token format and validity, obtain valid token again

Deployment and Environment Issues​

Q: What should I pay attention to for production deployment?​

  1. Disable debug mode:
env: 'production',
enableDebugMode: false
  1. Configure error monitoring:
controller.emitter.on('error', (error) => {
    // Report to monitoring system
    if (error.severity === 'high' || error.severity === 'critical') {
        reportToMonitoring(error);
    }
});

If issues persist, contact technical support for domain whitelist configuration.

Microphone Device Troubleshooting​

Q: How to check if microphone is available?​

Use controller.checkAudioDevice() method for device check:

// Listen for check result
controller.emitter.on('microphone_available', (result) => {
    console.log('Device available:', result.available);

    if (!result.available) {
        console.error('Error type:', result.error);
        console.error('Error prompt:', result.userMessage);
    }
    else {
        console.log('Found', result.devices?.length, 'audio devices');
        console.log('Permission status:', result.permissionState);
    }
});

// Perform check
await controller.checkAudioDevice();

Q: Common microphone errors and solutions​

Error 3100: Browser doesn't support MediaDevices API​

Symptom: Prompt "Browser doesn't support MediaDevices API"

Cause: Browser version is too old

Solutions:

  1. Upgrade to modern browser:
    • Chrome 53+ / Edge 79+
    • Firefox 36+
    • Safari 11+
    • Opera 40+

Error 3101: HTTPS security context required​

Symptom: Prompt "HTTPS security context required"

Cause: Accessing in non-HTTPS environment (browser security policy requirement)

Solutions:

  1. Production Environment: Deploy using HTTPS protocol
  2. Development Environment: Use any of the following methods:
    • Access using localhost or 127.0.0.1
    • Configure local HTTPS certificate
    # Start using localhost
    npm run dev -- --host localhost

Error 3102: Audio device enumeration failed​

Symptom: Prompt "Audio device enumeration failed"

Cause: System cannot list available audio devices

Solutions:

  1. Check if microphone is properly connected
  2. Re-plug microphone device
  3. Check if device is recognized in system sound settings
  4. Windows: Check if audio driver is normal in "Device Manager"
  5. macOS: Check "System Preferences → Sound → Input"

Error 3103: User denied permission request​

Symptom: Prompt "User denied permission request" or "Microphone permission denied"

Cause: User clicked "Deny" button in browser permission popup

Solutions:

Chrome / Edge:

  1. Click the 🔒 icon on the left side of browser address bar
  2. Find "Microphone" permission, click dropdown menu
  3. Select "Allow"
  4. Refresh page

Firefox:

  1. Click the 🔒 icon on the left side of address bar
  2. Click the > next to "Connection Security"
  3. Find "Use Microphone", select "Allow"
  4. Refresh page

Safari:

  1. Select "Safari → Settings" in menu bar
  2. Go to "Websites" tab
  3. Click "Microphone" on the left
  4. Find current website, select "Allow"
  5. Refresh page

Error 3104: Device occupied or not readable​

Symptom: Prompt "Device occupied or not readable"

Cause: Other application is using microphone

Solutions:

  1. Close the following applications that may occupy microphone:
    • Video conferencing software: such as VooV Meeting, Microsoft Teams, Tencent Meeting, DingTalk, Feishu
    • Instant messaging software: WeChat, QQ, Skype
    • Recording software: Audacity, GarageBand
    • Voice applications in other browser tabs
  2. Check system task manager, end processes occupying audio devices
  3. Windows: Open "Settings → Privacy → Microphone", confirm app permissions
  4. macOS: Open "System Preferences → Security & Privacy → Privacy → Microphone", confirm browser permissions

Error 3105: Audio device check timeout​

Symptom: Prompt "Audio device check timeout"

Cause: Device check took too long (possible network or system issue)

Solutions:

  1. Check if network connection is normal
  2. Close other resource-intensive applications
  3. Try again later
  4. If continues to fail, try restarting browser or system

Q: Special considerations for Safari browser​

Safari doesn't support Permissions API, so permissionState field may be undefined.

Recommendations:

  • Don't rely on permissionState to determine permission status
  • Use available field to determine if device is available
  • Use error field to determine specific error type
controller.emitter.on('microphone_available', result => {
    // ✅ Correct approach: use available field
    if (!result.available) {
        if (result.error === 'PERMISSION_DENIED') {
            showPermissionGuide();
        }
    }

    // ❌ Wrong approach: rely on permissionState (Safari doesn't support)
    // if (result.permissionState === 'denied') { ... }
});

Q: How to automatically detect device before ASR starts?​

Use checkAudioDeviceBeforeStart configuration item:

const controller = await createAaaSPilotKit({
    checkAudioDeviceBeforeStart: true, // Default is true, auto-detect before start
    // ... other configurations
});

// Listen for check result
controller.emitter.on('microphone_available', result => {
    if (!result.available) {
        // ASR startup will be automatically blocked, display error prompt
        showToast(result.userMessage);
    }
});

Related Documentation:

More Help​

If the above questions cannot solve your problem, please:

  1. Check console error logs
  2. Enable debug mode for detailed information
  3. Contact technical support team

Contact Information:

联系我们