# 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:
   ```bash
   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):
   ```bash
   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.