FFmpeg for Kotlin Multiplatform, as plain Kotlin calls: convert, cut, filter and read video and audio from commonMain, with FFmpeg already inside the artifact.

_{AI tools wrote much of the code, tests and documentation in this project, under the direction and review of its author.}

Documentation · API reference · Changelog

You call Kotlin functions. No ffmpeg process starts, and no log text is parsed. Every native, JVM and Android artifact carries its own copy of FFmpeg, so a dependency line is the whole setup on most targets.

This shrinks a video to 640 by 360 and re-encodes its sound. Memory stays flat whether the file lasts one minute or three hours.

import io.github.yuroyami.kiteffmpeg.AudioEncoderSpec
import io.github.yuroyami.kiteffmpeg.CodecId
import io.github.yuroyami.kiteffmpeg.Rational
import io.github.yuroyami.kiteffmpeg.Transcoder
import io.github.yuroyami.kiteffmpeg.VideoEncoderSpec

suspend fun shrink(input: String, output: String) {
    Transcoder.transcode(
        input = input,
        output = output,
        spec = VideoEncoderSpec(
            codec = CodecId.Mpeg4,              // in every published build
            width = 640, height = 360,
            frameRate = Rational(30, 1),
            bitrateBps = 1_500_000,
        ),
        videoFilter = "scale=640:360,format=yuv420p",
        audioSpec = AudioEncoderSpec(codec = CodecId.Aac),
        onProgress = { p -> println("${p.framesEncoded} frames") },
    )
}

When something goes wrong, you get one FFmpegException that carries a typed FFmpegError. So "this build has no AAC encoder" is a case you match in code, not a message you read.

[!NOTE] KiteFFmpeg is not at 1.0 yet, so the API can still change between minor versions. A snapshot of the whole public API is checked on every push, so no change slips through unseen.

commonMain.dependencies {
    implementation("io.github.yuroyami:kiteffmpeg:0.5.1")
}

Every target you declare gets FFmpeg, about 10 MB per platform. You do not install FFmpeg, and there is no Gradle plugin. In a plain Android or JVM project, put the line in your usual dependencies { } block.

[!IMPORTANT] Three setups need one more step. Without it, the link, the App Store upload or the first call fails.

-lz -framework CoreFoundation -framework CoreMedia -framework CoreVideo -framework VideoToolbox -framework AudioToolbox

KiteFFmpegWeb.load()                 // fetches ./kite.mjs; or attach() a module the page made
check(FFmpeg.identity.isAcceptable)

Run these from a coroutine, because the work calls suspend. The documentation has one guide per task.

import io.github.yuroyami.kiteffmpeg.Remuxer

// Change the container and keep every stream as it is. Fast, and it loses nothing.
Remuxer.remux(input = "movie.mkv", output = "movie.mp4")

// Keep 0:10 to 0:40, still without re-encoding.
Remuxer.remux(input = "movie.mp4", output = "clip.mp4", startMicros = 10_000_000, endMicros = 40_000_000)

Times are microseconds from the start of the content, not the raw timestamps stored in the file. A cut without re-encoding starts at the keyframe at or before startMicros, because a copy cannot make a new keyframe. Transcoder.transcode takes the same two times when you need the exact frame. See Remuxing and Transcoding.

import io.github.yuroyami.kiteffmpeg.MediaSource

MediaSource.open("movie.mp4").use { source ->
    source.extractFrame(atMicros = 5_000_000).use { frame ->
        println("${frame.info.width}x${frame.info.height}")
        val pixels = frame.copyPlanesToByteArray()
    }
}

A Frame holds native memory until you close it, so close every frame, as use { } does.

MediaSource.open("movie.mp4").use { source ->
    val video = source.primaryVideo ?: error("no video track")
    source.decodedFrames(video).collect { frame ->
        frame.use { println("shown at ${it.info.ptsSeconds}s") }
    }
}

Use decodeStreams(...) to read video and audio together in one pass. To buffer frames, use bufferFrames(), not buffer(), so that each frame still gets closed. See Decoding.

A filter string uses FFmpeg's own syntax, so a chain that works with ffmpeg -vf works here. Pass it as videoFilter or audioFilter to transcode, or build a FilterGraph to run frames through yourself. A graph names its inputs [in0], [in1] and so on, and its one output [out]. Platform support lists the filters that every build carries, and Filtering shows the graph API.

A MediaByteSource feeds FFmpeg bytes from memory, a cache, an encrypted store or your own HTTP client. For an HLS playlist, a MediaByteOpener also serves the segments and keys that the playlist names, which is how an https stream plays with no TLS inside FFmpeg:

val stream = MediaSource.open(
    io = fetch("https://cdn.example/live/index.m3u8"),
    url = "https://cdn.example/live/index.m3u8",
    nestedOpener = { address -> if (address.startsWith("https://cdn.example/")) fetch(address) else null },
)

Here fetch stands for your own HTTP client. The addresses come from the playlist, so open only the ones you expect. See Decoding. On Android, "fd:" with the fd option reads a file the user picked, without a copy, as Platform support shows.

FFmpeg.hasEncoder("h264_videotoolbox")      // true on macOS
FFmpeg.hasFilter("scale")                   // true everywhere but the web
FFmpeg.setLogSink(FFmpegLogLevel.Warning) { level, component, message -> println("$component: $message") }

FFmpeg prints nothing unless you install a log sink. The sink runs on whichever thread FFmpeg logs from, so keep it quick, and do not call KiteFFmpeg from inside it.

[!TIP] Building a media player? The calls above read a file from front to back, which suits converting and does not suit playback. A player needs audio and video to move separately and to jump while both run. The lower-level API behind @KiteFFmpegLowLevelApi does that, and KitePlayer is built on it. You free its objects yourself, so stay with the calls above unless you write a player.

Android and iOS play real media on phones every day, because this is the engine under KitePlayer. No phone runs in this repository's CI, so that evidence is checked by hand and by a shipping app. Desktop and Windows are the reverse: CI checks them on every push. Platform support has the detail for each target.

./gradlew :kiteffmpeg-sample:linkDebugExecutableMacosArm64
KEXE=kiteffmpeg-sample/build/bin/macosArm64/debugExecutable/kiteffmpeg-sample.kexe
$KEXE transcode in.mp4 out.mp4 "scale=1280:720" -acopy   # also: info, probe, thumbnail, remux

./gradlew :kiteffmpeg:macosArm64Test          # or linuxX64Test, mingwX64Test
scripts/e2e.sh "$KEXE"

cd native/kitecodec-c
./scripts/build-host.sh plain && ./scripts/run-c-tests.sh plain   # also asan, tsan

Apache-2.0. See NOTICE and the changelog.

Not affiliated with the FFmpeg project. FFmpeg is a trademark of Fabrice Bellard, and KiteFFmpeg is an independent Kotlin binding that links FFmpeg's LGPL libraries. The logo is not official FFmpeg artwork, and the Apache-2.0 grant does not cover it; the artwork credits record its sources.

Part of the Kite family: KitePlayer, Kite3D and KitePDF.