# 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.

## Packaging

Three distribution formats are provided. Prebuilt artifacts are tracked in
the repo under `dist/` (click to view on the remote; raw downloads require
access to the Gitea server):

- [AppImage](http://homeserver:3050/pedley/TeleportFling/src/branch/main/dist/TeleportFling-0.1.0-x86_64.AppImage)
- [Debian/Ubuntu .deb](http://homeserver:3050/pedley/TeleportFling/src/branch/main/dist/teleportfling_0.1.0_amd64.deb)

### Nix / NixOS

The flake builds both binaries as packages:

```sh
nix build .#teleportfling        # headless CLI
nix build .#teleportfling-gui    # desktop GUI + tray (default)
nix run .#teleportfling-gui
```

The GUI package also installs a `.desktop` entry and icon.

### AppImage

A self-contained AppImage of the GUI (bundles the runtime libraries):

```sh
./packaging/appimage.sh
# → dist/TeleportFling-0.1.0-x86_64.AppImage
```

Requires `appimagetool` in `dist/` (see the script header) and the flake dev
shell for building.

### Debian / Ubuntu

A `.deb` for Debian/Ubuntu (both binaries + desktop entry + icon):

```sh
./packaging/deb.sh
# → dist/teleportfling_0.1.0_amd64.deb
```

Install with `sudo dpkg -i dist/teleportfling_0.1.0_amd64.deb` (then
`sudo apt-get install -f` to pull dependencies if needed). The binaries
require glibc ≥ 2.34, so Ubuntu 22.04+ / Debian 12+ are supported.

## 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.