Platform Setup

Android

Android requires both a manifest permission and runtime initialization.

Set up Android

Add the microphone permission to your AndroidManifest.xml:
<uses-permission android:name="android.permission.RECORD_AUDIO" />
Initialize Kodio in your Application class before recording:
class MyApp : Application() { override fun onCreate() { super.onCreate() Kodio.initialize(this) } }
Make sure your Application class is registered in the manifest:
<application android:name=".MyApp" ...>

Runtime permissions

On Android 6.0+, you also need to request the permission at runtime. If you're using Compose, RecorderState handles this automatically:

val recorderState = rememberRecorderState()

if (recorderState.needsPermission) {
    Button(onClick = { recorderState.requestPermission() }) {
        Text("Grant Microphone Access")
    }
}

iOS

iOS requires a usage description in your Info.plist explaining why your app needs microphone access.

Set up iOS

Open your Xcode project and locate Info.plist (or your app's info dictionary).
Add the microphone usage description key:
<key>NSMicrophoneUsageDescription</key> <string>This app needs microphone access to record audio.</string>

macOS

macOS requires both an Info.plist entry and a sandbox entitlement for production apps.

Set up macOS

Add the microphone usage description to Info.plist:
<key>NSMicrophoneUsageDescription</key> <string>This app needs microphone access to record audio.</string>
Add the audio input entitlement to your .entitlements file:
<key>com.apple.security.device.audio-input</key> <true/>

Native audio backend

On macOS, Kodio uses native CoreAudio via Panama FFI for optimal audio quality and device support. This requires Java 21 or later.

If the native library isn't available, Kodio automatically falls back to JavaSound.

Development troubleshooting

When running from an IDE or Terminal during development, you may encounter silent audio (all zeros). This happens because macOS grants microphone permissions per-app, not per-process.

Solution: Go to System Settings → Privacy & Security → Microphone and enable access for:

Your IDE (IntelliJ IDEA, Android Studio, Cursor, etc.)
Terminal.app (if running from command line)

JVM (Desktop)

No setup required for basic usage. ✅

Kodio uses the Java Sound API which is available on all JVM platforms. Recording and playback work out of the box.

fun main() = runBlocking {
    val recording = Kodio.record(duration = 5.seconds)
    recording.play()
}

System properties

Kodio supports the following system properties for JVM configuration:

Property	Default	Description
`kodio.useJavaSound`	`false`	Force using JavaSound (javax.sound.sampled) instead of native CoreAudio on macOS.

When to use kodio.useJavaSound:

Debugging audio issues on macOS
If the native CoreAudio library fails to load
When you need guaranteed cross-platform behavior

Set it in code before any Kodio calls:

fun main() {
    System.setProperty("kodio.useJavaSound", "true")
    
    runBlocking {
        val recording = Kodio.record(duration = 5.seconds)
        recording.play()
    }
}

Or via command line:

java -Dkodio.useJavaSound=true -jar your-app.jar

Web (JS / Wasm)

Web platforms require HTTPS and browser permission prompts.

Set up Web

Ensure your site is served over HTTPS (or localhost for development). Browsers block microphone access on insecure origins.
That's it! The browser will automatically prompt the user for microphone permission when you call Kodio.record().

Browser compatibility

Browser	Support
Chrome	✅ Full support
Firefox	✅ Full support
Safari	✅ Full support
Edge	✅ Full support

Quick reference

Platform	Permission	Initialization	Extra
🤖 Android	Manifest + Runtime	`Kodio.initialize(context)`	—
🍎 iOS	Info.plist	—	—
🍏 macOS	Info.plist	—	Entitlement, Java 21+
☕ JVM	—	—	`kodio.useJavaSound` option
🌐 Web	Browser prompt	—	HTTPS