DocumentationmDNS discovery

mDNS discovery

The goal is for a bandmate to join without typing anything. To get there, the app tries several routes to the leader at once.

How discovery works

When the leader starts a session:

  1. It resolves its own local IP address.
  2. It starts an HTTP server.
  3. It announces itself over mDNS/Bonjour as the service _eutepio._tcp.

A device looking for a session runs two modes simultaneously:

  • mDNS query — the fast path, works within seconds
  • Local range scan — the fallback for networks without multicast
The scan walks addresses 1 through 254 in your subnet and repeats every 2 seconds. Addresses where a leader was last seen are tried first (up to the last eight), so rejoining the same band is usually instant.
ℹ

Both routes run in parallel, not one after the other. If multicast is broken on your network the session is still found — just slightly slower.

Service record and ports

text
Service type:  _eutepio._tcp
Protocol:      TCP
Port:          8765
Fallback:      8766, 8767, 8768, 8769
The leader tries to claim port 8765. If it is taken — by another app, or by another Eutepio instance on the same machine — it tries the next four in turn. The scanning device walks the same range, so the fallback works even without mDNS.

HTTP endpoints

The leader's server exposes four endpoints:

EndpointMethodPurpose
/discoverGETReturns session info — name, member count, whether a password is set
/joinPOSTMember joins, password is verified, identity is assigned
/wsGETUpgrade to the WebSocket that carries all session traffic
/healthGETQuick check that the leader is still alive
Once the WebSocket is up, a ping every 10 seconds keeps it alive and the member sends a heartbeat every 5 seconds. A member the leader has not heard from for 25 seconds is dropped from the list.

Other ways to connect

QR code

The leader shows a QR code holding a link of the form:

text
eutepio://join?ip=192.168.0.42&port=8765&pin=1234&session=…&leader=…

The member scans it with the built-in reader and connects directly — no waiting for discovery. Useful in venues where the network is crowded or multicast is blocked.

Manual IP address

The session list has an option to type an address by hand. The leader shows its IP on the sync screen.

Session password

The leader can protect a session with a PIN. It is verified during the /join call; without the right password the member never reaches the WebSocket. The PIN is part of the QR code, so scanning skips typing it.

Network requirements

ConditionWhy
Same local network / subnetBoth the scan and mDNS only work inside your network segment
Multicast allowedRequired for the fast mDNS path
Client isolation offMany hotel and venue WiFi networks forbid device-to-device traffic
VPN offA VPN routes traffic away from the local network
When the network is unreliable, the most dependable fix is a hotspot from one of the phones. It needs no internet — both devices just have to be on it.

iOS permission

iOS 14 and later requires explicit consent for local network access. The app declares the _eutepio._tcp service and the prompt text in the project; the dialog appears on the first discovery attempt.

Android permission

Android needs the multicast permission for mDNS. To survive the screen turning off, an active session runs a foreground service with a notification.

Troubleshooting

The session does not show up on the other device

  1. Check that both devices are on the same network — not one on WiFi and the other on mobile data.
  2. Check whether the network has client isolation enabled (typical for public and hotel WiFi).
  3. Turn off VPN on both devices.
  4. Try the QR code or manual IP — both skip discovery entirely.
  5. If nothing helps, turn one phone into a hotspot and join through it.

The local-network dialog never appeared on iOS

The dialog is shown once. If you declined it, the permission is re-enabled in iOS Settings → Eutepio → Local Network.

The connection drops while playing

The usual cause is roaming between access points, or a power-saving mode putting the network interface to sleep. The app reconnects automatically after a drop — exactly how is described in Conflict resolution.

The leader came up on a different port

That is normal behaviour when 8765 is taken. Discovery and the scan both account for it, but a manually typed address cannot guess the port — use the QR code in that situation.

← PreviousNext →