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:pass@10.0.0.12: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:pass@10.0.0.12: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_front

Perhatikan 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_front dengan { "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; gunakan DELETE /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 eksponensial AUTO_RESTART_BACKOFF_BASE (2 s) sampai AUTO_RESTART_BACKOFF_MAX (60 s), ditambah jitter acak sampai RESTART_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 tiap SUSPEND_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

Devices (Ingest)

Pengenalan

Cara Menggunakan

Tambahkan device

Periksa statusnya

Tonton atau rekam

Kelola siklus hidupnya

Fitur Utama

Idempoten berdasarkan `channel/name`

Channel dan perekaman

Auto-restart dan suspend

`silent_audio`

Persistensi

Status dan field penting

API Reference

Tips & Troubleshooting

Selanjutnya

API Reference: Devices

Live Streaming

Recordings & Playback

Monitoring

On this page

Devices (Ingest)

Semua endpoint /devices mengembalikan 404

Status tetap `starting` lalu berubah ke `error`

`suspended: true` dan tidak pernah pulih

409 Conflict saat menambah device

Stream vod/vop tidak bisa ditarik lewat RTMP langsung

Ratusan kamera: apa yang perlu disiapkan?

API Reference: Devices

Live Streaming

Recordings & Playback

Monitoring

On this page