# 实现媒体流和信令传输 (/zh-CN/realtime-media/rtsa/build/media-and-signaling-transmission/implement-transmission) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). 本文介绍通过 RTSA SDK 实现媒体流和信令传输涉及的 API 方法和调用流程。 ## 前提条件 [#前提条件] 开始前,请确保满足如下要求: - 一个有效的 License。RTSA 通过 License 对设备鉴权,详见[申请和使用 License](/zh-CN/realtime-media/rtsa/build/project-preparation/license)。 - 一台开发机,可以是电脑或嵌入式设备。环境要求见[平台兼容](/zh-CN/realtime-media/rtsa/reference/supported-platforms)。本文以安装 Ubuntu 18.04 系统的电脑为例。 - 参考[开通服务](/zh-CN/realtime-media/rtsa/build/project-preparation/enable-service)获取 App ID、RTC 和 RTM 临时 Token。 ## 实现流程 [#实现流程] ### 1. 初始化 [#1-初始化] 开始媒体流或信令传输前,你需要调用 `agora_rtc_init` 方法初始化 RTSA SDK。初始化操作只需要进行一次,成功初始化后,你可以根据实际需求选择只传输媒体流或信令,还是二者都传输。 在该方法中,你需要进行如下操作: - 填入获取到的 App ID。只有 App ID 相同的应用程序才能进入同一个频道进行互通。 - 设置 RTC 事件回调,用以通知 SDK 在运行过程中发生的事件。 - 如果需要传输媒体流,则需在 `agora_rtc_event_handler_t` 中设置事件回调,详见[监听事件](#eventlistener)。 - 如果无需传输媒体流,则需设置 `agora_rtc_event_handler_t` 为 `0`。示例代码如下: ```c agora_rtc_event_handler_t rtc_event_handler = { 0 }; rtc_service_option_t service_options = { 0 }; agora_rtc_init(appid, &rtc_event_handler, &service_options); ``` - (可选)通过 `rtc_service_option_t` 结构体设置 RTSA 服务选项。 ### 2. 传输媒体流 [#2-传输媒体流] #### 2.1 监听事件 [#21-监听事件] 设置 `agora_rtc_event_handler_t` 中的 RTC 事件回调。 示例代码如下: ```c // 初始化事件回调 static void __on_join_channel_success(connection_id_t conn_id, uint32_t uid, int elapsed) { g_connected_flag = true; agora_rtc_get_connection_info(conn_id, &g_conn_info); printf("[conn-%u] Join the channel %s successfully, uid %u elapsed %d ms\n", conn_id, g_conn_info.channel_name, uid, elapsed); } static void __on_reconnecting(connection_id_t conn_id) { g_connected_flag = false; printf("[conn-%u] connection timeout, reconnecting\n", conn_id); } static void __on_connection_lost(connection_id_t conn_id) { g_connected_flag = false; printf("[conn-%u] Lost connection from the channel\n", conn_id); } static void __on_rejoin_channel_success(connection_id_t conn_id, uint32_t uid, int elapsed_ms) { g_connected_flag = true; printf("[conn-%u] Rejoin the channel successfully, uid %u elapsed %d ms\n", conn_id, uid, elapsed_ms); } static void __on_user_joined(connection_id_t conn_id, uint32_t uid, int elapsed_ms) { printf("[conn-%u] Remote user \"%u\" has joined the channel, elapsed %d ms\n", conn_id, uid, elapsed_ms); } static void __on_user_offline(connection_id_t conn_id, uint32_t uid, int reason) { printf("[conn-%u] Remote user \"%u\" has left the channel, reason %d\n", conn_id, uid, reason); } static void __on_user_mute_audio(connection_id_t conn_id, uint32_t uid, bool muted) { printf("[conn-%u] audio: uid=%u muted=%d\n", conn_id, uid, muted); } static void __on_user_mute_video(connection_id_t conn_id, uint32_t uid, bool muted) { printf("[conn-%u] video: uid=%u muted=%d\n", conn_id, uid, muted); } static void __on_error(connection_id_t conn_id, int code, const char *msg) { if (code == ERR_SEND_VIDEO_OVER_BANDWIDTH_LIMIT) { printf("Not enough uplink bandwdith. Error msg \"%s\"\n", msg); return; } if (code == ERR_INVALID_APP_ID) { printf("Invalid App ID. Please double check. Error msg \"%s\"\n", msg); } else if (code == ERR_INVALID_CHANNEL_NAME) { printf("Invalid channel name. Please double check. Error msg \"%s\"\n", msg); } else if (code == ERR_INVALID_TOKEN || code == ERR_TOKEN_EXPIRED) { printf("Invalid token. Please double check. Error msg \"%s\"\n", msg); } else if (code == ERR_DYNAMIC_TOKEN_BUT_USE_STATIC_KEY) { printf("Dynamic token is enabled but is not provided. Error msg \"%s\"\n", msg); } else { printf("Error %d is captured. Error msg \"%s\"\n", code, msg); } g_stop_flag = true; } static void __on_audio_data(connection_id_t conn_id, const uint32_t uid, uint16_t sent_ts, const void *data, size_t len, const audio_frame_info_t *info_ptr) {} static void __on_mixed_audio_data(connection_id_t conn_id, const void *data, size_t len, const audio_frame_info_t *info_ptr) {} static void __on_video_data(connection_id_t conn_id, const uint32_t uid, uint16_t sent_ts, const void *data, size_t len, const video_frame_info_t *info_ptr) {} static void __on_target_bitrate_changed(connection_id_t conn_id, uint32_t target_bps) { printf("[conn-%u] Bandwidth change detected. Please adjust encoder bitrate to %u kbps\n", conn_id, target_bps / 1000); } static void __on_key_frame_gen_req(connection_id_t conn_id, uint32_t uid, video_stream_type_e stream_type) { printf("[conn-%u] Frame loss detected. Please notify the encoder to generate key frame immediately\n", conn_id); } static void app_init_event_handler(agora_rtc_event_handler_t *event_handler) { event_handler->on_join_channel_success = __on_join_channel_success; event_handler->on_reconnecting = __on_reconnecting; event_handler->on_connection_lost = __on_connection_lost; event_handler->on_rejoin_channel_success = __on_rejoin_channel_success; event_handler->on_user_joined = __on_user_joined; event_handler->on_user_offline = __on_user_offline; event_handler->on_user_mute_audio = __on_user_mute_audio; event_handler->on_user_mute_video = __on_user_mute_video; event_handler->on_target_bitrate_changed = __on_target_bitrate_changed; event_handler->on_key_frame_gen_req = __on_key_frame_gen_req; event_handler->on_video_data = __on_video_data; event_handler->on_error = __on_error; event_handler->on_mixed_audio_data = __on_mixed_audio_data; event_handler->on_audio_data = __on_audio_data; } agora_rtc_event_handler_t event_handler = {0}; app_init_event_handler(&event_handler); rtc_service_option_t service_opt = {0}; service_opt.area_code = DEFAULT_AREA_CODE; service_opt.log_cfg.log_path = DEFAULT_SDK_LOG_PATH; rval = agora_rtc_init(AGORA_APP_ID_FOR_TEST, &event_handler, &service_opt); if (rval < 0) { printf("Failed to initialize声网sdk, reason: %s\n", agora_rtc_err_2_str(rval)); return -1; } ``` #### 2.2 创建 Connection 并加入 RTC 频道 [#22-创建-connection-并加入-rtc-频道] 调用 `agora_rtc_create_connection` 方法创建 Connection。调用 `agora_rtc_join_channel` 方法关联 Connection 并加入 RTC 频道。 在该方法中,你需要传入如下信息: - Connection ID。一个 Connection 可以连接多个 RTC 频道。 - 能标识 RTC 频道的频道名称。输入相同 RTC 频道名称的用户会进入同一个 RTC 频道。 - 能标识 RTC 频道用户的用户 ID。 - 能标识用户角色和权限的 RTC Token。如果安全要求不高,使用的是 App ID,可以将 `token` 设为空。 :::warning[注意] RTM Token 与 RTC Token 生成机制不同,作用范围也不同,不能混用。 ::: 用户与 RTC 频道的关系如下: - 一个 RTC 频道内的用户可以互相传输数据。 - 一个用户可以同时加入多个 RTC 频道。该用户加入的所有 RTC 频道都能接收到他发送的音视频数据。 成功加入 RTC 频道后,SDK 会触发 `on_join_channel_success` 回调。 示例代码如下: ```c // 创建 Connection rval = agora_rtc_create_connection(&g_conn_id); if (rval < 0) { printf("Failed to create connection, reason: %s\n", agora_rtc_err_2_str(rval)); return -1; } rtc_channel_options_t channel_options = { 0 }; channel_options.auto_subscribe_audio = true; channel_options.auto_subscribe_video = true; // 示例使用 SDK 内置编码器,编码格式为 Opus channel_options.audio_codec_opt.audio_codec_type = AUDIO_CODEC_TYPE_OPUS; channel_options.audio_codec_opt.pcm_sample_rate = 16000; channel_options.audio_codec_opt.pcm_channel_num = 1; // 加入 RTC 频道 rval = agora_rtc_join_channel(g_conn_id, DEFAULT_CHANNEL_NAME, DEFAULT_USER_ID, DEFAULT_TOKEN, &channel_options); if (rval < 0) { printf("Failed to join channel \"%s\", reason: %s\n", DEFAULT_CHANNEL_NAME, agora_rtc_err_2_str(rval)); return -1; } while (!g_connected_flag) { usleep(100 * 1000); } ``` #### 2.3 发送和接收音视频流 [#23-发送和接收音视频流] 成功加入 RTC 频道后,可以开始发送和接收音视频流: - 通过 `on_audio_data` 回调接收已加入频道的**音频**数据流。 - 通过 `on_video_data` 回调接收已加入频道的**视频**数据流。 - 调用 `agora_rtc_send_audio_data` 方法向任意已加入频道发送**音频**数据流。 - 调用 `agora_rtc_send_video_data` 方法向任意已加入频道发送**视频**数据流。 示例代码如下: ```c static void __on_audio_data(connection_id_t conn_id, const uint32_t uid, uint16_t sent_ts, const void *data, size_t len, const audio_frame_info_t *info_ptr) {} static void __on_video_data(connection_id_t conn_id, const uint32_t uid, uint16_t sent_ts, const void *data, size_t len, const video_frame_info_t *info_ptr) {} // 发送音频数据流 static int send_audio_frame(uint8_t *data, uint32_t len) { audio_frame_info_t info = {0}; info.data_type = AUDIO_DATA_TYPE_PCM; int rval = agora_rtc_send_audio_data(g_conn_id, data, len, &info); if (rval < 0) { printf("Failed to send audio data, reason: %s\n", agora_rtc_err_2_str(rval)); return -1; } return 0; } // 发送视频数据流 static int send_video_frame(uint8_t *data, uint32_t len) { video_frame_info_t info = {0}; info.frame_type = VIDEO_FRAME_KEY; info.frame_rate = CONFIG_SEND_FRAME_RATE; info.stream_type = VIDEO_STREAM_HIGH; info.data_type = VIDEO_DATA_TYPE_H264; int rval = agora_rtc_send_video_data(g_conn_id, data, len, &info); if (rval < 0) { printf("Failed to send video data, reason: %s\n", agora_rtc_err_2_str(rval)); return -1; } return 0; } ``` 发送音视频数据时,需要设置发送间隔。对于视频,发送间隔长度需要和帧率一致;对于音频,发送间隔长度需要和音频帧长度一致。 ```c // 视频发送线程 static void *video_send_thread(void *threadid) { int video_send_interval_ms = 1000 / CONFIG_SEND_FRAME_RATE; void *pacer = pacer_create(video_send_interval_ms); uint32_t frame_count = 0; int num_frames = sizeof(test_video_frames) / sizeof(test_video_frames[0]); while (g_connected_flag && !g_stop_flag) { int i = (frame_count++ % num_frames); send_video_frame(test_video_frames[i].data, test_video_frames[i].len); wait_for_next_pace(pacer); } pacer_destroy(pacer); return NULL; } // 示例为 640 KB,实际值取决于 PCM 数据的采集设备 #define CONFIG_PCM_FRAME_LEN (640) #define CONFIG_PCM_SAMPLE_RATE (16000) #define CONFIG_PCM_CHANNEL_NUM (1) #define CONFIG_AUDIO_FRAME_DURATION_MS \ (CONFIG_PCM_FRAME_LEN * 1000 / CONFIG_PCM_SAMPLE_RATE / CONFIG_PCM_CHANNEL_NUM / sizeof(int16_t)) // 音频发送线程 static void *audio_send_thread(void *threadid) { int audio_send_interval_ms = CONFIG_AUDIO_FRAME_DURATION_MS; void *pacer = pacer_create(audio_send_interval_ms); uint32_t pcm_offset = 0; while (g_connected_flag && !g_stop_flag) { send_audio_frame((uint8_t *)pcm_test_data + pcm_offset, CONFIG_PCM_FRAME_LEN); pcm_offset += CONFIG_PCM_FRAME_LEN; if ((pcm_offset + CONFIG_PCM_FRAME_LEN) > sizeof(pcm_test_data)) { pcm_offset = 0; } wait_for_next_pace(pacer); } pacer_destroy(pacer); return NULL; } ``` #### 2.4 离开频道并销毁 Connection [#24-离开频道并销毁-connection] 调用 `agora_rtc_leave_channel` 方法离开指定频道,结束在该频道的数据传输。如果不再需要在 Connection 中传输数据,调用 `agora_rtc_destroy_connection` 方法销毁 Connection。 示例代码如下: ```c agora_rtc_leave_channel(g_conn_id); agora_rtc_destroy_connection(g_conn_id); ``` ### 3. 传输信令 [#3-传输信令] #### 3.1 登录 RTM 系统 [#31-登录-rtm-系统] 调用 `agora_rtm_login` 方法登录 RTM 系统。登录成功之后,你可以发送和接收信令。 在该方法中,你需要进行如下操作: - 传入能标识 RTM 系统用户的 RTM 用户 ID。 - 传入能标识 RTM 系统用户角色和权限的 [RTM Token](/zh-CN/realtime-media/rtm/build/authentication-and-connection/token-generation)。如果安全要求不高,使用的是 App ID,可以将 `token` 设为空。 - 在 `agora_rtm_handler_t` 结构体中设置 RTM 事件回调。 :::warning[注意] RTM Token 与 RTC Token 生成机制不同,作用范围也不同,不能混用。 ::: 示例代码如下: ```c agora_rtm_handler_t rtm_handler = {0}; rtm_handler.on_rtm_data = __on_rtm_data; rtm_handler.on_rtm_event = __on_rtm_event; rtm_handler.on_rtm_send_data_result = __on_rtm_send_data_result; rval = agora_rtm_login(rtm_uid, token, &rtm_handler); if (rval < 0) { printf("login rtm failed\n"); goto EXIT; } ``` #### 3.2 发送和接收信令 [#32-发送和接收信令] 成功登录 RTM 系统后,你可以开始发送和接收信令: :::caution[注意] 只有收到 `RTM_EVENT_TYPE_LOGIN` 且 `ERR_RTM_OK` 的成功回调后,才能调用 `agora_rtm_send_data`。 ::: - 通过 `on_rtm_data` 回调接收远端发送给你的信令。 - 通过 `on_rtm_event` 回调监听本地用户状态。 - 通过 `on_rtm_send_data_result` 回调监听本地信令发送结果。 - 调用 `agora_rtm_send_data` 方法向指定 RTM 用户发送信令。 示例代码如下: ```c // 接收你登录的 RTM 系统中远端发送的信令 static void __on_rtm_data(const char *user_id, const void *data, size_t data_len, rtm_message_type_e msg_type, const char *custom_type) { if (msg_type == RTM_MESSAGE_TYPE_STRING) { printf("Receive data[%.*s] from user[%s] length[%zu]\n", (int)data_len, (const char *)data, user_id, data_len); } else { printf("Receive data from user[%s] length[%zu]\n", user_id, data_len); } } // 监听本地用户状态 static void __on_rtm_event(const char *user_id, rtm_event_type_e event_type, rtm_err_code_e err_code) { printf("%s event type[%d], err code[%d]\n", user_id, event_type, err_code); if (event_type == RTM_EVENT_TYPE_LOGIN && err_code == ERR_RTM_OK) { g_rtm_login_success_flag = 1; } } // 监听本地信令发送结果 static void __on_rtm_send_data_result(const char *rtm_uid, uint32_t msg_id, rtm_msg_state_e state) { printf("user [%s] msg_id [%u], state[%d]\n", rtm_uid, msg_id, state); } // 向指定 RTM 用户发送信令 uint32_t g_message_id = 0; uint32_t message_id = ++g_message_id; const unsigned char buffer[] = {0x01, 0x02, 0x03}; size_t msg_len = sizeof(buffer); if (!g_rtm_login_success_flag) { printf("RTM login not successful, skip sending data\n"); goto EXIT; } rval = agora_rtm_send_data(peer_uid, buffer, msg_len, message_id, RTM_MESSAGE_TYPE_BINARY, NULL); if (rval < 0) { printf("send data failed, rval=%d\n", rval); goto EXIT; } printf("send message_id=%u successfully\n", message_id); ``` #### 3.3 登出 RTM 系统 [#33-登出-rtm-系统] 调用 `agora_rtm_logout` 方法登出 RTM,结束在 RTM 系统中的消息传输。 示例代码如下: ```c agora_rtm_logout(); ``` ### 4. 销毁 SDK 实例 [#4-销毁-sdk-实例] 当你不再需要使用 RTSA SDK 的任何功能时,调用 `agora_rtc_fini` 销毁 SDK 实例释放资源。 示例代码如下: ```c agora_rtc_fini(); ``` ## 参考信息 [#参考信息] ### API 时序图 [#api-时序图] 下图展示了从设备端向客户端发送实时音视频的 API 时序: ![实时音视频 API 时序图](https://web-cdn.agora.io/docs-portal/img/rtsa/quickstart-c-rtc.svg) ### API 参考 [#api-参考] 你可以通过 API 参考文档了解更多信息。 - [API 参考](/zh-CN/api-reference/rtsa/c/overview)