Filecast

UDP broadcast file transfer — sends a single file to every host on the same LAN at once, with automatic retransmission of dropped packets.

Table of Contents

• Features
• Quick Start
• Installation
• Parameters
• Examples
• How It Works
• Packet Structure
• Limitations
• Building from Source
• License

Features

• Broadcast to every host on a LAN with a single transmission
• Unicast mode for point-to-point transfer
• Automatic retransmission of lost packets
• Configurable MTU and timeout
• Windows, Linux, and macOS binaries built on every release

Quick Start

Download the binary for your platform from the releases page and run it directly. No installation required.

Sender (host that has the file):

./filecast --type sender --file photo.jpg

Receiver (one or more hosts on the same LAN):

./filecast --type receiver --file photo.jpg

Send to a specific host instead of broadcasting to the whole LAN:

./filecast --type sender --file photo.jpg --broadcast 192.168.1.50

Installation

Pre-built binaries for Linux x86_64, macOS arm64, and Windows x86_64 are attached to every GitHub Release.

If your platform isn't covered, see Building from Source.

Parameters

Parameter	Default	Range	Description
-f, --file	file.out	—	File to send or save
-t, --type	sender	sender / receiver	Run mode
--broadcast	yes	yes or IPv4	yes for LAN broadcast, or a specific IP for unicast
-p, --port	33333	1..65535	Destination port for outgoing packets
--bind-port	33333	1..65535	Local port to bind on
--mtu	1500	64..65507	Max packet size in bytes
--ttl	15	> 0	Seconds of silence before giving up
--delay-ms	20	≥ 0	Pause between successive packets (use 0 for loopback / tests)
-h, --help	—	—	Print help
--version	—	—	Print version

Examples

LAN broadcast (one sender, many receivers):

# On the sender host
./filecast --type sender --file album.zip

# On every receiver host
./filecast --type receiver --file album.zip

Targeted unicast (when broadcast is blocked or you only have one receiver):

# On the sender host (sends data to 10.0.0.42)
./filecast --type sender --file album.zip --broadcast 10.0.0.42

# On 10.0.0.42 (receiver default --broadcast=yes broadcasts RESENDs)
./filecast --type receiver --file album.zip

Loopback test (sender and receiver on the same host — useful for development):

# Receiver listens on 33401, sends RESEND back to the sender's bind port (33402)
./filecast --type receiver --file out.bin \
           --broadcast 127.0.0.1 --port 33402 --bind-port 33401 &

# Sender listens on 33402, sends data to the receiver's bind port (33401)
./filecast --type sender --file in.bin \
           --broadcast 127.0.0.1 --port 33401 --bind-port 33402

How It Works

1. Sender broadcasts a NEW_PACKET packet with the total file size.
2. Each receiver allocates a buffer of that size and clears its part registry.
3. Sender splits the file into MTU-sized chunks and broadcasts each one as a TRANSFER packet.
4. Sender broadcasts a FINISH packet when all chunks have been sent.
5. Each receiver scans for missing chunks and requests them with RESEND packets.
6. Sender retransmits each requested chunk.
7. Steps 5–6 repeat until every chunk is received or the TTL expires.

Packet Structure

Limitations

• The whole file is held in RAM on both sides. The receiver enforces a 4 GiB cap on the announced file size; the sender is bounded only by available memory.
• No data integrity check beyond UDP's optional 16-bit checksum. If the payload is corrupted in a way the checksum doesn't catch, the receiver will silently produce a corrupted file.
• No authentication. Any host on the same LAN can send a NEW_PACKET and any receiver bound to the chosen port will accept it.
• No encryption. The payload travels as plaintext UDP.

Building from Source

Requirements

• CMake 3.15+
• A C++17 compiler:
  • GCC 7+ or Clang 5+ on Linux/macOS,
  • MinGW64 GCC via MSYS2 on Windows,
  • or MSVC 2019+ through the Visual Studio CMake generator.
• pthreads (Linux/macOS).

Build

git clone https://github.com/gistrec/filecast.git
cd filecast
git submodule update --init --recursive
cmake -S . -B build
cmake --build build --config Release

The binary lands at build/filecast (or build\Release\filecast.exe with the multi-config Visual Studio generator).

Tests

ctest --test-dir build --output-on-failure

Runs the unit tests, the loopback end-to-end test, and a lossy variant that drops packets through a Python UDP proxy to exercise the RESEND branch. Pass -E e2e to skip the e2e cases on Windows, where Winsock semantics break two-process loopback.

License

MIT.