kestrelos/docs/live-streaming.md

Share live (mobile device as a live camera)

Share live lets you stream your phone’s camera and location to KestrelOS. You appear as a live session on the map and in the Cameras list; others can click your marker to watch the stream in real time. Uses WebRTC (Mediasoup) and requires HTTPS when using the app from a phone.

---

How it works

1. You open the Share live page on your mobile browser (sidebar → Share live; or /share-live).
2. You tap Start sharing. The app requests camera and location permission.
3. A live session is created on the server and your video/location is sent over WebRTC.
4. Your device appears on the map and in Cameras. Others click your marker or select you in the list to view the stream.
5. Tap Stop sharing to end the stream.

Only admin and leader roles see the Share live item in the sidebar; they are the ones who can start a live share. Any signed-in user can view live sessions on the map and Cameras page.

---

Requirements

• HTTPS when using the app from a phone. Browsers require a secure context for camera and geolocation. Use:
  • A server with a real TLS certificate, or
  • For local testing: a self-signed cert and your machine’s LAN IP (see below).
• Camera and location permission in the browser when prompted.
• Network: Server must be reachable from the phone. For WebRTC, UDP and TCP ports 40000–49999 must be open on the server (or the ports Mediasoup is configured to use).

---

Using Share live on your phone

1. Open the app over HTTPS

• Production: Open https://your-kestrelos.example.com, sign in, then go to Share live (sidebar).
• Local / LAN: Use the same HTTPS URL you use for the server (e.g. https://192.168.1.10:3000). If you use a self-signed cert, accept the browser warning once (e.g. Advanced → Proceed).

2. Start sharing

1. Tap Share live in the sidebar (or open /share-live).
2. Tap Start sharing.
3. Allow camera and location when the browser asks.
4. Wait for “Live — you appear on the map.” Your marker and stream are now visible to others.

3. View yourself on the map

• On another device (or in another tab), open the KestrelOS map. Your device appears as a live-session marker; click it to open the stream panel.
• Or open Cameras and select your session from the list (shown as “Live”).

4. Stop sharing

Tap Stop sharing on the Share live page. The session ends and your marker disappears after a short time.

---

Local development: HTTPS and LAN

To test Share live from a phone on your LAN without a public domain or cert:

1. Generate a self-signed cert (once) using your machine’s LAN IP:

   chmod +x scripts/gen-dev-cert.sh
   ./scripts/gen-dev-cert.sh 192.168.1.123
   

   Use your machine’s actual LAN IP instead of 192.168.1.123.

2. Start the dev server (it will use HTTPS if .dev-certs/ exists):

   npm run dev
   

3. On your phone, open https://192.168.1.123:3000 (same IP as above). Accept the “untrusted certificate” warning once, then sign in and go to Share live.

If you see a warning about NODE_TLS_REJECT_UNAUTHORIZED=0, you can ignore it in local dev; the server still works.

---

WebRTC and firewall

• The server uses Mediasoup and needs UDP and TCP in the range 40000–49999 (by default) open for WebRTC.
• The server tries to detect the LAN IP for WebRTC. If you run in Docker or have multiple NICs, set MEDIASOUP_ANNOUNCED_IP to the IP or hostname that clients use to reach the server.
• Wrong host: If the Share live page shows “Wrong host” (server hostname vs. client hostname), open the app using the same hostname the server reports, or set MEDIASOUP_ANNOUNCED_IP so the server advertises the correct address.

---

Troubleshooting

Issue	What to do
“HTTPS required” or camera/location not available	Open the app over https:// (not http). On a phone, use a tunnel (e.g. ngrok) or a server with TLS.
“Media devices not available”	Ensure you’re on HTTPS and that the browser has permission for camera (and location if needed).
“WebRTC: failed” / “Wrong host”	Use the same URL on phone and server, or set MEDIASOUP_ANNOUNCED_IP. Open firewall for ports 40000–49999.
Stream doesn’t appear for others	Check that the server is reachable and that no firewall blocks WebRTC ports.

---

Summary

Step	Action
1	Open KestrelOS over HTTPS on your phone and sign in.
2	Go to Share live (sidebar).
3	Tap Start sharing and allow camera and location.
4	Your device appears on the map and Cameras; others click your marker or entry to view.
5	Tap Stop sharing when done.

For local testing, use the dev cert script with your LAN IP and open https://<LAN-IP>:3000 on the phone. For production, use a proper TLS setup and ensure WebRTC ports (40000–49999) are open on the server.