ebyte.org

EByte and Binary Schemas Explained in Plain Language

Tue, 20 Oct 2026 00:00:00 +0000

A text file explains itself. Open a CSV or a JSON file and you can read it, more or less. A binary file doesn’t. Open one in a hex editor and you see rows of numbers like 45 42 01 02 01 41 00, and nothing tells you where one value stops and the next begins.

That’s because the meaning lives outside the file. Some program decided that the first two bytes are a magic number, the next byte is a version, the one after that counts how many records follow, and so on. The program knows. The file doesn’t. If you want to read that file in another program, you need a copy of that knowledge.

EByte and the Story of the Byte Behind the Name

Tue, 20 Oct 2026 00:00:00 +0000

EByte is a tool that cares about bytes, every one of them, so the name starts there. The word itself is younger than most people guess, and its odd spelling was on purpose.

First came the bit. The word is short for binary digit, and Claude Shannon put it in print in 1948 in his paper on the mathematics of communication, crediting John Tukey with it. A bit is a single 0 or 1. Useful, but too small to hold a letter or a number on its own.

EByte Case Study Flipping and Editing a Real BMP Image

Tue, 20 Oct 2026 00:00:00 +0000

BMP is about as plain as image formats get, which makes it a good test of whether a schema can describe a real file down to the last byte. This case study made a tiny bitmap with Python’s Pillow library, read it with the released ebyte 0.1.1 binary, edited it four ways and broke it five ways. Every number below is what the tools printed.

The image is 5 pixels wide and 3 tall: a red stripe on top, green in the middle, blue at the bottom. Pillow saved it as a 102-byte, 24-bit BMP. That’s a 14-byte file header, a 40-byte info header and 48 bytes of pixels. Five pixels at 3 bytes each make 15 bytes a row, and BMP pads every row to a multiple of 4, so each row carries one extra zero byte.

EByte Case Study Inspecting and Editing a Real ZIP Archive

Tue, 20 Oct 2026 00:00:00 +0000

A ZIP file is a good test of whether a schema can follow a real format’s bookkeeping. Every file inside it is described twice: once in a local header just before its data, and again in a central directory near the end. A short end record then says where that directory starts. This case study built a one-file ZIP with Python’s zipfile module, read it with the released ebyte 0.1.1 binary, edited it and then fed it archives it wasn’t built for.

EByte Case Study Reading and Editing a Real WAV File

Tue, 20 Oct 2026 00:00:00 +0000

The example that ships with EByte is a made-up format. This case study uses a real one: a WAV audio file, made by Python’s standard wave module and read with the released ebyte 0.1.0 binary, downloaded from GitHub like anyone else would get it. Everything below, every number and every error, is what that binary actually printed.

The file is a tenth of a second of a 440 Hz tone, mono, 16-bit, 8,000 samples a second. That makes 1,644 bytes: a 44-byte header and 1,600 bytes of samples. The Linux archive’s checksum matched SHA256SUMS before anything ran.

EByte Launches One Schema for Reading and Writing Binary Files

Tue, 20 Oct 2026 00:00:00 +0000

EByte 0.1 is out. It’s a small Go library and a command-line tool for binary file formats, and it does one thing that sounds obvious until you’ve tried it: you describe a format once, and that single description reads files, writes them and explains them.

Here’s the usual situation it’s meant for. A device exports a file, or an old program saves one, and you need to look inside it, change a value and save it again. You end up writing a reader. Then a writer, which has to agree with the reader to the byte. Then, when a file won’t load, you open a hex editor and count bytes by hand to find out which field went wrong. That’s three descriptions of the same format, and they drift.

EByte Testing Starts From Bytes Written Down Before the Code

Tue, 20 Oct 2026 00:00:00 +0000

A codec has a sneaky way of passing its own tests. If the decoder and the encoder share a mistake, say both read a count from the wrong byte, then decoding a file and encoding it again still gives the original bytes back. The round trip looks perfect and the format is wrong. So EByte’s tests don’t start from the code. They start from bytes that were written down by hand before the decoder or encoder existed.

EByte Use Example Checking a Folder of Recordings in a Shell Script

Tue, 20 Oct 2026 00:00:00 +0000

Most of the time nobody opens a binary file by hand. Files arrive from devices, uploads and exports, and something has to decide which ones are fine before anything else reads them. EByte’s exit codes and one-line diagnostics are built for that job, so this example puts the released ebyte 0.1.1 binary in a short shell loop over a folder of audio recordings.

The folder holds seven .wav files of the kind a small sensor setup might collect overnight. Four are good recordings made with Python’s wave module, at three different sample rates, one of them stereo. The other three are the usual trouble. One upload was cut off at 5,000 bytes, one file is a text log someone saved with a .wav name, and one has four extra bytes after the audio where a recorder started writing a metadata chunk.

About

Mon, 01 Jan 0001 00:00:00 +0000

ebyte.org is the home of EByte, a small engine for binary file formats. You describe a format once, in a JSON schema: which fields come first, how wide each one is, which byte order, how many records follow. EByte then uses that one description three ways. It reads a file into JSON you can edit, it writes edited JSON back into a binary file, and it traces a file field by field, so when something doesn’t match you get the field, the byte offset and what was expected.

Command Reference

Mon, 01 Jan 0001 00:00:00 +0000

ebyte has four commands. They all use the same interpreter as the Go library, and they never guess a format: every command needs a schema. The full reference is cli.md on GitHub.

ebyte validate-schema --schema format.json
ebyte decode  --schema format.json --input file.bin  --output file.json
ebyte encode  --schema format.json --input file.json --output new.bin
ebyte inspect --schema format.json --input file.bin  --format text

Commands

validate-schema checks a schema and prints its name and SHA-256 identity as JSON. It doesn’t read any binary input.

Contact

Mon, 01 Jan 0001 00:00:00 +0000

ebyte.org would like to hear from:

Anyone trying EByte out. Which format you pointed it at, what worked, and what got in the way.
Anyone who found a bug. A file that didn’t come back byte for byte, an offset that looked wrong, an error you didn’t expect.
Anyone with a format EByte can’t describe yet. Bit fields, floats, offsets, checksums: knowing which ones people need decides what comes next.

Write to info@ebyte.org.

Download EByte

Mon, 01 Jan 0001 00:00:00 +0000

The ebyte command is one file with nothing else to install. Each archive below holds it along with a short quick start, the example format, the manual and the license files. The links always point to the latest release.

System	Download	Checked before release
Linux, x86-64	ebyte-linux-amd64.tar.gz	Run on Linux
Linux, ARM64	ebyte-linux-arm64.tar.gz	Cross-built
macOS, Apple silicon	ebyte-darwin-arm64.tar.gz	Run on macOS
macOS, Intel	ebyte-darwin-amd64.tar.gz	Cross-built
Windows, x86-64	ebyte-windows-amd64.zip	Run on Windows

Checksums are in SHA256SUMS. RELEASE-MANIFEST.json records the source commit, the Go version that built each binary and how each archive was checked. Every release is listed on GitHub.

Quick Start

Mon, 01 Jan 0001 00:00:00 +0000

EByte reads a binary file through a schema you write, turns it into JSON you can edit, and writes it back. This page goes from download to your first round trip in a few minutes, using the example that ships in every archive.

1. Get the Tool

Download the archive for your system from the download page and unpack it. On Linux or macOS:

tar -xzf ebyte-linux-amd64.tar.gz
cd ebyte
./ebyte --version

That prints the version, such as ebyte 0.1.1. The folder also holds examples/, the manual and the license files.

Schema Reference

Mon, 01 Jan 0001 00:00:00 +0000

A schema tells EByte what a binary format looks like: the fields in order, how wide each one is, and how they depend on each other. This page covers version 1 of the schema format, the one EByte 0.1 reads. The full contract, with every edge case, is schema-v1.md on GitHub.

The File

A schema is a UTF-8 JSON file with exactly four members:

{
  "schema_version": 1,
  "name": "ebyte_packet",
  "endian": "little",
  "fields": [ ... ]
}

endian is little or big, and integers inherit it unless they set their own. Names are ASCII letters, digits and underscores, up to 64 characters, starting with a letter or underscore. EByte is strict about the JSON: unknown members, duplicate members, null values and invalid Unicode are all rejected before any binary input is opened.