User guide

Install on a Mac

1. Download Air Kalon for Mac.
2. Open Air-Kalon.dmg and drag Air Kalon into Applications.
3. Open it. Air Kalon checks for a new version twice a day and installs it when you quit, so it never interrupts a transfer; Air Kalon › Check for Updates… looks right away.

It needs macOS 14 or later, on Apple silicon, and is signed with a Developer ID and notarized by Apple.

Before you start

Both devices need the current build of Air Kalon; earlier builds used a different format and cannot exchange files with it. The receiving device needs camera access, which it asks for the first time you start receiving. Nothing needs to be paired or connected, and it makes no difference whether Wi-Fi or Bluetooth is on.

Each app has two tabs, Send and Receive. On the Mac they sit in the title bar, and the menu bar item opens either one directly.

Send from a Mac

1. Open Air Kalon and choose Send. A demo image is already loaded, so you can try a transfer straight away.
2. Load what you want to send:

• drag a file, a folder or several files onto the window;
• press ⌘V to paste a copied file or copied text;
• click Choose File… to pick one file, several files or a folder;
• click Text Snippet… to type or paste text.

3. Several files or a folder become one zip archive named bundle.zip. Text becomes snippet.txt, or snippet.rtf if it carries formatting. A file or selection over 256 MiB is refused when you pick it, with the reason.
4. Click Start. The Send surface stays white to give the code full contrast, and the Mac keeps its display awake until the transfer stops.
5. Point the receiving device's camera at the code. Click Stop when the receiver says the transfer is complete, or let auto-stop do it.

While a stream is running, pasting or dropping a new payload is refused until you press Stop, so an accidental ⌘V cannot end a long transfer.

The line under the code shows what the container did to the file, for example 2.1 MB → 1.4 MB (deflate) when compression paid, or the plain size when it did not.

When a file is too large for one stream

A stream carries at most 56,403 source symbols, one per frame. At the default frame size of 1,465 bytes that is about 77 MiB; at 2,953 bytes it is about 157 MiB. If a file needs more, the sender refuses to start and asks you to raise the frame size. The limits for each size are on the limitations page.

Send from an iPhone or iPad

1. Choose Send.
2. Tap Choose File… and pick a source: Photo Library, Files or Folders or Paste Text. You can also drag an item onto the screen, or tap Text Snippet….
3. Tap Start. The screen goes to full brightness and will not lock while the stream runs. Both are restored when it stops.
4. Hold the screen steady in front of the receiving camera.

Receive

1. Choose Receive and press Start Receiving.
2. Point the camera at the sender's screen. The screen reads searching for a stream… until the first frame locks, then shows live figures: capture and decode rates, frames collected, the source block count K, the frame size and the payload size.
3. When the file is complete and verified, the screen shows Transfer Complete! with the file name, its size, the time taken and the rate. The detail line reads, for example, image/png · 2.1 MB · deflate · SHA verified ✓; deflate appears only when the file travelled compressed.
4. Choose what to do with it:

• Save… On the Mac, a save panel suggests the original file name. On iPhone and iPad, the system share sheet opens, which includes Save to Files.
• Copy copies a text payload to the clipboard. Rich text is copied with its styling.
• Open appears when the payload is a single web link, and names the host it will open. Nothing opens until you tap it.
• Receive Another starts a new receive.

On the Mac, Reveal in Finder appears after you save.

A bundle shows how many files it contains and opens as an ordinary zip archive. Text up to 64 KB is shown in full on the completion screen; longer text shows the first 64 KB, and Copy still takes all of it up to 10 MB.

If anything about the received data does not check out, the screen reads Transfer failed with the reason, and the file is not offered. The reasons are a damaged transfer (the checksum did not match), a payload that is not a Kalon container, a damaged container, a file that could not be expanded, and a SHA-256 mismatch. Press Try Again. The troubleshooting page says what each one means.

Auto-stop

By default the sender streams until you press Stop. Auto-stop lets the receiver's screen stop it instead.

1. On the sender, open the stream settings and switch on Auto-stop. The sender's camera starts only while a stream is on air, and a small viewfinder labelled Watching for delivery shows what it sees.
2. When the receiver finishes, it shows Delivered with a large acknowledgement code and the line "Show this screen to the sender to stop it".
3. Turn the receiver's screen toward the sender's camera. The stream stops on its own.
4. Tap Done on the receiver to dismiss the card. It stays up until you do.

Auto-stop needs the sender's camera to see the receiver's screen. When an iPhone receives from a Mac with its back camera, the phone's screen faces away from the Mac, so you have to turn the phone around at the end. If the sender never sees the acknowledgement, nothing breaks: it keeps streaming until you stop it.

Stream settings

Open the settings from the Send screen. Changing a setting while streaming restarts the stream from the beginning.

The largest frame each error correction level allows is 2,953 bytes at L, 2,331 at M, 1,663 at Q and 1,273 at H.

Getting a fast, clean transfer

• Turn off Low Power Mode on the receiving device. In every measured device pairing it lengthened the time the receiver spends decoding each code.
• Keep the sender at full brightness.
• Hold the devices steady. The measured sessions used a receiver about 30 cm from the sender. Movement makes the camera refocus.
• Fill the camera's view with the code. Presentation mode helps when the devices are further apart.
• Use the grid only from a Mac or iPad. On a phone-sized screen two codes are too small to read, so the app does not offer it there.

Session report

Both the sender and the receiver have Copy Session Report. It copies the whole run as plain text: the mode (always mode: 2 (RaptorQ)), the frame geometry, frame counts, rates, the verification result and, on the sender, whether the acknowledgement was seen. A verified receive reads delivered ✓ · SHA verified; a failed one starts with FAILED and gives the same reason the screen showed. It is what to attach if a transfer misbehaves.

Receiver experiments

The gear on the idle Receive screen opens Receiver Experiments: alternative capture and decoding settings used in measurement sessions. They are off by default, apply to the next run and are not needed for normal use.