使用 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 以备用。

  开通方式

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

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

• 在项目中实现了基础的音视频互动场景。你也可以参考文档使用声网实时互动 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"
     "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 文件中，添加如下代码，定义或配置关键参数，取值参考前提条件。

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。

Go

// 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 以备后用。

Go

// 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 开始录制。

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, &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 结束录制。

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 文件中完整代码如下，你可自行比对：

完整示例代码

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 文件夹内包含如下：

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

参考信息

示例项目

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

Gitee 示例项目

GitHub 示例项目

排查错误

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