文档

Go SDK

更新时间:

本文介绍如何使用阿里云智能语音服务提供的Go SDK,包括SDK的安装方法及SDK代码示例。

前提条件

在使用SDK前,请先阅读接口说明,详情请参见接口说明

下载安装

说明
  • SDK支持Go 1.16及以上版本。

  • 请确认已经安装Golang环境,并完成基本配置。

  1. 下载并安装SDK。

    通过以下命令完成SDK下载和安装。

    go get github.com/aliyun/alibabacloud-nls-go-sdk
  2. 导入SDK。

    在代码中通过添加以下字段导入SDK。

    import ("github.com/aliyun/alibabacloud-nls-go-sdk")

SDK常量

常量

含义

SDK_VERSION

SDK版本。

PCM

PCM音频格式。

WAV

WAV音频格式。

OPUS

OPUS音频格式。

OPU

OPU音频格式。

DEFAULT_DISTRIBUTE

获取Token时使用的默认区域,默认为"cn-shanghai"。

DEFAULT_DOMAIN

获取Token时使用的默认URL,默认为"nls-meta.cn-shanghai.aliyuncs.com"。

DEFAULT_VERSION

获取Token时使用的协议版本,默认为"2019-02-28"。

DEFAULT_URL

默认公有云URL,默认为"wss://nls-gateway-cn-shanghai.aliyuncs.com/ws/v1"。

建立连接

重要

使用AkidAkkey来获取Token时,建议针对Token进行缓存,并根据获取Token时获得的过期时间参数进行及时更新;请勿频繁调用获取Token的接口,否则会造成云端限流。

1.ConnectionConfig

用于建立连接的基础参数。

参数说明:

参数

类型

参数说明

Url

String

访问的公有云URL,如果不确定,可以使用常量DEFAULT_URL

Token

String

访问Token,详情可参见获取Token概述

Akid

String

阿里云账号AccessKey ID。

  • 若未填写Token字段,则需要填写该字段。

  • 若已填写Token字段,则该字段可不填写。

Akkey

String

阿里云账号AccessKey Secret。

  • 若未填写Token字段,则需要填写该字段。

  • 若已填写Token字段,则该字段可不填写。

Appkey

String

对应项目Appkey。

2.func NewConnectionConfigWithToken(url string, appkey string, token string) *ConnectionConfig

通过URL、Appkey和Token创建连接参数。

  • 参数说明:

参数

类型

参数说明

Url

String

访问的公有云URL,如果不确定,可以使用常量DEFAULT_URL

Appkey

String

对应项目Appkey。

Token

String

访问Token,详情可参见获取Token概述

  • 返回值:

*ConnectionConfig:连接配置对象指针。

3. func NewConnectionConfigFromJson(jsonStr string) (*ConnectionConfig, error)

通过JSON字符串来创建连接参数。

  • 参数说明:

参数

类型

参数说明

jsonStr

String

描述连接参数的JSON字符串,有效字段如下:urltokenakidakkeyappkey。其中必须包含urlappkey,如果包含Token则不需要包含akidakkey

  • 返回值:

*ConnectionConfig:连接配置对象指针。

语音合成

1.SpeechSynthesisStartParam

实时语音合成参数。

参数

类型

参数说明

Voice

String

发音人,默认值:“xiaoyun”。

Format

String

音频格式,默认使用WAV。

SampleRate

Integer

采样率,默认值:16000 Hz。

Volume

Integer

音量,范围为0~100,默认值:50。

SpeechRate

Integer

语速,范围为-500~500,默认值:0。

PitchRate

Integer

音高,范围为-500~500,默认值:0。

EnableSubtitle

Boolean

是否开启字幕功能,默认不开启。

  • true:开启。

  • false:不开启。

2.func DefaultSpeechSynthesisParam() SpeechSynthesisStartParam

创建一个默认的语音合成参数。

  • 参数说明:无。

  • 返回值:

    SpeechSynthesisStartParam:默认参数。

3.func NewSpeechSynthesis(...) (*SpeechSynthesis, error)

创建一个新的语音合成对象。

  • 参数说明:

参数

类型

参数说明

config

*ConnectionConfig

参见建立连接相关内容。

logger

*NlsLogger

参见SDK日志相关内容。

realtimeLongText

Boolean

  • false:短文本。

  • true:实时长文本。

taskfailed

func(string, interface{})

识别过程中的错误处理回调参数,interface{}为用户自定义参数。

synthesisresult

func([]byte, interface{})

语音合成数据回调参数。

metainfo

func(string, interface{})

字幕数据回调,需要参数中EnableSubtitle为true。

completed

func(string, interface{})

合成完毕结果回调参数。

closed

func(interface{})

连接断开回调参数。

param

interface{}

用户自定义参数。

  • 返回值:无。

4.func (tts *SpeechSynthesis) Start(text string, param SpeechSynthesisStartParam, extra map[string]interface{}) (chan bool, error)

给定文本和参数进行语音合成。

  • 参数说明:

参数

类型

参数说明

text

String

待合成文本。

param

SpeechRecognitionStartParam

实时合成参数。

extra

map[string]interface{}

额外key:value参数。

  • 返回值:

    • chan bool:语音合成完成通知管道。

    • error:错误异常。

5.func (tts *SpeechSynthesis) Shutdown()

强制停止语音合成。

  • 参数说明:无。

  • 返回值:无。

SDK日志

1.func DefaultNlsLog() *NlsLogger

用于创建全局唯一的默认日志对象,默认日志以NLS为前缀,输出到标准错误。

  • 参数说明:无。

  • 返回值:

NlsLogger:日志对象指针。

2.func NewNlsLogger(w io.Writer, tag string, flag int) *NlsLogger

创建一个新的日志。

  • 参数说明:

参数

类型

参数说明

w

io.Writer

任意实现io.Writer接口的对象。

tag

String

日志前缀,会打印到日志行首部。

flag

Integer

日志flag,具体请参见Go官方log文档

  • 返回值:

NlsLogger:日志对象指针。

3.func (logger *NlsLogger) SetLogSil(sil bool)

设置日志是否输出到对应的io.Writer。

  • 参数说明:

参数

类型

参数说明

sil

Boolean

是否禁止日志输出。

  • true:禁止。

  • false:允许。

  • 返回值:无。

4.func (logger *NlsLogger) SetDebug(debug bool)

设置是否打印Debug日志,仅影响通过Debugf或Debugln进行输出的日志。

  • 参数说明:

参数

类型

参数说明

debug

Boolean

是否允许Debug日志输出。

  • true:允许。

  • false:禁止。

  • 返回值:无。

5. func (logger *NlsLogger) SetOutput(w io.Writer)

设置日志输出方式。

  • 参数说明:

参数

类型

参数说明

w

io.Writer

任意实现io.Writer接口的对象。

  • 返回值:无。

6. func (logger *NlsLogger) SetPrefix(prefix string)

设置日志行的标签。

  • 参数说明:

参数

类型

参数说明

prefix

String

日志行标签,会输出在日志行行首。

  • 返回值:无。

7. func (logger *NlsLogger) SetFlags(flags int)

设置日志属性。

  • 参数说明:

参数

类型

参数说明

flags

Integer

日志属性,具体请参见Go官方文档

  • 返回值:无。

8. 日志打印

日志打印方法:

方法名

方法说明

func (l *NlsLogger) Print(v ...interface{})

标准日志输出。

func (l *NlsLogger) Println(v ...interface{})

标注日志输出,行尾自动换行。

func (l *NlsLogger) Printf(format string, v ...interface{})

带Format的日志输出,Format方式见具体请参见Go官方文档

func (l *NlsLogger) Debugln(v ...interface{})

Debug信息日志输出,行尾自动换行。

func (l *NlsLogger) Debugf(format string, v ...interface{})

带Format的Debug信息日志输出。

func (l *NlsLogger) Fatal(v ...interface{})

致命错误日志输出,输出后自动进程退出。

func (l *NlsLogger) Fatalln(v ...interface{})

致命错误日志输出,行尾自动换行,输出后自动进程退出。

func (l *NlsLogger) Fatalf(format string, v ...interface{})

带Format的致命错误日志输出,输出后自动进程退出。

func (l *NlsLogger) Panic(v ...interface{})

致命错误日志输出,输出后自动进程退出并打印崩溃信息。

func (l *NlsLogger) Panicln(v ...interface{})

致命错误日志输出,行尾自动换行,输出后自动进程退出并打印崩溃信息。

func (l *NlsLogger) Panicf(format string, v ...interface{})

带Format的致命错误日志输出,输出后自动进程退出并打印崩溃信息。

代码示例

package main

import (
  "errors"
  "io"
  "log"
  "os"
  "sync"
  "time"

  nls "github.com/aliyun/alibabacloud-nls-go-sdk"
)

const (
  //online key
  APPKEY = "Your APPKEY" //获取Appkey请前往控制台:https://nls-portal.console.aliyun.com/applist
  TOKEN  = "Your TOKEN"  //获取Token具体操作,请参见:https://help.aliyun.com/document_detail/450514.html
)

type TtsUserParam struct {
  F      io.Writer
  Logger *nls.NlsLogger
}

func onTaskFailed(text string, param interface{}) {
  p, ok := param.(*TtsUserParam)
  if !ok {
    log.Default().Fatal("invalid logger")
    return
  }

  p.Logger.Println("TaskFailed:", text)
}

func onSynthesisResult(data []byte, param interface{}) {
  p, ok := param.(*TtsUserParam)
  if !ok {
    log.Default().Fatal("invalid logger")
    return
  }
  p.F.Write(data)
}

func onCompleted(text string, param interface{}) {
  p, ok := param.(*TtsUserParam)
  if !ok {
    log.Default().Fatal("invalid logger")
    return
  }

  p.Logger.Println("onCompleted:", text)
}

func onClose(param interface{}) {
  p, ok := param.(*TtsUserParam)
  if !ok {
    log.Default().Fatal("invalid logger")
    return
  }

  p.Logger.Println("onClosed:")
}

func waitReady(ch chan bool, logger *nls.NlsLogger) error {
  select {
  case done := <-ch:
    {
      if !done {
        logger.Println("Wait failed")
        return errors.New("wait failed")
      }
      logger.Println("Wait done")
    }
  case <-time.After(60 * time.Second):
    {
      logger.Println("Wait timeout")
      return errors.New("wait timeout")
    }
  }
  return nil
}

var lk sync.Mutex
var fail = 0
var reqNum = 0

const (
  TEXT = "你好小德,今天天气怎么样。"
)

func testMultiInstance() {
  param := nls.DefaultSpeechSynthesisParam()
  config := nls.NewConnectionConfigWithToken(nls.DEFAULT_URL, APPKEY, TOKEN)
  strId := "ID0"
  fname := "ttsdump.wav"
  ttsUserParam := new(TtsUserParam)
  fout, err := os.OpenFile(fname, os.O_RDWR|os.O_TRUNC|os.O_CREATE, 0666)
  logger := nls.NewNlsLogger(os.Stderr, strId, log.LstdFlags|log.Lmicroseconds)
  logger.SetLogSil(false)
  logger.SetDebug(true)
  logger.Printf("Test Normal Case for SpeechRecognition:%s", strId)
  ttsUserParam.F = fout
  ttsUserParam.Logger = logger
  //第三个参数控制是否请求长文本语音合成,false为短文本语音合成
  tts, err := nls.NewSpeechSynthesis(config, logger, false,
    onTaskFailed, onSynthesisResult, nil,
    onCompleted, onClose, ttsUserParam)
  if err != nil {
    logger.Fatalln(err)
    return
  }

  lk.Lock()
  reqNum++
  lk.Unlock()
  logger.Println("SR start")
  ch, err := tts.Start(TEXT, param, nil)
  if err != nil {
    lk.Lock()
    fail++
    lk.Unlock()
    tts.Shutdown()
  }

  err = waitReady(ch, logger)
  if err != nil {
    lk.Lock()
    fail++
    lk.Unlock()
    tts.Shutdown()
  }
  logger.Println("Synthesis done")
  tts.Shutdown()

}

func main() {
  testMultiInstance()
}