Devices (Ingest)
Mendaftarkan kamera, file, dan live stream media sosial sebagai device Liodra, lalu memantau siklus hidup prosesnya.
Pengenalan
Device adalah unit kerja dasar Liodra: satu sumber video yang ditarik oleh satu proses ingest terisolasi dan dipublish sebagai stream {channel}/{name}. Semua fitur lain (rekaman, playback, live viewing, retensi) bekerja di atas device.
Identitas device adalah pasangan channel/name. URL sumber hanyalah atribut, sehingga Anda bisa mengganti URL kamera tanpa mengubah identitas (dan tanpa memutus riwayat rekamannya).
| Scheme | Sumber | Contoh URL |
|---|---|---|
rtsp | Kamera IP, NVR, encoder | rtsp://user:[email protected]:554/Streaming/Channels/101 |
rtmp | Encoder atau server RTMP lain | rtmp://encoder.local/live/cam01 |
file | File video di dalam container (di-loop terus) | /usr/share/nginx/html/storage/vods/test.mp4 |
http / https | HTTP-FLV, HTTP-TS, HLS, atau file HTTP | https://cdn.example.com/live/cam.m3u8 |
social | Live stream YouTube, TikTok, Instagram, Twitch | https://www.youtube.com/watch?v=... |
Scheme ditentukan oleh segmen URL endpoint (POST /api/v1/devices/{scheme}), bukan oleh body. Channel default adalah live.
Di Lenz, device dibuat otomatis saat operator mengaktifkan Aktifkan Recording pada sebuah stream: name = stream_id Visionaire, channel = live, scheme mengikuti prefiks URL kamera. Lihat Integrasi dengan Lenz.
Cara Menggunakan
Tambahkan device
curl -X POST http://localhost:9080/api/v1/devices/rtsp \
-H 'Content-Type: application/json' \
-d '{
"name": "camera_front",
"url": "rtsp://admin:[email protected]:554/Streaming/Channels/101",
"channel": "live",
"silent_audio": true
}'Respons 201 Created berisi status awal starting. Beberapa detik kemudian status menjadi active begitu proses ingest berhasil mem-publish stream.
Periksa statusnya
curl http://localhost:9080/api/v1/devices/rtsp/live/camera_frontPerhatikan field status, message, error_count, restart_count, dan srs_stream (codec, resolusi, jumlah klien yang menonton). Untuk memantau banyak device sekaligus, gunakan GET /api/v1/devices atau WebSocket /ws/v1/monitor/devices.
Tonton atau rekam
Begitu active, stream tersedia di semua protokol keluaran (lihat Live Streaming), dan bila Liodra berjalan dengan --as-nvr, DVR mulai menulis segmen ke recordings/live/camera_front/ (lihat Recordings).
Kelola siklus hidupnya
- Ganti URL tanpa mengubah identitas:
PATCH /api/v1/devices/rtsp/live/camera_frontdengan{ "url": "rtsp://..." }. - Restart proses ingest:
POST .../restart. - Hentikan sementara (device tetap terdaftar, tidak di-restart otomatis):
POST .../stop. - Hapus device dan hentikan prosesnya:
DELETE .../live/camera_front. Rekaman yang sudah ada tidak ikut dihapus; gunakanDELETE /api/v1/recordings/{path}bila diperlukan.
Fitur Utama
Idempoten berdasarkan channel/name
Mengirim POST dengan name dan url yang sama persis tidak membuat duplikat: Liodra mengembalikan device yang ada (dan menyalakannya kembali bila statusnya stopped). name yang sama dengan url berbeda ditolak 409 Conflict; gunakan PATCH untuk memindahkan device ke URL baru.
Channel dan perekaman
channel boleh bertingkat (live/gedung-a, live/hls/camera_01). Ada tiga keluarga channel dengan perilaku berbeda:
| Channel | Direkam? | Kegunaan |
|---|---|---|
live, live/..., dan channel lain | Ya (bila --as-nvr) | Kamera CCTV dan sumber yang perlu diarsipkan |
vod | Tidak | Video hasil unggah yang diputar ulang sebagai stream (lihat VoD) |
vop/{platform} | Tidak | Live stream media sosial. Kirim channel: "vop" dan Liodra mendeteksi platform dari URL, misalnya menjadi vop/youtube |
Channel vod dan vop/* disajikan lewat host virtual terpisah. Saat menarik stream-nya lewat RTMP atau HTTP-TS langsung (port 1935/8080), sertakan ?vhost=vod atau ?vhost=vop pada URL. Endpoint GET /api/v1/play/ts/{path} dan RTSP 8554 menanganinya otomatis.
Auto-restart dan suspend
Setiap device dijaga oleh supervisor:
- Setelah proses ingest berhenti, Liodra menunggu
AUTO_RESTART_GRACE(10 s), lalu me-restart dengan backoff eksponensialAUTO_RESTART_BACKOFF_BASE(2 s) sampaiAUTO_RESTART_BACKOFF_MAX(60 s), ditambah jitter acak sampaiRESTART_JITTER_MAX(2 s). - Paling banyak
AUTO_RESTART_CONCURRENCY(2) restart berjalan bersamaan agar puluhan kamera yang putus serentak tidak membanjiri CPU. - Bila sebuah device gagal terus selama
SUSPEND_THRESHOLD(60 s), device masuk mode suspended (suspended: true). Liodra hanya melakukan probe ringan tiapSUSPEND_PROBE_INTERVAL(10 s) dan menyalakan ingest kembali begitu sumbernya bisa dijangkau.
Device yang dihentikan lewat POST .../stop tidak ikut siklus ini sampai di-restart secara eksplisit. Semua nilai dapat diubah lewat variabel lingkungan.
silent_audio
Default true: audio kamera diganti dengan trek audio hening agar semua stream punya trek audio yang konsisten (beberapa pemutar dan pipeline menolak stream tanpa audio) tanpa merekam suara lingkungan. Set false bila audio asli memang dibutuhkan.
Persistensi
Daftar device disimpan ke recordings.yaml di volume storage secara berkala (DEVICE_PERSISTENCE_INTERVAL, 60 s) dan pada setiap perubahan. Saat container di-restart, semua device dinyalakan kembali dengan jitter awal (INITIAL_LAUNCH_JITTER_MAX, 500 ms) agar tidak bertabrakan.
Status dan field penting
| Field | Arti |
|---|---|
status | starting, active, error, atau stopped |
message | Pesan terakhir dari supervisor (mis. alasan error) |
warning | Peringatan non-fatal, mis. [EncoderLag] saat transcode eksperimental tertinggal |
error_count / restart_count | Akumulasi sejak device dibuat |
suspended | true saat berada dalam mode suspend |
last_seen | Terakhir kali proses ingest terlihat hidup |
uptime | Durasi proses ingest saat ini |
publish_url | URL RTMP internal tujuan publish |
srs_stream | Ringkasan stream dari media engine: codec video/audio, resolusi, jumlah klien |
API Reference
Detail request dan response setiap endpoint ada di halaman API Reference: Devices.
| Method | Path | Fungsi |
|---|---|---|
GET | /api/v1/devices | Semua device di semua scheme |
GET | /api/v1/devices/{scheme} | Device dengan scheme tertentu |
POST | /api/v1/devices/{scheme} | Tambah device |
GET | /api/v1/devices/{scheme}/{channel}/{name} | Detail satu device |
PATCH | /api/v1/devices/{scheme}/{channel}/{name} | Ubah url dan/atau silent_audio |
DELETE | /api/v1/devices/{scheme}/{channel}/{name} | Hapus device |
POST | /api/v1/devices/{scheme}/{channel}/{name}/restart | Restart proses |
POST | /api/v1/devices/{scheme}/{channel}/{name}/stop | Hentikan proses |
Tips & Troubleshooting
Selanjutnya
Integrasi dengan Lenz & Visionaire
Posisi Liodra dalam platform Nodeflux, cara mendaftarkannya sebagai Media Server (Visionaire Media) di Lenz, pemetaan endpoint Lenz ke Liodra, dan cara memakai stream Liodra sebagai sumber Visionaire.
API Reference: Devices
Endpoint untuk mendaftarkan, memeriksa, memperbarui, me-restart, menghentikan, dan menghapus device ingest Liodra.