C# SDK

SDK下载

可通过以下两种方法获取SDK。

• 方法一：从GitHub获取最新源码，详细编译和运行方式可见下文，或查看源码中的readme.md。

  git clone --depth 1 https://github.com/aliyun/alibabacloud-nls-cpp-sdk

• 方法二：直接从下文表中选取需要的SDK包进行下载。其中SDK源码包为SDK原始代码，需要通过下文的编译方法生成集成所需的库文件。其他对应平台的SDK包内含相关库文件、头文件，无需编译。

  最新SDK包	平台	MD5
  alibabacloud-nls-cpp-sdk3.1.17-master_fd7c7d8.zip	SDK源码	8beeaad832d4b249464f4338429c3b15
  NlsCsharpSdk_Windows_3.1.17_fd7c7d8.zip	Windows	81fdd1579e103d8c93b4dab98ee0f71c

  其中：

  • alibabacloud-nls-cpp-sdk<version>-master_<github commit id>.zip为SDK源码包。

  • NlsCsharpSdk_Windows_<版本号>_<github commit id>.zip为Windows平台下开发需要的SDK包，详见内部readme.md。

Windows平台C#编译运行

推荐直接使用已经编译好的库NlsCsharpSdk_Windows_<version>_<github commit id>.zip进行集成。若有编译需求，请下载alibabacloud-nls-cpp-sdk<version>-master_<github commit id>.zip并解压到本地，或从GitHub获取最新代码，然后参考其中的readme.md的编译步骤。

关键接口

using nlsCsharpSdk;

• 基础接口

  • NlsClient：语音处理客户端，利用该客户端可以进行一句话识别、实时语音识别和语音合成的语音处理任务。该客户端为线程安全，建议全局仅创建一个实例。

    接口名	启用版本	功能描述
    SetLogConfig	3.1.9	设置日志文件与存储路径。越早调用记录的信息越详细。
    GetVersion	3.1.9	获取SDK版本号。
    CreateNlsToken	3.1.9	创建Token获取对象，用于获取阿里云token，详见下方NlsToken相关表格。
    ReleaseNlsToken	3.1.9	销毁CreateNlsToken所建立的NlsToken对象。
    SetDirectHost	3.1.16	跳过DNS域名解析直接设置服务器IP地址，若调用，则需要在StartWorkThread之前。
    StartWorkThread	3.1.9	启动工作线程数，默认1即启动一个线程，若-1则启动CPU核数的线程数。在高并发的情况下建议选择-1。这一接口有初始化NlsClient的作用。
    ReleaseInstance	3.1.9	销毁NlsClient对象实例，即释放NLS SDK。此操作需要在销毁所有请求后再调用。
    CreateNlsToken	3.1.9	创建Token获取对象，用于申请获取TokenId。详见下方NlsToken相关说明。
    ReleaseNlsToken	3.1.9	销毁Token获取对象。
    CreateRecognizerRequest	3.1.9	创建一句话识别对象，线程安全，支持高并发请求。
    ReleaseRecognizerRequest	3.1.9	销毁一句话识别对象，需要在当前请求的closed事件后调用。

  • NlsToken：创建Token对象，用于申请获取TokenId。申请新Token时需要先获取有效时间戳，若超过有效时间则再申请。若在有效时间内多次申请Token会导致TokenId错误而无法使用。

    接口名	功能描述
    SetAccessKeyId	设置阿里云账号AccessKey ID。
    SetKeySecret	设置阿里云账号AccessKey Secret。
    ApplyNlsToken	申请获取TokenId。此TokenId在有效期内对所有此阿里云账号AccessKey ID下的所有语音请求有效，无需在每个语音请求前申请获得。
    GetToken	获取TokenId
    GetExpireTime	获取Token有效期时间戳（秒）。
    GetErrorMsg	获取TokenId失败的错误信息。

  • NlsEvent：事件对象NLS_EVENT_STRUCT，通过CallbackDelegate返回。您可以从中获取Request状态码、云端返回结果、失败信息等。

    参数名	功能描述
    statusCode	获取状态码，正常情况为0或者20000000，失败时对应失败的错误码。
    taskId	获取任务的TaskId。
    msg	获取云端返回的response结果，用于获得事件信息，如Started、Closed、TaskFailed回调的事件信息。
    result	获取云端返回的识别结果，用于获得识别结果，如ResultChanged、Completed回调的事件信息。

• 识别接口

  SpeechRecognizerRequest：一句话识别请求对象，用于短语音识别。

  接口名	功能描述
  SetOnTaskFailed	设置错误回调函数。
  SetOnRecognitionStarted	设置一句话识别开始回调函数。
  SetOnRecognitionResultChanged	设置一句话识别中间结果回调函数。
  SetOnRecognitionCompleted	设置服务端结束服务回调函数。
  SetOnChannelClosed	设置通道关闭回调函数。
  SetAppKey	设置Appkey。
  SetToken	口令认证。所有的请求都必须通过SetToken方法认证通过，才可以使用。
  SetUrl	设置服务URL地址，默认可不设置则调用公有云上海域名的服务。
  SetIntermediateResult	设置是否返回中间识别结果，结果会从OnRecognitionResultChanged回调返回。
  SetPunctuationPrediction	设置是否在后处理中添加标点。
  SetInverseTextNormalization	设置是否在后处理中执行数字转换。
  SetEnableVoiceDetection	设置是否启动自定义静音检测。
  SetMaxStartSilence	允许的最大开始静音，可选，单位为毫秒。超出后服务端将会发送RecognitionCompleted事件，开始本次识别。需要先设置SetEnableVoiceDetection为true. 建议设置为2000~5000。
  SetMaxEndSilence	允许的最大结束静音，可选，单位是毫秒。超出后服务端将会发送RecognitionCompleted事件，结束本次识别。需要先设置SetEnableVoiceDetection为true. 建议时间0~5000。
  SetFormat	设置音频数据编码格式，Windows环境推荐用PCM格式。
  SetSampleRate	音频采样率设置。
  SetCustomizationId	设置定制模型，例如("TestId_123")。
  SetVocabularyId	设置泛热词，例如("TestId_456")。
  SetTimeout	设置Socket接收超时时间。
  SetOutputFormat	设置输出文本的编码格式。Windows平台下默认为GBK。非中文语种情况下，请设置成UTF-8，否则会出现乱码。
  SetPayloadParam	参数设置，入参为JSON格式字符串。如指定声学模型，例如"{\"model\":\"test-regression-model\"}")。
  SetContextParam	设置用户自定义参数，入参为JSON格式字符串。
  AppendHttpHeaderParam	设置用户自定义ws阶段http header参数。
  Start	异步接口，启动SpeechRecognizerRequest。需要等待OnRecognitionStarted回调以确保请求进入工作状态。
  Stop	异步接口，会与服务端确认关闭，正常停止链接操作。需要等待OnChannelClosed回调以确保请求结束工作状态。
  Cancel	不会与服务端确认关闭，直接关闭链接。
  SendAudio	异步接口，发送语音数据。为保证实时性，每次发送数据不建议太长，建议一次发送100ms时长以内的音频数据，范围为640字节~16384字节。

SDK错误码

服务端响应状态码

关于服务状态码，请参见服务状态码。

代码示例​

• 示例中使用的音频文件为16000Hz采样率，管控台设置的模型为通用模型。如果使用其他音频，请设置为支持该音频场景的模型。关于模型设置，请参见管理项目。

• 示例中使用了SDK内置的默认一句话识别服务的外网访问服务URL，如果您使用阿里云上海ECS且需要使用内网访问URL，则在创建SpeechRecognizerRequest的对象中设置内网访问的URL。

    SpeechRecognizerRequest srPtr;
    srPtr.SetUrl(srPtr, "ws://nls-gateway.cn-shanghai-internal.aliyuncs.com/ws/v1")

• 以下为简要示例，完整示例请参见SDK压缩包中demo目录的nlsCsharpSdkDemo.cs文件。

  using System;
  using System.IO;
  using System.Threading;
  using System.Windows.Forms;
  using nlsCsharpSdk;
  
  namespace nlsCsharpSdkDemo
  {
      public partial class nlsCsharpSdkDemo : Form
   {
          private NlsClient nlsClient;
          private SpeechRecognizerRequest srPtr;
          private NlsToken tokenPtr;
          private UInt64 expireTime;
  
          private string appKey;
          private string akId;
          private string akSecret;
          private string token;
          private string url;
  
          static bool running;
          static string cur_nls_result;
  
          static bool sr_send_audio_flag = false;
          static bool sr_audio_loop_flag = false;
          static Thread sr_send_audio;
          static string cur_sr_result;
          static string cur_sr_completed;
          static string cur_sr_closed;
  
          private void FlushLab()
          {
              while (running)
              {
                  if (cur_sr_result != null && cur_sr_result.Length > 0)
                  {
                      srResult.Text = cur_sr_result;
                  }
                  if (cur_sr_completed != null && cur_sr_completed.Length > 0)
                  {
                      srCompleted.Text = cur_sr_completed;
                  }
                  if (cur_sr_closed != null && cur_sr_closed.Length > 0)
                  {
                      srClosed.Text = cur_sr_closed;
                  }
  
                  Thread.Sleep(200);
              }
          }
  
          private void SRAudioLab()
          {
              string file_name = System.Environment.CurrentDirectory + @"\audio_files\test3.wav";
              System.Diagnostics.Debug.WriteLine("sr audio file_name = {0}", file_name);
              FileStream fs = new FileStream(file_name, FileMode.Open, FileAccess.Read);
              BinaryReader br = new BinaryReader(fs);
  
              while (sr_audio_loop_flag)
              {
                  if (sr_send_audio_flag)
                  {
                      byte[] byData = br.ReadBytes((int)3200);
                      if (byData.Length > 0)
                      {
                          // 音频数据以PCM格式，byData.Length字节进行推送。
                          srPtr.SendAudio(srPtr, byData, (UInt64)byData.Length, EncoderType.ENCODER_PCM);
                      }
                      else
                      {
                          /*
                           * 音频推送完成,重新打开循环继续
                           */
                          br.Close();
                          fs.Dispose();
                          fs = new FileStream(file_name, FileMode.Open, FileAccess.Read);
                          br = new BinaryReader(fs);
                      }
                  }
                  /*
                   * 上面推送3200字节音频数据，相当于模拟100MS的音频。
                   * 真实环境从录音获得音频数据，不需要调用此Sleep。
                   */
                  Thread.Sleep(100);
              }
              br.Close();
              fs.Dispose();
          }
  
          public nlsCsharpSdkDemo()
          {
              InitializeComponent();
              System.Windows.Forms.Control.CheckForIllegalCrossThreadCalls = false;
  
              nlsClient = new NlsClient();
          }
  
          private void button1_Click(object sender, EventArgs e)
          {
              // 开启日志系统，以Debug级别将名字为nlsLog.log的日志以单个400MB 10个日志文件循环的形式储存。
              int ret = nlsClient.SetLogConfig("nlsLog", LogLevel.LogDebug, 400, 10);
              if (ret == 0)
                  nlsResult.Text = "OpenLog Success";
              else
                  nlsResult.Text = "OpenLog Failed";
          }
  
          private void button1_Click_1(object sender, EventArgs e)
          {
              // 获取当前SDK的版本号
              string version = nlsClient.GetVersion();
              nlsResult.Text = version;
          }
  
          private void button1_Click_2(object sender, EventArgs e)
          {            
              // -1则表示启动CPU核数的事件池数量，用于进行内部事件的处理。
              // 单路调用的情况下，建议入参为1，即启动单个事件池进行处理。
              // 高并发(几百路)的情况下，入参建议4 ~ CPU核数，入参越大，处理延迟越低但是CPU占用越高。
              nlsClient.StartWorkThread(1);
              nlsResult.Text = "StartWorkThread and init NLS success.";
              running = true;
              Thread t = new Thread(FlushLab);
              t.Start();
          }
  
          private void button1_Click_3(object sender, EventArgs e)
          {
              // 释放NlsClient，与StartWorkThread互为反操作
              nlsClient.ReleaseInstance();
              nlsResult.Text = "Release NLS success.";
          }
  
          #region Info
          private void textBox1_TextChanged(object sender, EventArgs e)
          {
              akId = tAkId.Text;
          }
  
          private void tAppKey_TextChanged(object sender, EventArgs e)
          {
              appKey = tAppKey.Text;
          }
  
          private void tAkSecret_TextChanged(object sender, EventArgs e)
          {
              akSecret = tAkSecret.Text;
          }
  
          private void tToken_TextChanged(object sender, EventArgs e)
          {
              token = tToken.Text;
          }
  
          private void tUrl_TextChanged(object sender, EventArgs e)
          {
              url = tUrl.Text;
          }
          #endregion
  
          #region TokenButton
          // create token
          private void button3_Click_1(object sender, EventArgs e)
          {
              int ret = 0;
              tokenPtr = nlsClient.CreateNlsToken();
              if (tokenPtr.native_token != IntPtr.Zero)
              {
                  if (akId != null && akSecret != null & akId.Length > 0 && akSecret.Length > 0)
                  {
                      tokenPtr.SetAccessKeyId(tokenPtr, akId);
                      tokenPtr.SetKeySecret(tokenPtr, akSecret);
  
                      ret = tokenPtr.ApplyNlsToken(tokenPtr);
                      if (ret < 0)
                      {
                          System.Diagnostics.Debug.WriteLine("ApplyNlsToken failed");
                          nlsResult.Text = tokenPtr.GetErrorMsg(tokenPtr);
                      }
                      else
                      {
                          System.Diagnostics.Debug.WriteLine("ApplyNlsToken success");
                          token = tokenPtr.GetToken(tokenPtr);
                          tToken.Text = token;
                          expireTime = tokenPtr.GetExpireTime(tokenPtr);
                          nlsResult.Text = "ExpireTime:" + expireTime.ToString();
                      }
                  }
                  else
                  {
                      nlsResult.Text = "CreateToken Failed, akId or Secret is null";
                  }
              }
              else
              {
                  nlsResult.Text = "CreateToken Failed";
              }
          }
  
          // release token
          private void button4_Click(object sender, EventArgs e)
          {
              if (tokenPtr.native_token != IntPtr.Zero)
              {
                  nlsClient.ReleaseNlsToken(tokenPtr);
                  tokenPtr.native_token = IntPtr.Zero;
                  nlsResult.Text = "ReleaseNlsToken Success";
              }
              else
              {
                  nlsResult.Text = "ReleaseNlsToken is nullptr";
              }
          }
          #endregion
  
          #region RecognizerCallback
          private CallbackDelegate DemoOnRecognitionStarted =
              (ref NLS_EVENT_STRUCT e, ref string uuid) =>
          {
              System.Diagnostics.Debug.WriteLine("DemoOnRecognitionStarted user uuid = {0}", uuid);
              string msg = System.Text.Encoding.Default.GetString(e.msg).TrimEnd('\0');
              System.Diagnostics.Debug.WriteLine("DemoOnRecognitionStarted msg = {0}", msg);
              cur_sr_completed = "msg : " + msg;
  
              sr_send_audio_flag = true;
          };
          private CallbackDelegate DemoOnRecognitionClosed =
              (ref NLS_EVENT_STRUCT e, ref string uuid) =>
          {
              string msg = System.Text.Encoding.Default.GetString(e.msg).TrimEnd('\0');
              System.Diagnostics.Debug.WriteLine("DemoOnRecognitionClosed = {0}", msg);
              cur_sr_closed = "msg : " + msg;
          };
          private CallbackDelegate DemoOnRecognitionTaskFailed =
              (ref NLS_EVENT_STRUCT e, ref string uuid) =>
          {
              System.Diagnostics.Debug.WriteLine("DemoOnRecognitionTaskFailed user uuid = {0}", uuid);
              string msg = System.Text.Encoding.Default.GetString(e.msg).TrimEnd('\0');
              System.Diagnostics.Debug.WriteLine("DemoOnRecognitionTaskFailed = {0}", msg);
              cur_sr_completed = "msg : " + msg;
  
              sr_send_audio_flag = false;
              sr_audio_loop_flag = false;
          };
          private CallbackDelegate DemoOnRecognitionResultChanged =
              (ref NLS_EVENT_STRUCT e, ref string uuid) =>
          {
              System.Diagnostics.Debug.WriteLine("DemoOnRecognitionResultChanged user uuid = {0}", uuid);
              // 若识别为非中文，请设置UTF-8格式，并用UTF-8解码，否则可能乱码。
              // string result = System.Text.Encoding.UTF8.GetString(e.result).TrimEnd('\0');
              string result = System.Text.Encoding.Default.GetString(e.result).TrimEnd('\0');
              cur_sr_result = "middle result : " + result;
          };
          private CallbackDelegate DemoOnRecognitionCompleted =
              (ref NLS_EVENT_STRUCT e, ref string uuid) =>
          {
              System.Diagnostics.Debug.WriteLine("DemoOnRecognitionCompleted user uuid = {0}", uuid);
              // 若识别为非中文，请设置UTF-8格式，并用UTF-8解码，否则可能乱码。
              // string result = System.Text.Encoding.UTF8.GetString(e.result).TrimEnd('\0');
              string result = System.Text.Encoding.Default.GetString(e.result).TrimEnd('\0');
              cur_sr_completed = "final result : " + result;
          };
          #endregion
  
              // create recognizer
              private void button8_Click(object sender, EventArgs e)
          {
              srPtr = nlsClient.CreateRecognizerRequest();
              if (srPtr.native_request != IntPtr.Zero)
              {
                  nlsResult.Text = "CreateRecognizerRequest Success";
              }
              else
              {
                  nlsResult.Text = "CreateRecognizerRequest Failed";
              }
              cur_sr_result = "null";
              cur_sr_closed = "null";
              cur_sr_completed = "null";
          }
  
          // start recognizer
          private void button6_Click(object sender, EventArgs e)
          {
              int ret = -1;
              if (srPtr.native_request != IntPtr.Zero)
              {
                  srPtr.SetAppKey(srPtr, appKey);
                  srPtr.SetToken(srPtr, token);
                  srPtr.SetUrl(srPtr, url);
                  srPtr.SetFormat(srPtr, "pcm");
                  srPtr.SetSampleRate(srPtr, 16000);
                  srPtr.SetIntermediateResult(srPtr, true);
                  srPtr.SetPunctuationPrediction(srPtr, true);
                  srPtr.SetInverseTextNormalization(srPtr, true);
  
                  string uuid = System.Guid.NewGuid().ToString("N");
  
                  srPtr.SetOnRecognitionStarted(srPtr, DemoOnRecognitionStarted, uuid);
                  srPtr.SetOnChannelClosed(srPtr, DemoOnRecognitionClosed, uuid);
                  srPtr.SetOnTaskFailed(srPtr, DemoOnRecognitionTaskFailed, uuid);
                  srPtr.SetOnRecognitionResultChanged(srPtr, DemoOnRecognitionResultChanged, uuid);
                  srPtr.SetOnRecognitionCompleted(srPtr, DemoOnRecognitionCompleted, uuid);
  
                  ret = srPtr.Start(srPtr);
  
                  if (sr_audio_loop_flag == false)
                  {
                      sr_audio_loop_flag = true;
                      sr_send_audio = new Thread(SRAudioLab);
                      sr_send_audio.Start();
                  }
              }
  
              if (ret != 0)
              {
                  nlsResult.Text = "Recognizer Start failed";
              }
              else
              {
                  nlsResult.Text = "Recognizer Start success";
              }
          }
  
       // stop recognizer
       private void button5_Click(object sender, EventArgs e)
       {
           int ret = -1;
           if (srPtr.native_request != IntPtr.Zero)
               ret = srPtr.Stop(srPtr);
  
           sr_send_audio_flag = false;
           sr_audio_loop_flag = false;
           if (ret != 0)
           {
               nlsResult.Text = "Recognizer Stop failed";
           }
           else
           {
               nlsResult.Text = "Recognizer Stop success";
           }
       }
  
       // release recognizer
       private void button7_Click(object sender, EventArgs e)
       {
           if (srPtr.native_request != IntPtr.Zero)
           {
               nlsClient.ReleaseRecognizerRequest(srPtr);
               srPtr.native_request = IntPtr.Zero;
               nlsResult.Text = "ReleaseRecognizerRequest Success";
           }
           else
           {
               nlsResult.Text = "ReleaseRecognizerRequest is nullptr";
           }
           cur_sr_result = "null";
           cur_sr_closed = "null";
           cur_sr_completed = "null";
       }
   }
  }