File-to-Video-CLI

A robust tool for archiving files as video.

Securely convert any file (PDF, ZIP, DOCX, binary, etc.) into a playable video format for cloud backup or data transfer. This tool employs advanced error correction to mathematically guarantee bit-perfect file reconstruction. Even when uploaded to platforms with harsh lossy video compression, your original data is safely preserved and easily retrievable.

Why?

Most "file to video" implementations simply map one byte to one pixel. This approach permanently destroys the file the second it is uploaded to a video platform due to H.264/VP9 compression.

By using massive Macro-Blocks and Triple Modular Redundancy (TMR) error correction, this tool ensures your file can survive the harsh compression algorithms of modern streaming sites without losing a single bit of original data.

Architecture

This project features TWO distinct operational modes tailored to different environments. Both modes utilize a strict 512-byte payload header containing Magic Bytes (FVFB), size, filename, and a SHA-256 checksum to guarantee correct extraction.

1. Lossless Mode (--mode lossless)

• Purpose: Local archive storage, peer-to-peer transfer, and native file-system hoarding.
• Pixel Mapping: 1 Byte = 1 RGB Pixel.
• Codec: Uses the lossless FFV1 codec.
• Why it works: Because no lossy compression is applied, the exact RGB values written are the exact RGB values read. This results in the smallest possible video file for a given payload, but it will not survive upload to streaming platforms like YouTube.

2. YouTube Mode (--mode youtube)

• Purpose: Cloud storage using video streaming platforms (YouTube, Vimeo, etc.).
• Pixel Mapping: 1 Bit = 8x8 Pixel Macro-Block (Black = 0, White = 1).
• Error Correction: Uses Triple Modular Redundancy (TMR). Every single bit of data is written 3 times.
• Codec: Uses the highly compressed H.264 codec.
• Why it works: Streaming platforms aggressively compress videos using lossy algorithms, blurring pixels together. By using massive 8x8 blocks, the decoder can sample the center of the block and read the luminance. Even if compression significantly degrades the edges or drops frames, the mathematical TMR majority-voting allows the exact byte stream to be perfectly reconstructed.

Prerequisites

• Node.js (v18+)

All encoding and decoding logic, including FFmpeg binaries, are self-contained using ffmpeg-static. No external FFmpeg installations are required.

CLI Usage

If you installed the package globally (npm i -g file-to-video-cli), you can use the f2v command directly. Alternatively, you can run npx file-to-video-cli.

npm i -g file-to-video-cli

Encode

Converts a target file to a video format:

# YouTube Mode (Default - Generates a highly redundant, compression-resistant MP4)
f2v encode --mode youtube --input ./my-file.zip --output ./encoded.mp4

# Lossless Mode (Generates a mathematically perfect, small MKV for local storage)
f2v encode --mode lossless --input ./my-file.zip --output ./encoded.mkv

Decode

Reads the encoded video, validates it using the integrated SHA-256 checksum, and perfectly reconstructs the original file:

# Decoding YouTube
f2v decode --mode youtube --input ./encoded.mp4 --output ./out_directory

# Decoding Lossless
f2v decode --mode lossless --input ./encoded.mkv --output ./out_directory