overlays-server 0.0.0-stage → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +661 -0
- package/README-tr.md +292 -0
- package/README.md +295 -2
- package/config.example.json +40 -0
- package/dist/app.d.ts +19 -0
- package/dist/app.js +127 -0
- package/dist/cli.d.ts +2 -0
- package/dist/cli.js +176 -0
- package/dist/config.d.ts +62 -0
- package/dist/config.js +115 -0
- package/dist/core/driver.d.ts +56 -0
- package/dist/core/driver.js +5 -0
- package/dist/core/hub.d.ts +100 -0
- package/dist/core/hub.js +280 -0
- package/dist/core/last-position.d.ts +23 -0
- package/dist/core/last-position.js +67 -0
- package/dist/core/protocol.d.ts +56 -0
- package/dist/core/protocol.js +27 -0
- package/dist/core/registry.d.ts +9 -0
- package/dist/core/registry.js +29 -0
- package/dist/core/types.d.ts +83 -0
- package/dist/core/types.js +2 -0
- package/dist/drivers/ddpai/http-api.d.ts +30 -0
- package/dist/drivers/ddpai/http-api.js +84 -0
- package/dist/drivers/ddpai/index.d.ts +20 -0
- package/dist/drivers/ddpai/index.js +107 -0
- package/dist/drivers/ddpai/messages.d.ts +29 -0
- package/dist/drivers/ddpai/messages.js +76 -0
- package/dist/drivers/index.d.ts +6 -0
- package/dist/drivers/index.js +8 -0
- package/dist/drivers/simulator.d.ts +13 -0
- package/dist/drivers/simulator.js +64 -0
- package/dist/index.d.ts +26 -0
- package/dist/index.js +26 -0
- package/dist/lib/delimited.d.ts +21 -0
- package/dist/lib/delimited.js +51 -0
- package/dist/lib/log.d.ts +27 -0
- package/dist/lib/log.js +80 -0
- package/dist/lib/nmea.d.ts +57 -0
- package/dist/lib/nmea.js +141 -0
- package/dist/lib/options.d.ts +29 -0
- package/dist/lib/options.js +85 -0
- package/dist/lib/reconnecting-tcp.d.ts +35 -0
- package/dist/lib/reconnecting-tcp.js +91 -0
- package/dist/lib/redact.d.ts +10 -0
- package/dist/lib/redact.js +30 -0
- package/dist/tools/probe.d.ts +37 -0
- package/dist/tools/probe.js +208 -0
- package/dist/transports/diagnostics.d.ts +65 -0
- package/dist/transports/diagnostics.js +49 -0
- package/dist/transports/feed.d.ts +22 -0
- package/dist/transports/feed.js +78 -0
- package/dist/transports/http-server.d.ts +39 -0
- package/dist/transports/http-server.js +196 -0
- package/dist/transports/security.d.ts +15 -0
- package/dist/transports/security.js +78 -0
- package/dist/transports/status-page.d.ts +7 -0
- package/dist/transports/status-page.js +204 -0
- package/dist/version.d.ts +2 -0
- package/dist/version.js +4 -0
- package/docs/architecture.md +85 -0
- package/docs/data.md +87 -0
- package/docs/devices/README.md +29 -0
- package/docs/devices/ddpai.md +99 -0
- package/docs/drivers.md +130 -0
- package/docs/new-device.md +94 -0
- package/docs/protocol.md +160 -0
- package/docs/remote.md +126 -0
- package/docs/testing-locally.md +150 -0
- package/docs/windows-network.md +58 -0
- package/package.json +72 -4
package/README-tr.md
ADDED
|
@@ -0,0 +1,292 @@
|
|
|
1
|
+
# overlays-server
|
|
2
|
+
|
|
3
|
+
[English](README.md) · **Türkçe**
|
|
4
|
+
|
|
5
|
+
Yayıncının bilgisayarında (ya da araçtaki bir Raspberry Pi'de) çalışan küçük bir **yerel köprü sunucu**. Araç
|
|
6
|
+
kamerasından (şimdilik **DDPAI**) canlı GPS verisini alır, [Stream Overlays](https://overlays.ramazansancar.com.tr)
|
|
7
|
+
harita overlay'ine WebSocket üzerinden saniyede bir aktarır. Telefon, bulut servisi ya da RealtimeIRL gerekmez: konum
|
|
8
|
+
kameradan doğrudan, yerel ağdan gelir.
|
|
9
|
+
|
|
10
|
+
```text
|
|
11
|
+
DDPAI kamera (Wi-Fi, 193.168.0.1:6100) ──► overlays-server (127.0.0.1:3456) ──► OBS tarayıcı kaynağı (harita)
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
- **Canlı konum, hız, yön, rakım, uydu sayısı, GPS kalitesi** — kameranın kendi GPS'inden, 1 Hz.
|
|
15
|
+
- **Cihazdan alınabilen her şey** — ivme (G-sensör), hafıza kartı doluluğu, kamera sayısı, RTSP adresleri, cihaz
|
|
16
|
+
bilgileri, tanınmayan mesajlar ham olarak. Overlay istediğini kullanır: [docs/data.md](docs/data.md).
|
|
17
|
+
- **Tünelde de harita boş kalmaz** — GPS koparsa son bilinen konum kullanılır, yeniden başlatmada bile korunur.
|
|
18
|
+
- **Başka cihazda / VPN üzerinden** — Raspberry Pi, Tailscale/WireGuard, kendi alan adın (token + TLS ile):
|
|
19
|
+
[docs/remote.md](docs/remote.md).
|
|
20
|
+
- **Modüler sürücü yapısı** — yeni kamera / GPS cihazı tek bir modülle eklenir ([docs/drivers.md](docs/drivers.md)).
|
|
21
|
+
- **Kendi kendini onarır** — kamera kapanıp açılsa ya da Wi-Fi kopsa yeniden bağlanır.
|
|
22
|
+
- **Gizlilik öncelikli** — varsayılan olarak yalnız `127.0.0.1`'i dinler, yalnız izin verilen siteler veriyi okuyabilir.
|
|
23
|
+
- **Tek bağımlılık** (`ws`), Node.js 22.18+.
|
|
24
|
+
|
|
25
|
+
## Desteklenen cihazlar
|
|
26
|
+
|
|
27
|
+
| Cihaz | Sürücü | Durum |
|
|
28
|
+
| --- | --- | --- |
|
|
29
|
+
| DDPAI N5 Pro (firmware v8.0.0.10) | `ddpai` | Sahada test edildi |
|
|
30
|
+
| Diğer DDPAI modelleri (TCP 6100 telemetrisi olanlar) | `ddpai` | Büyük olasılıkla çalışır, deneyip [bildir](https://github.com/ramazansancar/overlays-server/issues/new?template=device-report.yml) |
|
|
31
|
+
| Simülatör (cihazsız deneme) | `simulator` | — |
|
|
32
|
+
|
|
33
|
+
Cihaz ayrıntıları ve test edildiği ortamlar: [docs/devices/](docs/devices/README.md).
|
|
34
|
+
**Cihazın listede yok mu?** [Yeni cihaz ekleme rehberi](docs/new-device.md): tek komutla (`--probe`) cihazını
|
|
35
|
+
incele, raporu issue olarak gönder.
|
|
36
|
+
|
|
37
|
+
## Kurulum
|
|
38
|
+
|
|
39
|
+
İki yol var, ikisi de aynı sunucuyu çalıştırır. **Node.js 22.18 veya üstü** gerekli ([nodejs.org](https://nodejs.org)).
|
|
40
|
+
|
|
41
|
+
### A) npm ile (en kolay)
|
|
42
|
+
|
|
43
|
+
```bash
|
|
44
|
+
npx overlays-server@latest
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
`@latest` her açılışta npm'deki son sürümü kontrol eder (yalnız `npx overlays-server` yazarsan daha önce indirilen
|
|
48
|
+
sürüm kullanılabilir). Kalıcı kurmak istersen:
|
|
49
|
+
|
|
50
|
+
```bash
|
|
51
|
+
npm install -g overlays-server
|
|
52
|
+
overlays-server
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
**Güncelleme (kalıcı kurulum):**
|
|
56
|
+
|
|
57
|
+
```bash
|
|
58
|
+
overlays-server --version # kurulu sürüm
|
|
59
|
+
npm outdated -g overlays-server # yeni sürüm var mı? (çıktı boşsa güncelsin)
|
|
60
|
+
npm install -g overlays-server@latest
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
Kaldırmak için: `npm uninstall -g overlays-server`.
|
|
64
|
+
|
|
65
|
+
### B) Git ile (kaynaktan)
|
|
66
|
+
|
|
67
|
+
```bash
|
|
68
|
+
git clone https://github.com/ramazansancar/overlays-server.git
|
|
69
|
+
cd overlays-server
|
|
70
|
+
npm install --omit=dev # ya da: pnpm install --prod
|
|
71
|
+
npm start
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
Windows'ta klasördeki **`start.cmd`** dosyasına çift tıklamak da yeterli: her açılışta önce `git pull` ile kendini
|
|
75
|
+
günceller, gerekirse bağımlılıkları kurar, sonra sunucuyu başlatır. İnternet yoksa uyarı verip mevcut sürümle açılır;
|
|
76
|
+
otomatik güncellemeyi kapatmak için `set OVERLAYS_SERVER_NO_UPDATE=1`.
|
|
77
|
+
|
|
78
|
+
**Güncelleme (git kurulumu):** `start.cmd` kullanıyorsan bir şey yapmana gerek yok. Elle:
|
|
79
|
+
|
|
80
|
+
```bash
|
|
81
|
+
cd overlays-server
|
|
82
|
+
git pull
|
|
83
|
+
npm install --omit=dev # bağımlılıklar değiştiyse günceller
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
Belirli bir sürüme geçmek için: `git fetch --tags && git checkout v0.1.0`. Değişiklikler: [CHANGELOG.md](CHANGELOG.md).
|
|
87
|
+
|
|
88
|
+
Derleme adımı yok: Node.js 22.18+ TypeScript dosyalarını doğrudan çalıştırır.
|
|
89
|
+
|
|
90
|
+
### Çalıştığını kontrol et
|
|
91
|
+
|
|
92
|
+
Tarayıcıda **<http://127.0.0.1:3456>** adresini aç. Durum sayfası kameranın bağlı olup olmadığını ve GPS durumunu
|
|
93
|
+
canlı gösterir (koordinatlar varsayılan olarak gizli, yayında gösterilebilir).
|
|
94
|
+
|
|
95
|
+
## Kullanım
|
|
96
|
+
|
|
97
|
+
1. **Bilgisayarı kameranın Wi-Fi'ına bağla** (`DDPAI_...` ağı). İnternet Ethernet'ten (ör. Superbox) gelmeye devam
|
|
98
|
+
etmeli. Windows ayarı için: [docs/windows-network.md](docs/windows-network.md).
|
|
99
|
+
2. **overlays-server'ı başlat** (yukarıdaki iki yoldan biri). Konsolda `ddpai: link online` ve `ddpai: gps fix` görünür.
|
|
100
|
+
3. **[Overlay ayarlarında](https://overlays.ramazansancar.com.tr)** harita overlay'inin *Konum kaynağı* olarak
|
|
101
|
+
**Araç kamerası GPS — overlays-server [yerel]** seçeneğini seç. Altında açılan *Sunucu adresi* (`127.0.0.1`) ve
|
|
102
|
+
*Sunucu portu* (`3456`) varsayılan kurulumda olduğu gibi kalabilir. Sonra URL'yi OBS tarayıcı kaynağına ekle.
|
|
103
|
+
|
|
104
|
+
Kamera yoksa sistemi denemek için: `npx overlays-server@latest --simulate` (Ankara'da daire çizen sahte konum).
|
|
105
|
+
|
|
106
|
+
### Başka bir cihazda ya da VPN üzerinden
|
|
107
|
+
|
|
108
|
+
Sunucu bir Raspberry Pi'de, başka bir bilgisayarda ya da uzakta çalışabilir; overlay (yayın bilgisayarındaki ya da
|
|
109
|
+
buluttaki OBS) ona yerel IP, VPN IP'si ya da alan adı/genel IP ile bağlanır. Kısaca:
|
|
110
|
+
|
|
111
|
+
| Kurulum | Sunucu | Overlay ayarı |
|
|
112
|
+
| --- | --- | --- |
|
|
113
|
+
| Aynı ağdaki Pi / VPN IP'si | `"host": "0.0.0.0"`, `"token"` | Pi'nin IP'si, port, token |
|
|
114
|
+
| Tailscale + HTTPS (önerilen) | `tailscale serve --https=443 http://127.0.0.1:3456`, `"allowedHosts"` | `pi.<tailnet>.ts.net`, `443`, **Güvenli bağlantı** |
|
|
115
|
+
| Genel IP / alan adı | `"host": "0.0.0.0"`, `"token"`, `"tls"` ya da Caddy/Nginx | alan adı, port, token, **Güvenli bağlantı** |
|
|
116
|
+
|
|
117
|
+
`127.0.0.1` dışında dinlerken **mutlaka token kullan**. Ayrıntılı rehber, systemd ve Caddy örnekleri:
|
|
118
|
+
[docs/remote.md](docs/remote.md).
|
|
119
|
+
|
|
120
|
+
### Windows açılışında otomatik başlatma
|
|
121
|
+
|
|
122
|
+
`Win + R` → `shell:startup` → açılan klasöre `start.cmd`'nin (git kurulumu) ya da şu içerikte bir `.cmd` dosyasının
|
|
123
|
+
kısayolunu koy:
|
|
124
|
+
|
|
125
|
+
```bat
|
|
126
|
+
@echo off
|
|
127
|
+
npx overlays-server@latest
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
## Ayarlar
|
|
131
|
+
|
|
132
|
+
Varsayılanlar çoğu kurulum için yeterli. Değiştirmek için bir JSON dosyası oluştur
|
|
133
|
+
([config.example.json](config.example.json) örneğini kopyala). Sunucu ayar dosyasını şu sırayla arar:
|
|
134
|
+
|
|
135
|
+
1. `--config <dosya>`
|
|
136
|
+
2. `OVERLAYS_SERVER_CONFIG` ortam değişkeni
|
|
137
|
+
3. Çalışma klasöründe `overlays-server.config.json`
|
|
138
|
+
4. Kullanıcı klasörü: Windows `%APPDATA%\overlays-server\config.json`, Linux/macOS `~/.config/overlays-server/config.json`
|
|
139
|
+
|
|
140
|
+
| Anahtar | Varsayılan | Açıklama |
|
|
141
|
+
| --- | --- | --- |
|
|
142
|
+
| `port` | `3456` | Dinlenecek port |
|
|
143
|
+
| `host` | `127.0.0.1` | Dinlenecek arayüz. Başka cihazdan erişim için `0.0.0.0` (token ile) |
|
|
144
|
+
| `allowedOrigins` | overlay sitesi + localhost | Veriyi okuyabilecek web siteleri (`https://site`, `http://localhost:*`, `*`) |
|
|
145
|
+
| `token` | — | Ayarlanırsa istemciler `?token=...` göndermek zorunda |
|
|
146
|
+
| `allowedHosts` | `[]` | Ters vekil (Tailscale Serve, Caddy) arkasında kabul edilecek ek alan adları |
|
|
147
|
+
| `tls` | — | `{ "certFile", "keyFile" }`: doğrudan HTTPS / WSS sun |
|
|
148
|
+
| `staleAfterMs` | `5000` | Bu kadar süre GPS gelmezse durum `stale` olur |
|
|
149
|
+
| `gpsPriority` | `[]` | Birden fazla GPS kaynağı varsa tercih sırası (ilk sıradaki koparsa sonrakine geçer) |
|
|
150
|
+
| `motionMaxHz` | `10` | İstemci başına saniyedeki en fazla ivme mesajı |
|
|
151
|
+
| `logLevel` | `info` | `debug`, `info`, `warn`, `error`, `silent` |
|
|
152
|
+
| `rememberLastPosition` | `true` | Son konumu diske yaz; GPS yokken (tünel) ya da yeniden başlatmadan sonra onu göster |
|
|
153
|
+
| `stateFile` | kullanıcı klasöründe `last-position.json` | Son konumun saklandığı dosya |
|
|
154
|
+
| `sources` | `[{ "driver": "ddpai" }]` | Kaynak listesi; her biri `id`, `driver`, `enabled`, `options` |
|
|
155
|
+
|
|
156
|
+
Sürücü seçenekleri: [docs/devices/ddpai.md](docs/devices/ddpai.md#options), [docs/drivers.md](docs/drivers.md#simulator).
|
|
157
|
+
|
|
158
|
+
### Komut satırı
|
|
159
|
+
|
|
160
|
+
```text
|
|
161
|
+
overlays-server [seçenekler]
|
|
162
|
+
-c, --config <dosya> Ayar dosyası
|
|
163
|
+
-p, --port <port> Port (varsayılan 3456)
|
|
164
|
+
--host <adres> Dinlenecek arayüz (varsayılan 127.0.0.1)
|
|
165
|
+
--origin <origin> Ek izinli site (tekrarlanabilir)
|
|
166
|
+
--token <gizli> İstemcilerden ?token= iste
|
|
167
|
+
--allowed-host <ad> Ters vekil arkasındaki ek alan adı (tekrarlanabilir)
|
|
168
|
+
--tls-cert <dosya> HTTPS/WSS için PEM sertifika (--tls-key ile)
|
|
169
|
+
--tls-key <dosya> PEM özel anahtar
|
|
170
|
+
--ddpai-host <ip> DDPAI kamera adresi (varsayılan 193.168.0.1)
|
|
171
|
+
--ddpai-http-port <port> DDPAI HTTP API portu (varsayılan 80)
|
|
172
|
+
--simulate Kaynak yerine simülatörü kullan
|
|
173
|
+
--log-level <seviye> debug | info | warn | error | silent
|
|
174
|
+
--print-config Geçerli ayarları yazdır ve çık
|
|
175
|
+
--list-drivers Sürücüleri listele ve çık
|
|
176
|
+
--probe <adres> Cihazı incele (portlar, model, veri örnekleri), issue için rapor yazdır
|
|
177
|
+
--probe-ports <liste> --probe için portlar, virgülle (ör. 80,554,6100)
|
|
178
|
+
-v, --version / -h, --help
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
Ortam değişkenleri: `OVERLAYS_SERVER_PORT`, `OVERLAYS_SERVER_HOST`, `OVERLAYS_SERVER_LOG_LEVEL`, `OVERLAYS_SERVER_CONFIG`.
|
|
182
|
+
|
|
183
|
+
## Uç noktalar
|
|
184
|
+
|
|
185
|
+
| Yol | Açıklama |
|
|
186
|
+
| --- | --- |
|
|
187
|
+
| `GET /` | Durum sayfası |
|
|
188
|
+
| `GET /health` | Sunucu açık mı? (sürüm, kaynakların bağlantı durumu; konum yok, token istemez) |
|
|
189
|
+
| `GET /v1/state` | Tüm kaynakların durumu ve son konumu (JSON) |
|
|
190
|
+
| `WS /v1/ws` | Canlı akış (ana kanal) |
|
|
191
|
+
| `GET /v1/stream` | Canlı akış, Server-Sent Events (yedek) |
|
|
192
|
+
| `GET /v1/diagnostics` | Tanı dosyası (son ham cihaz verisi, loglar, ayarlar) |
|
|
193
|
+
|
|
194
|
+
Akış parametreleri: `source=<id|auto|*>`, `motion=1` (ivme), `events=1` (ham cihaz mesajları), `all=1`, `token=...`.
|
|
195
|
+
Mesaj biçimi: [docs/protocol.md](docs/protocol.md). **Hangi veriler var?** (konum, hız, yön, rakım, uydu, HDOP, ivme,
|
|
196
|
+
hafıza kartı, kamera sayısı, RTSP adresleri, cihaz bilgileri, ham olaylar): [docs/data.md](docs/data.md).
|
|
197
|
+
|
|
198
|
+
## Sorun giderme
|
|
199
|
+
|
|
200
|
+
**Önce durum sayfasına bak:** <http://127.0.0.1:3456>. Kaynakların bağlantı ve GPS durumu canlı görünür; konumu
|
|
201
|
+
gösterip Google Maps / Yandex / OpenStreetMap'te açabilirsin.
|
|
202
|
+
|
|
203
|
+
**Hata bildirirken tanı dosyasını ekle:** durum sayfasının altındaki **Tanı verisini indir** butonu tek bir `.json`
|
|
204
|
+
dosyası verir: cihazdan gelen son ~2 dakikalık ham veri, son log satırları, ayarlar ve durum. Bu dosyayla sorunu
|
|
205
|
+
kendi bilgisayarımızda aynen tekrar oynatıp düzeltebiliyoruz. Wi-Fi şifresi, seri numarası ve MAC adresleri her zaman
|
|
206
|
+
gizlenir; konum yalnızca **Konumu dahil et** işaretliyse eklenir (harita/konum sorunlarında gerekli). Komut satırından:
|
|
207
|
+
`curl.exe -o tani.json http://127.0.0.1:3456/v1/diagnostics`. Aynı dosya overlay ayar sayfasından da (konum kaynağı
|
|
208
|
+
*Araç kamerası GPS — overlays-server [yerel]* seçiliyken **Tanı verisini indir**) tarihli adla indirilebilir.
|
|
209
|
+
|
|
210
|
+
**Durum sayfasında `connecting` / "is this PC connected to the camera Wi-Fi?"** — Bilgisayar kameranın Wi-Fi'ına
|
|
211
|
+
bağlı değil ya da Windows `193.168.0.1`'i yanlış arayüze yolluyor. [docs/windows-network.md](docs/windows-network.md).
|
|
212
|
+
|
|
213
|
+
**`gps: no_fix`** — Kamera bağlı ama uydu kilidi yok. Açık gökyüzünde birkaç dakika bekle.
|
|
214
|
+
|
|
215
|
+
**Tünel / kapalı otopark (GPS koptu)** — Harita son bilinen konumda kalır, hız 0 görünür; sinyal gelince kaldığı
|
|
216
|
+
yerden devam eder. OBS sahnesi ya da bilgisayar bu sırada yeniden başlasa bile son konum korunur: sunucu son konumu
|
|
217
|
+
`last-position.json` dosyasında saklar ve yeni bağlanan overlay'e "son bilinen konum" olarak gönderir, overlay de
|
|
218
|
+
tarayıcıda son konumu hatırlar. Kapatmak için `"rememberLastPosition": false`.
|
|
219
|
+
|
|
220
|
+
**Overlay bir uyarı gösteriyor** — Overlay bağlanamazsa sunucunun `/health` ucuna sorup nedenini yazar:
|
|
221
|
+
|
|
222
|
+
| Overlay'deki mesaj | Ne yapmalı |
|
|
223
|
+
| --- | --- |
|
|
224
|
+
| *Yerel sunucuya ulaşılamadı* | Sunucu kapalı, adres/port yanlış ya da overlay'i açtığın site `allowedOrigins`'te değil. Durum sayfası açılıyorsa sunucunun konsoluna bak (`refused an overlay connection`) ve aşağıdaki tarayıcı izni maddesine bak |
|
|
225
|
+
| *Yerel sunucu açık ama canlı bağlantıyı reddetti* | Sunucuda `token` ayarlı: overlay ayarlarındaki *Sunucu anahtarı* alanına yaz |
|
|
226
|
+
| *Sunucu kameraya bağlanıyor…* / *Kamera uydu arıyor* | Sunucu çalışıyor; sorun kamera tarafında (Wi-Fi, uydu) |
|
|
227
|
+
|
|
228
|
+
Sunucu reddettiği her bağlantıyı konsola yazar (`refused an overlay connection: ...`). İzin verilmeyen sitelere güvenlik
|
|
229
|
+
gereği hiçbir yanıt vermediği için overlay o durumu "ulaşılamadı" olarak görür.
|
|
230
|
+
|
|
231
|
+
**Durum sayfası çalışıyor ama overlay sunucuya ulaşamıyor** — Tarayıcının *Yerel Ağ Erişimi* (Local Network Access)
|
|
232
|
+
kısıtı:
|
|
233
|
+
|
|
234
|
+
- **OBS 33.0+**: localhost erişimine otomatik izin veriyor. OBS 33 **beta** kullandıysan eski bir ret kalıcı
|
|
235
|
+
kaydedilmiş olabilir: OBS'i kapat, `%APPDATA%\obs-studio\plugin_config\obs-browser` klasörünü sil, OBS'i aç.
|
|
236
|
+
Hâlâ olmuyorsa OBS kısayolunun sonuna `--disable-features=LocalNetworkAccessChecks` ekle.
|
|
237
|
+
- **Chrome / Edge** (ayar sayfası, "Pencerede aç" modu): adres çubuğunda çıkan izin isteğinde **İzin ver** de.
|
|
238
|
+
- **Sunucu başka cihazda / alan adıyla** erişiliyorsa `wss://` gerekir: [docs/remote.md](docs/remote.md).
|
|
239
|
+
|
|
240
|
+
**`port 3456 is already in use`** — Sunucu zaten açık (ikinci pencere?) ya da port başka programda. `--port` ile değiştir
|
|
241
|
+
ve overlay ayarındaki adresi de güncelle.
|
|
242
|
+
|
|
243
|
+
## Güvenlik ve gizlilik
|
|
244
|
+
|
|
245
|
+
Canlı konum hassas bir veridir. Sunucu varsayılan olarak:
|
|
246
|
+
|
|
247
|
+
- yalnız `127.0.0.1`'i dinler (ağdaki başka cihazlar erişemez); başka bir arayüzde token'sız dinlerse uyarır,
|
|
248
|
+
- yalnız `allowedOrigins` listesindeki sitelerin veriyi okumasına izin verir; diğer sitelere CORS başlığı bile
|
|
249
|
+
göndermez (sunucunun varlığını öğrenemezler),
|
|
250
|
+
- DNS rebinding saldırılarına karşı `Host` başlığını kontrol eder (`127.0.0.1.saldirgan.com` gibi adlar dahil),
|
|
251
|
+
- kameraya **yalnız okuma** komutları gönderir, hiçbir ayarı değiştirmez,
|
|
252
|
+
- kameranın döndürdüğü Wi-Fi şifresini, seri numaralarını ve MAC adreslerini hiçbir yere yazmaz ya da iletmez.
|
|
253
|
+
|
|
254
|
+
Bunların hepsi otomatik testlerle doğrulanır (`test/security-e2e.test.ts`, `e2e/`). Ayrıntı ve açık bildirme:
|
|
255
|
+
[SECURITY.md](SECURITY.md). DDPAI kameranın **varsayılan Wi-Fi şifresini değiştir**: aynı ağa giren herkes kameranın
|
|
256
|
+
görüntüsüne ve ayarlarına erişebilir.
|
|
257
|
+
|
|
258
|
+
## Geliştirme
|
|
259
|
+
|
|
260
|
+
```bash
|
|
261
|
+
pnpm install
|
|
262
|
+
pnpm dev # kamerasız geliştirme: sahte DDPAI kamera + sunucu tek terminalde, dosya değişince yeniden başlar
|
|
263
|
+
pnpm dev:fake-camera # ya da iki terminal: 1) sahte kamera (bağlantıları loglar)
|
|
264
|
+
pnpm dev:server # 2) ona bağlanan sunucu
|
|
265
|
+
pnpm dev -- --no-fix --speed 90 --drop-every 20 # uydu yok / hız / bağlantı kopma senaryoları
|
|
266
|
+
pnpm dev -- --replay tani.json # bir yayıncının tanı dosyasını tekrar oynat
|
|
267
|
+
pnpm dev:camera # gerçek kamerayla (193.168.0.1), izleme modunda
|
|
268
|
+
pnpm check # tip kontrolü (TypeScript 7) + birim, entegrasyon ve süreç testleri
|
|
269
|
+
pnpm test:coverage # kapsama raporuyla
|
|
270
|
+
pnpm test:e2e # durum sayfası tarayıcı testleri (Playwright)
|
|
271
|
+
pnpm build # dist/ (npm paketi)
|
|
272
|
+
```
|
|
273
|
+
|
|
274
|
+
Yerelde uçtan uca test (sahte kamera + overlay sitesi + OBS): [docs/testing-locally.md](docs/testing-locally.md).
|
|
275
|
+
Mimari, kod kuralları ve yeni sürücü ekleme: [CONTRIBUTING.md](CONTRIBUTING.md), [docs/architecture.md](docs/architecture.md).
|
|
276
|
+
|
|
277
|
+
## Katkıda bulunanlar
|
|
278
|
+
|
|
279
|
+
Katkılar memnuniyetle karşılanır. Özellikle **farklı kamera modelleriyle test sonuçları** çok değerli.
|
|
280
|
+
[CONTRIBUTING.md](CONTRIBUTING.md) dosyasına göz at. Tüm katkıda bulunanlar:
|
|
281
|
+
[github.com/ramazansancar/overlays-server/graphs/contributors](https://github.com/ramazansancar/overlays-server/graphs/contributors).
|
|
282
|
+
|
|
283
|
+
## Lisans
|
|
284
|
+
|
|
285
|
+
[GNU AGPL-3.0](LICENSE) (veya sonraki sürümleri) © 2026 Ramazan Sancar.
|
|
286
|
+
|
|
287
|
+
Kısaca: ücretsiz kullanabilir, değiştirebilir, ticari işlerde de kullanabilirsin. Ama değiştirilmiş bir sürümü
|
|
288
|
+
**dağıtırsan** (paket, exe, kurulum) **ya da ağ üzerinden başkalarına hizmet olarak sunarsan**, o sürümün kaynak kodunu
|
|
289
|
+
da aynı lisansla açmak zorundasın. Durum sayfasındaki kaynak kod linkini kendi kaynağını gösterecek şekilde koru.
|
|
290
|
+
Bağlayıcı olan [LICENSE](LICENSE) metnidir.
|
|
291
|
+
|
|
292
|
+
DDPAI, DDPAI Technology Co., Ltd.'nin markasıdır; bu proje onlarla bağlantılı değildir.
|
package/README.md
CHANGED
|
@@ -1,3 +1,296 @@
|
|
|
1
|
-
#
|
|
1
|
+
# overlays-server
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
**English** · [Türkçe](README-tr.md)
|
|
4
|
+
|
|
5
|
+
A small **local bridge server** that runs on the streamer's PC (or on a Raspberry Pi in the car). It reads live GPS
|
|
6
|
+
from a dashcam (currently **DDPAI**) and streams it once per second over WebSocket to the
|
|
7
|
+
[Stream Overlays](https://overlays.ramazansancar.com.tr) map overlay. No phone, no cloud service, no RealtimeIRL: the
|
|
8
|
+
position comes straight from the camera over the local network.
|
|
9
|
+
|
|
10
|
+
```text
|
|
11
|
+
DDPAI camera (Wi-Fi, 193.168.0.1:6100) ──► overlays-server (127.0.0.1:3456) ──► OBS browser source (map)
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
- **Live position, speed, heading, altitude, satellites, GPS quality** — from the camera's own GPS, 1 Hz.
|
|
15
|
+
- **Everything the device offers** — acceleration (G-sensor), memory card usage, camera count, RTSP URLs, device
|
|
16
|
+
details, unknown messages passed through raw. Overlays use what they need: [docs/data.md](docs/data.md).
|
|
17
|
+
- **No empty map in tunnels** — when GPS drops, the last known position is used, even across restarts.
|
|
18
|
+
- **On another device / over a VPN** — Raspberry Pi, Tailscale/WireGuard, your own domain (with token + TLS):
|
|
19
|
+
[docs/remote.md](docs/remote.md).
|
|
20
|
+
- **Modular drivers** — a new camera / GPS device is one module ([docs/drivers.md](docs/drivers.md)).
|
|
21
|
+
- **Self-healing** — reconnects when the camera restarts or its Wi-Fi drops.
|
|
22
|
+
- **Privacy first** — listens on `127.0.0.1` by default, only allowed websites can read the data.
|
|
23
|
+
- **One runtime dependency** (`ws`), Node.js 22.18+.
|
|
24
|
+
|
|
25
|
+
## Supported devices
|
|
26
|
+
|
|
27
|
+
| Device | Driver | Status |
|
|
28
|
+
| --- | --- | --- |
|
|
29
|
+
| DDPAI N5 Pro (firmware v8.0.0.10) | `ddpai` | Field tested |
|
|
30
|
+
| Other DDPAI models with TCP 6100 telemetry | `ddpai` | Very likely; try it and [report](https://github.com/ramazansancar/overlays-server/issues/new?template=device-report.yml) |
|
|
31
|
+
| Simulator (no hardware) | `simulator` | — |
|
|
32
|
+
|
|
33
|
+
Device details and tested environments: [docs/devices/](docs/devices/README.md).
|
|
34
|
+
**Your device is not listed?** [New device guide](docs/new-device.md): inspect it with one command (`--probe`) and
|
|
35
|
+
send the report as an issue.
|
|
36
|
+
|
|
37
|
+
## Install
|
|
38
|
+
|
|
39
|
+
Two ways, both run the same server. Requires **Node.js 22.18 or newer** ([nodejs.org](https://nodejs.org)).
|
|
40
|
+
|
|
41
|
+
### A) With npm (easiest)
|
|
42
|
+
|
|
43
|
+
```bash
|
|
44
|
+
npx overlays-server@latest
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
`@latest` checks npm for the newest version on every start (plain `npx overlays-server` may reuse an older download).
|
|
48
|
+
To install it permanently:
|
|
49
|
+
|
|
50
|
+
```bash
|
|
51
|
+
npm install -g overlays-server
|
|
52
|
+
overlays-server
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
**Updating (permanent install):**
|
|
56
|
+
|
|
57
|
+
```bash
|
|
58
|
+
overlays-server --version # installed version
|
|
59
|
+
npm outdated -g overlays-server # is there a newer one? (no output = up to date)
|
|
60
|
+
npm install -g overlays-server@latest
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
Uninstall: `npm uninstall -g overlays-server`.
|
|
64
|
+
|
|
65
|
+
### B) With git (from source)
|
|
66
|
+
|
|
67
|
+
```bash
|
|
68
|
+
git clone https://github.com/ramazansancar/overlays-server.git
|
|
69
|
+
cd overlays-server
|
|
70
|
+
npm install --omit=dev # or: pnpm install --prod
|
|
71
|
+
npm start
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
On Windows, double-clicking **`start.cmd`** in the folder is enough: on every start it updates itself with `git pull`,
|
|
75
|
+
installs dependencies when needed, then starts the server. Without internet it warns and starts the current version;
|
|
76
|
+
set `OVERLAYS_SERVER_NO_UPDATE=1` to skip the update.
|
|
77
|
+
|
|
78
|
+
**Updating (git install):** nothing to do when you use `start.cmd`. By hand:
|
|
79
|
+
|
|
80
|
+
```bash
|
|
81
|
+
cd overlays-server
|
|
82
|
+
git pull
|
|
83
|
+
npm install --omit=dev # updates dependencies if they changed
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
A specific version: `git fetch --tags && git checkout v0.1.0`. Changes: [CHANGELOG.md](CHANGELOG.md).
|
|
87
|
+
|
|
88
|
+
There is no build step: Node.js 22.18+ runs the TypeScript files directly.
|
|
89
|
+
|
|
90
|
+
### Check that it works
|
|
91
|
+
|
|
92
|
+
Open **<http://127.0.0.1:3456>** in a browser. The status page shows live whether the camera is connected and the GPS
|
|
93
|
+
state (coordinates are hidden by default, so it can be shown on stream).
|
|
94
|
+
|
|
95
|
+
## Usage
|
|
96
|
+
|
|
97
|
+
1. **Connect the PC to the camera's Wi-Fi** (`DDPAI_...` network). Internet should keep coming over Ethernet (e.g. a
|
|
98
|
+
4.5G/5G router). Windows setup: [docs/windows-network.md](docs/windows-network.md).
|
|
99
|
+
2. **Start overlays-server** (either way above). The console shows `ddpai: link online` and `ddpai: gps fix`.
|
|
100
|
+
3. In the **[overlay settings](https://overlays.ramazansancar.com.tr)** pick **Dashcam GPS — overlays-server [local]**
|
|
101
|
+
as the map overlay's *Location source*. The *Server address* (`127.0.0.1`) and *Server port* (`3456`) below it can
|
|
102
|
+
stay as they are for the default setup. Then add the URL as an OBS browser source.
|
|
103
|
+
|
|
104
|
+
To try everything without a camera: `npx overlays-server@latest --simulate` (a fake position driving in circles in
|
|
105
|
+
Ankara).
|
|
106
|
+
|
|
107
|
+
### On another device or over a VPN
|
|
108
|
+
|
|
109
|
+
The server can run on a Raspberry Pi, another computer or somewhere remote; the overlay (OBS on the streaming PC or
|
|
110
|
+
in the cloud) reaches it by LAN IP, VPN IP or a domain / public IP. In short:
|
|
111
|
+
|
|
112
|
+
| Setup | Server | Overlay settings |
|
|
113
|
+
| --- | --- | --- |
|
|
114
|
+
| Pi on the same LAN / VPN IP | `"host": "0.0.0.0"`, `"token"` | Pi's IP, port, token |
|
|
115
|
+
| Tailscale + HTTPS (recommended) | `tailscale serve --https=443 http://127.0.0.1:3456`, `"allowedHosts"` | `pi.<tailnet>.ts.net`, `443`, **Secure connection** |
|
|
116
|
+
| Public IP / domain | `"host": "0.0.0.0"`, `"token"`, `"tls"` or Caddy/Nginx | domain, port, token, **Secure connection** |
|
|
117
|
+
|
|
118
|
+
**Always use a token** when listening on anything other than `127.0.0.1`. Full guide with systemd and Caddy examples:
|
|
119
|
+
[docs/remote.md](docs/remote.md).
|
|
120
|
+
|
|
121
|
+
### Start with Windows
|
|
122
|
+
|
|
123
|
+
`Win + R` → `shell:startup` → put a shortcut to `start.cmd` (git install) or to a `.cmd` file with this content in
|
|
124
|
+
that folder:
|
|
125
|
+
|
|
126
|
+
```bat
|
|
127
|
+
@echo off
|
|
128
|
+
npx overlays-server@latest
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
## Configuration
|
|
132
|
+
|
|
133
|
+
The defaults fit most setups. To change them, create a JSON file (copy [config.example.json](config.example.json)).
|
|
134
|
+
The server looks for it in this order:
|
|
135
|
+
|
|
136
|
+
1. `--config <file>`
|
|
137
|
+
2. the `OVERLAYS_SERVER_CONFIG` environment variable
|
|
138
|
+
3. `overlays-server.config.json` in the working directory
|
|
139
|
+
4. the user folder: Windows `%APPDATA%\overlays-server\config.json`, Linux/macOS `~/.config/overlays-server/config.json`
|
|
140
|
+
|
|
141
|
+
| Key | Default | Description |
|
|
142
|
+
| --- | --- | --- |
|
|
143
|
+
| `port` | `3456` | Port to listen on |
|
|
144
|
+
| `host` | `127.0.0.1` | Interface to listen on. `0.0.0.0` for access from other devices (with a token) |
|
|
145
|
+
| `allowedOrigins` | overlay site + localhost | Websites allowed to read the data (`https://site`, `http://localhost:*`, `*`) |
|
|
146
|
+
| `token` | — | When set, clients must send `?token=...` |
|
|
147
|
+
| `allowedHosts` | `[]` | Extra host names accepted behind a reverse proxy (Tailscale Serve, Caddy) |
|
|
148
|
+
| `tls` | — | `{ "certFile", "keyFile" }`: serve HTTPS / WSS directly |
|
|
149
|
+
| `staleAfterMs` | `5000` | A source without GPS for this long is `stale` |
|
|
150
|
+
| `gpsPriority` | `[]` | Preference order with several GPS sources (falls back when the first drops) |
|
|
151
|
+
| `motionMaxHz` | `10` | Maximum acceleration messages per client per second |
|
|
152
|
+
| `logLevel` | `info` | `debug`, `info`, `warn`, `error`, `silent` |
|
|
153
|
+
| `rememberLastPosition` | `true` | Keep the last position on disk; show it while GPS is lost (tunnel) or after a restart |
|
|
154
|
+
| `stateFile` | `last-position.json` in the user folder | Where the last position is kept |
|
|
155
|
+
| `sources` | `[{ "driver": "ddpai" }]` | List of sources; each has `id`, `driver`, `enabled`, `options` |
|
|
156
|
+
|
|
157
|
+
Driver options: [docs/devices/ddpai.md](docs/devices/ddpai.md#options), [docs/drivers.md](docs/drivers.md#simulator).
|
|
158
|
+
|
|
159
|
+
### Command line
|
|
160
|
+
|
|
161
|
+
```text
|
|
162
|
+
overlays-server [options]
|
|
163
|
+
-c, --config <file> Config file
|
|
164
|
+
-p, --port <port> Port (default 3456)
|
|
165
|
+
--host <address> Interface to listen on (default 127.0.0.1)
|
|
166
|
+
--origin <origin> Extra allowed website (repeatable)
|
|
167
|
+
--token <secret> Require ?token= from clients
|
|
168
|
+
--allowed-host <name> Extra host name behind a reverse proxy (repeatable)
|
|
169
|
+
--tls-cert <file> PEM certificate for HTTPS/WSS (with --tls-key)
|
|
170
|
+
--tls-key <file> PEM private key
|
|
171
|
+
--ddpai-host <ip> DDPAI camera address (default 193.168.0.1)
|
|
172
|
+
--ddpai-http-port <port> DDPAI HTTP API port (default 80)
|
|
173
|
+
--simulate Use the simulator instead of the configured sources
|
|
174
|
+
--log-level <level> debug | info | warn | error | silent
|
|
175
|
+
--print-config Print the effective config and exit
|
|
176
|
+
--list-drivers List drivers and exit
|
|
177
|
+
--probe <address> Inspect a device (ports, model, data samples) and print a report for an issue
|
|
178
|
+
--probe-ports <list> Ports for --probe, comma separated (e.g. 80,554,6100)
|
|
179
|
+
-v, --version / -h, --help
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
Environment variables: `OVERLAYS_SERVER_PORT`, `OVERLAYS_SERVER_HOST`, `OVERLAYS_SERVER_LOG_LEVEL`, `OVERLAYS_SERVER_CONFIG`.
|
|
183
|
+
|
|
184
|
+
## Endpoints
|
|
185
|
+
|
|
186
|
+
| Path | Description |
|
|
187
|
+
| --- | --- |
|
|
188
|
+
| `GET /` | Status page |
|
|
189
|
+
| `GET /health` | Is the server up? (version, per-source state; no position, no token needed) |
|
|
190
|
+
| `GET /v1/state` | Every source's state and last position (JSON) |
|
|
191
|
+
| `WS /v1/ws` | Live stream (main channel) |
|
|
192
|
+
| `GET /v1/stream` | Live stream, Server-Sent Events (fallback) |
|
|
193
|
+
| `GET /v1/diagnostics` | Diagnostics file (recent raw device data, logs, settings) |
|
|
194
|
+
|
|
195
|
+
Stream parameters: `source=<id|auto|*>`, `motion=1` (acceleration), `events=1` (raw device messages), `all=1`,
|
|
196
|
+
`token=...`. Message format: [docs/protocol.md](docs/protocol.md). **What data is there?** (position, speed, heading,
|
|
197
|
+
altitude, satellites, HDOP, acceleration, memory card, camera count, RTSP URLs, device details, raw events):
|
|
198
|
+
[docs/data.md](docs/data.md).
|
|
199
|
+
|
|
200
|
+
## Troubleshooting
|
|
201
|
+
|
|
202
|
+
**Look at the status page first:** <http://127.0.0.1:3456>. Connection and GPS state of every source are live there;
|
|
203
|
+
you can show the position and open it in Google Maps / Yandex / OpenStreetMap.
|
|
204
|
+
|
|
205
|
+
**Attach a diagnostics file to bug reports:** the **Download diagnostics** button at the bottom of the status page
|
|
206
|
+
gives one `.json` file: the last ~2 minutes of raw device data, recent log lines, settings and state. With it we can
|
|
207
|
+
replay the problem exactly on our machine and fix it. Wi-Fi passwords, serial numbers and MAC addresses are always
|
|
208
|
+
removed; the position only when **Include my position** is ticked (needed for map / position problems). From the
|
|
209
|
+
command line: `curl -o diagnostics.json http://127.0.0.1:3456/v1/diagnostics`. The overlay settings page offers the
|
|
210
|
+
same download (with the local server selected as location source), named with the date and time.
|
|
211
|
+
|
|
212
|
+
**Status page says `connecting` / "is this PC connected to the camera Wi-Fi?"** — the PC is not on the camera's Wi-Fi,
|
|
213
|
+
or Windows sends `193.168.0.1` to the wrong adapter. [docs/windows-network.md](docs/windows-network.md).
|
|
214
|
+
|
|
215
|
+
**`gps: no_fix`** — the camera is connected but has no satellite lock. Wait a few minutes under open sky.
|
|
216
|
+
|
|
217
|
+
**Tunnel / underground car park (GPS lost)** — the map stays at the last known position with speed 0 and continues
|
|
218
|
+
when the signal returns. Even if OBS or the PC restarts meanwhile, the position is kept: the server stores it in
|
|
219
|
+
`last-position.json` and sends it to newly connected overlays as "last known position", and the overlay also remembers
|
|
220
|
+
it in the browser. Turn off with `"rememberLastPosition": false`.
|
|
221
|
+
|
|
222
|
+
**The overlay shows a warning** — when it cannot connect, the overlay asks the server's `/health` and says why:
|
|
223
|
+
|
|
224
|
+
| Overlay message | What to do |
|
|
225
|
+
| --- | --- |
|
|
226
|
+
| *Cannot reach the local server* | Server not running, wrong address/port, or the site you opened the overlay from is not in `allowedOrigins`. If the status page opens, check the server console (`refused an overlay connection`) and the browser permission point below |
|
|
227
|
+
| *Local server is up but refused the live connection* | The server has a `token`: enter it in the overlay settings' *Server token* field |
|
|
228
|
+
| *Server is connecting to the camera…* / *Camera is searching satellites* | The server works; the problem is on the camera side (Wi-Fi, satellites) |
|
|
229
|
+
|
|
230
|
+
The server logs every refused connection (`refused an overlay connection: ...`). It does not answer websites that are
|
|
231
|
+
not allowed at all (for security), so the overlay sees that case as "cannot reach".
|
|
232
|
+
|
|
233
|
+
**Status page works but the overlay cannot reach the server** — the browser's *Local Network Access* restriction:
|
|
234
|
+
|
|
235
|
+
- **OBS 33.0+** allows localhost automatically. If you ran an OBS 33 **beta**, an old denial may be stored: close OBS,
|
|
236
|
+
delete `%APPDATA%\obs-studio\plugin_config\obs-browser`, start OBS. Still failing: add
|
|
237
|
+
`--disable-features=LocalNetworkAccessChecks` to the OBS shortcut.
|
|
238
|
+
- **Chrome / Edge** (settings page, "open in window" mode): click **Allow** on the permission prompt.
|
|
239
|
+
- **Server on another device / reached by domain:** needs `wss://`, see [docs/remote.md](docs/remote.md).
|
|
240
|
+
|
|
241
|
+
**`port 3456 is already in use`** — the server is already running (second window?) or another program uses the port.
|
|
242
|
+
Change it with `--port` and update the address in the overlay settings.
|
|
243
|
+
|
|
244
|
+
## Security and privacy
|
|
245
|
+
|
|
246
|
+
A live position is sensitive. By default the server:
|
|
247
|
+
|
|
248
|
+
- listens on `127.0.0.1` only (other devices cannot reach it) and warns when it listens elsewhere without a token,
|
|
249
|
+
- lets only websites in `allowedOrigins` read the data and sends no CORS headers to any other site (they cannot even
|
|
250
|
+
detect it),
|
|
251
|
+
- checks the `Host` header against DNS rebinding (including names like `127.0.0.1.attacker.example`),
|
|
252
|
+
- sends the camera **read-only** commands and never changes its settings,
|
|
253
|
+
- never stores or forwards the Wi-Fi password, serial numbers or MAC addresses the camera reports.
|
|
254
|
+
|
|
255
|
+
All of this is covered by automated tests (`test/security-e2e.test.ts`, `e2e/`). Details and reporting
|
|
256
|
+
vulnerabilities: [SECURITY.md](SECURITY.md). **Change the DDPAI camera's default Wi-Fi password**: anyone on that
|
|
257
|
+
network can see the camera's video and use its settings.
|
|
258
|
+
|
|
259
|
+
## Development
|
|
260
|
+
|
|
261
|
+
```bash
|
|
262
|
+
pnpm install
|
|
263
|
+
pnpm dev # no camera needed: fake DDPAI camera + server in one terminal, restarts on file changes
|
|
264
|
+
pnpm dev:fake-camera # or two terminals: 1) fake camera (logs connections)
|
|
265
|
+
pnpm dev:server # 2) a server connected to it
|
|
266
|
+
pnpm dev -- --no-fix --speed 90 --drop-every 20 # no satellites / speed / dropped connection scenarios
|
|
267
|
+
pnpm dev -- --replay diagnostics.json # replay a streamer's diagnostics file
|
|
268
|
+
pnpm dev:camera # with the real camera (193.168.0.1), watch mode
|
|
269
|
+
pnpm check # typecheck (TypeScript 7) + unit, integration and process tests
|
|
270
|
+
pnpm test:coverage # with a coverage report
|
|
271
|
+
pnpm test:e2e # status page browser tests (Playwright)
|
|
272
|
+
pnpm build # dist/ (npm package)
|
|
273
|
+
```
|
|
274
|
+
|
|
275
|
+
End-to-end testing on your machine (fake camera + overlay site + OBS): [docs/testing-locally.md](docs/testing-locally.md).
|
|
276
|
+
Architecture, code guidelines and adding a driver: [CONTRIBUTING.md](CONTRIBUTING.md),
|
|
277
|
+
[docs/architecture.md](docs/architecture.md).
|
|
278
|
+
|
|
279
|
+
## Contributors
|
|
280
|
+
|
|
281
|
+
Contributions are welcome, especially **test reports from other camera models**. See
|
|
282
|
+
[CONTRIBUTING.md](CONTRIBUTING.md). Everyone who contributed:
|
|
283
|
+
[github.com/ramazansancar/overlays-server/graphs/contributors](https://github.com/ramazansancar/overlays-server/graphs/contributors).
|
|
284
|
+
|
|
285
|
+
Translations of this README are welcome: `README-<language>.md`, with a region where it matters
|
|
286
|
+
(`README-pt-BR.md`, `README-zh-TW.md`), plus a link in the language line at the top of every README.
|
|
287
|
+
|
|
288
|
+
## License
|
|
289
|
+
|
|
290
|
+
[GNU AGPL-3.0](LICENSE) (or any later version) © 2026 Ramazan Sancar.
|
|
291
|
+
|
|
292
|
+
In short: free to use, modify and use commercially. But if you **distribute** a modified version (package, exe,
|
|
293
|
+
installer) **or offer it to others over a network**, you must publish its source under the same license. Keep the
|
|
294
|
+
status page's source link pointing to your code. The [LICENSE](LICENSE) text is binding.
|
|
295
|
+
|
|
296
|
+
DDPAI is a trademark of DDPAI Technology Co., Ltd.; this project is not affiliated with them.
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
{
|
|
2
|
+
"port": 3456,
|
|
3
|
+
"host": "127.0.0.1",
|
|
4
|
+
"allowedOrigins": [
|
|
5
|
+
"https://overlays.ramazansancar.com.tr",
|
|
6
|
+
"http://localhost:*",
|
|
7
|
+
"http://127.0.0.1:*"
|
|
8
|
+
],
|
|
9
|
+
"staleAfterMs": 5000,
|
|
10
|
+
"motionMaxHz": 10,
|
|
11
|
+
"logLevel": "info",
|
|
12
|
+
"rememberLastPosition": true,
|
|
13
|
+
"gpsPriority": ["ddpai"],
|
|
14
|
+
"sources": [
|
|
15
|
+
{
|
|
16
|
+
"id": "ddpai",
|
|
17
|
+
"driver": "ddpai",
|
|
18
|
+
"enabled": true,
|
|
19
|
+
"options": {
|
|
20
|
+
"host": "193.168.0.1",
|
|
21
|
+
"telemetryPort": 6100,
|
|
22
|
+
"httpPort": 80,
|
|
23
|
+
"deviceInfo": true,
|
|
24
|
+
"motion": true,
|
|
25
|
+
"idleTimeoutMs": 6000
|
|
26
|
+
}
|
|
27
|
+
},
|
|
28
|
+
{
|
|
29
|
+
"id": "simulator",
|
|
30
|
+
"driver": "simulator",
|
|
31
|
+
"enabled": false,
|
|
32
|
+
"options": {
|
|
33
|
+
"lat": 39.92077,
|
|
34
|
+
"lon": 32.85411,
|
|
35
|
+
"radiusM": 300,
|
|
36
|
+
"speedKmh": 40
|
|
37
|
+
}
|
|
38
|
+
}
|
|
39
|
+
]
|
|
40
|
+
}
|
package/dist/app.d.ts
ADDED
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
import type { AppConfig } from './config.ts';
|
|
2
|
+
import type { AnyDriver } from './core/driver.ts';
|
|
3
|
+
import { Hub } from './core/hub.ts';
|
|
4
|
+
import { type Logger } from './lib/log.ts';
|
|
5
|
+
export interface StartOptions {
|
|
6
|
+
config: AppConfig;
|
|
7
|
+
/** Drivers to use; defaults to the built-in ones. Pass your own list to add third-party drivers. */
|
|
8
|
+
drivers?: readonly AnyDriver[];
|
|
9
|
+
log?: Logger;
|
|
10
|
+
}
|
|
11
|
+
export interface RunningServer {
|
|
12
|
+
/** Base URL, e.g. `http://127.0.0.1:3456`. */
|
|
13
|
+
url: string;
|
|
14
|
+
port: number;
|
|
15
|
+
hub: Hub;
|
|
16
|
+
close(): Promise<void>;
|
|
17
|
+
}
|
|
18
|
+
/** Builds every enabled source, starts the HTTP/WebSocket server, then starts the sources. */
|
|
19
|
+
export declare function startServer(options: StartOptions): Promise<RunningServer>;
|