AudioCapture/dev.piotrprus.audiocapture

Package-level declarations

The public API: the capture entry point, sessions, configuration and audio types.

Types

AndroidAudioSource

enum AndroidAudioSource : Enum<AndroidAudioSource>

MediaRecorder.AudioSource. Decides which processing the device applies before you get the audio.

AndroidOptions

data class AndroidOptions(val audioSource: AndroidAudioSource = AndroidAudioSource.VoiceRecognition)

AudioCapture

interface AudioCapture

Entry point to the microphone.

AudioCaptureException

class AudioCaptureException(message: String, cause: Throwable? = null) : Exception

AudioCaptureInitializer

class AudioCaptureInitializer : Initializer<Unit>

Captures the application context at startup so the no-argument AudioCapture() works.

AudioChunk

class AudioChunk(val bytes: ByteArray, val format: PcmFormat, val timestamp: Duration)

One block of interleaved PCM: CaptureConfig.chunkDuration of audio.

AudioEncoder

enum AudioEncoder : Enum<AudioEncoder>

AudioLevel

data class AudioLevel(val peak: Float, val rms: Float)

Loudness of one chunk, linear 0..1 relative to full scale.

CaptureConfig

data class CaptureConfig(val sampleRate: Int, val channels: Int = 1, val chunkDuration: Duration = 100.milliseconds, val pcm: PcmOutput? = PcmOutput(), val file: FileOutput? = null, val device: InputDevice? = null, val voiceProcessing: VoiceProcessing? = null, val interruption: InterruptionMode = InterruptionMode.Pause, val android: AndroidOptions = AndroidOptions(), val ios: IosOptions = IosOptions())

What to capture and where it goes.

CaptureSession

interface CaptureSession

One run of the microphone, from AudioCapture.start to stop or cancel.

CaptureState

sealed interface CaptureState

ExperimentalVoiceProcessing

@RequiresOptIn(level = RequiresOptIn.Level.WARNING, message = "Voice processing sounds very different per platform; on iOS it noticeably changes the tone of the voice.")

@Target(allowedTargets = [AnnotationTarget.CONSTRUCTOR])

annotation class ExperimentalVoiceProcessing

Marks the VoiceProcessing constructor: its result differs a lot between platforms and may change.

FileOutput

data class FileOutput(val path: String, val encoder: AudioEncoder = AudioEncoder.forPath(path), val bitRate: Int)

InputDevice

data class InputDevice(val id: String, val name: String, val type: InputDeviceType)

InputDeviceType

enum InputDeviceType : Enum<InputDeviceType>

InterruptionMode

enum InterruptionMode : Enum<InterruptionMode>

What happens when the system takes the microphone away mid-session. See PauseReason.Interruption for what counts as one on each platform. Android reports interruptions from API 29.

IosBluetoothInput

enum IosBluetoothInput : Enum<IosBluetoothInput>

IosDucking

enum IosDucking : Enum<IosDucking>

AVAudioVoiceProcessingOtherAudioDuckingLevel.

IosOptions

data class IosOptions(val manageAudioSession: Boolean = true, val category: IosSessionCategory = IosSessionCategory.PlayAndRecord, val mode: IosSessionMode = IosSessionMode.Default, val bluetoothInput: IosBluetoothInput = IosBluetoothInput.Off, val mixWithOthers: Boolean = false, val defaultToSpeaker: Boolean = true, val deactivateOnPause: Boolean = false)

IosSessionCategory

enum IosSessionCategory : Enum<IosSessionCategory>

IosSessionMode

enum IosSessionMode : Enum<IosSessionMode>

LevelNormalizer

class LevelNormalizer(floor: Float = DEFAULT_FLOOR, attack: Duration = 400.milliseconds, release: Duration = 20.seconds)

Turns AudioLevel.peak into a 0..1 value for visuals that looks the same on every device.

MicPermission

enum MicPermission : Enum<MicPermission>

PauseReason

enum PauseReason : Enum<PauseReason>

PcmEncoding

enum PcmEncoding : Enum<PcmEncoding>

PcmFormat

data class PcmFormat(val sampleRate: Int, val channels: Int, val encoding: PcmEncoding)

PcmOutput

data class PcmOutput(val encoding: PcmEncoding = PcmEncoding.Int16, val bufferedChunks: Int = 50)

How CaptureSession.chunks delivers raw PCM.

Recording

data class Recording(val path: String, val encoder: AudioEncoder, val durationMillis: Long)

A finished file.

VoiceProcessing

data class VoiceProcessing(val echoCancel: Boolean = true, val noiseSuppress: Boolean = true, val autoGain: Boolean = false, val applyOnIos: Boolean = true, val iosDucking: IosDucking = IosDucking.Default)

Platform echo cancellation, noise suppression and gain control, applied before you get the audio.

Functions

AudioCapture

actual fun AudioCapture(): AudioCapture

The platform's AudioCapture.

fun AudioCapture(context: Context): AudioCapture

For apps that disable androidx.startup initializers. Any context works; only the application context is kept.

expect fun AudioCapture(): AudioCapture

The platform's AudioCapture.

actual fun AudioCapture(): AudioCapture

The platform's AudioCapture.

record

suspend fun AudioCapture.record(fileName: String = "recording.m4a"): CaptureSession

The shortest way to record: asks for permission if needed and starts recording fileName (.m4a for AAC, .wav for WAV) into AudioCapture.recordingPath. Chunks and levels are on the returned session for live visuals; call CaptureSession.stop to get the file.

stream

fun AudioCapture.stream(config: CaptureConfig = CaptureConfig()): Flow<AudioChunk>

Streams raw PCM for as long as the flow is collected.