Control Messages
This document specifies the control messages for keyframe requests and FPS changes.
Overview
Control messages allow coordination between components without transferring video data.
| Message Type | Direction | Purpose |
|---|---|---|
| Keyframe Request | Server → Sentinel | Request immediate keyframe |
| FPS Change Request | Server → Sentinel | Change capture framerate |
Keyframe Request
Allows the Server to request an on-demand keyframe from a Sentinel.
Flow Diagram
Request Message (Server → Sentinel)
| Field | Type | Required | Description |
|---|---|---|---|
type | string | yes | Message type identifier |
Example:
{
"type": "keyframe.request"
}Sentinel Behavior
When the Sentinel receives a keyframe request:
- The next captured frame becomes an IDR frame (keyframe)
- A new join fragment begins with this keyframe
- The join fragment is sent to the Server as usual
Response
No explicit response message is defined. The Server knows the keyframe request was fulfilled when a new join fragment arrives.
FPS Change Request
Allows the Server to request a framerate change from a Sentinel.
Flow Diagram
Request Message (Server → Sentinel)
| Field | Type | Required | Description |
|---|---|---|---|
type | string | yes | Message type identifier |
framerate | number | yes | New target framerate (0.2 to 5) |
Example:
{
"type": "fps.change",
"framerate": 2
}Sentinel Behavior
When the Sentinel receives an FPS change request:
Finish Current Segment
Complete and send the current fragment with the old framerate.
Generate Keyframe
The next frame is an IDR frame, starting a new join fragment.
Apply New Framerate
Begin capturing at the new framerate.
Continue Streaming
New fragments are sent at the new framerate.
Framerate Bounds
| Bound | Value | Behavior if Exceeded |
|---|---|---|
| Minimum | 0.2 fps (1 frame per 5 seconds) | Clamp to minimum |
| Maximum | 5 fps | Clamp to maximum |
If the requested framerate is outside bounds, the Sentinel clamps it and applies the bounded value.
Response
No explicit response message is defined. The Server observes the framerate change via fragment metadata.
Server-Initiated vs Proctor-Initiated
| Message | Who Initiates | Server’s Role |
|---|---|---|
| Keyframe Request | Server | Originates from Server |
| FPS Change | Server | Originates from Server |
The Proctor cannot directly request an FPS change or keyframe request. These are Server-side decisions based on:
- Server load
- Network conditions
- Administrative policy
Timing Guarantees
| Message | Timing |
|---|---|
| Keyframe Request | Keyframe on next capture (up to 1/framerate delay) |
| FPS Change | Takes effect on next join fragment |
Error Handling
Keyframe Request Errors
| Condition | Handling |
|---|---|
| Sentinel not found | Server returns error to Proctor |
| Sentinel offline | Server returns error to Proctor |
| Request during encoding | Sentinel queues request for next frame |
FPS Change Errors
| Condition | Handling |
|---|---|
| Invalid framerate | Sentinel clamps to valid range |
| Sentinel busy | Sentinel applies on next join fragment boundary |
Message Type Summary
| Type Identifier | Direction | Description |
|---|---|---|
keyframe.request | Server → Sentinel | Request keyframe for a Sentinel |
fps.change | Server → Sentinel | Request framerate change |