vibecompress

v0.1.0

Published

19 days ago

The greatest AI-powered image compression utility ever made. Creates vibes and returns hallucinations.

0High
0Medium
0Low

vibecompress vbz ai image-compression lossy-compression hallucinations flux openrouter openai

vibecompress (CLI: vbz / vibecompress) replaces traditional mathematical compression with pure generative hallucination:

Compress: A Vision-Language model (openai/gpt-4o-mini) describes your image in exhaustive detail. That text is gzipped into a tiny .vbz container (~1 KB).
Decompress: A generative image model (black-forest-labs/flux.2-klein-4b) dreams the image back into existence from the stored prompt.

Does the decompressed image match the original byte-for-byte? Absolutely not.
Does it capture the vibes? 100%.
Did you just achieve a 99.6% compression ratio? Yes. You're welcome.

🚀 Quickstart

Like ffmpeg, just point -i at your file. It auto-detects whether to compress or decompress:

# 1. Set your OpenRouter or OpenAI API Key
export VBZ_API_KEY="sk-or-v1-..."
export VBZ_BASE_LLM_URL="https://openrouter.ai/api/v1"
export VBZ_BASE_IMAGE_URL="https://openrouter.ai/api/v1"

# 2. Compress image -> photo.vbz (99%+ space saved)
npx vibecompress -i photo.jpg

# 3. Decompress vibes -> photo.png (hallucinates image back into existence)
npx vibecompress -i photo.vbz

Global Install:

npm install -g vibecompress
# Both 'vibecompress' and the short 'vbz' command are installed!
vbz -i photo.jpg

No API key? Try the offline mock mode with -s / --stub:
npx vibecompress -s -i photo.jpg

🖼️ Visual Proof & Real-World Examples

Real results generated from license-free Unsplash reference assets using the default stack (openai/gpt-4o-mini + black-forest-labs/flux.2-klein-4b):

| Original Input (.jpg / .png) | Reconstructed Vibe (.vibe.png) | Asset & Statistics | | :---: | :---: | :--- | | | | Guitar Guy Illustration• Original: 287.6 KB• .vbz: 1,259 bytes• Saved: 99.56% (228.4×)• Verdict: Pure acoustic joy intact. | | | | Solitary Ocean Puffin• Original: 108.5 KB• .vbz: 1,091 bytes• Saved: 98.99% (99.5×)• Verdict: Regal beak dignity preserved. | | | | Red Shirt Girl at Café• Original: 330.4 KB• .vbz: 1,193 bytes• Saved: 99.64% (276.9×)• Verdict: 10/10 confident café aura. |

📊 Full Benchmark Suite

| Test Asset | Original Size | Compressed .vbz | Space Saved | Compression Factor | Restored Size | Vibe Fidelity Rating | | :--- | :--- | :--- | :--- | :--- | :--- | :--- | | red_shirt_girl.jpg | 330.4 KB | 1,193 bytes | 99.64% | 276.9× | 356.3 KB | 🟢 Relaxed confidence; café ambiance intact | | illustration_guitar_guy.png | 287.6 KB | 1,259 bytes | 99.56% | 228.4× | 180.0 KB | 🟢 Boy strumming guitar with joy | | soda_statue.jpg | 171.9 KB | 1,364 bytes | 99.21% | 126.1× | 235.5 KB | 🟢 Translucent carbonated humanoid | | puffin.jpg | 108.5 KB | 1,091 bytes | 98.99% | 99.5× | 228.8 KB | 🟢 Regal orange beak; ocean solitude | | construction_rendering.jpg | 128.0 KB | 1,493 bytes | 98.83% | 85.7× | 290.0 KB | 🟢 Floating brickwork surrealism | | spiffo.png (Meme Mascot) | 355.0 KB | 1,023 bytes | 99.72% | 355.0× | 226.0 KB | 🟢 Spiky wooden club; 100% raccoon energy |

👉 Inspect all side-by-side proofs and decoded prompt containers in the Evidence Locker ➔

🌌 The Idea: Ontological Compression

For over 70 years, cowardly engineers have operated under the oppressive regime of Claude Shannon’s Source Coding Theorem. They quibble over discrete cosine transforms, Huffman trees, chroma subsampling, and arithmetic coding just to shave 14% off a JPEG.

vbz introduces the post-entropy era.

We do not compress pixels. Pixels are fleeting material illusions. We compress the essence of the scene—the vibe.

📐 Architecture Flow

┌─────────────────┐       Vision Model        ┌──────────────────────┐       gzip        ┌────────────┐
│   photo.jpg     │  ───────────────────────► │ "Golden retriever in │ ───────────────►  │  photo.vbz │
│    330 KB       │   (openai/gpt-4o-mini)    │ golden hour light..."│                   │   1.1 KB   │
└─────────────────┘                           └──────────────────────┘                   └────────────┘
                                                                                               │
   =================================== 10 YEARS IN COLD STORAGE ===============================│
                                                                                               ▼
┌─────────────────┐     Generative Model      ┌──────────────────────┐      gunzip       ┌────────────┐
│ photo_vibe.png  │  ◄─────────────────────── │ "Golden retriever in │ ◄──────────────── │  photo.vbz │
│    356 KB       │  (flux.2-klein-4b)        │ golden hour light..."│                   │   1.1 KB   │
└─────────────────┘                           └──────────────────────┘                   └────────────┘
 (1 extra paw, but
  immaculate vibe)

📊 Industry Benchmarks (The Weissman Showdown)

Benchmark run on a 5.4 MB 4K photograph of a picnic in Central Park:

"Shannon said you cannot compress past Kolmogorov complexity. VibeCompress proves that Shannon simply lacked vision and a budget for GPU inference."
— Dr. H. V. Vibe, Senior Vice President of Hallucination Dynamics

✨ Features

⚡ Infinite Space Glitch: Turn a 50 GB photo archive into a text file you can scribble on a sticky note.
🎨 Generative Super-Resolution: Did your original camera have a dirty lens and terrible lighting? The generative model will automatically invent high-res lighting and textures you never had. It's not an artifact; it's a spiritual upgrade.
🔮 Quantum Non-Determinism: Decompress the same family vacation photo three times, receive three slightly different childhood memories.
📦 Zero Runtime Dependencies: Zero external npm packages. Built exclusively on native Node.js standard libraries (node:zlib, node:fs, node:util, and global fetch). Zero node_modules bloat.
🔌 Universal Provider Support: Run with OpenRouter, OpenAI, local Ollama, or vLLM effortlessly.

🛠️ CLI Reference

vibecompress -i <file> [-o <output>] [options]
# (or using alias: vbz -i <file> ...)

1. Compress (`image` ➔ `.vbz`)

Passing any image into -i automatically triggers compression:

# Auto-names output to photo.vbz
npx vibecompress -i photo.jpg

# Custom output destination
npx vibecompress -i photo.jpg -o ./archive/compressed_photo.vbz

2. Decompress (`.vbz` ➔ `image`)

Passing a .vbz file into -i automatically triggers decompression:

# Optimistically detects original format from embedded metadata, defaults to .png
npx vibecompress -i photo.vbz

# Explicit output format
npx vibecompress -i photo.vbz -o restored_photo.png

3. Vibe Inspection Mode (Free, 0-Token-Cost Preview)

Want to read the soul of your image without spending image gen tokens? Pass -t / --text:

# Dump the raw decompressed description
npx vibecompress -i photo.vbz -t

# Or interrogate your photo using an LLM prompt:
npx vibecompress -i photo.vbz -t -p "What was the subject wearing?"

4. Stub Mode (Offline Mock Simulation)

No API key? Airplane mode? Pass -s / --stub:

npx vibecompress -s -i photo.jpg
npx vibecompress -s -i photo.vbz

5. Explicit Subcommands (For Traditionalists)

If you prefer explicit subcommands, they are fully supported:

npx vibecompress compress -i photo.jpg -o photo.vbz
npx vibecompress expand   -i photo.vbz -o photo.png
npx vibecompress decompress -i photo.vbz

💻 Programmatic JavaScript API

vibecompress exports clean, promise-based functions for integration into your Node.js apps:

import { compressImage, decompressImage, OpenAIClient } from 'vibecompress';

const client = OpenAIClient.fromEnv();

// Compress photo.jpg -> photo.vbz
await compressImage('photo.jpg', 'photo.vbz', client);

// Decompress photo.vbz -> restored.png
await decompressImage('photo.vbz', 'restored.png', client);

⚙️ Environment Variables

Configure your providers effortlessly. VibeCompress supports OpenRouter, OpenAI, Ollama, and vLLM:

⚡ Running with OpenRouter (Unified Vision & Image Gen)

OpenRouter natively supports image generation via its Unified Image API (POST https://openrouter.ai/api/v1/images or /images/generations). Just provide your OpenRouter key, point both base URLs to OpenRouter, and set OpenRouter model slugs:

# 1. Provide your OpenRouter API key & endpoints
export VBZ_API_KEY="sk-or-v1-..."
export VBZ_BASE_LLM_URL="https://openrouter.ai/api/v1"
export VBZ_BASE_IMAGE_URL="https://openrouter.ai/api/v1"

# 2. Pick OpenRouter-compatible models
export VBZ_LLM_MODEL="openai/gpt-4o-mini"
export VBZ_IMAGE_MODEL="black-forest-labs/flux.2-klein-4b"

# 3. Compress & decompress seamlessly
npx vibecompress -i photo.jpg
npx vibecompress -i photo.vbz

[!NOTE] OpenRouter Image Model Slugs: OpenRouter does not serve images under legacy names like dall-e-2 or dall-e-3. Set VBZ_IMAGE_MODEL to an OpenRouter slug (e.g. black-forest-labs/flux.2-klein-4b, openai/gpt-image-1-mini, black-forest-labs/flux.2-pro). Discover all 50+ models via:
curl -s https://openrouter.ai/api/v1/images/models | jq '.data[].id'

Example: Running with Local Ollama

export VBZ_BASE_LLM_URL="http://localhost:11434/v1"
export VBZ_LLM_MODEL="llama3.2-vision"
npx vbz -i cat.png

[!TIP] Production Defaults (Speed & Cost Efficiency): VibeCompress defaults out-of-the-box to high-velocity, budget-friendly models:
Compression / Vision (VBZ_LLM_MODEL): openai/gpt-4o-mini (Fractions of a cent per image)
Decompression / Image Gen (VBZ_IMAGE_MODEL): black-forest-labs/flux.2-klein-4b (Rapid, high-fidelity FLUX diffusion)
To customize models on the fly, pass -m <model> --image-model <model> or set the environment variables.

🧠 Certified Vibe Encoders (Vision Models for `VBZ_LLM_MODEL`)

Not all vision models perceive reality with the same spiritual depth. Choose your compression philosophy:

🎨 Certified Vibe Hallucinators (Generators for `VBZ_IMAGE_MODEL`)

When turning vibes back into pixels, pick your preferred hallucinatory engine:

🔬 File Format Anatomy

A .vbz file is an unapologetic, standard RFC 1952 gzip stream whose payload is UTF-8 text containing the raw scene description.

You can decompress and read it with standard terminal utilities dating back to 1993:

gzip -dc photo.vbz
# "The character, a young boy, is centered in the frame, exuding a joyful demeanor..."

💬 Frequently Asked Questions (FAQ)

Q: Is this production ready?

A: We define "production" as "it produced an output without a kernel panic." Under that definition, yes, enterprise-grade.

Q: Can I use this for medical imaging (X-rays, MRI scans)?

A: Absolutely. However, please note that any fractures or tumors may be replaced with artistic interpretations of bone density, a vintage sepia tint, or an ethereal lens flare. Consult your doctor or an art curator.

Q: Why does my decompressed dog have 6 legs?

A: The model determined that your dog was a very good boy who deserved two additional legs for optimal running efficiency. We do not question the network.

Q: How does this comply with GDPR / 'Right to Be Forgotten'?

A: It is the ultimate privacy tool. The original pixels were vaporized at the moment of compression. The output is a legally distinct, synthetic parody of what occurred.

Q: Is this lossy?

A: Lossy implies loss. Nothing was lost; reality was merely upgraded into the latent space.

🗺️ Roadmap

[x] Vision-Language text compression via openai/gpt-4o-mini
[x] Generative image decompression via black-forest-labs/flux.2-klein-4b
[x] Node.js package (npx vbz) with 0 external dependencies
[x] FFmpeg-style auto-detect CLI syntax (vbz -i <file>)
[x] Visual Evidence Locker with side-by-side Unsplash benchmarks
[ ] VibeCompress Audio (.vbza): Transcribe speech to text via Whisper, compress with gzip, decompress by asking Suno to generate a death metal cover.
[ ] VibeCompress Video (.vbzv): Summarize each 10-minute scene into a single haiku. Reconstruct with Sora. Store the entire Lord of the Rings trilogy in 14 kilobytes.
[ ] Vibe-Diff: Git diff tool that only alerts you if the spiritual aura of your company logo has diminished.

📜 License

MIT License. Run it, fork it, hallucinate it.
No pixels were harmed in the making of this format (they were simply deleted).