gRPC Frame & AI Metadata API Reference
RUSEON Core exposes a high-performance gRPC service (FrameService, default port 50051) built with Protocol Buffers v3 (api/proto/frame.proto). It allows computer vision engines (YOLOv11, DeepStream, custom Python/C++ workers) to subscribe to raw video frames or push bounding box detections with microsecond overhead.
1. Protobuf Definitions (frame.proto)
protobuf
syntax = "proto3";
package ruseon.core.frame;
option go_package = "github.com/RUSEGAL/ruseon-core/pkg/grpc/pb";
// FrameService provides streaming access to raw video frames and accepts AI metadata.
service FrameService {
// StreamFrames subscribes to a camera stream and yields raw H.264/H.265 frames.
rpc StreamFrames(StreamRequest) returns (stream FrameResponse) {}
// PushMetadata accepts a continuous stream of AI detections (e.g. Bounding Boxes).
rpc PushMetadata(stream MetadataRequest) returns (MetadataResponse) {}
}
message BoundingBox {
float x = 1; // Top-left X coordinate normalized (0.0 - 1.0)
float y = 2; // Top-left Y coordinate normalized (0.0 - 1.0)
float width = 3; // Box width normalized (0.0 - 1.0)
float height = 4; // Box height normalized (0.0 - 1.0)
string label = 5; // Class name (e.g. "person", "car")
float confidence = 6; // Detection confidence (0.0 - 1.0)
}
message MetadataRequest {
string camera_id = 1;
int64 pts = 2; // Presentation timestamp of associated video frame
repeated BoundingBox objects = 3; // Detected objects list
}
message MetadataResponse {
bool success = 1;
string message = 2;
}
message StreamRequest {
string camera_id = 1;
}
message FrameResponse {
string codec = 1; // "H264" or "H265"
bool is_keyframe = 2; // true if I-Frame (KeyFrame)
int64 pts = 3; // Presentation Time Stamp in milliseconds
bytes payload = 4; // Raw NAL unit byte payload
}2. Python Client Example (AI Ingestion)
Send real-time bounding boxes from a Python YOLOv11 worker directly into RUSEON Core:
python
import grpc
import time
import frame_pb2
import frame_pb2_grpc
def generate_metadata():
while True:
req = frame_pb2.MetadataRequest(
camera_id="cam-01",
pts=int(time.time() * 1000),
objects=[
frame_pb2.BoundingBox(
x=0.25,
y=0.30,
width=0.40,
height=0.45,
label="person",
confidence=0.96
)
]
)
yield req
time.sleep(0.04) # 25 FPS
def run():
channel = grpc.insecure_channel('localhost:50051')
stub = frame_pb2_grpc.FrameServiceStub(channel)
response = stub.PushMetadata(generate_metadata())
print(f"Metadata Push Status: {response.success}, {response.message}")
if __name__ == '__main__':
run()