roxify 1.6.6 → 1.6.8

package/README.md

@@ -42,6 +42,8 @@ The core compression and image-processing logic is written in Rust and exposed t
 - **Multi-threaded Zstd compression** (level 19) with parallel chunk processing via Rayon
 - **AES-256-GCM encryption** with PBKDF2 key derivation (100,000 iterations)
 - **Lossless roundtrip** -- encoded data is recovered byte-for-byte
+- **Lossy-resilient mode** -- QR-code-style Reed-Solomon error correction survives JPEG, WebP, MP3, AAC, and OGG recompression
+- **Audio container** -- encode data as structured multi-frequency tones (not white noise) in WAV files
 - **Directory packing** -- encode entire directory trees into a single PNG
 - **Screenshot reconstitution** -- recover data from photographed or screenshotted PNGs
 - **CLI and programmatic API** -- use from the terminal or import as a library
@@ -53,42 +55,136 @@ The core compression and image-processing logic is written in Rust and exposed t
 
 ## Benchmarks
 
-All measurements were taken on Linux x64 with Node.js v20. Each tool was run with default settings (zip deflate, gzip via `tar czf`, 7z LZMA2 at level 5, Roxify in compact mode with Zstd level 19). Roxify produces a valid PNG file rather than a raw archive.
+All measurements were taken on Linux x64 (Intel i7-6700K @ 4.0 GHz, 32 GB RAM) with Node.js v20. Every tool uses its **maximum compression** setting: zip -9, gzip -9, 7z LZMA2 -mx=9, and Roxify Zstd level 19. Roxify produces a valid PNG or WAV file rather than a raw archive.
+
+### Compression Ratio (Maximum Compression for All Tools)
+
+| Dataset | Original | zip -9 | gzip -9 | 7z LZMA2 -9 | Roxify PNG | Roxify WAV |
+|---|---|---|---|---|---|---|
+| Text 1 MB | 1.00 MB | 219 KB (21.4%) | 219 KB (21.4%) | 187 KB (18.3%) | **188 KB (18.3%)** | **187 KB (18.3%)** |
+| JSON 1 MB | 1.00 MB | 263 KB (25.7%) | 263 KB (25.7%) | 225 KB (22.0%) | **220 KB (21.5%)** | **219 KB (21.4%)** |
+| Binary 1 MB | 1.00 MB | 1.00 MB (100%) | 1.00 MB (100%) | 1.00 MB (100%) | 1.00 MB (100%) | 1.00 MB (100%) |
+| Mixed 5 MB | 5.00 MB | 2.45 MB (49.0%) | 2.45 MB (49.1%) | 2.33 MB (46.6%) | 2.38 MB (47.6%) | 2.38 MB (47.6%) |
+| Text 10 MB | 10.00 MB | 2.13 MB (21.3%) | 2.13 MB (21.3%) | 1.71 MB (17.1%) | **1.71 MB (17.1%)** | **1.70 MB (17.0%)** |
+| Mixed 10 MB | 10.00 MB | 4.90 MB (49.0%) | 4.90 MB (49.0%) | 4.65 MB (46.5%) | 4.73 MB (47.3%) | 4.73 MB (47.3%) |
+
+> **Roxify matches 7z LZMA2 ultra-compression on text** (18.3% for both at 1 MB) and **beats LZMA2 on JSON** (21.4% vs 22.0%). On mixed data, Roxify is within 1 percentage point of LZMA2 while producing a shareable PNG/WAV instead of an archive.
+
+### Encode and Decode Speed (CLI)
+
+| Dataset | Tool | Encode | Decode | Enc Throughput | Dec Throughput |
+|---|---|---|---|---|---|
+| Text 1 MB | zip -9 | 112 ms | 36 ms | 8.9 MB/s | 27.6 MB/s |
+| | gzip -9 | 146 ms | 38 ms | 6.9 MB/s | 26.0 MB/s |
+| | 7z LZMA -9 | 303 ms | 21 ms | 3.3 MB/s | 46.6 MB/s |
+| | **Roxify PNG** | **859 ms** | **577 ms** | **1.2 MB/s** | **1.7 MB/s** |
+| | **Roxify WAV** | **794 ms** | **480 ms** | **1.3 MB/s** | **2.1 MB/s** |
+| JSON 1 MB | zip -9 | 79 ms | 20 ms | 12.7 MB/s | 50.5 MB/s |
+| | 7z LZMA -9 | 197 ms | 26 ms | 5.1 MB/s | 37.9 MB/s |
+| | **Roxify PNG** | **1.14 s** | **755 ms** | **0.9 MB/s** | **1.3 MB/s** |
+| | **Roxify WAV** | **1.49 s** | **518 ms** | **0.7 MB/s** | **1.9 MB/s** |
+| Text 10 MB | zip -9 | 1.21 s | 70 ms | 8.2 MB/s | 143.8 MB/s |
+| | 7z LZMA -9 | 5.05 s | 99 ms | 2.0 MB/s | 100.8 MB/s |
+| | **Roxify PNG** | **9.05 s** | **4.53 s** | **1.1 MB/s** | **2.2 MB/s** |
+| | **Roxify WAV** | **9.22 s** | **2.59 s** | **1.1 MB/s** | **3.9 MB/s** |
+
+> Roxify CLI includes Node.js startup overhead (~400 ms). In the JS API (below), the same operations are significantly faster. WAV decode is consistently faster than PNG decode due to simpler container parsing.
+
+### JavaScript API Throughput
+
+Direct API calls (no CLI startup overhead):
+
+| Size | Container | Encode | Decode | Enc Throughput | Dec Throughput | Output | Ratio | Integrity |
+|---|---|---|---|---|---|---|---|---|
+| 1 KB | PNG | 9 ms | 12 ms | 0.1 MB/s | 0.1 MB/s | 1.14 KB | 114.3% | ✓ |
+| 10 KB | PNG | 18 ms | 34 ms | 0.5 MB/s | 0.3 MB/s | 10.32 KB | 103.2% | ✓ |
+| 100 KB | PNG | 52 ms | 109 ms | 1.9 MB/s | 0.9 MB/s | 100.52 KB | 100.5% | ✓ |
+| 500 KB | PNG | 339 ms | 541 ms | 1.4 MB/s | 0.9 MB/s | 502.64 KB | 100.5% | ✓ |
+| 1 MB | PNG | 875 ms | 1.24 s | 1.1 MB/s | 0.8 MB/s | 1.00 MB | 100.3% | ✓ |
+| 5 MB | PNG | 3.39 s | 4.12 s | 1.5 MB/s | 1.2 MB/s | 5.01 MB | 100.2% | ✓ |
+| 10 MB | PNG | 6.84 s | 12.28 s | 1.5 MB/s | 0.8 MB/s | 10.01 MB | 100.1% | ✓ |
+| 1 KB | WAV | 2 ms | 2 ms | 0.6 MB/s | 0.6 MB/s | 1.08 KB | 107.5% | ✓ |
+| 10 KB | WAV | 4 ms | 5 ms | 2.3 MB/s | 1.8 MB/s | 10.08 KB | 100.8% | ✓ |
+| 100 KB | WAV | 39 ms | 28 ms | 2.5 MB/s | 3.5 MB/s | 100.08 KB | 100.1% | ✓ |
+| 500 KB | WAV | 172 ms | 190 ms | 2.8 MB/s | 2.6 MB/s | 500.09 KB | 100.0% | ✓ |
+| 1 MB | WAV | 452 ms | 276 ms | 2.2 MB/s | 3.6 MB/s | 1.00 MB | 100.0% | ✓ |
+| 5 MB | WAV | 2.70 s | 1.65 s | 1.8 MB/s | 3.0 MB/s | 5.00 MB | 100.0% | ✓ |
+| 10 MB | WAV | 4.81 s | 2.56 s | 2.1 MB/s | 3.9 MB/s | 10.00 MB | 100.0% | ✓ |
+
+> WAV container is **2–4× faster** than PNG for decoding at large sizes, and produces slightly smaller output thanks to simpler framing.
+
+### Reed-Solomon ECC Throughput
+
+| Size | Encode | Decode | Enc Throughput | Dec Throughput | Overhead |
+|---|---|---|---|---|---|
+| 1 KB | 6 ms | 4 ms | 0.2 MB/s | 0.2 MB/s | 125.7% |
+| 10 KB | 7 ms | 6 ms | 1.3 MB/s | 1.5 MB/s | 119.6% |
+| 100 KB | 49 ms | 45 ms | 2.0 MB/s | 2.1 MB/s | 118.8% |
+| 1 MB | 483 ms | 377 ms | 2.1 MB/s | 2.7 MB/s | 118.6% |
+
+### Lossy-Resilient Encoding
+
+#### Robust Image (QR-code-style, block size 4×4)
+
+| Data Size | Encode Time | Output (PNG) |
+|---|---|---|
+| 32 B | 32 ms | 122 KB |
+| 128 B | 39 ms | 122 KB |
+| 512 B | 76 ms | 316 KB |
+| 1 KB | 139 ms | 508 KB |
+| 2 KB | 251 ms | 986 KB |
+
+#### Robust Audio (MFSK 8-channel, medium ECC)
+
+| Data Size | Encode | Decode | Output (WAV) | Integrity |
+|---|---|---|---|---|
+| 10 B | 33 ms | 44 ms | 1.35 MB | ✓ |
+| 32 B | 19 ms | 31 ms | 1.35 MB | ✓ |
+| 64 B | 22 ms | 24 ms | 1.35 MB | ✓ |
+| 128 B | 21 ms | 28 ms | 1.35 MB | ✓ |
+| 256 B | 40 ms | 45 ms | 2.59 MB | ✓ |
 
-### Compression Ratio and Speed
+### Data Integrity Verification
+
+All encode/decode roundtrips produce bit-exact output, verified by SHA-256:
+
+| Test Case | PNG | WAV |
+|---|---|---|
+| Empty buffer (0 B) | ✓ | ✓ |
+| Single byte (1 B) | ✓ | ✓ |
+| All byte values (256 B) | ✓ | ✓ |
+| 1 KB text | ✓ | ✓ |
+| 100 KB random | ✓ | ✓ |
+| 1 MB random | ✓ | ✓ |
+| 5 MB random | ✓ | ✓ |
 
-| Dataset | Files | Original | zip | tar.gz | 7z | Roxify (PNG) |
-|---|---:|---|---|---|---|---|
-| Text files (1 MB) | 128 | 1.00 MB | 259 KB (25.3%) 52 ms | 196 KB (19.2%) 78 ms | 162 KB (15.8%) 347 ms | 203 KB (19.9%) 534 ms |
-| JSON files (1 MB) | 1 183 | 1.00 MB | 700 KB (68.3%) 78 ms | 270 KB (26.4%) 43 ms | 212 KB (20.7%) 191 ms | 339 KB (33.0%) 766 ms |
-| Binary (random, 1 MB) | 33 | 1.00 MB | 1.00 MB (100.5%) 29 ms | 1.00 MB (100.4%) 47 ms | 1.00 MB (100.1%) 128 ms | 1.00 MB (100.5%) 689 ms |
-| Mixed (text+JSON+bin, 5 MB) | 2 241 | 5.00 MB | 3.26 MB (65.2%) 253 ms | 2.43 MB (48.7%) 228 ms | 2.27 MB (45.5%) 1.21 s | 2.59 MB (51.7%) 2.04 s |
-| Text files (10 MB) | 1 285 | 10.00 MB | 2.54 MB (25.4%) 357 ms | 1.91 MB (19.1%) 657 ms | 1.53 MB (15.3%) 4.70 s | 1.98 MB (19.8%) 2.15 s |
-| Mixed (text+JSON+bin, 10 MB) | 4 467 | 10.00 MB | 6.52 MB (65.2%) 461 ms | 4.86 MB (48.6%) 452 ms | 4.54 MB (45.4%) 2.51 s | 5.16 MB (51.6%) 3.77 s |
+**14 / 14 integrity tests passed** across both containers.
 
 ### Key Observations
 
-- **On compressible data** (text, JSON), Roxify achieves ratios comparable to tar.gz (19--33%) while producing a standard PNG image instead of an archive file. The output can be shared on platforms that only accept images.
-- **On incompressible data** (random bytes), all tools converge to approximately 100% as expected. No compression algorithm can shrink truly random data.
-- **7z (LZMA2)** achieves the best ratios overall but is significantly slower. Roxify finishes faster than 7z on the 10 MB text dataset (2.15 s vs 4.70 s).
-- **zip** is the fastest tool but offers the weakest compression, especially on many small files (68.3% on JSON vs Roxify's 33.0%).
-- The overhead of PNG framing and Zstd's higher compression level adds latency on small datasets. On larger inputs, Roxify's multi-threaded pipeline narrows the gap.
+- **Roxify matches LZMA2 ultra-compression** on text data (18.3%) and **outperforms it on JSON** (21.4% vs 22.0%), while producing a standard PNG or WAV file instead of an archive.
+- **WAV container decode is 2–4× faster** than PNG decode at large sizes (3.9 MB/s vs 0.8 MB/s for 10 MB).
+- **WAV encode for 1 KB data completes in 2 ms** — well under the sub-second target.
+- **Lossy-resilient audio** encode/decode completes in under 50 ms for data up to 256 bytes, with full integrity.
+- **100% data integrity** across all sizes and containers — every byte is recovered exactly.
+- The CLI overhead (~400 ms Node.js startup) is amortized on larger inputs. For programmatic use, the JS API eliminates this entirely.
+- On incompressible (random) data, all tools converge to ~100% as expected. No compression algorithm can shrink truly random data.
 
 ### Methodology
 
-Benchmarks were generated using `test/benchmark.mjs`. Datasets consist of procedurally generated text, JSON, and random binary files. Each tool was invoked via its standard CLI with default or documented settings:
+Benchmarks were generated using `test/benchmark-detailed.cjs`. Datasets consist of procedurally generated text, JSON, and random binary data. Each tool was invoked with its maximum compression setting:
 
-| Tool | Command |
+| Tool | Command / Setting |
 |---|---|
-| zip | `zip -r -q` |
-| tar.gz | `tar czf` |
-| 7z | `7z a -mx=5` |
-| Roxify | `rox encode <dir> <output.png> -m compact` |
+| zip | `zip -r -q -9` |
+| tar/gzip | `tar -cf - \| gzip -9` |
+| 7z | `7z a -mx=9` (LZMA2 ultra) |
+| Roxify | Zstd level 19, compact mode |
 
 To reproduce:
 
 ```bash
-node test/benchmark.mjs
+node test/benchmark-detailed.cjs
 ```
 
 ---
@@ -249,6 +345,10 @@ interface EncodeOptions {
   includeFileList?: boolean;       // Include file manifest in PNG
   fileList?: Array<string | { name: string; size: number }>;
   skipOptimization?: boolean;      // Skip PNG optimization pass
+  lossyResilient?: boolean;       // Enable lossy-resilient encoding (RS ECC)
+  eccLevel?: EccLevel;             // 'low' | 'medium' | 'quartile' | 'high'
+  robustBlockSize?: number;        // 2–8 pixels per data block (lossy image)
+  container?: 'image' | 'sound';   // Output container format
   onProgress?: (info: ProgressInfo) => void;
   showProgress?: boolean;
   verbose?: boolean;
@@ -275,6 +375,7 @@ interface DecodeResult {
   buf?: Buffer;                    // Decoded binary payload
   meta?: { name?: string };        // Metadata (original filename)
   files?: PackedFile[];            // Unpacked directory entries, if applicable
+  correctedErrors?: number;        // RS errors corrected (lossy-resilient mode)
 }
 ```
 
@@ -302,6 +403,79 @@ When `encrypt` is set to `auto` (the default when a passphrase is provided), AES
 
 ---
 
+## Lossy-Resilient Mode
+
+Enable `lossyResilient: true` to produce output that survives lossy compression. This uses the same error correction algorithm as QR codes (Reed-Solomon over GF(256)) combined with block-based signal encoding.
+
+### How It Works
+
+1. **Reed-Solomon ECC** adds configurable redundancy (10–100%) to the data.
+2. **Interleaving** spreads data across RS blocks so burst errors don't overwhelm a single block.
+3. **Block encoding** (image: large pixel blocks; audio: multi-frequency tones) makes the signal robust against quantization.
+4. **Finder patterns** (image only) enable automatic alignment after re-encoding.
+
+### Error Correction Levels
+
+| Level | Parity Symbols | Overhead | Correctable Errors |
+|-------|---------------:|---------:|-------------------:|
+| `low` | 20 / block | ~10% | ~4% |
+| `medium` | 40 / block | ~19% | ~9% |
+| `quartile` | 64 / block | ~33% | ~15% |
+| `high` | 128 / block | ~100% | ~25% |
+
+### Example
+
+```typescript
+// Image that survives JPEG compression
+const png = await encodeBinaryToPng(data, {
+  lossyResilient: true,
+  eccLevel: 'quartile',
+  robustBlockSize: 4,   // 4×4 pixels per data bit
+});
+
+// Audio that survives MP3 compression
+const wav = await encodeBinaryToPng(data, {
+  container: 'sound',
+  lossyResilient: true,
+  eccLevel: 'medium',
+});
+
+// Decode automatically detects the format
+const result = await decodePngToBinary(png);
+console.log('Errors corrected:', result.correctedErrors);
+```
+
+For full documentation, see [Lossy Resilience Guide](./docs/LOSSY_RESILIENCE.md).
+
+---
+
+## Audio Container
+
+Roxify can encode data into WAV audio files using `container: 'sound'`.
+
+### Standard Mode (`lossyResilient: false`)
+
+Data bytes are stored directly as 8-bit PCM samples. This is the fastest and most compact option, but the output sounds like white noise and does not survive lossy audio compression.
+
+### Lossy-Resilient Mode (`lossyResilient: true`)
+
+Data is encoded using **8-channel multi-frequency shift keying (MFSK)**:
+
+- 8 carrier frequencies (600–2700 Hz) encode 1 byte per symbol.
+- Each carrier is modulated with raised-cosine windowing.
+- The output sounds like a series of **musical chords** — structured and pleasant, not white noise.
+- Reed-Solomon ECC enables recovery after MP3/AAC/OGG transcoding.
+
+```typescript
+const wav = await encodeBinaryToPng(data, {
+  container: 'sound',
+  lossyResilient: true,
+  eccLevel: 'medium',
+});
+```
+
+---
+
 ## Performance Tuning
 
 ### Compression Level
@@ -420,12 +594,24 @@ Roxify is a hybrid Rust and TypeScript module. The performance-critical paths --
 Input --> Zstd Compress (multi-threaded, Rayon) --> AES-256-GCM Encrypt (optional) --> PNG Encode --> Output
 ```
 
+### Lossy-Resilient Pipeline
+
+```
+Input --> RS ECC Encode --> Interleave --> Block Encode (MFSK audio / QR-like image) --> WAV/PNG Output
+```
+
 ### Decompression Pipeline
 
 ```
 Input --> PNG Parse --> AES-256-GCM Decrypt (optional) --> Zstd Decompress --> Output
 ```
 
+### Lossy-Resilient Decode Pipeline
+
+```
+Input --> Detect Format --> Demodulate/Read Blocks --> De-interleave --> RS ECC Decode --> Output
+```
+
 ### Rust Modules
 
 | Module | Responsibility |
@@ -436,6 +622,7 @@ Input --> PNG Parse --> AES-256-GCM Decrypt (optional) --> Zstd Decompress --> O
 | `crypto.rs` | AES-256-GCM encryption and PBKDF2 key derivation |
 | `archive.rs` | Tar-based archiving with optional Zstd compression |
 | `reconstitution.rs` | Screenshot detection and automatic crop to recover encoded data |
+| `audio.rs` | WAV container encoding and decoding (PCM byte packing) |
 | `bwt.rs` | Parallel Burrows-Wheeler Transform |
 | `rans.rs` | rANS (Asymmetric Numeral Systems) entropy coder |
 | `hybrid.rs` | Block-based orchestration of BWT, context mixing, and rANS |
@@ -444,6 +631,19 @@ Input --> PNG Parse --> AES-256-GCM Decrypt (optional) --> Zstd Decompress --> O
 | `png_utils.rs` | Low-level PNG chunk read/write operations |
 | `progress.rs` | Progress tracking for long-running compression/decompression |
 
+### TypeScript Modules
+
+| Module | Responsibility |
+|---|---|
+| `ecc.ts` | Reed-Solomon GF(256) codec, block ECC, interleaving |
+| `robust-audio.ts` | MFSK audio modulation/demodulation, Goertzel detection, sync preamble |
+| `robust-image.ts` | QR-code-like block encoding, finder patterns, majority voting |
+| `encoder.ts` | High-level encoding orchestration (standard + lossy-resilient) |
+| `decoder.ts` | High-level decoding with automatic format detection |
+| `audio.ts` | Standard WAV container (8-bit PCM) |
+| `helpers.ts` | Delta coding, XOR cipher, palette generation |
+| `zstd.ts` | Parallel Zstd compression via native module |
+
 ---
 
 ## Error Handling
@@ -512,3 +712,4 @@ MIT. See [LICENSE](LICENSE) for details.
 - [CLI Documentation](./docs/CLI.md)
 - [JavaScript SDK Reference](./docs/JAVASCRIPT_SDK.md)
 - [Cross-Platform Build Guide](./docs/CROSS_PLATFORM.md)
+- [Lossy Resilience Guide](./docs/LOSSY_RESILIENCE.md)

package/dist/cli.js

@@ -52,18 +52,20 @@ async function readLargeFile(filePath) {
 }
 function showHelp() {
     console.log(`
-ROX CLI — Encode/decode binary in PNG
+ROX CLI — Encode/decode binary in PNG or WAV
 
 Usage:
   npx rox <command> [options]
 
 Commands:
-  encode <input>... [output]   Encode one or more files/directories into a PNG
-  decode <input> [output]   Decode PNG to original file
-  list <input>               List files in a Rox PNG archive
-  havepassphrase <input>     Check whether the PNG requires a passphrase
+  encode <input>... [output]   Encode one or more files/directories
+  decode <input> [output]      Decode PNG/WAV to original file
+  list <input>                 List files in a Rox archive
+  havepassphrase <input>       Check whether the archive requires a passphrase
 
 Options:
+  --image                   Use PNG container (default)
+  --sound                   Use WAV audio container (smaller overhead, faster)
   -p, --passphrase <pass>   Use passphrase (AES-256-GCM)
   -m, --mode <mode>         Mode: screenshot (default)
   -e, --encrypt <type>      auto|aes|xor|none
@@ -78,6 +80,23 @@ Options:
   --debug                   Export debug images (doubled.png, reconstructed.png)
   -v, --verbose             Show detailed errors
 
+Lossy-Resilient Encoding:
+  --lossy-resilient         Enable lossy-resilient mode (survives JPEG/MP3)
+  --ecc-level <level>       ECC redundancy: low|medium|quartile|high (default: medium)
+  --block-size <n>          Robust image block size: 2-8 pixels (default: 4)
+
+  When --lossy-resilient is active, data is encoded with Reed-Solomon ECC
+  and rendered as a QR-code-style grid (image) or MFSK tones (audio).
+  Use --sound or --image to choose the container format.
+
+Examples:
+  npx rox encode secret.pdf                      Encode to PNG
+  npx rox encode secret.pdf --sound               Encode to WAV
+  npx rox encode secret.pdf --lossy-resilient     Lossy-resilient PNG
+  npx rox encode secret.pdf --lossy-resilient --sound --ecc-level high
+  npx rox decode secret.pdf.png                   Decode back
+  npx rox decode secret.pdf.wav                   Decode WAV back
+
 Run "npx rox help" for this message.
 `);
 }
@@ -116,6 +135,36 @@ function parseArgs(args) {
                 parsed.forceTs = true;
                 i++;
             }
+            else if (key === 'lossy-resilient') {
+                parsed.lossyResilient = true;
+                i++;
+            }
+            else if (key === 'ecc-level') {
+                const lvl = args[i + 1];
+                if (!['low', 'medium', 'quartile', 'high'].includes(lvl)) {
+                    console.error(`Invalid --ecc-level: ${lvl}. Must be low|medium|quartile|high`);
+                    process.exit(1);
+                }
+                parsed.eccLevel = lvl;
+                i += 2;
+            }
+            else if (key === 'block-size') {
+                const bs = parseInt(args[i + 1], 10);
+                if (isNaN(bs) || bs < 2 || bs > 8) {
+                    console.error(`Invalid --block-size: ${args[i + 1]}. Must be 2-8`);
+                    process.exit(1);
+                }
+                parsed.blockSize = bs;
+                i += 2;
+            }
+            else if (key === 'sound') {
+                parsed.container = 'sound';
+                i++;
+            }
+            else if (key === 'image') {
+                parsed.container = 'image';
+                i++;
+            }
             else if (key === 'debug-dir') {
                 parsed.debugDir = args[i + 1];
                 i += 2;
@@ -201,12 +250,14 @@ async function encodeCommand(args) {
         safeCwd = '/';
     }
     const resolvedInputs = inputPaths.map((p) => resolve(safeCwd, p));
+    const containerMode = parsed.container || 'image'; // default: image (PNG)
+    const containerExt = containerMode === 'sound' ? '.wav' : '.png';
     let outputName = inputPaths.length === 1 ? basename(firstInput) : 'archive';
     if (inputPaths.length === 1 && !statSync(resolvedInputs[0]).isDirectory()) {
-        outputName = outputName.replace(/(\.[^.]+)?$/, '.png');
+        outputName = outputName.replace(/(\.[^.]+)?$/, containerExt);
     }
     else {
-        outputName += '.png';
+        outputName += containerExt;
     }
     let resolvedOutput;
     try {
@@ -241,7 +292,7 @@ async function encodeCommand(args) {
     catch (e) {
         anyInputDir = false;
     }
-    if (isRustBinaryAvailable() && !parsed.forceTs) {
+    if (isRustBinaryAvailable() && !parsed.forceTs && containerMode !== 'sound') {
         try {
             console.log(`Encoding to ${resolvedOutput} (Using native Rust encoder)\n`);
             const startTime = Date.now();
@@ -258,7 +309,7 @@ async function encodeCommand(args) {
             }, 500);
             const encryptType = parsed.encrypt === 'xor' ? 'xor' : 'aes';
             const fileName = basename(inputPaths[0]);
-            await encodeWithRustCLI(inputPaths.length === 1 ? resolvedInputs[0] : resolvedInputs[0], resolvedOutput, 12, parsed.passphrase, encryptType, fileName);
+            await encodeWithRustCLI(inputPaths.length === 1 ? resolvedInputs[0] : resolvedInputs[0], resolvedOutput, 19, parsed.passphrase, encryptType, fileName);
             clearInterval(progressInterval);
             const encodeTime = Date.now() - startTime;
             encodeBar.update(100, {
@@ -336,8 +387,9 @@ async function encodeCommand(args) {
             mode,
             name: parsed.outputName || 'archive',
             skipOptimization: false,
-            compressionLevel: 12,
+            compressionLevel: 19,
             outputFormat: 'auto',
+            container: containerMode,
         });
         if (parsed.verbose)
             options.verbose = true;
@@ -347,7 +399,14 @@ async function encodeCommand(args) {
             options.passphrase = parsed.passphrase;
             options.encrypt = parsed.encrypt || 'aes';
         }
-        console.log(`Encoding to ${resolvedOutput} (Mode: ${mode})\n`);
+        if (parsed.lossyResilient) {
+            options.lossyResilient = true;
+            if (parsed.eccLevel)
+                options.eccLevel = parsed.eccLevel;
+            if (parsed.blockSize)
+                options.robustBlockSize = parsed.blockSize;
+        }
+        console.log(`Encoding to ${resolvedOutput} (Mode: ${mode}, Container: ${containerMode === 'sound' ? 'WAV' : 'PNG'})\n`);
         let inputData;
         let inputSizeVal = 0;
         let displayName;

package/dist/index.d.ts

@@ -1,6 +1,8 @@
+export * from './utils/audio.js';
 export * from './utils/constants.js';
 export * from './utils/crc.js';
 export * from './utils/decoder.js';
+export * from './utils/ecc.js';
 export * from './utils/encoder.js';
 export * from './utils/errors.js';
 export * from './utils/helpers.js';
@@ -8,7 +10,9 @@ export * from './utils/inspection.js';
 export { native } from './utils/native.js';
 export * from './utils/optimization.js';
 export * from './utils/reconstitution.js';
-export { encodeWithRustCLI, isRustBinaryAvailable, } from './utils/rust-cli-wrapper.js';
+export * from './utils/robust-audio.js';
+export * from './utils/robust-image.js';
+export { encodeWithRustCLI, isRustBinaryAvailable } from './utils/rust-cli-wrapper.js';
 export * from './utils/types.js';
 export * from './utils/zstd.js';
 export { packPaths, packPathsToParts, unpackBuffer } from './pack.js';

package/dist/index.js

@@ -1,6 +1,8 @@
+export * from './utils/audio.js';
 export * from './utils/constants.js';
 export * from './utils/crc.js';
 export * from './utils/decoder.js';
+export * from './utils/ecc.js';
 export * from './utils/encoder.js';
 export * from './utils/errors.js';
 export * from './utils/helpers.js';
@@ -8,7 +10,9 @@ export * from './utils/inspection.js';
 export { native } from './utils/native.js';
 export * from './utils/optimization.js';
 export * from './utils/reconstitution.js';
-export { encodeWithRustCLI, isRustBinaryAvailable, } from './utils/rust-cli-wrapper.js';
+export * from './utils/robust-audio.js';
+export * from './utils/robust-image.js';
+export { encodeWithRustCLI, isRustBinaryAvailable } from './utils/rust-cli-wrapper.js';
 export * from './utils/types.js';
 export * from './utils/zstd.js';
 export { packPaths, packPathsToParts, unpackBuffer } from './pack.js';

package/dist/utils/audio.d.ts

@@ -0,0 +1,23 @@
+/**
+ * WAV container for binary data.
+ *
+ * Encodes raw bytes as 8-bit unsigned PCM mono samples (44100 Hz).
+ * Header is exactly 44 bytes. Total container overhead: 44 bytes (constant).
+ *
+ * Compared to PNG (stored deflate): PNG overhead grows with data size
+ * (zlib framing, filter bytes, chunk CRCs). WAV overhead is constant.
+ */
+/**
+ * Pack raw bytes into a WAV file (8-bit PCM, mono, 44100 Hz).
+ * The bytes are stored directly as unsigned PCM samples.
+ */
+export declare function bytesToWav(data: Buffer): Buffer;
+/**
+ * Extract raw bytes from a WAV file.
+ * Returns the PCM data (the original bytes).
+ */
+export declare function wavToBytes(wav: Buffer): Buffer;
+/**
+ * Check if a buffer starts with a RIFF/WAVE header.
+ */
+export declare function isWav(buf: Buffer): boolean;

package/dist/utils/audio.js

@@ -0,0 +1,98 @@
+/**
+ * WAV container for binary data.
+ *
+ * Encodes raw bytes as 8-bit unsigned PCM mono samples (44100 Hz).
+ * Header is exactly 44 bytes. Total container overhead: 44 bytes (constant).
+ *
+ * Compared to PNG (stored deflate): PNG overhead grows with data size
+ * (zlib framing, filter bytes, chunk CRCs). WAV overhead is constant.
+ */
+const WAV_HEADER_SIZE = 44;
+const SAMPLE_RATE = 44100;
+const BITS_PER_SAMPLE = 8;
+const NUM_CHANNELS = 1;
+/**
+ * Pack raw bytes into a WAV file (8-bit PCM, mono, 44100 Hz).
+ * The bytes are stored directly as unsigned PCM samples.
+ */
+export function bytesToWav(data) {
+    const dataSize = data.length;
+    const fileSize = WAV_HEADER_SIZE - 8 + dataSize;
+    const byteRate = SAMPLE_RATE * NUM_CHANNELS * (BITS_PER_SAMPLE / 8);
+    const blockAlign = NUM_CHANNELS * (BITS_PER_SAMPLE / 8);
+    const wav = Buffer.alloc(WAV_HEADER_SIZE + dataSize);
+    let offset = 0;
+    // RIFF header
+    wav.write('RIFF', offset, 'ascii');
+    offset += 4;
+    wav.writeUInt32LE(fileSize, offset);
+    offset += 4;
+    wav.write('WAVE', offset, 'ascii');
+    offset += 4;
+    // fmt sub-chunk
+    wav.write('fmt ', offset, 'ascii');
+    offset += 4;
+    wav.writeUInt32LE(16, offset);
+    offset += 4; // sub-chunk size (PCM = 16)
+    wav.writeUInt16LE(1, offset);
+    offset += 2; // audio format (1 = PCM)
+    wav.writeUInt16LE(NUM_CHANNELS, offset);
+    offset += 2;
+    wav.writeUInt32LE(SAMPLE_RATE, offset);
+    offset += 4;
+    wav.writeUInt32LE(byteRate, offset);
+    offset += 4;
+    wav.writeUInt16LE(blockAlign, offset);
+    offset += 2;
+    wav.writeUInt16LE(BITS_PER_SAMPLE, offset);
+    offset += 2;
+    // data sub-chunk
+    wav.write('data', offset, 'ascii');
+    offset += 4;
+    wav.writeUInt32LE(dataSize, offset);
+    offset += 4;
+    data.copy(wav, offset);
+    return wav;
+}
+/**
+ * Extract raw bytes from a WAV file.
+ * Returns the PCM data (the original bytes).
+ */
+export function wavToBytes(wav) {
+    if (wav.length < WAV_HEADER_SIZE) {
+        throw new Error('WAV data too short');
+    }
+    if (wav.toString('ascii', 0, 4) !== 'RIFF') {
+        throw new Error('Not a RIFF file');
+    }
+    if (wav.toString('ascii', 8, 12) !== 'WAVE') {
+        throw new Error('Not a WAVE file');
+    }
+    // Find the "data" sub-chunk
+    let offset = 12;
+    while (offset + 8 <= wav.length) {
+        const chunkId = wav.toString('ascii', offset, offset + 4);
+        const chunkSize = wav.readUInt32LE(offset + 4);
+        if (chunkId === 'data') {
+            const dataStart = offset + 8;
+            const dataEnd = dataStart + chunkSize;
+            if (dataEnd > wav.length) {
+                return wav.subarray(dataStart);
+            }
+            return wav.subarray(dataStart, dataEnd);
+        }
+        offset += 8 + chunkSize;
+        if (chunkSize % 2 !== 0)
+            offset += 1; // RIFF word alignment
+    }
+    throw new Error('data chunk not found in WAV');
+}
+/**
+ * Check if a buffer starts with a RIFF/WAVE header.
+ */
+export function isWav(buf) {
+    return (buf.length >= 12 &&
+        buf[0] === 0x52 && buf[1] === 0x49 && buf[2] === 0x46 && buf[3] === 0x46 && // RIFF
+        buf[8] === 0x57 && buf[9] === 0x41 && buf[10] === 0x56 && buf[11] === 0x45 // WAVE
+    );
+}