bitsplit 2.0.1

Stop serving ready-to-download files.

Any file becomes two objects: a binary block and a short text key. The block is not a ready-to-download copy of the original; a client must obtain both parts and reconstruct the file before it can be used normally.

photo.jpg  -->  data.bin + key.txt
  1.05 MB       1.05 MB    102 B

How it works

The file is interpreted as a single large number. The top 128 bits are sliced off to become the key, the rest is saved as a binary block.

File (bytes)  -->  Number  -->  [ data: 128 bits | indices: the rest ]
                                      |                  |
                                   key file          data file

Recovery is a single bitwise operation: (data << count) | indices.

Install

pip install bitsplit

Usage

CLI

# Encode: file -> block + key
bitsplit encode photo.jpg
bitsplit encode photo.jpg -d photo.dat -k photo.key

# Decode: block + key -> file
bitsplit decode restored.jpg
bitsplit decode restored.jpg -d photo.dat -k photo.key

Python API

from bitsplit import encode, decode

# Encode
block, key = encode(open("photo.jpg", "rb").read())
# block = bytes, key = "340079...:8843264:1105424"

# Decode
content = decode(block, key)
open("restored.jpg", "wb").write(content)

Key format

340079864808174098294188674279182237768:8843264:1105424
|                                      |       |
data (128-bit number)                  count   size (bytes)

What the split does

bitsplit removes the top 128 bits from the file's numeric representation. The matching key is required for exact reconstruction through the supported API. This disrupts direct downloads and forces a downloader to reproduce the client reconstruction flow.

The block is not encrypted: it retains most of the source bytes and may reveal content or structure. The split is a delivery obstacle, not a confidentiality boundary.

Use cases

• Public media delivery — serve blocks instead of ready JPEG, MP4, or audio files
• Video reconstruction — make downloaders collect ranges or chunks and rebuild the media container
• Anti-hotlinking — a copied block URL does not point to the original ready-to-use file
• Scraping resistance — generic downloaders must reproduce the site's reconstruction protocol
• Browser assembly — restore content on demand in JavaScript or a Service Worker
• Controlled delivery flows — combine blocks with sessions, short-lived URLs, or access checks

[!CAUTION] bitsplit is not encryption or DRM. A determined downloader who can observe the reconstruction flow can automate it. The goal is to stop serving a finished file at one public URL and raise the effort required for casual downloading, hotlinking, and generic scraping. Use established encryption when confidentiality is required.

Performance

bitsplit uses two bitwise operations with no loops, no block processing, and no rounds — just a single shift and OR. Benchmarked on Apple M2 (8 GB RAM):

Encode

Decode

Peak memory

Bold = fastest in row. Streaming I/O keeps memory flat at ~20 MB regardless of file size.

All files restored with identical SHA-256 checksums. Pure Python, zero dependencies.

Features

• Zero dependencies — pure Python, standard library only
• Any file — jpg, mp4, zip, exe, anything with bytes
• Output size = input size — no overhead
• Instant — two bitwise operations, no loops
• Key fits in one line — memorize it, write it down, send it in a message
• Custom paths — specify any output/input file names

Requirements

Python 3.11+