MediaPipeTasksAudio Framework Reference

AudioRecord

class AudioRecord: NSObject

A wrapper class to record the device's microphone continuously. Currently this class only supports recording up to 2 channels. If the number of channels is 2, then the mono microphone input is duplicated to provide dual channel data.

Internally the class manages an instance of AVAudioEngine for tapping the microphone samples.

Recording sets the following parameters on the AVAudioSession.sharedInstance():

1. category = .playAndRecord 2. mode = .default 3. categoryOptions = [.overrideMutedMicrophoneInterruption]

If you need more control, use the native AVAudioEngine directly for tapping the microphone. AudioRecord does not actively monitor audio interruptions, route changes, resetting of media services etc. They can be handled in the app using the notifications provided by AVFAudio. Refer to the official docs for the following: 1. Handling audio interruptions https://developer.apple.com/documentation/avfaudio/handling_audio_interruptions

2. Responding to audio route changes https://developer.apple.com/documentation/avfaudio/responding_to_audio_route_change

3. Responding to resetting of media services https://developer.apple.com/documentation/avfaudio/avaudiosessionmediaserviceswereresetnotification

iOS may automatically stop the audio engine in some cases. A few examples of such events are a system interrupt, route change, etc. In such cases, read(offset:length:) returns TasksErrorCode.audioRecordNotTappingMicError. You can restart recording using startRecording().

Note: Avoid setting the AVAudioSession.sharedInstance() category, mode, options, channel configuration (enabling stereo) or other parameters while audio is being actively recorded using the audio record. Setting these parameters or changing the configuration of AVAudioSession.sharedInstance() while a recording is in progress will result in undefined behaviour.

• init(audioDataFormat:bufferLength:)

  Initializes a new AudioRecord with the given audio format and buffer length.

  Declaration

  Swift

  init(audioDataFormat format: AudioDataFormat, bufferLength bufferSize: UInt) throws

  Parameters

  format	An audio format of type AudioDataFormat.
  bufferLength	Maximum number of elements the internal buffer of AudioRecord can hold at any given point of time. The buffer length must be a multiple of format.channelCount.

  Return Value

  An new instance of AudioRecord with the given audio format and buffer length. nil if there is an error in initializing AudioRecord.

• audioDataFormat

  Audio format specifying the number of channels and sample rate supported.

  Declaration

  Swift

  var audioDataFormat: AudioDataFormat { get }

• bufferLength

  Size of the buffer held by AudioRecord. It ensures delivery of audio data of length bufferLength arrays when you start recording the microphone input.

  Declaration

  Swift

  var bufferLength: UInt { get }

• read(offset:length:)

  Returns the length number of elements in the internal buffer of AudioRecord starting at offset, i.e, buffer[offset:offset+length].

  iOS may automatically stop the audio engine in some cases. A few examples of such events are a system interrupt, route change, etc. In such cases, this function returns TasksErrorCode.audioRecordNotTappingMicError. You can restart recording using startRecording().

  Declaration

  Swift

  func read(offset: UInt, length: UInt) throws -> MPPFloatBuffer

  Parameters

  offset	Index in the buffer from which elements are to be read.
  length	Number of elements to be returned.

  Return Value

  A FloatBuffer containing the elements of the internal buffer of AudioRecord in the range, buffer[offset:offset+size]. Returns nil if there is an error in reading the internal buffer.

• startRecording()

  This function starts recording the audio from the microphone if audio record permissions have been granted by the user.

  Before calling this function, you must use AVAudioSession.sharedInstance.requestRecordPermission() to acquire record permissions. If the user has denied permission or the permissions are undetermined, this method will throw an error. The internal buffer of AudioRecord of will always have the most recent audio samples acquired from the microphhone if this function returns successfully. Use: read(offset:length:) to get the data from the buffer at any point of time after audio recording has started successfully.

  Use stop() to stop recording audio sample from the microphone.

  Internally this function activates the AVAudioSession.sharedInstance() with the following parameters before tapping the microphone using the AVAudioEngine: 1. category = .playAndRecord 2. mode = .default 3. categoryOptions = [.overrideMutedMicrophoneInterruption]

  If you need more control, use the native AVAudioEngine directly for tapping the microphone. AudioRecord does not actively monitor audio interruptions, route changes, resetting of media services etc. They can be handled in the app using the notifications provided by AVFAudio. Refer to the official docs for the following: 1. Handling audio interruptions https://developer.apple.com/documentation/avfaudio/handling_audio_interruptions

  2. Responding to audio route changes https://developer.apple.com/documentation/avfaudio/responding_to_audio_route_change

  3. Responding to resetting of media services https://developer.apple.com/documentation/avfaudio/avaudiosessionmediaserviceswereresetnotification

  Declaration

  Swift

  func startRecording() throws

  Return Value

  Returns successfully if audio recording has started.

• stop()

  Stops recording audio from the microphone. All elements in the internal buffer of AudioRecord will also be set to zero.

  Internally, this function deactivates the AVAudioSession.sharedInstance() after recording is stopped. If some audio resources are running in the app when the session is deactivated, this function throws an error. The session gets deactivated by the OS irrespective of the return status of this function. The error thrown is a warning to indicate the termination of any running audio resources. Refer to the official documentation for more details: https://developer.apple.com/documentation/avfaudio/avaudiosession/1616627-setactive

  Declaration

  Swift

  func stop() throws

  Return Value

  Returns successfully if recording was stopped and the deactivation of AVAudioSession.sharedInstance() succeeded. Throws any error encountered when deactivating AVAudioSession.sharedInstance().