Original Audio Data Acquisition
Feature Overview
The SDK provides developers with the function to obtain original audio data. The obtained original audio data format is PCM. Developers can write this data to local devices to implement audio recording.
Example Source Code
Please refer to Download Example Source Code to get the source code.
For related source code, please check the files in the "/ZegoExpressExample/AdvancedAudioProcessing/src/main/java/im/zego/advancedaudioprocessing/originalaudiodataacquisition" directory.
Prerequisites
Before obtaining original audio data, please ensure:
- You have created a project in the ZEGOCLOUD Console and applied for a valid AppID and AppSign. For details, please refer to Console - Project Information.
- You have integrated ZEGO Express SDK in your project and implemented basic audio and video publish and play stream functionality. For details, please refer to Quick Start - Integration and Quick Start - Implementation.
Usage Steps
1 Initialize SDK
Please refer to "Create Engine" in Quick Start - Implementation.
2 Enable original audio data acquisition function
Developers can call the startAudioDataObserver interface to enable original audio data callback monitoring. The callback audio data type is ZegoAudioDataCallbackBitMask, including CAPTURED, PLAYBACK, MIXED, PLAYER. All four callback types need to be enabled.
// Enable original audio data acquisition function
ZegoAudioFrameParam param=new ZegoAudioFrameParam();
param.channel = ZegoAudioChannel.STEREO;
param.sampleRate = ZegoAudioSampleRate.ZEGO_AUDIO_SAMPLE_RATE_16K;
int bitmask = 0;
// Add bitmask to enable captured audio data callback switch.
// The bit mask values for capture, playback, mix, and play stream are: CAPTURED=1, PLAYBACK=2, MIXED=4, PLAYER=8, respectively. The final value of bitmask is 15, indicating that original data callbacks for capture, playback, mix, and play stream will be triggered simultaneously.
bitmask |= ZegoAudioDataCallbackBitMask.CAPTURED.value();
bitmask |= ZegoAudioDataCallbackBitMask.PLAYBACK.value();
bitmask |= ZegoAudioDataCallbackBitMask.MIXED.value();
bitmask |= ZegoAudioDataCallbackBitMask.PLAYER.value();
engine.startAudioDataObserver(bitmask, param);Application Scenarios
All numbers in a program are stored in binary form in the computer's memory, while bitwise operations directly operate on the binary bits of integers in memory.
| Symbol | Meaning | Operation Rules | Example |
|---|---|---|---|
| & | AND | The result is 1 only when both bits are 1. | 0&1=0, 1&1=1. |
| | | OR | The result is 0 only when both bits are 0. | 0|0=0, 0|1=1. |
| ^ | XOR | Same bits are 0, different bits are 1. | 1^1=0, 0^1=1. |
| ~ | NOT | 0 becomes 1, 1 becomes 0. | ~1=0, ~0=1. |
| << | Left Shift | Shift all bits to the left by the corresponding number of positions in binary form, high bits are shifted out (discarded), and low bits are filled with zeros. | For example, the binary of integer 3 is 00000011, 3 << 2 left shift by 2 positions is 00001100. |
| >> | Signed Right Shift | Shift all bits to the right by the corresponding number of positions in binary form, low bits are shifted out (discarded), and high bits are filled with the sign bit, i.e., positive numbers are filled with 0, negative numbers are filled with 1. | For example, the binary of integer 3 is 00000011, 3 >> 1 signed right shift by 1 position is 00000001. |
| >>> | Unsigned Right Shift | Shift all bits to the right by the corresponding number of positions in binary form, low bits are shifted out (discarded), and high bits are filled with zeros. For positive numbers, this is the same as signed right shift, but different for negative numbers. | For example, the binary of integer 3 is 00000011, 3 >>> 1 unsigned right shift by 1 position is 00000001. |
The SDK mainly uses the bitmask principle to implement multiple switch operations, that is, when multiple module switches need to be selected in an API, developers need to pass the bitmask result to the SDK.
Examples
Taking the raw audio and video data acquisition function as an example, the bitmask usage examples for different languages are as follows:
enum ZegoAudioDataCallbackBitMask
{
/** This property controls whether the SDK triggers the [onCapturedAudioData] method callback */
ZEGO_AUDIO_DATA_CALLBACK_BIT_MASK_CAPTURED = 1 << 0,
/** This property controls whether the SDK triggers the [onPlaybackAudioData] method callback */
ZEGO_AUDIO_DATA_CALLBACK_BIT_MASK_PLAYBACK = 1 << 1,
/** This property controls whether the SDK triggers the [onMixedAudioData] method callback */
ZEGO_AUDIO_DATA_CALLBACK_BIT_MASK_MIXED = 1 << 2,
/** This property controls whether the SDK triggers the [onPlayerAudioData] method callback */
ZEGO_AUDIO_DATA_CALLBACK_BIT_MASK_PLAYER = 1 << 3
};
// Enable the SDK to acquire raw audio data, specifying that the SDK needs to trigger both captured audio data callback and playback audio data callback
unsigned int bitmask = ZEGO_AUDIO_DATA_CALLBACK_BIT_MASK_CAPTURED | ZEGO_AUDIO_DATA_CALLBACK_BIT_MASK_PLAYBACK;
engine->startAudioDataObserver(bitmask, param);3 Set callback to receive original audio data and process
Developers can call the setAudioDataHandler interface to set an additional callback for receiving audio data. According to needs, you can implement callbacks onCapturedAudioData, onPlaybackAudioData, onMixedAudioData, onPlayerAudioData, corresponding to the four audio data types in ZegoAudioDataCallbackBitMask above.
// Set original audio data callback
engine.setAudioDataHandler(new IZegoAudioDataHandler() {
@Override
public void onCapturedAudioData(ByteBuffer data, int dataLength, ZegoAudioFrameParam param) {
// Local captured audio data, callback received after publishing stream
}
@Override
public void onPlaybackAudioData (ByteBuffer data, int dataLength, ZegoAudioFrameParam param) {
// Audio data played by SDK. When the engine is in started state without playing stream and the media player is not playing media files, the callback audio data is silent audio data
}
@Override
public void onMixedAudioData(ByteBuffer data, int dataLength, ZegoAudioFrameParam param) {
// Audio data callback after mixing local captured and SDK played sounds
}
@Override
public void onPlayerAudioData(ByteBuffer data, int dataLength, ZegoAudioFrameParam param, String streamID) {
// Remote play stream audio data, callback for each play stream data after starting to play stream
}
});4 Stop audio data callback monitoring
If you want to stop audio data callback monitoring, you can call the stopAudioDataObserver interface.
engine.stopAudioDataObserver();