diff --git a/en/application-dev/media/audio-capturer.md b/en/application-dev/media/audio-capturer.md new file mode 100644 index 0000000000000000000000000000000000000000..a5762b949e5f870f0d6bece4cee17486ca5a02bf --- /dev/null +++ b/en/application-dev/media/audio-capturer.md @@ -0,0 +1,152 @@ +# Audio Recorder Development Using AudioCapturer + +--- +## ***Note***: + 1. This document applies to JavaScript. +--- +## **Summary** +This guide will show how a JS application can use AudioCapturer to record the audio. +Applications can use the APIs provided in this document to record raw audio files. + +## **AudioCapturer Framework** +The AudioCapturer interface is one of the most important components of the audio framework. +### **Audio Capturing:** +The AudioCapturer framework provides APIs for capturing raw audio files. + +## **Usage** +Here's an example of how to use AudioCapturer to capture a raw audio file. +1. Use **createAudioCapturer()** to create an AudioCapturer instance. Capturer parameters can be set in **audioCapturerOptions**.\ + This instance can be used to record, control, and obtain the recording status, as well as to register a callback for notifications. + ``` + var audioStreamInfo = { + samplingRate: audio.AudioSamplingRate.SAMPLE_RATE_44100, + channels: audio.AudioChannel.CHANNEL_1, + sampleFormat: audio.AudioSampleFormat.SAMPLE_FORMAT_S16LE, + encodingType: audio.AudioEncodingType.ENCODING_TYPE_RAW + } + + var audioCapturerInfo = { + source: audio.SourceType.SOURCE_TYPE_MIC, + capturerFlags: 1 + } + + var audioCapturerOptions = { + streamInfo: audioStreamInfo, + capturerInfo: audioCapturerInfo + } + + let audioCapturer = await audio.createAudioCapturer(audioCapturerOptions); + var state = audioRenderer.state; + ``` + +2. (Optional) Subscribe to audio capturer state change events using the **on('stateChange')** API. + If an application wants to take some action based on the state updates in capturer, the application can subscribe to the state change event. + There are more events that applications can subscribe to, such as 'markReach' and 'periodReach'. Refer to [**js-apis-audio.md**](https://gitee.com/openharmony/docs/blob/master/en/application-dev/reference/apis/js-apis-audio.md) for more details. + ``` + audioCapturer.on('stateChange',(state) => { + console.info('AudioCapturerLog: Changed State to : ' + state) + switch (state) { + case audio.AudioState.STATE_PREPARED: + console.info('--------CHANGE IN AUDIO STATE----------PREPARED--------------'); + console.info('Audio State is : Prepared'); + break; + case audio.AudioState.STATE_RUNNING: + console.info('--------CHANGE IN AUDIO STATE----------RUNNING--------------'); + console.info('Audio State is : Running'); + break; + case audio.AudioState.STATE_STOPPED: + console.info('--------CHANGE IN AUDIO STATE----------STOPPED--------------'); + console.info('Audio State is : stopped'); + break; + case audio.AudioState.STATE_RELEASED: + console.info('--------CHANGE IN AUDIO STATE----------RELEASED--------------'); + console.info('Audio State is : released'); + break; + default: + console.info('--------CHANGE IN AUDIO STATE----------INVALID--------------'); + console.info('Audio State is : invalid'); + break; + } + }); + + ``` + +3. Call the **start()** function on the AudioCapturer instance to start/resume the recording task.\ + The capturer state will be STATE_RUNNING once the start is complete. The application can then begin reading buffers. + ``` + await audioCapturer.start(); + if (audioCapturer.state == audio.AudioState.STATE_RUNNING) { + console.info('AudioRecLog: Capturer started'); + } else { + console.info('AudioRecLog: Capturer start failed'); + } + + ``` + +4. Obtain the minimum buffer size to read using the **getBufferSize()** API. + ``` + var bufferSize = await audioCapturer.getBufferSize(); + console.info('AudioRecLog: buffer size: ' + bufferSize); + + ``` + +5. Read the captured audio data and convert it to a byte stream. Call the **read()** API repeatedly to read the data + until the application wants to stop the recording. The following example shows how to write recorded data into a file. + ``` + import fileio from '@ohos.fileio'; + + const path = '/data/data/.pulse_dir/capture_js.wav'; + let fd = fileio.openSync(path, 0o102, 0o777); + if (fd !== null) { + console.info('AudioRecLog: file fd created'); + } + else{ + console.info('AudioRecLog: file fd create : FAILED'); + return; + } + + fd = fileio.openSync(path, 0o2002, 0o666); + if (fd !== null) { + console.info('AudioRecLog: file fd opened in append mode'); + } + + var numBuffersToCapture = 150; + while (numBuffersToCapture) { + var buffer = await audioCapturer.read(bufferSize, true); + if (typeof(buffer) == undefined) { + console.info('read buffer failed'); + } else { + var number = fileio.writeSync(fd, buffer); + console.info('AudioRecLog: data written: ' + number); + } + + numBuffersToCapture--; + } + ``` +6. Once the recording is complete, call the **stop()** API on the AudioCapturer instance to stop the recording. + ``` + await audioCapturer.stop(); + if (audioCapturer.state == audio.AudioState.STATE_STOPPED) { + console.info('AudioRecLog: Capturer stopped'); + } else { + console.info('AudioRecLog: Capturer stop failed'); + } + ``` + +7. After the recording task is complete, call the **release()** API on the AudioCapturer instance to release the stream resources. + ``` + await audioCapturer.release(); + if (audioCapturer.state == audio.AudioState.STATE_RELEASED) { + console.info('AudioRecLog: Capturer released'); + } else { + console.info('AudioRecLog: Capturer release failed'); + } + ``` + +## **Importance of State Check** +Application developers should keep in mind that an AudioCapturer is state-based. +That is, the AudioCapturer has an internal state that the application must always check when calling recorder control APIs, because some operations are only acceptable while the capturer is in a given state.\ +The system may throw an error/exception or generate other undefined behaviour if the application performs an operation while capturer is in an improper state. + +## **Other APIs** +See [**js-apis-audio.md**](https://gitee.com/openharmony/docs/blob/master/en/application-dev/reference/apis/js-apis-audio.md) for more useful APIs like **getAudioTime**, **getCapturerInfo** and **getStreamInfo**.