KitePlayer

A media playback library for Kotlin Multiplatform apps. Its engine is written in Kotlin and plays video, audio and subtitles on Android, iOS, macOS, the desktop JVM and the web, with FFmpeg already inside the artifacts through KiteFFmpeg. It takes mpv and VLC as its models, and aims for their performance and range of features.

 Android    iOS    macOS    Desktop JVM    Web 

Install ·  Play something ·  Control ·  Subtitles ·  Network ·  Platforms ·  Modules
_{Guides · API reference · Changelog · Contributing}

Not every platform has every feature. Where it runs and Limits say what is missing where.

This desktop JVM program plays a song, seeks, and closes the player:

import io.github.yuroyami.kiteplayer.KitePlayer
import io.github.yuroyami.kiteplayer.MediaItem
import kotlinx.coroutines.delay
import kotlinx.coroutines.runBlocking
import kotlin.time.Duration.Companion.seconds

fun main() = runBlocking {
    val player = KitePlayer()
    player.open(MediaItem("/path/to/song.mp3"))   // returns when the item is open and paused
    player.play()
    delay(10.seconds)
    player.seek(60.seconds)                       // returns when the seek has landed
    delay(10.seconds)
    player.closeAndAwait()
}

[!NOTE] KitePlayer has not reached 1.0. It plays real media on Android, iOS, macOS and the desktop JVM, and it runs inside a shipping app, but the API can still change between versions. Read Limits before you plan around it.

Pick one line. Both pull in the whole playback stack, and Gradle picks the platform pieces for each target you declare.

commonMain.dependencies {
    implementation("io.github.yuroyami:kiteplayer:0.2.0")            // native views, no Compose
    // or
    implementation("io.github.yuroyami:kiteplayer-compose:0.2.0")    // Compose, plus everything above

    implementation("io.github.yuroyami:kiteplayer-audioviz:0.2.0")   // optional: a visualiser for audio
}

You do not install FFmpeg, and there is no Gradle plugin. On Android, every artifact needs minSdk 26 or higher. In an Android-only app, put the line in your usual dependencies { } block. Modules draws what each line pulls in.

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

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

<key>NSPrivacyAccessedAPITypes</key>
<array>
    <dict>
        <key>NSPrivacyAccessedAPIType</key>
        <string>NSPrivacyAccessedAPICategorySystemBootTime</string>
        <key>NSPrivacyAccessedAPITypeReasons</key>
        <array><string>35F9.1</string></array>
    </dict>
    <dict>
        <key>NSPrivacyAccessedAPIType</key>
        <string>NSPrivacyAccessedAPICategoryFileTimestamp</string>
        <key>NSPrivacyAccessedAPITypeReasons</key>
        <array><string>C617.1</string><string>3B52.1</string></array>
    </dict>
</array>

Three steps: create a player, show it, open something. The order of the last two does not matter: media may open before the view is on screen.

import io.github.yuroyami.kiteplayer.KitePlayer

val player = KitePlayer()

KitePlayer() builds the player on this platform's default stack: FFmpeg, and the platform's own audio output. Where the platform cannot play, it throws a PlaybackException that says why; KitePlayer.isAvailable checks that first. Settings go in a block, for example KitePlayer { subtitles { preferredLanguages = listOf("ja") } }.

import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.runtime.LaunchedEffect
import androidx.compose.ui.Modifier
import io.github.yuroyami.kiteplayer.MediaItem
import io.github.yuroyami.kiteplayer.compose.KitePlayerVideo
import io.github.yuroyami.kiteplayer.compose.rememberKitePlayer

val player = rememberKitePlayer()
KitePlayerVideo(player, Modifier.fillMaxSize())
LaunchedEffect(Unit) {
    player.open(MediaItem("https://example.com/movie.mkv"))
    player.play()
}

KitePlayerVideo(player, Modifier.fillMaxSize()) { KitePlayerControls(player) }

view.player = player

Then open media from a coroutine that you own. A call that takes time suspends until it is done: open, seek and closeAndAwait. play, pause and the setters return at once. requestSeek is the seek that does not wait, for a seek bar being dragged.

import io.github.yuroyami.kiteplayer.MediaItem
import kotlin.time.Duration.Companion.seconds

player.open(MediaItem("https://example.com/movie.mkv"))
player.play()
player.seek(90.seconds)

// When the screen goes away, unless rememberKitePlayer owns the player:
player.closeAndAwait()

KitePlayerJava player = KitePlayerJava.create();
player.addListener(new KitePlayerListener() {
    @Override
    public void onState(PlayerSnapshot state) {
        statusView.setText(state.getStatus().name());
    }

    @Override
    public void onProgress(Progress progress) {
        seekBar.setProgress((int) progress.getPositionMillis());
    }
}, ContextCompat.getMainExecutor(context));

player.openAsync(new MediaItemBuilder("https://example.com/movie.mkv").build())
        .thenRun(() -> player.getPlayer().play());
player.seekAsync(90_000);

// When the screen goes away:
player.close();

A file path or a URL needs nothing more. MediaItem("/sdcard/movie.mkv") goes straight to FFmpeg's own file reader, which is the fastest way to read a local file. So does the address a Compose Multiplatform resource has, on every target: MediaItem(Res.getUri("files/intro.mp4")) plays the bundled file, from the app's assets on Android and from the app's jar on the desktop. On Android that reads the assets through the application context, which a small content provider of kiteplayer-io keeps from the moment the app starts, as Compose's own resources do.

For anything else, use a door: a function that turns what you have into a MediaIoFactory for the item's io field. Each open of the item gets a new reader from it, because a track switch, a loop or a recovery opens the item again.

import io.github.yuroyami.kiteplayer.MediaIo
import io.github.yuroyami.kiteplayer.MediaItem
import io.github.yuroyami.kiteplayer.from
import io.github.yuroyami.kiteplayer.io.ofUri

player.open(MediaItem.from(MediaIo.ofUri(contentResolver, uri), label = "picked.mkv"))
player.play()

The label names the item in logs and helps FFmpeg guess the format. A stream and a pipe read forward only, so the player cannot seek in them. MediaIo.ofBytes does not copy the array, so keep it unchanged while playback can read it. The first two doors are in kiteplayer-core, and the others in kiteplayer-io, which comes with kiteplayer.

A file that is still being written, such as a recording in progress or a download that plays as it arrives, plays to its current end and on as it grows when the item says so: MediaItem(path, growth = FileGrowth()). The player waits at the end for more, and ends the item once the file has not grown for FileGrowth.endsAfter, two seconds by default. Its length grows with the file, and a seek reaches any part already written. A plain path needs kiteplayer-io for this; an item with its own io needs nothing more.

import io.github.yuroyami.kiteplayer.CorruptPackets
import io.github.yuroyami.kiteplayer.ProbeDepth
import io.github.yuroyami.kiteplayer.mediaItem

val item = mediaItem("https://cdn.example.com/live/channel.ts") {
    header("Authorization", "Bearer $token")
    probe(ProbeDepth.Fast)
    corruptPackets(CorruptPackets.Drop)
    lowLatency()
}

Everything here works during playback, and everything is published on player.state, so your UI can read it back.

Five flows tell your UI what is happening: state, progress, stats, events and subtitleCues. position() reads the current time without collecting anything. Anything the player cannot do is refused with a typed error, never accepted and ignored, and two players in one process work.

[!TIP] SeekMode.Precise is the default seek. SeekMode.KeyframeThenRefine shows the nearest keyframe at once and replaces it with the exact frame a moment later, which makes scrubbing feel instant on large files.

• SubRip, WebVTT and SubStation Alpha, from the container or from an external file. External files load in the middle of playback.
• Synced lyrics: an .lrc file, or LRC lines in a song's own tags (an ID3 USLT frame, a Vorbis or Matroska LYRICS, an MP4 ©lyr), become a track that shows line by line through subtitleCues, selected when nothing else is. Lyrics without times are PlayerSnapshot.lyrics, for the application to show (#443).
• SubtitleConfig.hearingImpairedNotes hides the notes of subtitles made for deaf and hard-of-hearing viewers: [DOOR SLAMS], a (laughs) that opens a line, JOHN: and ♪ music lines, and with HideStrict every parenthesis. ASS scripts are left alone (#493).
• An external file added without a language takes one from its name, as Film.en.srt, Film.eng.forced.srt and Film.pt-BR.sdh.srt say it, with forced, and sdh, cc or hi, marking the track, and a file in a preferred language is chosen at open over the container's track in a later one (#514).
• A subtitle the player chose by itself follows the audio: switching an anime to the English dub shows the English signs track made for it, and switching back shows every line again. One the viewer chose stays. SubtitleConfig.withMatchingAudio, as mpv's subs-with-matching-audio, keeps only forced tracks, or none, under audio in a preferred subtitle language (#506).
• WebVTT keeps its colours: the standard's colour classes such as <c.yellow> and <c.bg_blue>, and the ::cue rules of its STYLE blocks for colour, background, bold, italic, underline, font and relative size, by class, voice and cue identifier. A rule that asks for anything more is ignored whole (#498). A SubtitleStyleOverride still wins over the file's colours.
• Blu-ray (PGS), DVB, DVD and XSUB image subtitles from the container, placed on the picture they were authored for.
• DVB teletext subtitles from a broadcast recording or an IPTV stream, read in Kotlin with no native library. Each subtitle page the channel lists is a track of its own, with its language and its hearing impaired mark, as VLC lists them, and a page shows its colours, its boxed backgrounds and its double height lines in the top or bottom half of the picture. The letters follow the page's national character set, Latin, Cyrillic, Greek or Hebrew, as libzvbi reads them (#510).
• The closed captions broadcast H.264, HEVC and MPEG-2 carry inside the picture, which have no subtitle stream of their own, become a track, CC1, from the first picture that carries any. Each screen shows as it is sent, as mpv shows them, and like a television the player shows them when the viewer's preferences or the viewer ask, not by default. Pictures a platform decoder draws straight to a surface carry none (#236).
• A disc's forced captions, the signs and foreign dialogue it marks forced among a Blu-ray or DVD track's pictures, can draw on their own. setForcedPicturesOnly, as mpv's sub-forced-events-only, draws only those of the chosen track, and SubtitleConfig.forcedPicturesWhenOff draws those of the track in the audio's language while no subtitle is chosen, following the audio, as Kodi does (#513).
• ASS and SSA tracks are drawn by libass as authored: moving signs, animated transforms, karaoke fills, clips and vector drawings. They re-render every video frame while they move.
• An ASS script's colours are matched to the video through its YCbCr Matrix header, as XySubFilter and libass's own notes ask, so a sign coloured to blend into the picture still blends in. A script with no header counts as BT.601 at studio range, None keeps its colours, and so do HDR and RGB video. The built-in styling does the same, and SubtitleConfig.assColorMatching = false keeps every colour as authored (#499).
• Fonts attached to a Matroska file load for the track, and SubtitleConfig.fonts adds your own. On Android and Linux, a bounded set of system fonts loads too.
• setSubtitleSafeArea keeps the built-in text out of a display cutout, rounded corners or a control bar. Subtitle placement says where subtitles land on every renderer.

HTTP and HTTPS work as soon as kiteplayer-network is on the classpath, and every standard entry point includes it. You do not build a resolver or a Ktor client.

• Android and the JVM use OkHttp with the platform trust store, and Apple uses NSURLSession.
• MediaItem.headers reach whichever transport is selected.
• The Android artifact declares the INTERNET permission for you. Cleartext HTTP follows your app's own policy. It also declares ACCESS_NETWORK_STATE, which Android grants at install, and a provider that keeps the application context, so a player waiting for the network hears at once when it comes back.
• A drop of the network longer than the reader's reconnects fails the item. Set NetworkConfig.recovery = NetworkRecovery() and the player waits for the network instead, says so with PlayerSnapshot.reconnecting, and opens the item again where it was, or at the live edge, for up to maxWait (#461). It is off by default.
• In a browser, a player on the page's own thread cannot play network media, because a read cannot wait there. KitePlayerWorker plays it from a web worker (#100), see Web setup. It downloads the whole file before it plays, up to 512 MiB, and HLS and DASH do not play there yet. On the page's thread, fetch the file and play it from memory with MediaItem.from(MediaIo.ofBytes(bytes), name).

HLS plays through the same transport. An address that ends in .m3u8, an HLS content type from the server, or formatHint = "hls" marks a playlist. When none of those does, the first bytes do: a playlist starts with #EXTM3U, so one behind an address with no extension, sent as text or as bytes, plays too (#400).

• A master playlist plays one variant: the one that DemuxPolicy.variant names, or else the one with the highest bitrate within DemuxPolicy.maxBitrate and DemuxPolicy.maxVideoHeight. Tracks.variants lists the variants, and KitePlayer.selectVariant plays another one from the current position. The stream opens again for that, so the picture holds for a moment.
• The choice follows the screen (#447). An HDR version plays on a display that shows HDR as HDR, under HdrPolicy.Auto, and the SDR one elsewhere. Nothing larger plays than the smallest variant that fills the view the picture is drawn into, so a phone does not fetch 4K, and the cap rises when the view grows. The player reads both from the attached renderer at each open and each step. Set DemuxPolicy.fit to decide for it, and VariantFit() for no cap. A DASH manifest's transfer characteristics property counts as HLS's VIDEO-RANGE. The Apple renderers do not report HDR yet (#540).
• The player steps down when the stream reads slower than it plays, or when playback has waited 4 s for data, and PlaybackWarning.VariantLowered says so.
• It steps up when the network carries the next higher variant with half again to spare and the buffer is full. The network reader measures that rate on its downloads, and reports it through MediaIo.networkBitsPerSecond. A reader of your own that answers null never steps up.
• A step up waits 30 s after a step down, and twice as long after each step up that did not last, up to 5 minutes.
• Each step opens the stream again, so the picture holds for a moment. A variant that you selected stays, and a step up never passes DemuxPolicy.maxBitrate, maxVideoHeight or the fit, and never moves between SDR and HDR.
• MPEG-TS and fMP4 segments, byte ranges, AES-128 keys, separate audio and subtitle renditions, and live playlists play. A finished playlist can seek. A rendition's NAME is its track's title, and its DEFAULT, FORCED and accessibility CHARACTERISTICS set the track's flags.
• Only the audio rendition being heard is downloaded, so a stream with six languages does not pay for five that nobody hears. A switch to another language reads it from the moment playing: the picture and the old language go on until the new one is there, usually within a second, and the reads go back once over what they had read ahead. A file switches instantly, as before.
• Playlist variables play: EXT-X-DEFINE by NAME and VALUE, by IMPORT from the master playlist, and by QUERYPARAM from the playlist's own address, so a token in the master playlist's address reaches every variant, segment and key that names it. A playlist that was redirected takes its QUERYPARAM and its relative addresses from where it was redirected to. A reference to a variable that nothing defined fails the open, and the error names it.
• A segment that cannot be read is skipped, and PlaybackWarning.SegmentSkipped says so. A stream that ends while its last segments fail ends with PlaybackError.SourceUnavailable.
• EXT-X-PROGRAM-DATE-TIME gives each position the time of day it was broadcast (#444), in milliseconds since 1970 UTC. Progress.timeOfDayMillis publishes it for the position, and firstTimeOfDayMillis and lastTimeOfDayMillis for the moments the playlist lists, the last of a live one being its edge. KitePlayer.timeOfDayAt and positionAtTimeOfDay map both ways, seekToTimeOfDay goes to one in a stream that can seek, and timeOfDayClock makes two players on one live stream follow the same broadcast moment. A DASH manifest's availabilityStartTime gives the same. A playlist that names its segments through variables gives no time of day yet.
• MediaItem.headers go only to the scheme, host and port of the item's own address, because a playlist can name segments on any server.
• Your own MediaIo can serve HLS too: report the address it read in location, and open the addresses the playlist names in openRelated.

A Shoutcast or Icecast station names each song as it starts, and the player shows it when it is heard rather than when it is read, seconds ahead (#423). The network reader asks for the titles, takes the title blocks out of the bytes, and reads a title in windows-1251 or another legacy table as the player reads a subtitle file. A chained Ogg's next song and the other tags a stream changes while it plays arrive the same way.

• PlayerSnapshot.metadata holds the song as StreamTitle, beside the station's icy-name.
• The media session shows the song as the title and the station on the artist line.
• setItemDetails replaces the playing item's title, artist and album without opening it again, for a station that publishes its song list somewhere else. It and the station's next song replace each other, whichever came last.
• A reader of your own reports tags through MediaIo.takeTags.

A radio station's link is often a list that names its stream rather than the stream itself, and it plays as it is (#450). A PLS file is recognised by its [playlist] first line, an audio/x-scpls type or a .pls address, and an M3U list by the same marks as an HLS playlist, but with no #EXT-X- tag in it.

• The first stream on the list that opens plays, so the backups a station lists after its main stream take over when that one is down. When none opens, the last failure is reported.
• The stream's title is the one the list gives it, TitleN in a PLS file and the #EXTINF text in an M3U list, unless the stream names itself.
• The streams open through the list's reader, on its client, so a MediaIo of your own serves them through openRelated, as for HLS. A list that names another list is followed, three levels deep at most.
• A station's server closes a listener's connection now and then, after a long pause, when its encoder restarts or when a load balancer moves the listener. A stream with no length and no ranges that carries Shoutcast or Icecast icy- headers connects again and goes on from the live edge, with PlaybackWarning.SourceReconnecting each time, and ends only when the station still answers 404 or 410 once the reconnects are spent (#508). Without those headers the stream ends where the server stops, because a media server that encodes a song as it sends it answers the same way, and asking it again would play the song again.

A DASH address plays as it is, through the same transport, with no call to make. The manifest is recognised by its application/dash+xml type, by a path that ends in .mpd, or, when the server sends it as text, XML or bytes, by its root element (#400).

• A manifest whose picture and sound are fragmented MP4, MPEG-TS or WebM plays through the HLS path: each video representation is a variant, each audio set an audio rendition, and each subtitle set a subtitle rendition. FFmpeg's HLS reader reads WebM segments although the HLS specification names only the other two (#401). Separate sets play together, a finished presentation seeks, and a live one plays from its live edge and fetches the manifest again after each update period.
• A live manifest counts its window on the time of day its UTCTiming names, by direct, http-xsdate, http-iso or http-head, and falls back to the device's clock with a line in the log; a refresh follows its Location (#404). In a browser http-head answers only from a server that exposes its Date header.
• An audio or subtitle track takes its set's Label as its title, main sound is the default, forced-subtitle is a forced track, and caption and description are marked as accessibility tracks. Digital rights management is out of scope: an encrypted set is left out, and an encrypted manifest is refused with DashUnsupportedException.
• Segment templates, numbered or with a timeline, segment lists, and single files all play: an MP4 file through its segment index (sidx), and a WebM file through its Cues.
• Subtitle sets of WebVTT play as they are. Sets of TTML, and of TTML or WebVTT in MP4 segments (stpp, wvtt), are served to the player as WebVTT, with their text, line breaks, italic, bold and underline, but not their placement (#402).
• A manifest of several Periods, as ad insertion and chapters stitch them, plays as one presentation (#403). Each later Period gives each track the set with the same id, at the same place or in the same language, and the representation nearest its bandwidth. Time runs on across each boundary although each Period's media time starts again, an fMP4 Period of another picture size decodes at its own, because its H.264 or HEVC parameter sets travel with its keyframes, and a live manifest that a refresh gives a new Period plays on into it. An fMP4 Period in another codec than the first is skipped.
• MediaItem.headers go to the manifest and to the segments of its own scheme, host and port, as for HLS.
• Dash.mediaItemFor builds the item yourself, for a client of your own, a DashUrlPolicy other than the default, or other size ceilings. Dash.manifest reads a manifest without playing it.

Android stops a process that plays in the background unless a foreground service holds it. kiteplayer has that service, KitePlayerMediaService, and your app declares it:

<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK" />
<uses-permission android:name="android.permission.WAKE_LOCK" />

<application>
    <service
        android:name="io.github.yuroyami.kiteplayer.session.KitePlayerMediaService"
        android:exported="false"
        android:foregroundServiceType="mediaPlayback" />
</application>

Then attach the media session. With notification options, it shows the media notification and keeps the app playing in the background. It also takes audio focus, and it closes with the player. smallIcon is your app's monochrome notification icon.

import io.github.yuroyami.kiteplayer.session.MediaNotificationOptions
import io.github.yuroyami.kiteplayer.session.attachMediaSession

player.attachMediaSession(context, MediaNotificationOptions(smallIcon = R.drawable.ic_notification))

On iOS, declare UIBackgroundModes with audio and call player.attachMediaSession() for the lock screen. A desktop app keeps playing without help, and a web page plays while its tab is open.

kiteplayer-audioviz draws the sound when the media has no picture. Show it in place of the video when isAudioOnly says so:

import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.runtime.collectAsState
import androidx.compose.runtime.getValue
import androidx.compose.ui.Modifier
import io.github.yuroyami.kiteplayer.audioviz.KiteAudioViz
import io.github.yuroyami.kiteplayer.audioviz.isAudioOnly
import io.github.yuroyami.kiteplayer.audioviz.rememberAudioVizState
import io.github.yuroyami.kiteplayer.compose.KitePlayerVideo

val viz = rememberAudioVizState(player)
val snapshot by player.state.collectAsState()

if (snapshot.isAudioOnly) {
    KiteAudioViz(viz, Modifier.fillMaxSize())
} else {
    KitePlayerVideo(player = player, modifier = Modifier.fillMaxSize())
}

Create the state where you create the player's screen, not inside the audio-only branch, so it is already listening when a song starts. Album art does not count as a picture.

KitePlayer's JVM and Android classes are Java 11 bytecode, and so is the KiteFFmpeg 0.5.0 jar, so a desktop app runs on Java 11 or later.

Everything else that is open lives in GitHub Issues.

What each install line pulls in. The violet boxes are the two lines you pick from, the magenta one is the optional visualiser, and a dotted arrow is a dependency used at runtime only.

%%{init: {"flowchart": {"nodeSpacing": 14, "rankSpacing": 44}}}%%
flowchart LR
    classDef entry fill:#7F52FF,stroke:#7F52FF,color:#ffffff
    classDef optional fill:#C518CB,stroke:#C518CB,color:#ffffff
    classDef outside stroke-dasharray:4 3

    compose([kiteplayer-compose]):::entry
    kp([kiteplayer]):::entry

    compose --> ui[kiteplayer-compose-ui]
    ui -. runtime only .-> interop[kiteplayer-compose-interop]
    ui -. runtime only .-> cvideo[kiteplayer-compose-video]
    compose --> kp

    kp --> bindings[kiteplayer-view-bindings]
    bindings --> view[kiteplayer-view]
    kp --> output[kiteplayer-output]
    kp -- not on Linux and Windows native --> network[kiteplayer-network]
    kp --> libass[kiteplayer-libass]
    kp --> io[kiteplayer-io]
    kp --> ffmpeg[kiteplayer-ffmpeg]
    ffmpeg --> subs[kiteplayer-subtitles]
    ffmpeg --> kff[(KiteFFmpeg)]:::outside
    kp --> core[kiteplayer-core]
    core -- native targets only --> rt[kiteplayer-rt]

    viz([kiteplayer-audioviz]):::optional
    viz --> core
    viz --> k3d[(Kite3D)]:::outside

To build your own stack, start from kiteplayer-core and supply backends through KitePlayer.create(PlayerConfig(backends = Backends(backend, output))). The SPI cookbook walks through one, and the module contract says what each entry point promises.

./scripts/testmedia.sh          # generate the test clips, needs ffmpeg on PATH
./scripts/check-gate.sh tier1   # the checks every change runs

Apache-2.0. See NOTICE.

_{Part of the Kite family: KiteFFmpeg · Kite3D · KitePDF
Back to top}