106 lines
5.0 KiB
Markdown
106 lines
5.0 KiB
Markdown
# 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.
|