Send and receive audio messages

This topic describes how to use the ZIM SDK and ZIM Audio SDK to send and receive audio messages.

Usage steps

The whole process mainly includes audio recording, sending, receiving, and playback. In this example, an audio message is sent from client A to client B:

1. Initialize the ZIM Audio SDK

Call the init method to initialize the ZIM Audio SDK before calling other methods of this SDK.

To only implement audio message sending and receiving, you can pass in an empty string for the parameter in this method.

To implement more features, pass in a license. For more information about how to obtain a license, see Implement online authentication.

// Initialize the ZIM Audio SDK.
// In this scenario, no license is required.
ZIMAudio.getInstance().init("");

2. Listen for the callback

Implement the callback methods in ZIMAudioEventHandler as needed. Take onError as an example.

ZIMAudio.getInstance().on("onError",function(onError){
    console.log('onError,code:'+onError.code+"message:"+onError.message);
});

3. Record an audio file

3.1 Start the recording

1. Call the startRecord method on the sending client to define the audio duration and the local absolute path to store the audio file, which must contain the filename and extension, for example, xxx/xxx/xxx.m4a. Only M4A and MP3 files are supported.

   Untitled

   ZIMAudio.getInstance().startRecord(ZIMAudioRecordConfig("path", maxDuration: 10 * 1000));
   
   // "path" is the absolute local path where the audio file is expected to be stored, including the file extension (only supports .m4a and .mp3), such as xxx/xxx/xxx.m4a
   
   // "maxDuration" is the maximum recording duration for the audio, in milliseconds.
   
   // The default is 60000 ms (i.e., 60 seconds). The maximum value should not exceed 120000 ms (i.e., 120 seconds).
   
   // This example indicates 10 times 1000 ms (i.e., 10 seconds).
   

   1

   Copied!

2. Trigger the callback.

   • After the recording starts, listen for the onRecorderStarted callback on the sending client to update the UI.

     Untitled

     onRecorderStarted: () => void;
     

     1

     Copied!

   • The ZIM Audio SDK updates the recording progress once every 500 ms in the onRecorderProgress callback, indicating the duration of the recorded audio file, which can be used to update the UI.

     Untitled

     onRecorderProgress: (currentDuration: number) => void;
     

     1

     Copied!

   • If the recording fails due to an error, the ZIM Audio SDK sends a notification in the onRecorderFailed callback, and you can handle the failure based on this callback and the error codes specified in ZIM Audio SDK error codes.

     Untitled

     onRecorderFailed: (errorCode: ZIMAudioErrorCode) => void;
     

     1

     Copied!

3.2 Complete the recording

1. To complete the recording, call the completeRecord method.

   Note

   • Make sure that you have received the onRecorderStarted callback before calling the completeRecord method; otherwise, the recording is canceled, and an error is reported, indicating that the duration is too short.
   • If the recording is not completed or canceled, the ZIM Audio SDK automatically completes it when the duration reaches the maximum and triggers the onRecorderCompleted callback.
   Untitled

   ZIMAudio.getInstance().completeRecord();
   

   1

   Copied!

2. After receiving the onRecorderCompleted callback, you can find the specified absolute audio file path.

   Untitled

   onRecorderCompleted: (totalDuration: number) => void;  // `totalDuration` indicates the total duration (ms) of the audio file.
   

   1

   Copied!

3.3 (Optional) Cancel the recording

1. To cancel the recording and delete the recorded audio, call the cancelRecord method.

   Untitled

   ZIMAudio.getInstance().cancelRecord();
   

   1

   Copied!

2. Calling the cancelRecord method triggers the onRecorderCancelled callback to the sending client, which uses the callback to update the UI.

   Untitled

   onRecorderCancelled: () => void;
   

   1

   Copied!

3.4 (Optional) Check whether the recording is in progress

To obtain the recording status, call the isRecording method.

ZIMAudio.getInstance().isRecording().then((isRecording) => {
    console.log(isRecording);
});

4. Send the audio message

After the onRecorderCompleted callback is triggered, build the ZIMAudioMessage object (ZIM audio message) by using the specified absolute path and call the sendMediaMessage method to send the message. Below is the sample code for sending an audio message in a one-to-one chat.

// The callback for recording completion.
ZIMAudio.getInstance().on("onRecorderCompleted",function(totalDuration){
    // Convert audio duration in milliseconds to ZIM seconds
    let second = Math.floor(totalDuration / 1000);
    // Create the audio message.
    /* Note: fileLocalPath is the absolute path of the local file. */
    var fileLocalPath = 'xxx/xxx.mp3';
    var conversationID = 'xxxx';
    var config = { priority: 1 };
    var notification = {
        onMessageAttached: function(message) {
            // todo: Loading
        },
        onMediaUploadingProgress: function(message, currentFileSize, totalFileSize) {
            // todo: upload progress
        }
    };

    mediaMessageObj = {
        fileLocalPath, 
        type: 13,
        audioDuration: second, 
    };
    // Send the audio message in a one-to-one chat.
    zim.sendMediaMessage(
        mediaMessageObj,
        conversationID,
        0,
        config,
        notification,
    );
});

For more information about the sending progress, see Callback for the sending progress of rich media content.

5. Receive the audio message

Based on the conversation type (one-to-one chat, voice chatroom, or group chat), listen for the onReceivePeerMessage, onReceiveGroupMessage and onReceiveRoomMessage callback on the receiving client to receive the audio message notification and then call the downloadMediaFile method to download the audio file to the local database.

Below is the sample code for receiving and downloading an audio message in a one-to-one chat.

zim.on('receivePeerMessage', function (zim, { messageList, fromConversationID }) {
    // Triggered when receiving a private chat message
    messageList.forEach(function (msg) {
        // If the message type is 13 (audio)
        if (msg.type == 13) {
            zim.downloadMediaFile(msg, 13, function(message, currentFileSize, totalFileSize) {}).then((result) => {
                result.message.fileLocalPath; // Download successful, get the absolute local path of the audio file
            });
        }
    });
});

For more information about the download progress, see Callback for the downloading progress of rich media content.

6. Play the audio file

6.1 Start the playback

1. To play the audio file, call the startPlay method on the receiving client to pass in the local absolute path of the audio file and set the routing type for audio output.

   Untitled

   // Play the audio.
   ZIMAudio.getInstance().startPlay({filePath:"Fill in the local path of the audio file",routeType:ZIMAudioRouteType.speaker});
   

   1

   Copied!

2. Trigger the callback.

   • Listen for the onPlayerStarted callback to update the UI.

     Untitled

     onPlayerStarted: (totalDuration: number) => void; // `totalDuration` indicates the total duration (ms) of the audio file.
     

     1

     Copied!

   • The ZIM Audio SDK updates the playback progress once every 500 ms in the onPlayerProgress callback, indicating the playback duration of the audio file, which can be used to update the UI.

     Untitled

     onPlayerProgress: (currentDuration: number) => void;
     

     1

     Copied!

   • If the playback fails due to an error, the ZIM Audio SDK sends a notification in the onPlayerFailed callback, and you can handle the failure based on this callback and the error codes specified in ZIM Audio SDK error codes.

     Untitled

     onPlayerFailed: (errorCode: ZIMAudioErrorCode) => void;
     

     1

     Copied!

   • If the playback is interrupted by recording, an incoming call, or audio output device preemption, the ZIM Audio SDK sends the onPlayerInterrupted callback.

     Untitled

     onPlayerInterrupted: () => void;
     

     1

     Copied!

   • When the playback ends, the ZIM Audio SDK sends the onPlayerEnded callback.

     Untitled

     onPlayerEnded: () => void;
     

     1

     Copied!

3. (Optional) To switch the audio output device (loudspeaker or headphone) during playback, call the setAudioRouteType method.

   Warning

   If the headphone is connected, this method does not take effect, and the audio is still output from the headphone.

   Untitled

   // Set the output device to the loudspeaker.
   ZIMAudio.getInstance().setAudioRouteType(ZIMAudioRouteType.speaker);
   

   1

   Copied!

6.2 (Optional) Stop the playback

1. To stop the playback, call the stopPlay method.

   Untitled

   ZIMAudio.getInstance().stopPlay();
   

   1

   Copied!

2. Listen for the onPlayerStopped callback to update the UI. After the playback is stopped or ends, the ZIM Audio SDK releases the audio device.

   Untitled

   onPlayerStopped: () => void;
   

   1

   Copied!

7. Deinitialize the ZIM Audio SDK

If the audio feature is no longer in use, call the uninit method to release resources.

ZIMAudio.getInstance().uninit();