HowTo文档

如何在 XSwitch 中录音

录音是 XSwitch 中重要功能之一，本文将介绍在 XSwitch 中如何使用录音，以及如何下载录音文件。

通过呼叫形式区分，XSwitch 触发录音有以下三种方式：

  1. 路由触发：可在对应路由内开启【自动录音】功能，即可实现录音功能。
  2. XCC触发：需在XNode.Dial接口内添加额外参数或调用XNode.Record接口，亦可实现录音功能。
  3. REST API触发：可在对应路由内开启【自动录音】功能，即可实现录音功能。

录音

路由触发

无论呼叫方向（针对XSwitch而言）是呼入还是呼出，只要通过经过路由，您可在对应的路由界面打开【自动录音】功能，均可实现录音功能。如下图所示：

download-logs-terminal

注意，路由中的【自动录音】功能默认是关闭的

此方式产生的录音文件可在 XUI 【媒体文件】界面看到。也可通过 HTTP 形式下载。

XCC触发

呼入

一般情况下，若是呼入，则该通话是通过路由触发 XCC 功能，有以下两种触发录音形式：

  1. 通过开启路由中的【自动录音】功能，此方式与【路由触发】章节相同，不再赘述。
  2. 不开启【自动录音】功能时，可通过调用XNode.Record接口，亦可触发录音功能。

第一种形式产生的录音文件可在 XUI 【媒体文件】界面看到，也可通过 HTTP 形式下载。
第二种形式产生的录音文件不可在 XUI 【媒体文件】界面看到，但可通过 HTTP 形式下载。

若您想使用XNode.Record录制的录音文件也在 XUI 【媒体文件】界面中看到，在下发XNode.Record之前，您需下发如下命令：

{
  "method": "XNode.SetVar",
  "params": {
    "data": {
      "auto_record": "true",
      "auto_record_path": "/usr/local/freeswitch/storage/recordings/auto-record-41723533-6bc4-4123-950f-680d17414f00.wav",
      "api_hangup_hook": "lua xui/record_record.lua"
    }
}

其中auto_record_path需与您下发的XNode.Record中的path保持一致。

呼出

若您是使用 XCC 接口 XNode.Dial 发起外部呼叫，则此通话场景下不经过路由，需要您按照如下形式改造 XNode.Dial 接口：

{
    "jsonrpc": "2.0",
    "id": "49d6037f-e07e-4de9-aa31-a7e9bcc79676",
    "method": "XNode.Dial",
    "params": {
        "ctrl_uuid": "bb87cf05-0ae3-49a4-b95d-9b9ebae85b25",
        "destination": {
            "global_params": {
                "ignore_early_media": "true"
            },
            "call_params": [
                {
                    "uuid": "41723533-6bc4-4123-950f-680d17414f00",
                    "dial_string": "sofia/public/187xxxx",
                    "params": {
                        "absolute_codec_string": "PCMA",
                        "auto_record": "true",
                        "auto_record_path": "/usr/local/freeswitch/storage/recordings/auto-record-41723533-6bc4-4123-950f-680d17414f00.wav",
                        "api_hangup_hook": "lua xui/record_record.lua",
                        "api_on_answer_record": "uuid_record 41723533-6bc4-4123-950f-680d17414f00 start /usr/local/freeswitch/storage/recordings/auto-record-41723533-6bc4-4123-950f-680d17414f00.wav"
                    }
                }
            ]
        }
    }
}

关键参数说明：

  • auto_record：固定为字符串类型的true
  • auto_record_path：/usr/local/freeswitch/storage/recordings/为固定值，也可在最后加日期为目录，如/usr/local/freeswitch/storage/recordings/2025-06/；auto-record-41723533-6bc4-4123-950f-680d17414f00.wav中的auto-record-为固定值，不可更改，41723533-6bc4-4123-950f-680d17414f00推荐使用当前通话channel-uuid，需根据实际情况更改，.wav为固定值
  • api_hangup_hook：固定值
  • api_on_answer_record：uuid_record为固定值，41723533-6bc4-4123-950f-680d17414f00为当前通话的channle-uuid，start为固定值，其余部分需与auto_record_path保持一致。

至此，当您使用以上 JSONRPC 进行外呼时，当通话接通后，将开启录音功能。录音文件可在 XUI 【媒体文件】界面看到，也可通过 HTTP 形式下载。

REST API触发

若您使用 REST API 发起呼叫，则此类呼叫一般情况下为外呼。REST API 会根据您传入的destNumber值去查询路由表，构建呼叫字符串。因此您只需在与destNumber匹配的路由表内开启【自动录音】功能即可。

如您的destNumber为1000，则使用路由查询功能查询该号码所用的路由，再将此路由的【自动录音】功能开启。

此方式录音文件可在 XUI 【媒体文件】界面看到，也可通过 HTTP 形式下载。

录音文件下载

您有通过 XUI 界面和通过 HTTP 两种形式下载录音文件。

通过 XUI 界面下载

您可访问 XUI 的【媒体文件】界面，选择您所需下载的录音文件，点击下载即可。如下图所示：

download-logs-terminal

注意，若您是通过XNode.Record的形式进行录音，需按照XCC呼入录音事先设置一些通道变量，否则，您将无法在 XUI 界面看到您的录音文件

通过 HTTP 下载

此方式需要您启用xswitch-nginx-xui容器，您可联系我们的工程师为您开启此功能。

接下来我将假设您已开启此功能，为您介绍下载步骤。

您只需在浏览器中访问https://yxb.xswitch.cn/recordings/auto-record-41723533-6bc4-4123-950f-680d17414f00.wav，即可下载对应录音文件。

其中https://yxb.xswitch.cn/需根据实际情况更换为您自己的域名或ip地址。若您的nginx不是用的默认端口，需在域名后添加nginx的端口。

若您在录音时的路径添加了额外的下级目录，如：/usr/local/freeswitch/storage/recordings/2025-06/auto-record-41723533-6bc4-4123-950f-680d17414f00.wav的形式，请您将url做对应修改：https://yxb.xswitch.cn/recordings/2025-06/auto-record-41723533-6bc4-4123-950f-680d17414f00.wav。

录像

录像与录音类似，若您是视频通话，只需将文件后缀.wav改为.mp4即可。

XSwitch 如何跟运营商线路对接