oham — the command line for sealed .tsb containers

Huge pictures and video, usable on the device that receives them.

• A 423-megapixel photograph ships as a 712 KB file and opens on a phone.
• 4K video at 60 fps on a phone CPU — no GPU, no codec installed, nothing to license.
• One frame of a 136 MB clip is fetched by reading 116 KB of it.

That is the same job a compression format does for you. OHAM gets there a different way — it names content instead of storing a picture stream — and that difference is what buys three things a codec cannot do:

• Any frame, any moment, for the cost of that frame. No keyframes, no prediction chain — one 12-byte index read plus one record read. Join a stream anywhere and the picture is right.
• Any size out of the one file. Level 0 is native; each level up halves the block edge while keeping the block grid identical — so a 4096×2160 frame at block 64 is a 64×34 grid at every rung, and L1 is 2048×1088, not 1080. No transcode, no second file, no pyramid.
• A window costs the window. Reading a 512×512 rectangle of an 8.8-megapixel image touches 1,537 addresses instead of ~37,000, and the pixels are identical to cropping the full decode.

Quality is a dial, as in any format — performance / standard / quality. Standard deliberately picks the coarsest form that still clears the density floor, so smooth gradients can show block edges; quality keeps more detail for more bytes. Pick the mode deliberately.

Where it loses: small pictures. A 352×240 camera frame at the finest grid costs about 1.65× its own JPEG. Cost per pixel falls as the picture grows — big is where this wins, small is the expensive case.

Separately and always: every machine computes the same bytes. Integer arithmetic end to end, no floating point anywhere, so the command line, the browser receiver and the C surface — one compiled receiver, compared byte for byte — cannot disagree. That is determinism across machines. It is a different promise from how much detail a given quality setting kept, and the two are never merged.

npm i -g oham-cli
oham doctor

doctor decodes a container carried inside the binary and checks the pixels against a digest fixed when it was built. A checksum of the executable proves the file arrived; this proves the receiver computes the right pixels on your machine. Expect OHAM_DOCTOR_OK.

Reading is local; sealing is a service

Everything below runs entirely on your machine — no network, no service, no key, no GPU, no codec. Writing runs behind the OHAM API, so the substrate itself is never distributed. Nothing you decode ever depends on the service.

Five minutes, with the hashes that prove each step

Everything here uses one 117 KB file — a single-frame container holding an 8.8-megapixel image.

curl -O https://storage.googleapis.com/framecore-etch-video/lab/still300.tsb
sha256sum still300.tsb | cut -c1-16      # 3756b663647cd78f

Look inside. Structure is verified, never assumed; a structural violation is refused with the reason.

oham info still300.tsb --json
# TSB1 v1 · EVS6 4096x2160 · 1 record · 6x4 tiles · STRUCTURE_OK

Decode it — deterministically.

oham unseal still300.tsb --tick 0 --level 0
# t0 L0 4096x2160 · sha256/16 d7b3d597b92edda3
oham unseal still300.tsb --tick 0 --level 2
# t0 L2 1024x544 · sha256/16 f3814653d1c95773

Those two hashes are the published goldens the browser receiver produces for the same content — the native and WebAssembly faces are the same compiled receiver, and gates compare them byte for byte.

Read only a window. The cost is the window's, not the image's.

oham unseal still300.tsb --tick 0 --window 1024,512,1536,1024 --png crop.png
# t0 L0 512x512 · window @1024,512 · 1537 addresses · sha256/16 8871b5d7810adb8c

1,537 addresses out of the frame's ~37,000. You never download the image; you read a rectangle of the inscription.

Seal a picture of your own — no token, no setup

Any PNG or JPEG works — the step just above wrote crop.png, so this runs straight after it:

oham seal -o mine.tsb --image crop.png

That is the whole write side for a picture. It posts to the public converter, which chooses the block size, tile count and mode from your image's own dimensions and prints what it chose:

sealed -> mine.tsb · 22916 B · sha256/16 5957a6ad5cba0022
  chosen: width 512 · height 512 · block 8 · tiles 2 · grid 64x64 · mode standard · q 2 · magbits 7

The response is kept only if it passes the container law — a JSON error body saved under a .tsb name would otherwise look like a success. Then read it back with the commands below; that round trip is the whole system in two lines.

Sealing video goes through a token-gated endpoint: oham seal -o out.tsb --api <url> -- --w 1920 --h 1088 --frames 60, with the token in $OHAM_API_TOKEN, $HF_TOKEN or ~/.config/oham/token (it never rides argv). Ask via https://involvedinvolutions.com.

Convert wire forms, reversibly. v2 deflates each record; v1 restores it. The round trip is verified before the output file exists.

oham repack still300.tsb small.tsb --v2   # payload 116,585 -> 64,313 B (55.1%); file 117,405 -> 65,061 B
oham repack small.tsb back.tsb --v1
sha256sum back.tsb | cut -c1-16           # 3756b663647cd78f — byte-identical

Serve it to the browser receiver (HTTP ranges + CORS):

oham serve . --port 8207

The whole tool, in copy-paste commands each carrying its proving hash:

oham onboard          # or: oham onboard --json, for agents and scripts

Full flag surface: COMMANDS.md, generated from the binary's own --help so it cannot drift.

Other ways to use it

| | | |---|---| | In a page, one tag | npm i oham-stream → <oham-stream clip="…/clip.tsb"> | | From an assistant | npm i -g oham-mcp → OHAM as a native tool for any MCP agent | | In the browser, nothing installed | https://storage.googleapis.com/framecore-etch-video/edge.html — 4K, 60 fps, CPU-only |

Install notes

The binary ships as a platform package (oham-cli-linux-x64 today) pulled in as an optional dependency, so you download one binary and not five. If your platform has no build yet, oham says which platform it is and what is built, rather than failing as "not found". OHAM_BIN=/path/to/oham overrides the lookup entirely.

npm i --no-optional skips the binary — oham doctor will tell you so.

Prove it yourself — offline, in one command

oham verify

Six things the file must do, each tried on your machine, just now, offline. Nothing is downloaded and nothing is read off a table:

| | | |---|---| | 1 | this machine decodes to the same pixels the build did | | 2 | reading a rectangle gives the same pixels as cropping the whole picture | | 3 | every size comes out of the one file, and they line up | | 4 | cutting a frame out changes nothing about it | | 5 | the compressed wire form converts back to the original, byte for byte | | 6 | a damaged file is refused, not half-read — swept, not a single flip |

The last one is what makes the rest mean something: a checker that only ever sees good input hasn't shown it can tell the difference. (Each line also prints its V* code, which is what --json emits and what the gates key on.)

What it cannot tell you, printed on every run rather than left to be discovered: whether the picture inside is the picture that went in. The file carries no checksum over its picture data, so damaged picture data can decode to the wrong pixels — and the original is not present to compare against either way:

NOTE what this CANNOT tell you: whether the picture inside is the picture
     that went in.
     Damaging the picture data on purpose, 24 times: 10 were caught ·
     2 changed nothing · 3 crashed the decoder ·
     9 QUIETLY GAVE THE WRONG PICTURE.

The file's structure and rules are checked; the pixels are not vouched for by anything here. That is a limit of the format as it stands, disclosed on every run.

Run the same laws against your own file:

oham verify --clip still300.tsb

If a hash differs from one printed here, run oham doctor first — it separates a broken install from a real finding, and a real finding is worth reporting.

Licence

Apache-2.0 with the Commons Clause — free to use, study, verify, modify and build on. You may not sell the software, or sell a service whose value derives substantially from it; commercial use requires a paid licence. That combination is deliberately not OSI-approved open source, and this says so rather than borrowing the Apache badge.

Paul Phillips — solo developer. OHAM / OrthoHolonic Accessible Memory · https://involvedinvolutions.com