A keyframe is a full frame that stores all decoding information of a data stream. In video transmission, a frame only contains changes from the previous one. Hence, it is beneficial to generate keyframes at arbitrary intervals while encoding video to improve the overall video quality.
The Agora RTSA SDK provides the following methods and callbacks for keyframes.
When calling the agora_rtc_send_video_data
method to send a video frame, the sender informs the SDK whether or not this video frame is a keyframe by setting the is_key_frame
parameter.
In addition, the following situations may occur:
When the sender does not send any keyframe for a long time or the keyframe is lost or damaged during transmission, the SDK triggers the on_key_frame_gen_req
callback to advise the sender to generate a keyframe.
If the receiver encounters an error when decoding, it can call the agora_rtc_request_video_key_frame
method to request a remote user to generate a keyframe for a video stream.
The sender informs the SDK whether or not this video frame is a keyframe by setting the is_key_frame
parameter in the agora_rtc_send_video_data
method:
const uint8_t codec_type = 97;
const uint8_t stream_id = 0;
const int is_key = 1;
agora_rtc_send_video_data ("my_first_channel",
codec_type,
stream_id,
is_key,
video_data,
num_video_data_bytes);
The SDK triggers the on_key_frame_gen_req
callback:
static void OnKeyFrameGenReq (const char *channel, uint32_t remote_uid, uint8_t stream_id)
{
GetVideoEncoder (channel).Idr (stream_id); // Ask encoder for IDR on the stream
}
static const agora_rtc_event_handler_t listener = {
.on_key_frame_gen_req = OnKeyFrameGenReq,
// ...
};
The receiver calls the agora_rtc_request_video_key_frame
method to request a keyframe:
// Ask remote user with ID 666 to send a key frame for video stream 0
agora_rtc_request_video_key_frame ("my_first_channel", remote_uid, 0);
To improve the user experience, we recommend video encoders to generate keyframes regularly.