Limitations
- It is slow by network standards. The best measured transfers ran at 30.5 KB/s at the default frame size and 44.4 KB/s at the largest. A 10 MB file takes minutes, not seconds.
- Size limits. A file or a multi-file bundle can be up to 256 MiB, and every transfer is SHA-256 verified whatever its size. One stream also carries at most 56,403 symbols, so the frame size sets a lower practical ceiling. If a file needs more, the sender refuses to start and asks you to raise the frame size. The table below gives the ceiling for each frame size.
- No encryption. Anyone who can see the sender's screen can capture the file. See Security and privacy.
- No authentication. The receiver verifies that the bytes arrived intact, not who sent them.
- Line of sight. The receiver's camera has to see the sender's screen throughout.
- The grid is for large screens. From a phone, two codes are too small to read, so phones never show it.
- Auto-stop needs a camera that can see the receiver. When an iPhone receives with its back camera, you turn it around at the end.
- Both devices need the current build. Earlier builds of Air Kalon used a different frame format and container, and they do not interoperate with the current one in either direction. There is no browser receiver.
- Apple devices only. Apple silicon Macs, iPhone and iPad. Nothing has been measured on Android.
Largest stream by frame size
| Frame size | Symbol | Largest stream |
|---|---|---|
| 465 bytes | 440 bytes | about 23.7 MiB |
| 965 bytes | 936 bytes | about 50.3 MiB |
| 1,465 bytes (default) | 1,440 bytes | about 77 MiB |
| 2,953 bytes | 2,928 bytes | about 157 MiB |
The stream carries the container, so the largest file is smaller than the figure shown by the container's 58-byte header, the file name and the media type. The 2,953-byte size needs error correction L; see the user guide.
Troubleshooting
The receiver stays on "searching for a stream…"
- Check that the sender pressed Start and its screen is at full brightness.
- Move the camera until the whole code is in view and hold still for a moment.
- Check that both devices run the current build. Depending on how an earlier build is set, the receiver either never locks on to its stream or refuses the payload at the end.
- At error correction M, Q or H, large frame sizes are unavailable. Leave error correction at L unless you have a reason not to.
It locks on, then crawls
- Turn off Low Power Mode on the receiving device. In measurement it lengthened the decoder's time per code on every device.
- Steady the devices. The measured sessions propped the receiver about 30 cm from the sender.
- Close other heavy apps on the sender. A sender that cannot keep its frame rate shows fewer unique frames.
- Try Presentation mode on the sender to make each module larger.
- Try the default frame size. Larger frames carry more per code but take the receiver longer to read.
"Transfer failed"
The stream completed but the received data did not pass verification, so nothing was offered. The line under the heading gives the reason:
| Reason on screen | What it means | What to do |
|---|---|---|
| The received data was damaged in transit (checksum mismatch) | The assembled bytes did not match the stream's FNV-1a hash | Press Try Again while the sender keeps streaming |
| The received payload is not a Kalon container | The sender is running an earlier build | Update the sender |
| The sender uses a newer container version | The receiver is running an older build than the sender | Update the receiver |
| The container carries options this version does not understand | The container sets flags this build does not define, or two that conflict | Update the receiver |
| The container header is damaged | A length, a name or a media type broke the container's rules | Press Try Again |
| The compressed file could not be expanded | The DEFLATE body was invalid, had trailing bytes, or expanded to the wrong length | Press Try Again |
| The recovered file failed SHA-256 verification | The file's bytes do not match the digest the sender packed | Press Try Again |
If it fails repeatedly, copy both session reports. The receiver's report gives the same reason on its outcome line.
"no usable camera"
The message names the step that failed:
- no camera found on this device, which is what the iOS Simulator shows;
- would not open, with the system's error, and on the Mac a note when another app is using the camera;
- the capture session refused the camera at the named preset.
If the camera works in other apps and the error persists, restart the device. One field report of this error on an iPhone was cleared by a restart.
Auto-stop never stops the stream
- Check that Auto-stop is on in the sender's stream settings, and that the viewfinder next to Watching for delivery shows the receiver's screen.
- On the receiver, wait for Delivered, then turn the screen to the sender's camera. The card stays up until you tap Done.
- Copy the sender's session report. The
ackline says whether the watcher was running, how many frames it sampled, and whether it saw any matching acknowledgement.
A picker option is greyed out
The frame size does not fit a QR code at the selected error correction level. Lower the frame size or choose level L.
The sender says the file needs more frames than one stream can carry
The file is under the 256 MiB cap but needs more than 56,403 symbols at the chosen frame size. Raise the frame size in the stream settings, at error correction L, and press Start again.
The sender says a file is over the 256 MB limit
Files and bundles are capped at 256 MiB. Split the selection into smaller sends.
Paste or drop does nothing while sending
The sender refuses a new payload while a stream is running, so that an accidental ⌘V cannot end a transfer. Press Stop first.
FAQ
Does Air Kalon use the network at all?
Not for transfers: turn on airplane mode and they work the same. The only connection is the Mac app's update check, which asks GitHub for a newer version and sends only the version you have. Turn off Update automatically, in the Software Update window (Air Kalon › Check for Updates…), and Air Kalon makes no connection at all until you check yourself.
Why not AirDrop or a hotspot?
Both need a radio link between the two devices. Air Kalon needs only a screen and a camera, and works where radios are off, unavailable or not allowed.
What happens if my hand shakes?
The receiver misses frames and catches later ones. With RaptorQ any K distinct symbols are enough, so a missed frame costs time, never the file.
How big a file can I send?
Up to 256 MiB, and every size is SHA-256 verified. One stream carries about 77 MiB at the default frame size and about 157 MiB at the largest. At the best measured default-size rate of 30.5 KB/s, 1 MiB takes about 34 seconds.
Can someone nearby read what I send?
Yes, if their camera can see your screen clearly. The stream is not encrypted.
Can I send to a browser?
No. The wire format is read only by the Air Kalon apps, and both devices need the current build.
Does the receiver need to know the file size or type in advance?
No. Every frame carries the stream's parameters, and the container carries the name and type.
What is the session report for?
It records exactly what happened in a run, from the mode and geometry to frame counts and verification, including the reason for a failed transfer. It is the first thing to share when reporting a problem.