Developer Guide

Visionaire4 menyediakan REST API dan WebSocket API yang dapat digunakan langsung oleh developer untuk membangun aplikasi berbasis analitik video. Panduan ini menjelaskan semua endpoint umum yang tidak spesifik terhadap modul analitik tertentu.

Konsep Dasar

Sebelum menggunakan API, pahami empat entitas inti Visionaire4:

• Node — Unit komputasi dalam cluster. Deployment single-server menggunakan node_num=0. Setiap node mengelola sumber daya GPU/CPU-nya sendiri.
• Stream — Sumber video yang terhubung ke node (RTSP, file, USB). Setiap stream memiliki stream_id unik dan dapat menjalankan beberapa pipeline secara paralel.
• Pipeline — Instansi modul analitik yang berjalan pada stream tertentu. Pipeline dikonfigurasi saat pembuatan dan menghasilkan event secara real-time.
• Analytic — Modul analitik yang terinstal (misalnya NFV4-FR, NFV4-LPR3). Setiap modul memerlukan lisensi seat yang aktif.
• Event — Hasil deteksi yang dihasilkan pipeline, dikirim via WebSocket event channel ke aplikasi yang subscribe.

Arsitektur API

Hampir seluruh endpoint Visionaire4 mengikuti pola URL hierarkis yang mencerminkan relasi entitas di atas:

/{resource}/{node_num}/{stream_id}/{analytic_id}

• node_num selalu menjadi segmen pertama setelah resource karena setiap Stream secara fisik berada pada satu Node tertentu — penempatan ini memungkinkan master me-routing operasi langsung ke worker yang tepat tanpa pencarian tambahan.
• stream_id menjadi segmen kedua karena setiap Pipeline berjalan dalam konteks Stream tertentu. Stream tidak dapat diakses lintas-node — stream_id selalu di-scope pada node_num tempatnya dibuat.
• analytic_id menjadi segmen terakhir karena Pipeline merupakan kombinasi unik antara Stream dan modul analitik. Satu Stream dapat menjalankan banyak Pipeline berbeda secara bersamaan, tetapi setiap pasangan (stream_id, analytic_id) hanya boleh ada satu instance.

Endpoint yang lebih luas (mis. GET /streams/, WS /event_channel/) mengabaikan segmen-segmen yang lebih dalam untuk melakukan agregasi lintas Node atau Stream.

Base URL & Otentikasi

Visionaire4 berjalan pada port 4004 secara default:

http://<host>:4004

Otentikasi: Tidak diperlukan secara default. Untuk deployment produksi, pastikan akses ke port 4004 dibatasi via firewall atau reverse proxy.

CORS: Diaktifkan secara default (--enable-cors). Semua origin diizinkan. Dapat dinonaktifkan dengan flag --disable-cors=true saat menjalankan aplikasi.

Format Respons

Respons Sukses

{
  "code": 200,
  "message": "stream successfully created",
  "ok": true,
  "stream_id": "5136c6c0916cd30c"
}

Respons Error

{
  "code": 400,
  "message": "Invalid stream_address"
}

Kode HTTP Umum

Quick Start

curl -X POST http://localhost:4004/streams/0 \
  -H "Content-Type: application/json" \
  -d '{
    "stream_address": "rtsp://10.7.2.50:554/stream",
    "stream_name": "Camera Lobby"
  }'

curl -X POST http://localhost:4004/pipeline/0/<stream_id>/NFV4-FR \
  -H "Content-Type: application/json" \
  -d '{"mode": 0}'

curl -X POST http://localhost:4004/pipeline/0/<stream_id>/NFV4-LPR3 \
  -H "Content-Type: application/json" \
  -d '{}'

curl -X POST http://localhost:4004/pipeline/0/<stream_id>/NFV4-MPA \
  -H "Content-Type: application/json" \
  -d '{}'

const ws = new WebSocket('ws://localhost:4004/event_channel/0/<stream_id>');

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Event diterima:', data.analytic_id, data.primary_text);
};

wscat -c ws://localhost:4004/event_channel/

http://localhost:4004/mjpeg/0/<stream_id>/NFV4-FR?fps=15&height=480

<img src="http://localhost:4004/mjpeg/0/<stream_id>/NFV4-FR?fps=15&height=480"
     alt="Live Stream" />

Lifecycle Pipeline

Pipeline memiliki siklus hidup yang dimulai saat Anda mem-POST endpoint pipeline dan berakhir saat Anda mem-DELETE endpoint yang sama. Diagram berikut menunjukkan urutan event utama dari sisi master, slave, dan klien:

Saat Pipeline dibuat, master menyimpan konfigurasinya, men-dispatch perintah spawn ke node tujuan, dan meminta seat lisensi atas nama Pipeline. Bila lisensi tidak tersedia, Pipeline akan masuk state error dan tidak menghasilkan Event sampai seat tersedia kembali.

Selama Pipeline aktif, frame dari Stream didistribusikan ke Pipeline pada setiap iterasi loop — Pipeline memproses frame, menjalankan inferensi AI, dan menghasilkan Event saat kondisi deteksi terpenuhi. Event di-broadcast ke semua klien WebSocket yang sedang berlangganan endpoint event channel yang relevan, dan dipersistensi ke database internal. Saat Anda menghapus Pipeline, seat lisensi dilepaskan dan koneksi event terkait diakhiri secara graceful.

Event Channel (WebSocket)

Event channel adalah antarmuka utama untuk menerima hasil analitik secara real-time. Tersedia dalam tiga level granularitas:

Parameter Query

• ?logic=<logic_name> — Filter event berdasarkan nama aturan logika. Daftar logic yang tersedia dapat dilihat via GET /rules/pipeline/{analytic_id}/.

Format Pesan Event

Setiap pesan event yang dipancarkan melalui event channel berbentuk JSON dengan struktur berikut:

{
  "timestamp": 1674123456789,
  "node_num": 0,
  "stream_id": "a1b2c3d4e5f67890",
  "stream_name": "Camera Lobby",
  "stream_address": "rtsp://10.7.2.50:554/stream",
  "stream_longitude": 106.8456,
  "stream_latitude": -6.2088,
  "analytic_id": "NFV4-FR",
  "primary_text": "John Doe",
  "secondary_text": "Employee",
  "pipeline_data": {
    "event_id": "1674123456789-1a2b3c4d",
    "confidence": 0.95,
    "face_id": "face_abc"
  },
  "image_jpeg": "base64EncodedJpegString..."
}

Field Top-Level

pipeline_data.event_id berbentuk "<timestamp>-<hash8>" dan dijamin unik per kombinasi (timestamp, primary_text, secondary_text, pipeline_data, stream_id, analytic_id).

Live Stream (WebSocket fMP4)

Untuk konsumsi video di browser modern menggunakan Media Source Extensions (MSE):

Server mengirimkan fragmen fMP4 (fragmented MP4) secara berurutan via WebSocket. Klien browser menyuap data ini ke MediaSource API untuk playback real-time dengan latensi rendah.

Network Utilities (WebSocket)

Endpoint WebSocket untuk mendiagnosis konektivitas sumber stream. Semua endpoint mengambil node_num dan stream_id dari stream yang sudah terdaftar.

Server mengirimkan output utilitas secara streaming — setiap baris output dikirim sebagai pesan WebSocket terpisah. Koneksi ditutup otomatis saat operasi selesai.

Contoh — ping stream:

const ws = new WebSocket('ws://localhost:4004/netutils/ping/0/5136c6c0916cd30c');
ws.onmessage = (e) => console.log(e.data);
// Output: "PING 10.7.2.50: 56 data bytes"
// Output: "64 bytes from 10.7.2.50: icmp_seq=0 ttl=64 time=0.5 ms"
// ...

Modul Analitik

Setiap modul analitik memiliki halaman dokumentasi lengkap dengan endpoint pipeline spesifik, parameter konfigurasi, dan format event:

Referensi API Lengkap