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. Import the header file

Import the ZIMAudio.h header file to your project.

import im.zego.zim_audio.ZIMAudio;

2. 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.
String license = "";
ZIMAudio.getInstance().init(application, license);

3. Listen for the callback

1. Create a subclass that inherits the ZIMAudioEventHandler abstract class and override the methods in it.

   Untitled

    import im.zego.zim_audio.callback.ZIMAudioEventHandler;
    import im.zego.zim_audio.entity.ZIMAudioError;
   
    public class ZIMAudioEventHandler extends ZIMAudioEventHandler {
        
        @Override
        public void onError(ZIMAudioError errorInfo) {
            super.onError(errorInfo);
            
        }
    }
    @end
   

   1

   Copied!

2. Call the setEventHandler class to listen for one of its instances.

   Untitled

   ZIMAudio.getInstance().setEventHandler(ZIMAudioEventHandlerImpl.getInstance());
   

   1

   Copied!

4. Record an audio file

4.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

   
   ZIMAudioRecordConfig config = new ZIMAudioRecordConfig();
   config.maxDuration = 10 * 1000; // The maximum duration (ms) of the recorded audio.
                                   // The default duration is 60,000 ms, that is, 60 seconds. The maximum duration is 120,000 ms, that is, 120 seconds.
                                   // In this example, the duration is 10 x 1,000 ms, that is, 10 seconds.
   config.filePath = ""; //  The local absolute path to store the audio file, with the extension, for example, `xxx/xxx/xxx.m4a`. Only M4A and MP3 files are supported.
   
   ZIMAudio.getInstance().startRecord(config);
   

   1

   Copied!

2. Trigger the callback.

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

     Untitled

     public void onRecorderStarted() {}
     

     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

     public void onRecorderProgress(int currentDuration) {}
     

     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

     public void onRecorderFailed(ZIMAudioErrorCode errorCode) {}
     

     1

     Copied!

4.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.

  ZIMAudio.getInstance().completeRecord();

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

   Untitled

   public void onRecorderCompleted(int totalDuration) {}  // `totalDuration` indicates the total duration (ms) of the audio file.
   

   1

   Copied!

4.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

   public void onRecorderCancelled() {}
   

   1

   Copied!

4.4 (Optional) Check whether the recording is in progress

To obtain the recording status, call the isRecording method.

boolean isRecording = ZIMAudio.getInstance().isRecording();

5. 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.

ZIMAudio.getInstance().setEventHandler(new ZIMAudioEventHandler() {
    // The callback for recording completion.
    @Override
    public void onRecorderCompleted(int totalDuration) {
        super.onRecorderCompleted(totalDuration);
        // Convert audio duration in milliseconds to ZIM seconds
        int second = totalDuration / 1000;
        // Create the audio message.
        ZIMAudioMessage message = new ZIMAudioMessage("Recording audio file path", second);
        ZIMMessageSendConfig config = new ZIMMessageSendConfig();
        // Send the audio message in a one-to-one chat.
        ZIM.getInstance().sendMediaMessage(message, "One-to-one chat ID", ZIMConversationType.PEER, config, new ZIMMediaMessageSentCallback() {
            @Override
            public void onMessageSent(ZIMMessage message, ZIMError errorInfo) {
                    if(errorInfo.code == ZIMErrorCode.SUCCESS){
                        //The message is sent successfully.
                    }else{
                        //Handle the error based on the corresponding error code table.
                    }
            }
            @Override
            public void onMessageAttached(ZIMMediaMessage message){
            }
            @Override
            public void onMediaUploadingProgress(String fileUID, long currentFileSize, long totalFileSize, ZIMMediaMessage message) {
            }
        });
    }
});

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

6. 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.

// The `onReceivePeerMessage` callback is triggered when a one-to-one message is received.
 @Override
    public void onReceivePeerMessage(ZIM zim, ArrayList<ZIMMessage> messageList, String fromUserID) {
        super.onReceivePeerMessage(zim, messageList, fromUserID);
        // Traverse the received message list
        for (ZIMMessage message : messageList) {
            // When receiving a message, you can determine the type of message received by its Type
            // If the message type is audio
            if (message.getType() == ZIMMessageType.AUDIO) {
                // Get the audio message
                ZIMAudioMessage audioMessage = (ZIMAudioMessage) message;
                zim.downloadMediaFile(imageMessage, ZIMMediaFileType.ORIGINAL_FILE, new ZIMMediaDownloadedCallback() {

                    @Override
                    public void onMediaDownloaded(ZIMMediaMessage message, ZIMError errorInfo) {
                        if(errorInfo.code == ZIMErrorCodeSuccess){
                             message.fileLocalPath; // Download successful, get the local absolute path of the audio file
                        }else{
                            // Download failed, handle the failure event according to the ZIM official error code table
                        }
                    }

                    @Override
                    // Get the download progress of the audio file here
                    public void onMediaDownloadingProgress(ZIMMediaMessage message, long currentFileSize, long totalFileSize) {
                        // Download progress callback
                    }
                });
            }
        }
    }  

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

7. Play the audio file

7.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.
     // Configure playback settings.
   ZIMAudioPlayConfig config = new ZIMAudioPlayConfig();
       /**
         * ZIMAudioRouteTypeSpeaker: speaker playback
         * ZIMAudioRouteTypeReceiver: receiver playback
         */
       config.routeType = ZIMAudioRouteTypeSpeaker;
       config.filePath = "";//Fill in the local path of the audio file.
       ZIMAudio.getInstance().startPlay(config);
   

   1

   Copied!

2. Trigger the callback.

   • Listen for the onPlayerStarted callback to update the UI.

     Untitled

     public void onPlayerStarted(int totalDuration) {} // `totalDuration` is 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

     public void onPlayerProgress(int currentDuration) {}
     

     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

     public void onPlayerFailed(ZIMAudioErrorCode errorCode) {}
     

     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

     public void onPlayerInterrupted() {}
     

     1

     Copied!

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

     Untitled

     public void onPlayerEnded() {}
     

     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!

7.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

   public void onPlayerStopped() {}
   

   1

   Copied!

8. Deinitialize the ZIM Audio SDK

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

ZIMAudio.getInstance().uninit();