<Platform-Setup.md>

Platform requirements: Android needs initialization, Apple platforms need Info.plist entries, Web needs HTTPS.

Each platform has specific requirements for audio recording. This guide walks you through the setup for each supported platform.

Android

Android requires both a manifest permission and runtime initialization.

Add the microphone permission to your AndroidManifest.xml:

<uses-permission android:name="android.permission.RECORD_AUDIO" />

Initialize Kodio before recording. The recommended approach is to call Kodio.initialize() from your main Activity, which wires up both the application context and permission handling in one step:

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        Kodio.initialize(this) // sets context + permission activity
    }

    override fun onRequestPermissionsResult(
        requestCode: Int, permissions: Array<out String?>,
        grantResults: IntArray, deviceId: Int
    ) {
        Kodio.onRequestPermissionsResult(requestCode, grantResults)
    }
}

If you prefer initializing in your Application class, note that this only sets the application context. Permission handling must be wired separately from an Activity.

class MyApp : Application() {
    override fun onCreate() {
        super.onCreate()
        Kodio.initialize(this) // context only
    }
}

<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")
    }
}

Recording in the Android emulator

Recording on the Android emulator routes audio through QEMU's audio bridge, which resamples and re-quantises the host microphone signal before handing it to the guest's AudioRecord. On macOS/Apple-silicon hosts this commonly produces audibly noisy or grainy playback even when the host mic is clean (GitHub issue #1).

Mitigations that help in practice:

Match the host's preferred format. Request AudioQuality.High (48 kHz / Int16 / mono) or AudioQuality.Standard so the emulator's audio bridge does not need to resample.
Configure the AVD to use the host audio backend directly. From the command line:
Test on a physical device for production audio quality validation — the emulator bridge is a known weak link and is not representative of on-device capture.

If the noise persists after the steps above, please attach a host-mic recording plus the emulator-recorded version to the GitHub issue so we can compare.

iOS

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

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.

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.
`kodio.jvm.recording.warmupMillis`	`200`	Number of milliseconds of audio read-and-discarded after the JavaSound `TargetDataLine` starts, to swallow the priming silence (GitHub issue #5). Set to `0` to disable.

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

When to tune kodio.jvm.recording.warmupMillis:

Lower it (e.g. 50) if you're capturing extremely short snippets and the warmup is eating real audio
Raise it (e.g. 400) if your JDK / OS combination has a slower priming ramp than 200 ms — symptoms are silence at the start of recordings on JVM
Set it to 0 to disable the drain entirely (useful when measuring raw JavaSound latency)

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.

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(activity)`	—
🍎 iOS	Info.plist	—	—
🍏 macOS	Info.plist	—	Entitlement, Java 21+
☕ JVM	—	—	`kodio.useJavaSound` option
🌐 Web	Browser prompt	—	HTTPS

Last modified: 25 April 2026