使用 Go SDK 开始云端录制

本文向新手介绍如何使用声网 Go SDK 开始第一次云端录制。

Go SDK 旨在帮助开发者更轻松集成声网 RESTful API。该 SDK 具有如下特性：

• 简化通信流畅：通过封装 RESTful API 的请求和响应处理，让你与 RESTful API 的通信更加简单。
• 保障可用性：遇到 DNS 解析失败、网络错误、请求超时等网络问题时，会自动切换到最佳域名，确保 REST 服务的可用性。
• API 易用性：提供简洁易懂的 API，让你能轻松实现开启云端录制、停止云端录制等常用功能。
• 其他优势：基于 Go 语言编写，具有高效性、并发性、可扩展性。

前提条件

开通服务并获取关键参数

参考开通服务在声网控制台开通云端录制，并复制保存如下参数，以供后续使用：

• App ID
• 临时 Token
• 客户 ID
• 客户密钥

开通第三方云存储

云端录制文件需要上传到第三方云存储。开始录制前，请开通第三方云存储服务，并获取如下字段以备后用：

• Bucket
• Access Key
• Secret Key

开通方式

开通方式请参考云存储官网文档，本文后续步骤以阿里云为例：

• Amazon S3
• 阿里云
• 腾讯云
• Microsoft Azure
• 谷歌云
• 华为云
• 百度智能云

模拟音视频互动场景

模拟一个音视频互动场景，云端录制服务后续会录制该场景下的音视频。

此处使用声网实时互动 Web Demo 在浏览器中模拟一个基础视频直播场景，频道内有一名主播发流：

1. 打开 Web Demo，完成初始化设置。
2. 进入基础视频直播页面，在 Channel 填入频道名为 show，点击 Join as host。

如果模拟成功，你会在 local stream 区域看到你的视频画面。

准备开发环境

安装 Go

1. 访问官网下载 Go，版本要求不低于 1.18。

2. 在 Terminal 中执行如下命令，检查 Go 是否成功安装。

   Shell

   go version

   如果安装成功，你会得到版本号信息，例如 go version go1.22.2 darwin/arm64。

创建 Go 项目

创建一个 Go 项目。在项目文件夹下，执行如下命令初始化 Go 模块，并新建一个空的 main.go 文件。

Shell

go mod init <module_name>

安装 SDK

1. 在 Terminal 中，进入项目文件夹，执行如下命令，安装 Go SDK。

   Shell

   #（可选）设置代理，防止网络超时
   go env -w GOPROXY=https://goproxy.cn,direct
   # 安装 Go SDK
   go get -u github.com/AgoraIO-Community/agora-rest-client-go
   # 更新依赖
   go mod tidy

2. 安装完成后，在你的 main.go 文件中添加如下代码，以导入 Go SDK。

   Go

   import (
       "github.com/AgoraIO-Community/agora-rest-client-go/core"
       "github.com/AgoraIO-Community/agora-rest-client-go/services/cloudrecording"
       v1 "github.com/AgoraIO-Community/agora-rest-client-go/services/cloudrecording/v1"
   )

进行云端录制

本节介绍进行云端录制的极简流程。为方便说明，本节以录制之前模拟的音视频直播为例，并假设录制主播的音频和视频录制到 MP4 文件中。

定义变量

在 main.go 文件中，添加如下代码，定义或配置关键参数，取值参考前提条件。

Go

// 定义关键参数
const (
    appId    = "<your_app_id>"
    token    = "<your_token>"
    // 客户 ID
    username = "<your_key>"
    // 客户密钥
    password = "<your_secret>"
    cname    = "show"
    uid      = "123"
)

// 配置云存储
var storageConfig = &v1.StorageConfig{
    Vendor:         2,
    Region:         3,
    Bucket:         "<your_storage_bucket_name>",
    AccessKey:      "<your_storage_access_key>",
    SecretKey:      "<your_storage_secret_key>",
    FileNamePrefix: []string{
        "quickstart",
    },
}

Vendor: 2 代表使用阿里云，如果你使用其他云存储厂商，请下表进行赋值：

云存储厂商	Vendor ID
Amazon S3	1
阿里云	2
腾讯云	3
Microsoft Azure	5
谷歌云	6
华为云	7
百度智能云	8

创建并初始化 Client

在 main.go 文件中，添加如下代码，创建一个 main 函数，在其中创建并初始化 Client。

Go

func main() {
    client := core.NewClient(&core.Config{
        AppID:      appId,
        // 通过传入的客户 ID 和客户密钥进行 HTTP Basic Auth
        Credential: core.NewBasicAuthCredential(username, password),
        RegionCode: core.CNRegionArea,
        Logger:     core.NewDefaultLogger(core.LogDebug),
    })

    impl := cloudrecording.NewAPI(client).V1().MixRecording()
}

申请录制服务器资源

调用 acquire 申请录制服务器资源。你需要存储 resourceId 以备后用。

Go

func main() {
    // 创建并初始化 Client
    ...

    acquireResp, err := impl.Acquire().Do(context.TODO(), cname, uid, &v1.AcquireMixRecodingClientRequest{})

    if err != nil {
        log.Fatal(err)
    }

    if acquireResp.IsSuccess() {
        log.Printf("acquire success:%+v\n", acquireResp)
    } else {
        log.Fatalf("acquire failed:%+v\n", acquireResp)
    }

    resourceId := acquireResp.SuccessRes.ResourceId
}

开始录制

获取资源后，调用 start 开始录制。

Go

func main() {
    // 创建并初始化 Client
    ...

    // 申请录制服务器资源
    ...

    startResp, err := impl.Start().Do(context.TODO(), resourceId, cname, uid, &v1.StartMixRecordingClientRequest{
        Token: token,
        RecordingConfig: &v1.RecordingConfig{
            ChannelType: 1,
        },
        RecordingFileConfig: &v1.RecordingFileConfig{
            AvFileType: []string{
                "hls",
                "mp4",
            },
        },
        StorageConfig: storageConfig,
    })

    if err != nil {
        log.Fatal(err)
    }

    if startResp.IsSuccess() {
        log.Printf("start success:%+v\n", startResp)
    } else {
        log.Fatalf("start failed:%+v\n", startResp)
    }

}

补全 main.go 的代码后，在项目文件夹下，执行如下命令本地运行 Go 项目：

Shell

go run main.go

完整示例代码

main.go 文件中完整代码如下，你可自行比对：

完整示例代码

Go

package main

import (
    "context"
    "log"
    "time"
    "github.com/AgoraIO-Community/agora-rest-client-go/core"
    "github.com/AgoraIO-Community/agora-rest-client-go/services/cloudrecording"
    v1 "github.com/AgoraIO-Community/agora-rest-client-go/services/cloudrecording/v1"
)

// 定义关键参数
const (
    appId    = "<your_app_id>"
    token    = "<your_token>"
    // 客户 ID
    username = "<your_key>"
    // 客户密钥
    password = "<your_secret>"
    cname    = "show"
    uid      = "123"
)

// 配置云存储
var storageConfig = &v1.StorageConfig{
    Vendor:         2,
    Region:         3,
    Bucket:         "<your_storage_bucket_name>",
    AccessKey:      "<your_storage_access_key>",
    SecretKey:      "<your_storage_secret_key>",
    FileNamePrefix: []string{
        "quickstart",
    },
}

func main() {
	// 创建并初始化 Client
    client := core.NewClient(&core.Config{
        AppID:      appId,
        Credential: core.NewBasicAuthCredential(username, password),
        RegionCode: core.CNRegionArea,
        Logger:     core.NewDefaultLogger(core.LogDebug),
    })

    impl := cloudrecording.NewAPI(client).V1().MixRecording()

	// 申请录制服务器资源
    acquireResp, err := impl.Acquire().Do(context.TODO(), cname, uid, &v1.AcquireMixRecodingClientRequest{})

    if err != nil {
        log.Fatal(err)
    }

    if acquireResp.IsSuccess() {
        log.Printf("acquire success:%+v\n", acquireResp)
    } else {
        log.Fatalf("acquire failed:%+v\n", acquireResp)
    }

    resourceId := acquireResp.SuccessRes.ResourceId

    // 开始录制，并传入之前保存的 resourceId 等参数
    startResp, err := impl.Start().Do(context.TODO(), resourceId, cname, uid, &v1.StartMixRecordingClientRequest{
        Token: token,
        RecordingConfig: &v1.RecordingConfig{
            ChannelType: 1,
        },
        RecordingFileConfig: &v1.RecordingFileConfig{
            AvFileType: []string{
                "hls",
                "mp4",
            },
        },
        StorageConfig: storageConfig,
    })

    if err != nil {
        log.Fatal(err)
    }

    if startResp.IsSuccess() {
        log.Printf("start success:%+v\n", startResp)
    } else {
        log.Fatalf("start failed:%+v\n", startResp)
    }

    sid := startResp.SuccessResponse.Sid

    // 结束录制，并传入之前保存的 resourceId 和 sid 等参数
    stopResp, err := impl.Stop().DoHLSAndMP4(context.TODO(), resourceId, sid, cname, uid, false)

    if err != nil {
        log.Fatal(err)
    }

    if stopResp.IsSuccess() {
        log.Printf("stop success:%+v\n", stopResp)
    } else {
        log.Printf("stop failed:%+v\n", stopResp)
    }
}

查看录制文件

参考第三方云存储官方文档操作，查看云存储中的文件。录制文件位于 quickstart 目录下。如下截图以阿里云为例：

在录制过程中，会有一个 .m3u8 和多个 .ts 文件。点击任意一个 .ts 文件即可播放。

如果还需要查看 .mp4 文件，你需要先结束录制，再查看云存储文件。结束录制可参照如下代码：

Go

func main() {
    // 创建并初始化 Client
    ...

    // 申请录制服务器资源
    ...

    // 开始录制
    ...

    // 开始录制后得到 sid
    sid := startResp.SuccessResponse.Sid
    // 结束录制，并传入之前保存的 resourceId 和 sid 等参数
    stopResp, err := impl.Stop().DoHLSAndMP4(context.TODO(), resourceId, sid, cname, uid, false)

    if err != nil {
        log.Fatal(err)
    }

    if stopResp.IsSuccess() {
        log.Printf("stop success:%+v\n", stopResp)
    } else {
        log.Printf("stop failed:%+v\n", stopResp)
    }
}

最终 quickstart 录制文件夹内包含如下：

Shell

.
├── <sid>_show.m3u8
├── <sid>_show_0.mp4
├── <sid>_show_20240507070329192.ts
├── <sid>_show_20240507070346226.ts
├── <sid>_show_20240507070402264.ts
├── <sid>_show_20240507070418236.ts
├── <sid>_show_20240507070434208.ts
├── <sid>_show_20240507070450246.ts
├── <sid>_show_20240507070506218.ts
├── <sid>_show_20240507070522256.ts
├── <sid>_show_20240507070538236.ts
├── <sid>_show_20240507070554266.ts
├── <sid>_show_20240507070610238.ts
├── <sid>_show_20240507070626210.ts
└── <sid>_show_20240507070642248.ts

录制文件介绍请参考录制文件命名和切片规则。

进阶设置

本文提供的示例代码仅为快速上手时使用。在实际业务中，你需要根据实际业务场景修改请求参数。如下示例代码展示了录制直播频道中所有的音视频流，且输出的视频流需要转码的参数配置：

Go

startResp, err := impl.Start().Do(ctx, resourceId, s.cname, s.uid, &v1.StartMixRecordingClientRequest{
    Token: token,
    RecordingConfig: &v1.RecordingConfig{
        ChannelType: 1,
        StreamTypes: 2,
        MaxIdleTime: 30,
        AudioProfile: 2,
        TranscodingConfig: &v1.TranscodingConfig{
            Width:            640,
            Height:           640,
            FPS:              15,
            BitRate:          800,
            MixedVideoLayout: 0,
            BackgroundColor:  "#000000",
        },
        SubscribeAudioUIDs: []string{
            "#allstream#",
        },
        SubscribeVideoUIDs: []string{
            "#allstream#",
        },
    },
    RecordingFileConfig: &v1.RecordingFileConfig{
        AvFileType: []string{
            "hls",
            "mp4",
        },
    },
    StorageConfig: storageConfig,
})

云端录制支持设置的所有参数请参考 API 文档。

参考信息

示例项目

完成快速开始后，你可以体验更多云端录制示例：

Gitee 示例项目

GitHub 示例项目

排查错误

• 响应状态码和错误码
• 为什么成功开启云端录制后调用 query 方法返回 404？
• 如何选择云存储 bucket 区域及处理跨区上传问题？
• 为什么第三方云储存中没有录制文件？