使用 Go SDK 开始云端录制
本文向新手介绍如何使用声网 Go SDK 开始第一次云端录制。
Go SDK 旨在帮助开发者更轻松集成声网 RESTful API。该 SDK 具有如下特性:
- 简化通信流畅:通过封装 RESTful API 的请求和响应处理,让你与 RESTful API 的通信更加简单。
- 保障可用性:遇到 DNS 解析失败、网络错误、请求超时等网络问题时,会自动切换到最佳域名,确保 REST 服务的可用性。
- API 易用性:提供简洁易懂的 API,让你能轻松实现开启云端录制、停止云端录制等常用功能。
- 其他优势:基于 Go 语言编写,具有高效性、并发性、可扩展性。
前提条件
开始前请确保你的本地开发环境满足如下条件:
-
Go 1.18 或以上版本。
-
参考开通服务在声网控制台开通云端录制,并复制保存 App ID、临时 Token、客户 ID 和客户密钥。
注意临时 Token 的有效期是 24 小时。Token 过期会导致加入频道失败。
-
云端录制文件需要上传到第三方云存储。开始录制前,请开通第三方云存储服务,并获取 Bucket、Access Key、Secret Key 以备用。
-
在项目中实现了基础的音视频互动场景。你也可以参考文档使用声网实时互动 Web Demo 在浏览器中模拟一个音视频互动场景。
创建项目并安装 SDK
创建项目
参考如下步骤创建并配置新项目。
-
创建一个名为
test-recording
的空项目文件夹。 -
进入
test-recording
路径,执行如下命令初始化 Go 模块。Shellgo mod init test-recording
-
在项目路径下,新建一个空的
main.go
文件,我们会在这个文件中实现一个极简的云端录制任务。
安装并引入 SDK
按照如下命令行安装需要的依赖库,并将 SDK 引入项目中。
-
在项目路径下,执行如下命令,安装 Go SDK。
Shell# 安装 Go SDK
go get -u github.com/AgoraIO-Community/agora-rest-client-go
# 更新依赖
go mod tidy -
安装完成后,在你的
main.go
文件中添加如下代码,以引入 Go SDK。Goimport (
"context"
"log"
"time"
"github.com/AgoraIO-Community/agora-rest-client-go/agora"
"github.com/AgoraIO-Community/agora-rest-client-go/agora/auth"
"github.com/AgoraIO-Community/agora-rest-client-go/agora/domain"
agoraLogger "github.com/AgoraIO-Community/agora-rest-client-go/agora/log"
"github.com/AgoraIO-Community/agora-rest-client-go/services/cloudrecording"
cloudRecordingAPI "github.com/AgoraIO-Community/agora-rest-client-go/services/cloudrecording/api"
"github.com/AgoraIO-Community/agora-rest-client-go/services/cloudrecording/scenario/mixrecording"
)
开始云端录制
本节介绍进行云端录制的极简流程。为方便说明,本节以录制之前模拟的音视频直播为例,并假设录制主播的音频和视频录制到 MP4 文件中。
定义变量
在 main.go
文件中,添加如下代码,定义或配置关键参数,取值参考前提条件。
// 定义关键参数
const (
appId = "<your_app_id>"
cname = "show"
uid = "123"
// 客户 ID
username = "<your_key>"
// 客户密钥
password = "<your_secret>"
token = "<your_token>"
)
// 配置云存储
var storageConfig = &cloudRecordingAPI.StorageConfig{
Vendor: 2,
Region: 1,
Bucket: "<your_storage_bucket_name>",
AccessKey: "<your_storage_access_key>",
SecretKey: "<your_storage_secret_key>",
FileNamePrefix: []string{
"quickstart",
},
}
其中,
cname
值设为show
,表示加入录制实时音视频互动所在的频道。Vendor
值设为2
代表使用阿里云;Region
值设为1
表示CN_Shanghai
。如果你使用其他云存储厂商,参考第三方云存储地区说明赋值。
创建并初始化 Client
在 main.go
文件中,添加如下代码,创建并初始化 Client。
// Initialize Agora Config
config := &agora.Config{
AppID: appId,
Credential: auth.NewBasicAuthCredential(username, password),
// Specify the region where the server is located. Options include CN, EU, AP, US.
// The client will automatically switch to use the best domain based on the configured region.
DomainArea: domain.CN,
// Specify the log output level. Options include DebugLevel, InfoLevel, WarningLevel, ErrLevel.
// To disable log output, set logger to DiscardLogger.
Logger: agoraLogger.NewDefaultLogger(agoraLogger.DebugLevel),
}
// Initialize the cloud recording service client
cloudRecordingClient, err := cloudrecording.NewClient(config)
if err != nil {
log.Fatal(err)
}
申请录制服务器资源
调用 acquire
申请录制服务器资源。你需要存储 resourceId
以备后用。
// Call the Acquire API of the cloud recording service client
acquireResp, err := cloudRecordingClient.MixRecording().
Acquire(context.TODO(), cname, uid, &mixrecording.AcquireMixRecodingClientRequest{})
// Handle non-business errors
if err != nil {
log.Fatal(err)
}
// Handle business response
if acquireResp.IsSuccess() {
log.Printf("acquire success:%+v\n", acquireResp)
} else {
log.Fatalf("acquire failed:%+v\n", acquireResp)
}
开始录制
获取资源后,调用 start
开始录制。
// Call the Start API of the cloud recording service client
resourceId := acquireResp.SuccessRes.ResourceId
startResp, err := cloudRecordingClient.MixRecording().
Start(context.TODO(), resourceId, cname, uid, &mixrecording.StartMixRecordingClientRequest{
Token: token,
RecordingConfig: &cloudRecordingAPI.RecordingConfig{
ChannelType: 1,
},
RecordingFileConfig: &cloudRecordingAPI.RecordingFileConfig{
AvFileType: []string{
"hls",
"mp4",
},
},
StorageConfig: storageConfig,
})
// Handle non-business errors
if err != nil {
log.Fatal(err)
}
// Handle business response
if startResp.IsSuccess() {
log.Printf("start success:%+v\n", startResp)
} else {
log.Fatalf("start failed:%+v\n", startResp)
}
sid := startResp.SuccessResponse.Sid
停止录制
完成录制后,调用 stop
结束录制。
// Call the Stop API of the cloud recording service client
stopResp, err := cloudRecordingClient.MixRecording().
Stop(context.TODO(), resourceId, sid, cname, uid, true)
// Handle non-business errors
if err != nil {
log.Fatal(err)
}
// Handle business response
if stopResp.IsSuccess() {
log.Printf("stop success:%+v\n", stopResp)
} else {
log.Printf("stop failed:%+v\n", stopResp)
}
完整示例代码
main.go
文件中完整代码如下,你可自行比对:
package main
import (
"context"
"log"
"time"
"github.com/AgoraIO-Community/agora-rest-client-go/agora"
"github.com/AgoraIO-Community/agora-rest-client-go/agora/auth"
"github.com/AgoraIO-Community/agora-rest-client-go/agora/domain"
agoraLogger "github.com/AgoraIO-Community/agora-rest-client-go/agora/log"
"github.com/AgoraIO-Community/agora-rest-client-go/services/cloudrecording"
cloudRecordingAPI "github.com/AgoraIO-Community/agora-rest-client-go/services/cloudrecording/api"
"github.com/AgoraIO-Community/agora-rest-client-go/services/cloudrecording/scenario/mixrecording"
)
const (
appId = "<your appId>"
cname = "<your cname>"
uid = "<your uid>"
username = "<the username of basic auth credential>"
password = "<the password of basic auth credential>"
token = "<your token>"
)
var storageConfig = &cloudRecordingAPI.StorageConfig{
Vendor: 2,
Region: 1,
Bucket: "",
AccessKey: "",
SecretKey: "",
FileNamePrefix: []string{
"quickstart",
},
}
func main() {
// Initialize Agora Config
config := &agora.Config{
AppID: appId,
Credential: auth.NewBasicAuthCredential(username, password),
// Specify the region where the server is located. Options include CN, EU, AP, US.
// The client will automatically switch to use the best domain based on the configured region.
DomainArea: domain.CN,
// Specify the log output level. Options include DebugLevel, InfoLevel, WarningLevel, ErrLevel.
// To disable log output, set logger to DiscardLogger.
Logger: agoraLogger.NewDefaultLogger(agoraLogger.DebugLevel),
}
// Initialize the cloud recording service client
cloudRecordingClient, err := cloudrecording.NewClient(config)
if err != nil {
log.Fatal(err)
}
// Call the Acquire API of the cloud recording service client
acquireResp, err := cloudRecordingClient.MixRecording().
Acquire(context.TODO(), cname, uid, &mixrecording.AcquireMixRecodingClientRequest{})
// Handle non-business errors
if err != nil {
log.Fatal(err)
}
// Handle business response
if acquireResp.IsSuccess() {
log.Printf("acquire success:%+v\n", acquireResp)
} else {
log.Fatalf("acquire failed:%+v\n", acquireResp)
}
// Call the Start API of the cloud recording service client
resourceId := acquireResp.SuccessRes.ResourceId
startResp, err := cloudRecordingClient.MixRecording().
Start(context.TODO(), resourceId, cname, uid, &mixrecording.StartMixRecordingClientRequest{
Token: token,
RecordingConfig: &cloudRecordingAPI.RecordingConfig{
ChannelType: 1,
},
RecordingFileConfig: &cloudRecordingAPI.RecordingFileConfig{
AvFileType: []string{
"hls",
"mp4",
},
},
StorageConfig: storageConfig,
})
// Handle non-business errors
if err != nil {
log.Fatal(err)
}
// Handle business response
if startResp.IsSuccess() {
log.Printf("start success:%+v\n", startResp)
} else {
log.Fatalf("start failed:%+v\n", startResp)
}
sid := startResp.SuccessResponse.Sid
// Query
for i := 0; i < 6; i++ {
queryResp, err := cloudRecordingClient.MixRecording().
QueryHLSAndMP4(context.TODO(), resourceId, sid)
// Handle non-business errors
if err != nil {
log.Fatal(err)
}
// Handle business response
if queryResp.IsSuccess() {
log.Printf("query success:%+v\n", queryResp)
} else {
log.Printf("query failed:%+v\n", queryResp)
}
time.Sleep(time.Second * 10)
}
// Call the Stop API of the cloud recording service client
stopResp, err := cloudRecordingClient.MixRecording().
Stop(context.TODO(), resourceId, sid, cname, uid, true)
// Handle non-business errors
if err != nil {
log.Fatal(err)
}
// Handle business response
if stopResp.IsSuccess() {
log.Printf("stop success:%+v\n", stopResp)
} else {
log.Printf("stop failed:%+v\n", stopResp)
}
}
查看录制文件
参考第三方云存储官方文档操作,查看云存储中的文件。根据 start
方法中 storageconfig.fileNamePrefix
参数的设置,录制生成文件位于 quickstart
目录下。如下截图以阿里云为例:
录制过程中生成了 .m3u8
、.ts
和 mp4
文件。最终 quickstart
文件夹内包含如下:
.
├── <sid>_testchannel.m3u8
├── <sid>_testchannel_0.mp4
└── <sid>_testchannel_20241119070642248.ts
根据你在 start
方法中设置的录制时间,云存储中可能会有多个 .ts 文件。录制文件介绍请参考录制文件命名和切片规则。
进阶设置
本文提供的示例代码仅为快速上手时使用。在实际业务中,你需要根据实际业务场景修改请求参数。如下示例代码展示了录制直播频道中所有的音视频流,且输出的视频流需要转码的参数配置:
startResp, err := cloudRecordingClient.MixRecording().
Start(context.TODO(), resourceId, cname, uid, &mixrecording.StartMixRecordingClientRequest{
Token: token,
RecordingConfig: &cloudRecordingAPI.RecordingConfig{
ChannelType: 1,
StreamTypes: 2,
MaxIdleTime: 30,
AudioProfile: 2,
TranscodingConfig: &cloudRecordingAPI.TranscodingConfig{
Width: 640,
Height: 640,
FPS: 15,
BitRate: 800,
MixedVideoLayout: 0,
BackgroundColor: "#000000",
},
SubscribeAudioUIDs: []string{
"#allstream#",
},
SubscribeVideoUIDs: []string{
"#allstream#",
},
},
RecordingFileConfig: &cloudRecordingAPI.RecordingFileConfig{
AvFileType: []string{
"hls",
"mp4",
},
},
StorageConfig: storageConfig,
})
云端录制支持设置的所有参数请参考 API 文档。
参考信息
示例项目
完成快速开始后,你可以体验更多云端录制示例: