cloudrecording

README

Cloud Recording Service

English | 简体中文

Service Introduction

Cloud Recording is a recording component developed by Agora for audio and video calls and live broadcasts. It provides RESTful APIs for developers to implement recording functionality and store recording files in third-party cloud storage. Cloud Recording offers advantages such as stability, reliability, ease of use, cost control, flexible solutions, and support for private deployment, making it an ideal recording solution for online education, video conferences, financial supervision, and customer service scenarios.

Environment Preparation

• Obtain Agora App ID -------- Agora Console

  • Click Create Application

    

  • Select the type of application you want to create

    

• Obtain App Certificate ----- Agora Console

  In the project management page of the Agora Console, find your project and click Configure. Click the copy icon under Primary Certificate to obtain the App Certificate for your project.

• Check the status of the recording service

  

API Call Examples

Acquire Cloud Recording Resources

Before starting cloud recording, you need to call the acquire method to obtain a Resource ID. A Resource ID can only be used for one cloud recording service.

Parameters that need to be set:

• appId: Agora project AppID
• username: Agora Basic Auth authentication username
• password: Agora Basic Auth authentication password
• cname: Channel name
• uid: User UID
• For more parameters in clientRequest, see the Acquire API documentation

Implement acquiring cloud recording resources by calling the Acquire method

    appId := "xxxx"
    username := "xxxx"
    password := "xxxx"
    credential := auth.NewBasicAuthCredential(username, password)
	config := &agora.Config{
		AppID:      appId,
		Credential: credential,
        DomainArea: domain.CN,
		Logger:     agoraLogger.NewDefaultLogger(agoraLogger.DebugLevel),
	}

	cloudRecordingClient, err := cloudrecording.NewClient(config)
	if err != nil {
		log.Println(err)
		return
	}

	resp, err := cloudRecordingClient.Acquire(context.TODO(), &cloudRecordingAPI.AcquireReqBody{
		Cname: "12321",
		Uid:   "43434",
		ClientRequest: &cloudRecordingAPI.AcquireClientRequest{
			Scene:               0,
		},
	})
	if err != nil {
		log.Fatal(err)
	}
	if resp.IsSuccess() {
		log.Printf("resourceId:%s", resp.SuccessRes.ResourceId)
	} else {
		log.Printf("resp:%+v", resp)
	}

Start Cloud Recording

After acquiring cloud recording resources through the acquire method, call the start method to begin cloud recording.

Parameters that need to be set:

• cname: Channel name
• uid: User UID
• token: Token corresponding to the user UID
• resourceId: Cloud recording resource ID
• mode: Cloud recording mode
• For more parameters in clientRequest, see the Start API documentation

Implement starting cloud recording by calling the Start method

	startResp, err := cloudRecordingClient.Start(ctx, resp.SuccessRes.ResourceId, mode, &cloudRecordingAPI.StartReqBody{
		Cname: cname,
		Uid:   uid,
		ClientRequest: &cloudRecordingAPI.StartClientRequest{
			Token: token,
			RecordingConfig: &cloudRecordingAPI.RecordingConfig{
				ChannelType:  1,
				StreamTypes:  2,
				AudioProfile: 2,
				MaxIdleTime:  30,
				TranscodingConfig: &cloudRecordingAPI.TranscodingConfig{
					Width:            640,
					Height:           260,
					FPS:              15,
					BitRate:          500,
					MixedVideoLayout: 0,
					BackgroundColor:  "#000000",
				},
				SubscribeAudioUIDs: []string{
					"22",
					"456",
				},
				SubscribeVideoUIDs: []string{
					"22",
					"456",
				},
			},
			RecordingFileConfig: &cloudRecordingAPI.RecordingFileConfig{
				AvFileType: []string{
					"hls",
				},
			},
			StorageConfig: &cloudRecordingAPI.StorageConfig{
				Vendor:    2,
				Region:    3,
				Bucket:    "xxx",
				AccessKey: "xxxx",
				SecretKey: "xxx",
				FileNamePrefix: []string{
					"xx1",
					"xx2",
				},
			},
		},
	})
	if err != nil {
		log.Fatalln(err)
	}
	if startResp.IsSuccess() {
		log.Printf("success:%+v", &startResp.SuccessResponse)
	} else {
		log.Printf("failed:%+v", &startResp.ErrResponse)
	}

Stop Cloud Recording

After starting recording, you can call the stop method to leave the channel and stop recording. If you need to record again after stopping, you must call the acquire method again to request a new Resource ID.

Parameters that need to be set:

• cname: Channel name
• uid: User ID
• resourceId: Cloud recording resource ID
• sid: Session ID
• mode: Cloud recording mode
• For more parameters in clientRequest, see the Stop API documentation

Since the Stop interface does not return a fixed structure, you need to determine the specific return type based on the serverResponseMode returned

Implement stopping cloud recording by calling the Stop method

    stopResp, err := cloudRecordingClient.Stop(ctx, resourceId, sid, mode, &cloudRecordingAPI.cloudRecordingAPI{
		Cname: cname,
		Uid:   uid,
		ClientRequest: &cloudRecordingAPI.StopClientRequest{
			AsyncStop: true,
		},
	})
	if err != nil {
		log.Fatalln(err)
	}
	if stopResp.IsSuccess() {
		log.Printf("stop success:%+v", &stopResp.SuccessResponse)
	} else {
		log.Fatalf("stop failed:%+v", &stopResp.ErrResponse)
	}

Query Cloud Recording Status

After starting recording, you can call the query method to check the recording status.

Parameters that need to be set:

• cname: Channel name
• uid: User ID
• resourceId: Cloud recording resource ID
• sid: Session ID
• mode: Cloud recording mode
• For more parameters in clientRequest, see the Query API documentation

Since the Query interface does not return a fixed structure, you need to determine the specific return type based on the serverResponseMode returned

Implement querying cloud recording status by calling the Query method

	queryResp, err := cloudRecordingClient.Query(ctx, resourceId, sid, mode)
	if err != nil {
		log.Fatalln(err)
	}
	if queryResp.IsSuccess() {
		log.Printf("query success:%+v", queryResp.SuccessResponse)
	} else {
		log.Printf("query failed:%+v", queryResp.ErrResponse)
		return
	}

	var queryServerResponse interface{}

	querySuccess := queryResp.SuccessResponse
	switch querySuccess.GetServerResponseMode() {
	case cloudRecordingAPI.QueryServerResponseUnknownMode:
		log.Fatalln("unknown mode")
	case cloudRecordingAPI.QueryIndividualRecordingServerResponseMode:
		log.Printf("serverResponseMode:%d", cloudRecordingAPI.QueryIndividualRecordingServerResponseMode)
		queryServerResponse = querySuccess.GetIndividualRecordingServerResponse()
	case cloudRecordingAPI.QueryIndividualVideoScreenshotServerResponseMode:
		log.Printf("serverResponseMode:%d", cloudRecordingAPI.QueryIndividualVideoScreenshotServerResponseMode)
		queryServerResponse = querySuccess.GetIndividualVideoScreenshotServerResponse()
	case cloudRecordingAPI.QueryMixRecordingHlsServerResponseMode:
		log.Printf("serverResponseMode:%d", cloudRecordingAPI.QueryMixRecordingHlsServerResponseMode)
		queryServerResponse = querySuccess.GetMixRecordingHLSServerResponse()
	case cloudRecordingAPI.QueryMixRecordingHlsAndMp4ServerResponseMode:
		log.Printf("serverResponseMode:%d", cloudRecordingAPI.QueryMixRecordingHlsAndMp4ServerResponseMode)
		queryServerResponse = querySuccess.GetMixRecordingHLSAndMP4ServerResponse()
	case cloudRecordingAPI.QueryWebRecordingServerResponseMode:
		log.Printf("serverResponseMode:%d", cloudRecordingAPI.QueryWebRecordingServerResponseMode)
		queryServerResponse = querySuccess.GetWebRecording2CDNServerResponse()
	}

	log.Printf("queryServerResponse:%+v", queryServerResponse)

Update Cloud Recording Settings

After starting recording, you can call the update method to update the following recording configurations:

• For individual recording and composite recording, update the subscription list.
• For web recording, set pause/resume web recording, or update the streaming URL for pushing web recording to CDN.

Parameters that need to be set:

• cname: Channel name
• uid: User UID
• resourceId: Cloud recording resource ID
• sid: Session ID
• mode: Cloud recording mode
• For more parameters in clientRequest, see the Update API documentation

Implement updating cloud recording settings by calling the Update method

	updateResp, err := cloudRecordingClient.Update(ctx, resourceId, sid, mode, &cloudRecordingAPI.UpdateReqBody{
		Cname: cname,
		Uid:   uid,
		ClientRequest: &cloudRecordingAPI.UpdateClientRequest{
			StreamSubscribe: &cloudRecordingAPI.UpdateStreamSubscribe{
				AudioUidList: &cloudRecordingAPI.UpdateAudioUIDList{
					SubscribeAudioUIDs: []string{
						"999",
					},
				},
				VideoUidList: &cloudRecordingAPI.UpdateVideoUIDList{
					SubscribeVideoUIDs: []string{
						"999",
					},
				},
			},
		},
	})

	if err != nil {
		log.Fatalln(err)
	}
	if updateResp.IsSuccess() {
		log.Printf("update success:%+v", updateResp.SuccessResponse)
	} else {
		log.Printf("update failed:%+v", updateResp.ErrResponse)
		return
	}

Update Cloud Recording Composite Layout

After starting recording, you can call the updateLayout method to update the composite layout. Each call to this method will overwrite the previous layout settings. For example, if you set backgroundColor to "#FF0000" (red) when starting recording, if you call the updateLayout method to update the composite layout without setting the backgroundColor field again, the background color will change to black (default value).

Parameters that need to be set:

• cname: Channel name
• uid: User UID
• resourceId: Cloud recording resource ID
• sid: Session ID
• mode: Cloud recording mode
• For more parameters in clientRequest, see the UpdateLayout API documentation

Implement updating cloud recording composite layout by calling the UpdateLayout method

	updateLayoutResp, err := cloudRecordingClient.UpdateLayout(ctx, resourceId, sid, mode, &cloudRecordingAPI.UpdateLayoutReqBody{
		Cname: cname,
		Uid:   uid,
		ClientRequest: &cloudRecordingAPI.UpdateLayoutClientRequest{
			MixedVideoLayout: 3,
			BackgroundColor:  "#FF0000",
			LayoutConfig: []cloudRecordingAPI.UpdateLayoutConfig{
				{
					UID:        "22",
					XAxis:      0.1,
					YAxis:      0.1,
					Width:      0.1,
					Height:     0.1,
					Alpha:      1,
					RenderMode: 1,
				},
				{
					UID:        "2",
					XAxis:      0.2,
					YAxis:      0.2,
					Width:      0.1,
					Height:     0.1,
					Alpha:      1,
					RenderMode: 1,
				},
			},
		},
	})
	if err != nil {
		log.Fatalln(err)
	}
	if updateLayoutResp.IsSuccess() {
		log.Printf("updateLayout success:%+v", updateLayoutResp.SuccessResponse)
	} else {
		log.Printf("updateLayout failed:%+v", updateLayoutResp.ErrResponse)
		return
	}

Error Codes and Response Status Codes

For specific business response codes, please refer to the Business Response Codes documentation

Documentation

Index

• Variables
• type Client
  • func NewClient(config *Config) (*Client, error)
  • func (c *Client) Acquire(ctx context.Context, payload *api.AcquireReqBody) (*api.AcquireResp, error)
  • func (c *Client) IndividualRecording() *scenario.IndividualRecording
  • func (c *Client) MixRecording() *scenario.MixRecording
  • func (c *Client) Query(ctx context.Context, resourceID string, sid string, mode string) (*api.QueryResp, error)
  • func (c *Client) Start(ctx context.Context, resourceID string, mode string, payload *api.StartReqBody) (*api.StartResp, error)
  • func (c *Client) Stop(ctx context.Context, resourceID string, sid string, mode string, ...) (*api.StopResp, error)
  • func (c *Client) Update(ctx context.Context, resourceID string, sid string, mode string, ...) (*api.UpdateResp, error)
  • func (c *Client) UpdateLayout(ctx context.Context, resourceID string, sid string, mode string, ...) (*api.UpdateLayoutResp, error)
  • func (c *Client) WebRecording() *scenario.WebRecording
• type Config

Variables

var RetryCount = 3

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

func NewClient

func NewClient(config *Config) (*Client, error)

NewClient

@brief Creates a Cloud Recording client with the specified configuration

@param config Configuration of the Cloud Recording client instance. See Config for details.

@return Returns the Cloud Recording client instance.

@return Returns an error object. If the request fails, the error object is not nil and contains error information.

@since v0.8.0

func (*Client) Acquire

func (c *Client) Acquire(ctx context.Context, payload *api.AcquireReqBody) (*api.AcquireResp, error)

func (*Client) IndividualRecording

func (c *Client) IndividualRecording() *scenario.IndividualRecording

@brief Returns the individual recording scenario instance.

@return Returns the individual recording scenario instance. See scenario.IndividualRecording for details.

@since v0.8.0

func (*Client) MixRecording

func (c *Client) MixRecording() *scenario.MixRecording

@brief Returns the mix recording scenario instance.

@return Returns the mix recording scenario instance. See scenario.MixRecording for details.

@since v0.8.0

func (*Client) Query

func (c *Client) Query(ctx context.Context, resourceID string, sid string, mode string) (*api.QueryResp, error)

func (*Client) Start

func (c *Client) Start(ctx context.Context, resourceID string, mode string, payload *api.StartReqBody) (*api.StartResp, error)

func (*Client) Stop

func (c *Client) Stop(ctx context.Context, resourceID string, sid string, mode string, payload *api.StopReqBody) (*api.StopResp, error)

func (*Client) Update

func (c *Client) Update(ctx context.Context, resourceID string, sid string, mode string, payload *api.UpdateReqBody) (*api.UpdateResp, error)

func (*Client) UpdateLayout

func (c *Client) UpdateLayout(ctx context.Context, resourceID string, sid string, mode string, payload *api.UpdateLayoutReqBody) (*api.UpdateLayoutResp, error)

func (*Client) WebRecording

func (c *Client) WebRecording() *scenario.WebRecording

@brief Returns the web recording scenario instance.

@return Returns the web recording scenario instance. See scenario.WebRecording for details.

@since v0.8.0

type Config

type Config struct {
	// Agora AppID
	AppID string
	// Timeout for HTTP requests
	HttpTimeout time.Duration
	// Credential for accessing the Agora service.
	//
	// Available credential types:
	//
	//  - BasicAuthCredential: See auth.NewBasicAuthCredential for details
	Credential auth.Credential

	// Domain area for the REST Client. See domain.Area for details.
	DomainArea domain.Area

	// Logger for the REST Client
	//
	// Implement the log.Logger interface in your project to output REST Client logs to your logging component.
	//
	// Alternatively, you can use the default logging component. See log.NewDefaultLogger for details.
	Logger log.Logger
}

@brief Defines the configuration for the Cloud Recording client

@since v0.8.0