快速开始云端录制

  • Go

更新时间

了解如何通过 RESTful API、Go SDK、Java SDK 或 Node.js SDK 快速接入云端录制。

选择你要使用的接口或 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

创建项目

参考如下步骤创建并配置新项目。

  1. 创建一个名为 test-recording 的空项目文件夹。

  2. 进入 test-recording 路径,执行如下命令初始化 Go 模块。

    Shell
    go mod init test-recording
  3. 在项目路径下,新建一个空的 main.go 文件,我们会在这个文件中实现一个极简的云端录制任务。

安装并引入 SDK

按照如下命令行安装需要的依赖库,并将 SDK 引入项目中。

  1. 在项目路径下,执行如下命令,安装 Go SDK。

    Shell
    # 安装 Go SDK
    go get -u github.com/AgoraIO-Community/agora-rest-client-go
    # 更新依赖
    go mod tidy
  2. 安装完成后,在你的 main.go 文件中添加如下代码,以引入 Go SDK。

    Go
    import (
      "context"
      "log"
      "time"
    
      "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/req"
    )

开始云端录制

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

定义变量

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

Go
// 定义关键参数
const (
  appId    = "<your_app_id>"
  cname    = "show"
  // 录制服务加入频道的用户 ID
  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。

Go
// Initialize Cloud Recording Config
config := &cloudrecording.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 以备后用。

Go
// Call the Acquire API of the cloud recording service client
acquireResp, err := cloudRecordingClient.MixRecording().
  Acquire(context.TODO(), cname, uid, &req.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 开始录制。

Go
// Call the Start API of the cloud recording service client
resourceId := acquireResp.SuccessRes.ResourceId
startResp, err := cloudRecordingClient.MixRecording().
  Start(context.TODO(), resourceId, cname, uid, &req.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 结束录制。

Go
// 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 文件中完整代码如下,你可自行比对:

查看录制文件

参考第三方云存储官方文档操作,查看云存储中的文件。根据 start 方法中 storageconfig.fileNamePrefix 参数的设置,录制生成文件位于 quickstart 目录下。如下截图以阿里云为例:

录制过程中生成了 .m3u8、.ts 和 mp4 文件。最终 quickstart 文件夹内包含如下:

Shell
.
├── <sid>_testchannel.m3u8
├── <sid>_testchannel_0.mp4
└── <sid>_testchannel_20241119070642248.ts

根据你在 start 方法中设置的录制时间,云存储中可能会有多个 .ts 文件。录制文件介绍请参考录制文件命名和切片规则。

进阶设置

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

Go
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 文档。

参考信息

示例项目

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

排查错误