Native WhatsApp WebP sticker conversion for Bun and TypeScript. Media decoding, pixel processing, and WebP encoding run in a persistent C++ worker; the TypeScript API sends bytes and returns validated sticker bytes.
- PNG, JPEG, static WebP, animated WebP, and FFmpeg-decoded video input
- 512 × 512 static or animated WebP output with image payloads bounded to conservative WhatsApp sticker limits
- Alpha trimming, proportional sizing, and alpha-aware outlines
- Optional WhatsApp sticker-pack EXIF metadata, muxed with
libwebpmux - Fast high-quality lossy output by default, with an opt-in lossless static attempt
- Persistent workers, per-request deadlines, bounded input, and automatic worker replacement after a transport failure or timeout
bun add @rin-ts/stickerPrebuilt workers are selected automatically on Linux x64 and Linux ARM64.
Pass workerPath only when using a custom native worker executable.
Keep a custom worker on the same package version as its TypeScript wrapper. A
newer wrapper can send ordinary requests to an older worker, but that worker
keeps its older encoding default; preferLossless: true is rejected by an
older worker. exif also requires a matching worker version.
Create a worker once during application startup and reuse it for requests.
import { createNativeStickerWorker } from "@rin-ts/sticker";
const worker = createNativeStickerWorker({ timeoutMs: 15_000 });
const source = await Bun.file("./photo.png").arrayBuffer();
const sticker = await worker.transcode(source, {
trim: true,
alphaThreshold: 4,
outline: {
width: 8,
color: { red: 255, green: 255, blue: 255, alpha: 255 },
},
exif: {
packId: "com.example.my-pack",
packName: "My Sticker Pack",
emojis: ["✨"],
},
});
await context.reply({ type: "sticker", media: sticker.data });
await worker.close();transcode() resolves to:
| Field | Description |
|---|---|
data |
Validated WebP sticker bytes |
width, height |
Always 512 on success |
frameCount, durationMs |
Animation metadata; static stickers have one frame and zero duration |
isAnimated |
Whether the output contains multiple frames |
| Input | Result |
|---|---|
| PNG, JPEG, static WebP | Static WebP sticker |
| Animated WebP | Animated WebP sticker |
| FFmpeg-supported video such as MP4, MOV, WebM, MKV, and AVI | Animated WebP sticker; audio is ignored |
GIF, APNG, Lottie/Telegram .tgs |
Rejected |
The worker receives bytes only; it is not a file-path CLI or an HTTP service.
const worker = createNativeStickerWorker({
workerPath: "/opt/rin/sticker_worker", // optional
workerArgs: [], // optional
timeoutMs: 30_000, // optional
});worker.transcode(source, options) accepts an ArrayBuffer or any typed-array
view. options are:
| Option | Default | Description |
|---|---|---|
trim |
true |
Remove fully transparent outer rows and columns |
alphaThreshold |
0 |
Alpha value treated as transparent while trimming |
outline.width |
0 |
Outline radius, from 0 through 64 pixels |
outline.color |
opaque white | { red, green, blue, alpha? }, each channel 0 through 255 |
preferLossless |
false |
Attempt lossless static WebP before lossy fallback; it still falls back when output exceeds 100 KiB |
exif |
none | Optional { packId, packName, emojis? } metadata written to WebP EXIF; packId and packName must be nonempty strings, and encoded JSON is limited to 4 KiB |
timeoutMs |
worker default (30,000 ms) | Deadline for writing, conversion, and reading the response |
Calls to one worker are intentionally serialized. Use a finite pool of workers
when parallel conversion is required. close() stops new work, drains already
accepted work, and terminates the child process.
- Source assets are limited to 16 MiB.
- Output is always 512 × 512 WebP.
- Static image data is limited to 100 KiB; optional EXIF adds at most 4 KiB plus WebP container overhead to the final file.
- Animated image data is limited to 500 KiB, 10 seconds, and requires multiple frames with delays of at least 8 ms. Optional EXIF adds the same bounded overhead.
The worker is discarded after a timeout, malformed protocol response, or transport failure; the next queued call starts a clean process. Still enforce download limits before calling this package, set an appropriate worker-pool size, and apply OS-level CPU and memory limits in production.
Run the repeatable end-to-end suite:
bun run benchmarkIt builds the native worker, generates deterministic full-size media fixtures locally, then reports cold latency (worker spawn plus first conversion) and warm latency (a reused worker). File I/O is excluded from warm measurements. The default fixtures cover a 1280 × 854 image as PNG, JPEG, and static WebP; a 1024 × 1024 transparent graphic; a three-frame animated WebP; and a three-frame 640 × 360 MP4. They are real encoded media files, not 1 × 1 test pixels, and no fixture is downloaded.
Use your own media to measure the inputs your application handles:
bun run build:native
# Compare the fast default and lossless preference using the same source:
bun run benchmarks/benchmark.ts --iterations 10 ./artwork.webp
bun run benchmarks/benchmark.ts --iterations 10 --prefer-lossless ./artwork.webpThe report includes source and output size, cold latency, warm median and p95,
and warm throughput. Performance varies with codec library versions, CPU,
source dimensions, frame count, transparency, and how often an output must be
re-encoded to meet its byte limit; compare results on the deployment hardware.
Static output uses the high-quality lossy path by default for predictable
latency. Set preferLossless: true when lower latency is not important and a
lossless attempt is worthwhile; output still falls back to lossy above 100 KiB.
The native build requires Bun, CMake 3.20+, a C++20 compiler, pkg-config,
and development packages for libpng, libjpeg, libwebp, libwebpmux,
libwebpdemux, libavformat, libavcodec, libavutil, and libswscale. On Void,
install FFmpeg headers with:
sudo xbps-install -S ffmpeg6-develThen build:
bun install
bun run build:nativeThe worker is written to build/native/bin/sticker_worker.
bun run testMaintain matching package versions and a v<version> tag, then run the
repository’s Publish packages GitHub Actions workflow with the intended npm
distribution tag. It publishes the platform packages before the main package
and skips package versions already present on npm. Before publishing, configure
an npm trusted publisher with npm publish permission for each of
@rin-ts/sticker, @rin-ts/sticker-linux-x64-gnu, and
@rin-ts/sticker-linux-arm64-gnu; use repository rin-ts/sticker and workflow
file release.yml. The workflow uses GitHub
Actions OIDC, so it does not need an NPM_TOKEN secret.
GPL-3.0-only. See LICENSE.