Skip to main content

SDK Quickstart

This article explains how to use the Agora Go SDK to start cloud transcoding. The Go SDK helps developers integrate Agora's RESTful API more easily. It offers the following features:

  • Simplified communication: The SDK encapsulates RESTful API requests and responses to simplify communication.
  • Ensured availability: If DNS resolution fails, network errors occur, or requests time out, the SDK automatically switches to the optimal domain to ensure REST service availability.
  • Easy-to-use API: The SDK provides a simple and intuitive API that makes it easy to perform common tasks such as creating and destroying cloud transcoding sessions.
  • Additional benefits: Built with Go, the SDK offers efficiency, concurrency, and scalability.

Understand the tech

When you use the Go SDK for Cloud Transcoding:

  1. Call Acquire() to get a builder token for your transcoding task
  2. Call Create() with your configuration to start transcoding specified streams
  3. The service processes and publishes the transcoded streams to your target channels
  4. Viewers can subscribe to either original or transcoded streams

The following sections show you how to implement this workflow.

Prerequisites

Before you start, ensure that you have:

  • Go 1.18 or higher
  • Followed the Enable Cloud Transcoding guide to:
    • Set up your Agora account and activate the Cloud Transcoding service
    • Obtain your App ID from Agora Console
    • Obtain your Customer ID and Customer Secret for REST API authentication
    • Generate RTC tokens for your channels (valid for up to 24 hours)
  • A way to test transcoding input streams:

Set up your project

Follow these steps to create and configure a new project:

  1. Create an empty project folder named test-transcoder.

  2. Navigate to the test-transcoder directory and initialize a Go module:


    _1
    go mod init test-transcoder

  3. Create a main.go file in the project directory for implementing your cloud transcoding task.

  4. Install the Go SDK:


    _5
    # Install the Go SDK
    _5
    go get -u github.com/AgoraIO-Community/agora-rest-client-go
    _5
    _5
    # Update dependencies
    _5
    go mod tidy

  5. Add the required imports to main.go:


    _14
    package main
    _14
    _14
    import (
    _14
    "context"
    _14
    "log"
    _14
    "time"
    _14
    _14
    "github.com/AgoraIO-Community/agora-rest-client-go/agora"
    _14
    "github.com/AgoraIO-Community/agora-rest-client-go/agora/auth"
    _14
    "github.com/AgoraIO-Community/agora-rest-client-go/agora/domain"
    _14
    agoraLogger "github.com/AgoraIO-Community/agora-rest-client-go/agora/log"
    _14
    "github.com/AgoraIO-Community/agora-rest-client-go/services/cloudtranscoder"
    _14
    cloudTranscoderAPI "github.com/AgoraIO-Community/agora-rest-client-go/services/cloudtranscoder/api"
    _14
    )

Implement cloud transcoding

This section introduces the minimal workflow for cloud transcoding. For demonstration purposes, this example only transcodes the host's audio.

Define variables

In the main.go, add the following code to define and configure the key parameters.


_14
// Define key parameters
_14
const (
_14
appId = "<your_app_id>"
_14
token = "<your_token>" // Token for the transcoder in the input channel
_14
username = "<your_customer_key>" // Your customer ID
_14
password = "<your_customer_secret>" // Your customer secret
_14
inputChannelName = "show" // Channel name for the input stream
_14
inputUId = 0 // User ID for the input stream
_14
inputToken = "<your_token>" // Token for the input stream user
_14
outputChannelName = "show" // Channel name for the output stream
_14
outputUId = 0 // User ID for the transcoder in the output channel
_14
outputToken = "<your_token>" // Token for the transcoder in the output channel
_14
instanceId = "quickstart" // Instance ID of the transcoder
_14
)

info
  • In this example, the stream from the host of the show channel is used as the input stream for the transcoder. To simplify parameter configuration, the transcoder's output stream is also published to the same channel. The input and output streams share the same token.

  • For Cloud Transcoding, multiple input streams must come from the same channel, while the output can be one or more streams and may be assigned to any channel.

Create and initialize the client

In main.go, add the following code to create and initialize the client.


_15
config := &agora.Config{
_15
AppID: appId,
_15
Credential: auth.NewBasicAuthCredential(username, password),
_15
// Specify the region where the server is located. Options include US, EU, AP, CN.
_15
// The client automatically switches to use the best domain based on the configured region.
_15
DomainArea: domain.US,
_15
// Specify the log output level. Options include DebugLevel, InfoLevel, WarningLevel, ErrLevel.
_15
// To disable log output, set logger to DiscardLogger.
_15
Logger: agoraLogger.NewDefaultLogger(agoraLogger.DebugLevel),
_15
}
_15
_15
client, err := cloudtranscoder.NewClient(config)
_15
if err != nil {
_15
log.Fatal(err)
_15
}

Get cloud transcoding resources

Before creating a cloud transcoding task, call the Acquire method to obtain a builder token tokenName. A token can only be used for a single cloud transcoding task.


_20
// Call the Acquire API of the cloud transcoder service client
_20
acquireResp, err := client.Acquire(context.TODO(), &cloudTranscoderAPI.AcquireReqBody{
_20
InstanceId: instanceId,
_20
})
_20
if err != nil {
_20
log.Fatalln(err)
_20
}
_20
if acquireResp.IsSuccess() {
_20
log.Printf("acquire success:%+v\n", acquireResp)
_20
} else {
_20
log.Fatalf("acquire failed:%+v\n", acquireResp)
_20
}
_20
_20
tokenName := acquireResp.SuccessResp.TokenName
_20
_20
if tokenName == "" {
_20
log.Fatalln("tokenName is empty")
_20
}
_20
_20
log.Printf("tokenName:%s\n", tokenName)

Start cloud transcoding

Call Create to create a Cloud Transcoding task and start transcoding. In this example, the audio and video streams of two hosts in the same channel are mixed and combined.


_55
// Create a cloud transcoding task and start cloud transcoding
_55
createResp, err := client.Create(context.TODO(), tokenName, &cloudTranscoderAPI.CreateReqBody{
_55
Services: &cloudTranscoderAPI.CreateReqServices{
_55
CloudTranscoder: &cloudTranscoderAPI.CloudTranscoderPayload{
_55
ServiceType: "cloudTranscoderV2",
_55
Config: &cloudTranscoderAPI.CloudTranscoderConfig{
_55
Transcoder: &cloudTranscoderAPI.CloudTranscoderConfigPayload{
_55
IdleTimeout: 300,
_55
AudioInputs: []cloudTranscoderAPI.CloudTranscoderAudioInput{
_55
{
_55
Rtc: &cloudTranscoderAPI.CloudTranscoderRtc{
_55
RtcChannel: inputChannelName,
_55
RtcUID: inputUId,
_55
RtcToken: inputToken,
_55
},
_55
},
_55
},
_55
Outputs: []cloudTranscoderAPI.CloudTranscoderOutput{
_55
{
_55
Rtc: &cloudTranscoderAPI.CloudTranscoderRtc{
_55
RtcChannel: outputChannelName,
_55
RtcUID: outputUId,
_55
RtcToken: outputToken,
_55
},
_55
AudioOption: &cloudTranscoderAPI.CloudTranscoderOutputAudioOption{
_55
ProfileType: "AUDIO_PROFILE_MUSIC_STANDARD",
_55
},
_55
},
_55
},
_55
},
_55
},
_55
},
_55
},
_55
})
_55
if err != nil {
_55
log.Fatalln(err)
_55
}
_55
_55
if createResp.IsSuccess() {
_55
log.Printf("create success:%+v\n", createResp)
_55
} else {
_55
log.Printf("create failed:%+v\n", createResp)
_55
return
_55
}
_55
_55
taskId := createResp.SuccessResp.TaskID
_55
_55
if taskId == "" {
_55
log.Fatalln("taskId is empty")
_55
}
_55
_55
log.Printf("taskId:%s\n", taskId)
_55
_55
// Wait for 10 seconds before stopping the cloud transcoding
_55
time.Sleep(time.Second * 10)

Stop cloud transcoding

When the transcoding task is complete, call the Delete method to end cloud transcoding:


_13
// Stop the cloud transcoding task
_13
deleteResp, err := client.Delete(context.TODO(), taskId, tokenName)
_13
if err != nil {
_13
log.Println(err)
_13
return
_13
}
_13
_13
if deleteResp.IsSuccess() {
_13
log.Printf("delete success:%+v\n", deleteResp)
_13
} else {
_13
log.Printf("delete failed:%+v\n", deleteResp)
_13
return
_13
}

Complete example code

The complete sample code for this example is presented here for your reference and use.

Complete sample code

_138
package main
_138
_138
import (
_138
"context"
_138
"log"
_138
"time"
_138
_138
"github.com/AgoraIO-Community/agora-rest-client-go/agora"
_138
"github.com/AgoraIO-Community/agora-rest-client-go/agora/auth"
_138
"github.com/AgoraIO-Community/agora-rest-client-go/agora/domain"
_138
agoraLogger "github.com/AgoraIO-Community/agora-rest-client-go/agora/log"
_138
"github.com/AgoraIO-Community/agora-rest-client-go/services/cloudtranscoder"
_138
cloudTranscoderAPI "github.com/AgoraIO-Community/agora-rest-client-go/services/cloudtranscoder/api"
_138
)
_138
_138
// Define key parameters
_138
const (
_138
appId = "<your_app_id>"
_138
token = "<your_token>" // Token for the transcoder in the input channel
_138
username = "<your_customer_key>" // Your customer ID
_138
password = "<your_customer_secret>" // Your customer secret
_138
inputChannelName = "show" // Channel name for the input stream
_138
inputUId = 0 // User ID for the input stream
_138
inputToken = "<your_token>" // Token for the input stream user
_138
outputChannelName = "show" // Channel name for the output stream
_138
outputUId = 0 // User ID for the transcoder in the output channel
_138
outputToken = "<your_token>" // Token for the transcoder in the output channel
_138
instanceId = "quickstart" // Instance ID of the transcoder
_138
)
_138
_138
func main() {
_138
// Initialize Agora Config
_138
config := &agora.Config{
_138
AppID: appId,
_138
Credential: auth.NewBasicAuthCredential(username, password),
_138
// Specify the region where the server is located. Options include CN, EU, AP, US.
_138
// The client will automatically switch to use the best domain based on the configured region.
_138
DomainArea: domain.CN,
_138
// Specify the log output level. Options include DebugLevel, InfoLevel, WarningLevel, ErrLevel.
_138
// To disable log output, set logger to DiscardLogger.
_138
Logger: agoraLogger.NewDefaultLogger(agoraLogger.DebugLevel),
_138
}
_138
_138
client, err := cloudtranscoder.NewClient(config)
_138
if err != nil {
_138
log.Fatal(err)
_138
}
_138
_138
// Call the Acquire API of the cloud transcoder service client
_138
acquireResp, err := client.Acquire(context.TODO(), &cloudTranscoderAPI.AcquireReqBody{
_138
InstanceId: instanceId,
_138
})
_138
if err != nil {
_138
log.Fatalln(err)
_138
}
_138
if acquireResp.IsSuccess() {
_138
log.Printf("acquire success:%+v\n", acquireResp)
_138
} else {
_138
log.Fatalf("acquire failed:%+v\n", acquireResp)
_138
}
_138
_138
tokenName := acquireResp.SuccessResp.TokenName
_138
_138
if tokenName == "" {
_138
log.Fatalln("tokenName is empty")
_138
}
_138
_138
log.Printf("tokenName:%s\n", tokenName)
_138
_138
// Create a cloud transcoding task and start cloud transcoding
_138
createResp, err := client.Create(context.TODO(), tokenName, &cloudTranscoderAPI.CreateReqBody{
_138
Services: &cloudTranscoderAPI.CreateReqServices{
_138
CloudTranscoder: &cloudTranscoderAPI.CloudTranscoderPayload{
_138
ServiceType: "cloudTranscoderV2",
_138
Config: &cloudTranscoderAPI.CloudTranscoderConfig{
_138
Transcoder: &cloudTranscoderAPI.CloudTranscoderConfigPayload{
_138
IdleTimeout: 300,
_138
AudioInputs: []cloudTranscoderAPI.CloudTranscoderAudioInput{
_138
{
_138
Rtc: &cloudTranscoderAPI.CloudTranscoderRtc{
_138
RtcChannel: inputChannelName,
_138
RtcUID: inputUId,
_138
RtcToken: inputToken,
_138
},
_138
},
_138
},
_138
Outputs: []cloudTranscoderAPI.CloudTranscoderOutput{
_138
{
_138
Rtc: &cloudTranscoderAPI.CloudTranscoderRtc{
_138
RtcChannel: outputChannelName,
_138
RtcUID: outputUId,
_138
RtcToken: outputToken,
_138
},
_138
AudioOption: &cloudTranscoderAPI.CloudTranscoderOutputAudioOption{
_138
ProfileType: "AUDIO_PROFILE_MUSIC_STANDARD",
_138
},
_138
},
_138
},
_138
},
_138
},
_138
},
_138
},
_138
})
_138
if err != nil {
_138
log.Fatalln(err)
_138
}
_138
_138
if createResp.IsSuccess() {
_138
log.Printf("create success:%+v\n", createResp)
_138
} else {
_138
log.Printf("create failed:%+v\n", createResp)
_138
return
_138
}
_138
_138
taskId := createResp.SuccessResp.TaskID
_138
_138
if taskId == "" {
_138
log.Fatalln("taskId is empty")
_138
}
_138
_138
log.Printf("taskId:%s\n", taskId)
_138
_138
// Wait for 10 seconds before stopping the cloud transcoding
_138
time.Sleep(time.Second * 10)
_138
_138
// Stop the cloud transcoding
_138
deleteResp, err := client.Delete(context.TODO(), taskId, tokenName)
_138
if err != nil {
_138
log.Println(err)
_138
return
_138
}
_138
if deleteResp.IsSuccess() {
_138
log.Printf("delete success:%+v\n", deleteResp)
_138
} else {
_138
log.Printf("delete failed:%+v\n", deleteResp)
_138
return
_138
}
_138
}

Test your implementation

Follow these steps to test Cloud Transcoding:

  1. In the project folder, run the Go project:


    _1
    go run main.go

  2. Check the console output for successful execution:

    • Look for "acquire success" followed by a tokenName
    • Look for "create success" followed by a taskId
    • After 10 seconds, look for "delete success"
  3. To test the transcoded audio output:

    • Open the Agora Web Demo
    • Join the same channel you configured
    • You hear audio transcoded by your Go application

If you see error messages, check that your App ID, tokens, and credentials are correct.

Reference

This section contains content that completes the information on this page, or points you to documentation that explains other aspects to this product.

Sample project

For more Cloud Transcoding examples, see the Sample project on GitHub.