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:

Call Acquire() to get a builder token for your transcoding task
Call Create() with your configuration to start transcoding specified streams
The service processes and publishes the transcoded streams to your target channels
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:
- Implement the Video Calling Quickstart, or
- Use the Agora Web Demo to simulate audio and video streams

Set up your project

Follow these steps to create and configure a new project:

Create an empty project folder named test-transcoder.
Navigate to the test-transcoder directory and initialize a Go module:

_1go mod init test-transcoder
Create a main.go file in the project directory for implementing your cloud transcoding task.
Install the Go SDK:

_5# Install the Go SDK _5go get -u github.com/AgoraIO-Community/agora-rest-client-go _5 _5# Update dependencies _5go mod tidy
Add the required imports to main.go:

_14package main _14 _14import ( _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.

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

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.

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

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.

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

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

Stop cloud transcoding

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

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

Complete example code

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

Complete sample code

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/cloudtranscoder"
  cloudTranscoderAPI "github.com/AgoraIO-Community/agora-rest-client-go/services/cloudtranscoder/api"
)
// Define key parameters
const (
  appId             = "<your_app_id>"
  token             = "<your_token>"           // Token for the transcoder in the input channel
  username          = "<your_customer_key>"    // Your customer ID
  password          = "<your_customer_secret>" // Your customer secret
  inputChannelName  = "show"                   // Channel name for the input stream
  inputUId          = 0                        // User ID for the input stream
  inputToken        = "<your_token>"           // Token for the input stream user
  outputChannelName = "show"                   // Channel name for the output stream
  outputUId         = 0                        // User ID for the transcoder in the output channel
  outputToken       = "<your_token>"           // Token for the transcoder in the output channel
  instanceId        = "quickstart"             // Instance ID of the transcoder
)
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),
  }
  client, err := cloudtranscoder.NewClient(config)
  if err != nil {
    log.Fatal(err)
  }
  // Call the Acquire API of the cloud transcoder service client
  acquireResp, err := client.Acquire(context.TODO(), &cloudTranscoderAPI.AcquireReqBody{
    InstanceId: instanceId,
  })
  if err != nil {
    log.Fatalln(err)
  }
  if acquireResp.IsSuccess() {
    log.Printf("acquire success:%+v\n", acquireResp)
  } else {
    log.Fatalf("acquire failed:%+v\n", acquireResp)
  }
  tokenName := acquireResp.SuccessResp.TokenName
  if tokenName == "" {
    log.Fatalln("tokenName is empty")
  }
  log.Printf("tokenName:%s\n", tokenName)
  // Create a cloud transcoding task and start cloud transcoding
  createResp, err := client.Create(context.TODO(), tokenName, &cloudTranscoderAPI.CreateReqBody{
    Services: &cloudTranscoderAPI.CreateReqServices{
      CloudTranscoder: &cloudTranscoderAPI.CloudTranscoderPayload{
        ServiceType: "cloudTranscoderV2",
        Config: &cloudTranscoderAPI.CloudTranscoderConfig{
          Transcoder: &cloudTranscoderAPI.CloudTranscoderConfigPayload{
            IdleTimeout: 300,
            AudioInputs: []cloudTranscoderAPI.CloudTranscoderAudioInput{
              {
                Rtc: &cloudTranscoderAPI.CloudTranscoderRtc{
                  RtcChannel: inputChannelName,
                  RtcUID:     inputUId,
                  RtcToken:   inputToken,
                },
              },
            },
            Outputs: []cloudTranscoderAPI.CloudTranscoderOutput{
              {
                Rtc: &cloudTranscoderAPI.CloudTranscoderRtc{
                  RtcChannel: outputChannelName,
                  RtcUID:     outputUId,
                  RtcToken:   outputToken,
                },
                AudioOption: &cloudTranscoderAPI.CloudTranscoderOutputAudioOption{
                  ProfileType: "AUDIO_PROFILE_MUSIC_STANDARD",
                },
              },
            },
          },
        },
      },
    },
  })
  if err != nil {
    log.Fatalln(err)
  }
  if createResp.IsSuccess() {
    log.Printf("create success:%+v\n", createResp)
  } else {
    log.Printf("create failed:%+v\n", createResp)
    return
  }
  taskId := createResp.SuccessResp.TaskID
  if taskId == "" {
    log.Fatalln("taskId is empty")
  }
  log.Printf("taskId:%s\n", taskId)
  // Wait for 10 seconds before stopping the cloud transcoding
  time.Sleep(time.Second * 10)
  // Stop the cloud transcoding
  deleteResp, err := client.Delete(context.TODO(), taskId, tokenName)
  if err != nil {
    log.Println(err)
    return
  }
  if deleteResp.IsSuccess() {
    log.Printf("delete success:%+v\n", deleteResp)
  } else {
    log.Printf("delete failed:%+v\n", deleteResp)
    return
  }
}

Test your implementation

Follow these steps to test Cloud Transcoding:

In the project folder, run the Go project:

_1go run main.go
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"
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.

Refer to the API documentation for complete parameter details.
If you encounter any problems, refer to Troubleshooting.

Sample project

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