Troubleshooting Audio on Mobile SDKs

Capturing Audio Dump

Troubleshooting audio issues within mobile applications that leverage the Webex Mobile SDK can be greatly aided by the use of audio dump files. These files provide developers with valuable information about the audio streams during calls or meetings, which can be analyzed to identify and resolve audio-related problems.

Overview

The Webex Mobile SDK (version 3.13.0 and above) includes a suite of APIs that allow developers to record, manage, and retrieve audio dump files. These files can be used to diagnose audio quality issues, such as echoes, noise, or interruptions that users might experience during a Webex call or meeting.

Key APIs for Audio Troubleshooting

Here is an outline of the primary APIs available in the Webex Mobile SDK for troubleshooting audio issues:

isRecordingAudioDump

• Description: Check if the audio dump is currently being recorded for an ongoing call or meeting.
• Return Type: Bool
• Usage:

    let isRecording = call.isRecordingAudioDump

canStartRecordingAudioDump(completionHandler:)

• Description: Check if the audio dump can be started for an ongoing call or meeting.
• completionHandler: Closure to be executed with the result of the operation. If nil is passed, audio dump recording can begin; otherwise, an Error is provided.
• Usage:

    call.canStartRecordingAudioDump { error in
            if let error = error {
                // Handle error
            } else {
                // Proceed with recording
            }
        }

• Possible Failure Reasons:
  • notAHost: You have to be a host in case of a meeting
  • noActiveCall: No active call for the user
  • internalError: Internal error

startRecordingAudioDump(completionHandler:)

• Description: Start recording the audio dump for an ongoing call or meeting.
• completionHandler: Closure to be executed when the operation is completed. It returns nil if recording started successfully; otherwise, an Error is provided.
• Usage:

    call.startRecordingAudioDump { error in
            if let error = error {
                // Handle error
            } else {
                // Recording started
            }
        }

• Possible Failure Reasons:
  • alreadyRecording: No audio recording in progress to be stopped
  • dumpFolderCreationFailed: Error creating AudioDump directory
  • noActiveCall: No active call for the user
  • internalError: Internal error

stopRecordingAudioDump(completionHandler:)

• Description: Stop recording the audio dump.
• completionHandler: Closure to be executed when the operation is completed. It returns nil if recording stopped successfully; otherwise, an Error is provided.
• Usage:

    call.stopRecordingAudioDump { error in
            if let error = error {
                // Handle error
            } else {
                // Recording stopped
            }
        }

• Possible Failure Reasons:
  • alreadyNotRecording: No audio recording in progress to be stopped
  • noActiveCall: No active call for the user
  • internalError: Internal error

getLogFileUrl()

• Description: Retrieve a URL of the zipped log files, which now also include the recorded audio dump files.
• Return Type: URL?
• Usage:

    if let logFileURL = webex.getLogFileUrl() {
            // Use the URL to access the zipped logs and audio dumps
        } else {
            // Handle the case where the log files are unavailable
        }

Precondition for Audio Dump APIs

Before using the audio dump APIs, ensure that the user is on an active call or meeting. The APIs are designed to work in the context of a live session. Additional Precondition: Host Requirement

For recording audio dump for a meeting, you need to be the host.

How to Use the APIs for Audio Troubleshooting

1. Check Recording Eligibility: Before starting a new audio dump recording, call canStartRecordingAudioDump(completionHandler:) to ensure it's possible to record.
2. Determine Recording Status: Use isRecordingAudioDump to check if audio recording is already in progress.
3. Start Recording: If eligible, use startRecordingAudioDump(completionHandler:) to begin recording the audio dump.
4. Manage Existing Recordings: Before every recording, the previous recording is cleared. At a time, only one recording is saved in the logs folder.
5. Stop Recording: When the troubleshooting session is complete, call stopRecordingAudioDump(completionHandler:) to halt the recording.
6. Retrieve Logs: Use getLogFileUrl() to get the URL for the zipped log files, which includes the audio dump files for analysis.
7. Multiple Recordings: You can record multiple times in a single call. However, note that recording for more time will increase the size of the logs.

Conclusion

The audio dump feature in the Webex Mobile SDK is a powerful tool for developers to diagnose and troubleshoot audio-related issues. By leveraging these APIs, developers can gain valuable insights into audio streams during calls or meetings, helping to identify and resolve problems such as echoes, noise, or interruptions. The requirement to be a host for recording, the management of existing recordings, and the ability to perform multiple recordings in a single call are key considerations for effective use of this feature.