Home

pikpak-kotlin

A Kotlin Multiplatform SDK for PikPak cloud storage: every endpoint a suspend extension function on PikPakClient, with session persistence, token refresh, captcha re-authentication, retry, rate limiting, content hashing and OSS upload signing handled inside, and a playback stack that reads a remote file at any offset over as many connections as PikPak allows.

This wiki is the SDK's documentation beyond the README: how the pieces fit, what PikPak was measured to do, and why the code is shaped the way it is. The measurements are the part to keep. Each is dated, and a statement marked Fact is a measured property of PikPak — change the code around it freely, but do not contradict it without measuring again.

Pages

Using the SDK

• Getting Started — installing, building a client, sessions, errors
• Best Practices — what works, learned building a real client on it, with the reasons
• Playback — reading a file: range reads, handles, leases, the file cache, streams, prefetch, downloads, disk caching
• Magnets and Instant Create — from a magnet to a playable file in about a second, without an offline task
• Drive Operations — files, folders, trash, stars, search, shares, play history, archives
• Uploads and Offline Tasks — resumable uploads, content hashes, offline downloads and pruning
• Errors and Retries — what throws what, and what the client retries on its own

Understanding it

• Architecture — the layers, the request pipeline and its invariants, and the known design debts
• Measurements — connection limits, throughput, edge hosts, root domains, listing lag, all dated
• History — features that were removed and designs that were tried, so they are not tried again

Working on it

• Development — tests, probes, platform checks, releasing, keeping this wiki current

Built with it

Piko — a PikPak client for Android, Windows and macOS, by the same author. Its player streams through this SDK behind a loopback proxy, its random-clip feed prefetches in play order and keeps clip heads on disk, and it covers downloads, resumable uploads, magnets and offline packs, shares and archives. Most of Best Practices was learned there, and its source is a working example of every page here.

Versions

This wiki describes 2.0.0. It is updated as part of every release; a page that disagrees with the code is a bug in the page.