From 3084c438ee9e5b90bb8e7ec58ff1dc8e111b875c Mon Sep 17 00:00:00 2001
From: Peter Edley <peter@edleyit.com>
Date: Sat, 19 Sep 2026 09:22:58 +0100
Subject: [PATCH] docs: add README with build, usage and network requirements

Document the two ports TeleportFling needs (TCP 9756 stream, UDP 9999
multicast discovery) and how to open them on NixOS and other firewalls,
based on the two-machine test.
---
 README.md | 90 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 90 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..dcba169
--- /dev/null
+++ b/README.md
@@ -0,0 +1,90 @@
+# TeleportFling
+
+Standalone Linux screen + audio sender for the
+[OBS Teleport protocol](https://github.com/fzwoch/obs-teleport).
+
+TeleportFling captures a Wayland screen (via `xdg-desktop-portal` + PipeWire)
+and the system's default audio, encodes the video to JPEG, packetizes both
+into the Teleport protocol, and streams them over TCP so any OBS instance
+with the `obs-teleport` plugin can discover and display the stream.
+
+## Features
+
+- **Real screen + audio capture** on Wayland (PipeWire / xdg-desktop-portal).
+- **LAN discovery** via UDP multicast, matching obs-teleport's `AnnouncePayload`.
+- **Multiple receivers** — every connected OBS streams from one sender.
+- **Headless CLI** (`teleportfling`) and **desktop GUI + system tray**
+  (`teleportfling-gui`).
+- **Config persistence** at `~/.config/teleportfling/config.json`, customisable
+  with `--config`.
+- **Daemon mode** via a per-user systemd service (see `contrib/`).
+
+## Build & run
+
+Requires a Nix dev shell (or Go 1.26+ with libjpeg-turbo and the Fyne/GLFW
+native deps for the GUI).
+
+```sh
+nix develop
+go build ./cmd/teleportfling       # headless CLI
+go build ./cmd/teleportfling-gui   # desktop GUI + tray
+```
+
+Run:
+
+```sh
+./teleportfling --name "Studio" --port 9756
+```
+
+Flags: `--name`, `--port`, `--quality`, `--fps`, `--source screen|pattern`,
+`--audio`, `--no-announce`, `--stream-index`, `--duration`, `--config`.
+
+## Network requirements
+
+TeleportFling uses two kinds of traffic:
+
+| Port  | Proto | Direction      | Purpose                          |
+|-------|-------|----------------|----------------------------------|
+| 9756  | TCP   | Sender → listen | Video + audio stream to receivers |
+| 9999  | UDP   | Sender → listen | multicast discovery (peerdiscovery) |
+
+For a **sender** to be discoverable and reachable by OBS receivers on another
+machine, **both** machines need these ports open:
+
+### NixOS
+
+```nix
+networking.firewall = {
+  enable = true;
+  allowedTCPPorts = [ 9756 ]; # TeleportFling screen/audio streaming
+  allowedUDPPorts = [ 9999 ]; # TeleportFling multicast discovery
+};
+```
+
+Apply with `sudo nixos-rebuild switch --flake .#<hostname>`. If the machines
+are on separate/isolation LANs, Tailscale works as an alternative transport
+(point OBS at the receiver's Tailscale IP:port), but the multicast
+discovery list will only show senders reachable via LAN multicast.
+
+### Other distros / firewalls
+
+Open TCP **9756** inbound and UDP **9999** inbound on the sender machine;
+receivers just need outbound access (or the same rules if a firewall restricts
+it). mDNS (UDP 5353) is only needed for zero-config name resolution, not for
+TeleportFling itself.
+
+## Daemon mode
+
+See `contrib/README.md` — `contrib/install-daemon.sh` installs a per-user
+systemd unit that runs the headless CLI with its own config.
+
+## Development
+
+- `go build ./...` — build
+- `go test ./...` — tests
+- `golangci-lint run ./...` — lint
+- See `AGENTS.md` and `project.md` for workflow and milestone history.
+
+## License
+
+GPL-2.0, matching the obs-teleport project whose protocol we implement.
\ No newline at end of file