KolYesod: Communication over the sound spectrum
Dial-up is dead, Long live Dial-up!

A p2p data-over-sound networking stack. Encryption-first and memory safe.
I just want to experiment with an application
Visit the example chat app.
Using it in my application
Two core constructs: Node and LowerNode. Node is the recommended interface for most users. Much of the lower level details are abstracted. The offical implementation is memory-safe, so don't worry about an heap corruption RCE. Enable the library's audio feature to use Node.
use libkolyesod::node::{Node, NodeEvent};
fn main() -> libkolyesod::Result<()> {
let node = Node::new()?;
node.hello()?;
loop {
match node.recv()? {
NodeEvent::Peer(peer) => node.send(&peer, b"Shalom")?,
NodeEvent::Data { sender, bytes } => {
println!("{}: {}", sender.name, String::from_utf8_lossy(&bytes));
}
}
}
}
Does this follow the OSI model
Partially
Layers
Physical
The physical layer represents bytes as sound samples and recovers them from microphone samples. Its internal sample rate is 48,000 samples per second. It divides the signal into frames of 1,024 samples, so one frame lasts about 21.3 ms. Audio devices can use a different rate; a resampler converts between the device rate and the protocol rate.
With the default profile, a frame has 12 frequency lanes. Each lane chooses one of 16 tones, encoding a four-bit value. The tones occupy bins of a 1,024-sample frame, spaced 46.875 Hz apart, and span about 1.9 to 10.8 kHz. All 12 chosen tones play at once, giving six bytes per frame, or 2.25 kbit/s before packet markers and error correction. The decoder measures the energy at each candidate frequency and chooses the strongest tone in each lane.
Special tone patterns mark the beginning and end of an acoustic burst. The receiver scans microphone input for the start pattern, locates the transition into data frames, and uses the protected length field to know when the burst is complete. It also senses likely KolYesod carriers before transmission so a sender can wait for an idle channel. The experimental NEARULTRA profile in libkolyesod/crates/physical/src/parameters.rs is currently disabled; this description refers to the default profile.
Data link
The data-link layer turns a network message into one addressed frame. A frame contains a 32-byte source, a 32-byte destination, a one-byte payload length, the payload, and a two-byte CRC-16 checksum. The addresses are the peers' public keys; a broadcast destination is reserved for discovery. The payload can hold at most 255 bytes, and the receiver rejects a frame whose length or checksum is wrong.
Before sound modulation, the acoustic burst encoder protects that serialized frame with Reed–Solomon codes. It encodes the two-byte frame length with eight parity bytes, then splits the frame into 32-byte blocks with 16 parity bytes per block. Four start-marker frames and four end-marker frames surround the encoded bytes. The protected length lets the receiver decode a complete burst even if the end marker is damaged. The burst encoder accepts at most 512 serialized bytes.
Parity can repair a limited number of byte errors, while CRC-16 detects corruption that remains after decoding. Neither mechanism proves who sent the frame: that is the job of authenticated encryption in the layers above. These addresses currently name the sender and recipient on the same acoustic link. A relay would need separate next-hop addressing from the final sender and recipient identities.
Network
The network layer defines the bytes inside a data-link payload. Every message has a protocol version and kind. A hello broadcasts a public key and request ID; a hello-reply returns its own key and cites that request ID. A node checks that a claimed key matches the data-link source address and records the peer. Discovery establishes a usable key, but does not by itself establish that the person or device is trusted.
Data, reliable-data, and acknowledgment messages carry a message ID and an encrypted envelope. The implementation uses authenticated HPKE with X25519, HKDF-SHA256, and ChaCha20-Poly1305. The version, message kind, source and destination addresses, and message ID are additional authenticated data: changing any of them causes decryption to fail. The envelope adds 32 bytes of encapsulation and a 16-byte authentication tag. Given the 255-byte network-message limit, a data message can carry at most 197 application bytes.
On receipt, a node ignores frames for another destination and decrypts data only from a discovered peer. It remembers up to 128 source-and-message-ID pairs; an ordinary repeated data message is rejected, while a repeated reliable message can be acknowledged without delivering it again. There is no route table or forwarding rule. A peer beyond direct acoustic range cannot currently receive a message through another node.
Transport
Transport adds a delivery contract to a network data message. For a reliable send, the sender generates one message ID, encrypts the payload once, and waits for an acknowledgment from the intended peer carrying that ID. The acknowledgment itself is authenticated and has an empty plaintext payload. A matching acknowledgment means the receiving node accepted the packet; it says nothing about whether an application user read it.
The native Node retries the same encrypted frame up to five times, waiting six seconds after each transmission for an acknowledgment. Reusing the frame preserves its message ID, so the recipient can distinguish a retry from a new message. The recipient sends an acknowledgment for repeated reliable frames but reports the payload to the application only on its first receipt. The browser chat implements its retry scheduling in JavaScript using the LowerNode frame API.
Transport cannot restore data that the physical or data-link receiver never decodes; it can only try again. Retries cost another full acoustic burst and can collide with other senders, so delivery time depends on packet length and channel conditions. The current acknowledgment and retry path assumes the two peers are directly reachable. Multi-hop delivery would need forwarding and a clear choice of whether acknowledgments apply to each hop or to the final recipient.
Application
The application interprets the bytes delivered by the lower layers. The example chat starts each payload with a type byte for text, a text chunk, a photo chunk, or a nickname profile. The network layer neither parses these types nor knows that the payload represents a conversation. This boundary lets a different application use the same node and wire protocol.
The chat splits longer text into numbered chunks with a transfer ID and total count, then reassembles them after reception. It compresses photos and sends them in numbered chunks as well. A user's nickname is stored in the browser and sent to nearby peers as an application message; received nicknames replace generic peer labels. The chat tracks pending sends and displays acknowledgment status; complete reassembly determines when it can display a long message or image.
Node provides the native high-level interface: it manages audio I/O, peer events, sends, and acknowledgments. LowerNode exposes frame generation and processing without owning the audio device; the WASM chat uses it with browser audio APIs. The web chat generates a fresh identity when it starts. Native Node::new() also generates a fresh identity. Chunking and presentation remain application decisions.