keligrubb/kestrelos
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 11 Wiki Activity

simplify docs
Some checks failed
ci/woodpecker/pr/pr Pipeline failed
Details

Browse Source
This commit is contained in:
Madison Grubb
2026-02-17 11:25:40 -05:00
parent 82bd51c3a4
commit c696f38f4d
6 changed files with 181 additions and 570 deletions
Download Patch File Download Diff File Expand all files Collapse all files

119
docs/live-streaming.md
View File

@@ -1,105 +1,44 @@
# Share live (mobile device as a live camera)
# Share Live
**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.
Stream your phone's camera and location to KestrelOS. Appears as a **live session** on the map and in **Cameras**. Uses **WebRTC** (Mediasoup) and requires **HTTPS** on mobile.
---
## Usage
## How it works
1. Open **Share live** (sidebar → **Share live** or `/share-live`)
2. Tap **Start sharing**, allow camera/location permissions
3. Device appears on map and in **Cameras**
4. Tap **Stop sharing** to end
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.
---
**Permissions:** Admin/leader can start sharing. All users can view live sessions.
## 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).
- **HTTPS** (browsers require secure context for camera/geolocation)
- **Camera and location permissions**
- **WebRTC ports:** UDP/TCP `40000–49999` open on server
---
## Local Development
## Using Share live on your phone
**Generate self-signed cert:**
```bash
chmod +x scripts/gen-dev-cert.sh
./scripts/gen-dev-cert.sh 192.168.1.123 # Your LAN IP
npm run dev
```
### 1. Open the app over HTTPS
**On phone:** Open `https://192.168.1.123:3000`, accept cert warning, sign in, use Share live.
- **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).
## WebRTC Configuration
### 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.
---
- Server auto-detects LAN IP for WebRTC
- **Docker/multiple NICs:** Set `MEDIASOUP_ANNOUNCED_IP` to client-reachable IP/hostname
- **"Wrong host" error:** Use same URL on phone/server, or set `MEDIASOUP_ANNOUNCED_IP`
## 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.
| Issue | Fix |
|-------|-----|
| "HTTPS required" | Use `https://` (not `http://`) |
| "Media devices not available" | Ensure HTTPS and browser permissions |
| "WebRTC: failed" / "Wrong host" | Set `MEDIASOUP_ANNOUNCED_IP`, open firewall ports `40000–49999` |
| Stream not visible | Check server reachability and firewall |