roxify

Encode binary data into PNG images and decode them back. Supports CLI and programmatic API (Node.js ESM).

Roxify is a compact, color-based alternative to QR codes, designed specifically for digital-only use (not for printing). It encodes data using color channels (rather than monochrome patterns) for higher density, and is optimized for decoding from approximate screenshots — including nearest-neighbour resize/stretch and solid or gradient backgrounds. It is not intended for printed media and is not resilient to lossy compression or heavy image filtering.

Roxify creates PNGs that are often more space-efficient than ZIP or 7z archives for similar payloads without loss. Roxify provides superior compression ratios, making it ideal for embedding images, GIFs, audio, video, code, and other files without any quality loss — the original file is perfectly recovered upon decoding.

Key benefits:

• Superior Compression: Roxify outperforms traditional ZIP and 7z (LZMA) in speed and ratio, enabling smaller PNG outputs.
• Lossless Embedding: Compress and embed any file type (images, videos, code) with full fidelity restoration.
• Code Efficiency: Hyper-efficient for compressing source code, reducing file sizes dramatically.
• Obfuscation & Security: Obfuscate code or lock files with AES-256-GCM encryption, more compact than password-protected ZIPs.
• Visual Data Indicator: PNG size visually represents embedded data size, providing an intuitive overview.
• Archive Support: Pack directories into archives, list contents without decoding, and extract individual files selectively.
• Central Directory: Access file lists without passphrase, even for encrypted archives.

Installation

npm install roxify

CLI Usage

npx rox encode <inputName>.ext (<outputName>.png)
npx rox decode <inputName>.png (<outputName>.ext)
npx rox list <inputName>.png

If no output name is provided:

• Encoding: output defaults to <inputName>.png.
• Decoding: if the image contains the original filename it will be restored; otherwise the output will be decoded.bin.

Options:

• -p, --passphrase <pass> — Encrypt with AES-256-GCM
• -v, --verbose — Show detailed errors

Run npx rox help for full options.

API Usage

Basic Encoding and Decoding

import { readFileSync, writeFileSync } from 'fs';
import { encodeBinaryToPng } from 'roxify';

const fileName = 'input.bin';
const inputBuffer = readFileSync(fileName);
const pngBuffer = await encodeBinaryToPng(inputBuffer, {
  name: fileName,
});
writeFileSync('output.png', pngBuffer);

import { readFileSync, writeFileSync } from 'fs';
import { decodePngToBinary } from 'roxify';

const pngFromDisk = readFileSync('output.png');
const { buf, meta } = await decodePngToBinary(pngFromDisk);
writeFileSync(meta?.name ?? 'decoded.txt', buf);

With Passphrase

const pngBuffer = await encodeBinaryToPng(inputBuffer, {
  name: fileName,
  passphrase: 'mysecret',
});

const { buf, meta } = await decodePngToBinary(pngFromDisk, {
  passphrase: 'mysecret',
});

With Progress Logging

const pngBuffer = await encodeBinaryToPng(inputBuffer, {
  name: fileName,
  onProgress: (info) => {
    console.log(`Phase: ${info.phase}, Loaded: ${info.loaded}/${info.total}`);
  },
});

Requirements

• Node.js 18+ (ESM)
• Native dependencies: sharp (auto-installed)

License

This package is proprietary (UNLICENSED). The repository remains private; the package is published to npm for distribution. If there is significant community interest, it may be open-sourced in the future.

Minimal PNG container (minpng) 🔧

This library includes a compact encoder/decoder that targets the smallest possible PNG container while guaranteeing pixel-perfect recovery from screenshots when no lossy filtering is applied.

• Inputs must be raw RGB 8-bit buffers (no alpha).
• Transformations used: Paeth 2D predictor (left/top), RGB decorrelation (G, R−G, B−G), zigzag traversal.
• Compression: Zstd at maximum compression level.
• Output: neutral PNG (no ICC/gamma/alpha), all data mapped to RGB bytes only.
• The decoder searches for start/end markers and a compact header embedded in pixels to perform a reliable, deterministic roundtrip.

Use encodeMinPng(rgbBuf, width, height) and decodeMinPng(pngBuf) from the public API (roxify).