CKey documentation
CKey is an open optical code: a printed or on-screen symbol that carries bytes, like a QR code, with an open specification and a reference core anyone can build on. These pages cover reading one, making one, and building it into your own software.
CKey is experimental. It is a pre-1.0 research project. Formats can still change between builds, decoding is tested on rendered and simulated camera frames but not yet on a labelled set of real camera photos, and no phone camera app recognises CKey on its own. Don’t make a CKey the only way to reach something important.
Where to start
- Make a CKey in your browser and download it as PNG, SVG or PDF.
- Scan a CKey with your camera, or check a link with link status.
- Read how CKey works: the parts of a symbol, its sizes and error correction.
- Build with CKey using the SDK quick starts and the downloads.
Scanning a CKey
Ordinary camera apps don’t read CKey yet. To scan one you need software built with the CKey core:
- The Open CKey scanner at /scan, which runs the core in your browser.
- CKey Reader, the reference reader apps for iOS and macOS, built from source. They are early test builds.
- Any app that includes a CKey SDK. Every SDK has a scanner that finds the frame, fits it to each profile and decodes. See the SDK quick starts.
A conforming reader shows the decoded content first. For recognised forms, such as an https: link, it offers an action that names its target, like “Open openckey.org”, and waits for you to tap. It never opens anything by itself. The rules are on payloads and actions.
Readers try Profile 0 first, then Profiles 1, 2 and 3. The profile and version are identified from the symbol’s own calibration keys, so you never choose them when scanning.
Printing a CKey
Small prints fail for three reasons, in this order: marks thinner than the printer can draw, grey anti-aliased edges that the printer turns into noise, and ink spreading into the gaps. Five rules avoid all three:
- Print dark marks on paper. A light code on an inked background loses its thin light marks to ink spread. In simulation, dark on paper prints about 35% smaller on plain inkjet paper.
- Use the print layout for small sizes. Profile 0.1 keeps every mark and gap at about one module or more, so the same content prints at roughly half the width. In the renderer, choose the print layout.
- Print at 100% or “actual size”. A print PNG has black-or-white dots at the printer’s resolution and records its dpi. Don’t let the print dialog fit it to the page.
- Choose the paper. Coated or photo paper keeps dots sharp; plain paper spreads ink.
- Keep the quiet margin. The rendered image already includes it. Don’t crop it off.
Smallest widths that decoded reliably in simulation, for Profile 0.1 at level M, with a camera of about 23 pixels per millimetre (a phone at about 12 cm in 4K):
| Content | Plain paper, older inkjet | Photo paper, inkjet |
|---|---|---|
| 8 bytes | 0.19 in (4.8 mm) | 0.15 in (3.8 mm) or less |
| 30 bytes, a short link | 0.24 in (6.1 mm) | 0.15 in (3.8 mm) or less |
| 120 bytes | 0.32 in (8.1 mm) | 0.21 in (5.3 mm) |
| 400 bytes | 0.56 in (14 mm) | 0.38 in (9.7 mm) |
| 1,200 bytes | 0.91 in (23 mm) | 0.56 in (14 mm) |
| 2,400 bytes | 1.34 in (34 mm) | 0.83 in (21 mm) |
These are model estimates, not camera measurements. A weaker camera needs about 1.3 to 1.5 times these sizes, and printing larger than the minimum is always kinder to the reader. To measure your own printer, paper and phone, print the calibration sheet from the command-line tool at actual size and find the smallest cell that scans:
ckey print-sheet --out sheet.png # 8 to 400 bytes at 0.25 to 1.0 in
ckey print-sheet --set large --out big.png # 1,200 and 2,400 bytes at 1.0 to 2.0 inThe full guidance is in the CKey printing guide.
Profiles
A profile is a family of symbols with its own geometry and capacity. Profile 0 is the one to use; the others are kept for compatibility and research.
| Profile | Capacity | Use |
|---|---|---|
| 0 | 31 versions, 27 to 4,619 bytes at level M | The general-purpose code. The encoder picks the smallest version that fits, at error correction level L, M, Q or H. |
| 0.1 | 31 versions, 7 to 3,453 bytes at level M | The print layout of Profile 0: coarser marks for small printed sizes. |
| 1 | exactly 16 bytes | A compact locator, not a text carrier. |
| 2 | up to 200 bytes | Experimental text profile. |
| 3 | up to 2,048 bytes | Experimental extended profile with seven capacity tiers. |
The renderer on this site makes Profile 0 and 0.1 symbols. Each format is specified in the spec directory of the repository, one file per format version.
What openckey.org adds
You never need this site to read or make a CKey. It offers, for convenience:
- Destinations: hosted text and short links that give a CKey a short
https:address to carry. - Tools: the renderer, the scanner and link status, which run in your browser.
- Packages: downloads of every SDK, with checksums.
- Telemetry intake: the endpoint that receives optional, anonymous scan counts from SDKs. See telemetry.
Every endpoint is listed in the API reference.
Licences
CKey itself, meaning the specification, the core and the SDKs, is open source under the MIT licence. The openckey.org website and its service code are proprietary, all rights reserved, and are not covered by that licence.