WorldPlay — Remuxer Guide

Installation

Add the dependency to your build configuration. Hosted on Maven Central.

Gradle (Kotlin DSL)

build.gradle.kts

dependencies {
    implementation("io.gitlab.projectworldplay:worldplayremuxer:2.0.0")
}

Gradle (Groovy DSL)

build.gradle

dependencies {
    implementation 'io.gitlab.projectworldplay:worldplayremuxer:2.0.0'
}

How it works

WorldPlay Remuxer parses HLS playlists (`.m3u8`), downloads segment slices concurrently, decrypts AES segments, concatenates them, and packages them into standard MP4 wrappers.

Remuxing vs. Transcoding

Unlike transcoding, remuxing copy-pastes encoded tracks directly from HLS transport files (MPEG-TS/fMP4) to standard MP4 boxes. This takes seconds, puts minimal load on CPU, and guarantees lossless original quality.

Key Technologies

Fast-Start MP4: Moves the metadata `moov` atom to the front of the file (rather than the back), enabling web players to start streaming instantly without downloading the entire file.
HLS Audio Demuxing: Automatically resolves, downloads, and interleaves separate audio-only streams (`#EXT-X-MEDIA:TYPE=AUDIO`) into the final MP4 container.
AES-128 Decryption: Automatically parses keys and decrypts HLS segments protected by `#EXT-X-KEY:METHOD=AES-128` on the fly using a secure key cache.

Progress Tracking

Monitor download speeds, segment completion, and pipeline stages reactively using callbacks or Kotlin Coroutines StateFlow.

DownloadTask.kt

import kotlinx.coroutines.runBlocking
import org.worldplay.remuxer.api.Remuxer
import org.worldplay.remuxer.api.RemuxResult

fun main() = runBlocking {
    val task = Remuxer.download(
        url = "https://cdn.example.com/hls/master.m3u8",
        output = "/downloads/movie.mp4"
    )

    // Register progress listeners
    task.onProgress { progress ->
        println("Stage: ${progress.stage} | Percent: ${progress.percent}% | Speed: ${progress.speedBytesPerSecond / 1024} KB/s")
    }
    .onComplete { result ->
        println("Download success: ${result.outputFile.absolutePath} in ${result.durationMs}ms")
    }
    .onError { error ->
        System.err.println("Download failed: ${error.message}")
    }

    // Wait until finished
    task.await()
}

Configuration

Customize timeouts, workers parallelism, download rate-limiting, retries, and failure tolerances using custom configurations.

CustomConfiguration.kt

import org.worldplay.remuxer.api.RemuxOptions
import org.worldplay.remuxer.api.Remuxer
import java.io.File

val options = RemuxOptions(
    headers = mapOf("Referer" to "https://vidprovider.com"),
    userAgent = "CustomPlayer/3.0",
    maxConcurrentDownloads = 6, // Parallel workers (1-8)
    maxRetries = 5,
    tempDirectory = File("/tmp/downloader_temp"),
    fastStart = true, // Fast-Start Web Optimization
    allowMissingSegments = true // Continue on single missing segments
)

val task = Remuxer.download(
    url = "https://example.com/master.m3u8",
    output = "/output/video.mp4",
    options = options
)

API Reference

Core methods and properties of `Remuxer` and `RemuxTask` interfaces.

Interface	Member	Type	Description
`Remuxer`	`install(okHttpClient, muxer)`	Method	Install shared client or custom muxer backend.
`Remuxer`	`download(url, output, options)`	Method	Enqueues a background remux task.
`Remuxer`	`shutdown()`	Method	Cancels all running tasks.
`RemuxTask`	`await()`	Method (suspend)	Suspends until task completes or fails.
`RemuxTask`	`cancel()`	Method	Cancels execution and cleans up temp files.
`RemuxTask`	`progress`	Property (StateFlow)	Reactive flow of progress metrics.