update functions to better correspond to doc

Author: PatZhuang

MSP_CMN.py

@@ -16,6 +16,11 @@ def __init__(self, dll_path=None, appID=None):
             appID = APP_ID
         self.dll = cdll.LoadLibrary(dll_path)
         self.appID = appID
+        
+        self.login_params = {
+            'appid': self.appID
+        }
+        
         self.set_arg_types()
         self.set_res_type()
 
@@ -26,14 +31,39 @@ def set_arg_types(self):
     def set_res_type(self):
         self.dll.MSPGetVersion.restype = c_char_p
 
-    def Login(self):
-        loginParams = "appid={}".format(self.appID)
-        loginParams = bytes(loginParams, encoding="utf8")
-        ret = self.dll.MSPLogin(None, None, loginParams)
+    def Login(self, params=None):
+        """MSPLogin
+
+        Args:
+            params (dict or str, optional): params 参数. 默认使用 self.params
+
+        Raises:
+            RuntimeError: MSPLogin failed
+        """
+        if params is None:
+            params = self.login_params
+        if type(params) is dict:
+            params = ','.join(['{}={}'.format(k, v) for k, v in params.items()])
+        if type(params) is str:
+            params = params.encode('utf8')
+        ret = self.dll.MSPLogin(None, None, params)
         if MSP_SUCCESS != ret:
             raise RuntimeError("MSPLogin failed, error code is: %d", ret)
 
     def UploadData(self, data_name, data, params):
+        """MSPUploadData
+
+        Args:
+            data_name (str): dataName, 数据名称
+            data (bytes): 上传数据
+            params (dict or str): params 参数
+
+        Raises:
+            RuntimeError: MSPUploadData failed
+
+        Returns:
+            None: 上传成功后，联系人/用户词表功能返回 NULL
+        """
         # NOT TESTED.
         if type(data_name) is not bytes:
             data_name = data_name.encode('utf8')
@@ -45,16 +75,30 @@ def UploadData(self, data_name, data, params):
         error_code = c_int()
         ret = self.dll.MSPUploadData(data_name, data, data_len, params, byref(error_code))
         if MSP_SUCCESS != error_code.value:
-            raise RuntimeError('MSPUploadData failed. error code: %d' % error_code.value)
+            raise RuntimeError('MSPUploadData failed, error code: %d' % error_code.value)
         return ret
 
 
     def Logout(self):
+        """MSPLogout
+
+        Raises:
+            RuntimeError: MSPLogout failed
+        """
         ret = self.dll.MSPLogout()
         if MSP_SUCCESS != ret:
             raise RuntimeError("MSPLogout failed, error code is: %d", ret)
 
     def SetParam(self, params_name, params_value):
+        """MSPSetParam
+
+        Args:
+            params_name (str or bytes): paramsName, 参数名
+            params_value (str or bytes): paramsValue, 参数值
+
+        Raises:
+            RuntimeError: [description]
+        """
         if type(params_name) is not bytes:
             params_name = bytes(params_name, encoding='utf8')
         if type(params_value) is not bytes:
@@ -64,6 +108,18 @@ def SetParam(self, params_name, params_value):
             raise RuntimeError("MSPSetParam failed, error code: %d" % ret)
 
     def GetParam(self, param_name):
+        """MSPGetParam
+
+        Args:
+            param_name (str or bytes): paramName, 参数名
+
+        Raises:
+            ValueError: 参数名错误
+            RuntimeError: MSPGetParam failed
+
+        Returns:
+            str: 参数值
+        """
         # NOT WORKING!!!
         if type(param_name) is not bytes:
             param_name = param_name.encode('utf8')
@@ -74,17 +130,29 @@ def GetParam(self, param_name):
         ret = self.dll.MSPGetParam(param_name, param_value, byref(param_len))
         if MSP_SUCCESS != ret:
             raise RuntimeError("MSPGetParam failed, error code: %d" % ret)
-        return read_charp_with_len(param_value, param_len)
+        return read_charp_with_len(param_value, param_len).decode('utf8')
 
     def GetVersion(self, ver_name):
+        """MSPGetVersion, 获取 MSC 或本地引擎版本信息
+
+        Args:
+            ver_name (str or byte): verName, 参数名
+
+        Raises:
+            ValueError: 参数名错误
+            RuntimeError: MSPGetVersion failed
+
+        Returns:
+            str: 参数值
+        """
         if type(ver_name) is not bytes:
             ver_name = ver_name.encode('utf8')
         if ver_name.decode('utf8') not in ['ver_msc', 'ver_asr', 'ver_tts', 'ver_ivw']:
             raise ValueError("ver_name can only be: 'ver_msc', 'ver_asr', 'ver_tts' or 'ver_ivw'")
         error_code = c_int()
         ret = self.dll.MSPGetVersion(ver_name, byref(error_code))
         if MSP_SUCCESS != error_code.value:
-            raise RuntimeError("MSPGetVersion failed. error code: %d" % error_code.value)
+            raise RuntimeError("MSPGetVersion failed, error code: %d" % error_code.value)
         return ret.decode('utf8')
 
 if __name__ == '__main__':

MSP_TYPES.py

@@ -1,4 +1,6 @@
-# 状态值
+# 宏定义变量
+SAMPLE_RATE_8K      = 8000
+SAMPLE_RATE_16K     = 16000
 
 # ret code
 MSP_SUCCESS             = 0 # 通用成功标记

QISR.py

@@ -32,11 +32,8 @@ def __init__(self, dll: CDLL, recorder: Recorder, asr_res_path=None, grm_file=No
         self.asr_res_path = asr_res_path
         self.grm_build_path = grm_build_path
         self.grm_file = grm_file
-        
-        self.sessionID_local = c_void_p()
-        self.sessionID_cloud = c_void_p()
-        self._session_valid_local = False
-        self._session_valid_cloud = False
+        self.sessionID = c_char_p()
+        self._session_valid = False
 
         self.asr_data = UserData()
         memset(addressof(self.asr_data), 0, sizeof(self.asr_data))
@@ -146,7 +143,7 @@ def set_res_type(self):
         self.dll.QISRGetResult.restype = c_char_p
 
     def SessionBegin(self, params=None):
-        """QISRSessionBegin
+        """QISRSessionBegin, 开始一次语音识别。
 
         Args:
             params (dict or str, optional): SessionBegin 所需的参数. 默认使用 self.begin_params.
@@ -172,10 +169,10 @@ def SessionBegin(self, params=None):
         return self.sessionID
 
     def SessionEnd(self, hints="End session"):
-        """QISRSessionEnd
+        """QISRSessionEnd, 结束本次语音识别。
 
         Args:
-            hints (str, optional): EndSession 的 hints 参数. Defaults to "End session".
+            hints (str, optional): 结束本次语音识别的原因描述，为用户自定义内容. Defaults to "End session".
 
         Raises:
             RuntimeError: QISREndSession failed.
@@ -189,7 +186,7 @@ def SessionEnd(self, hints="End session"):
         self._session_valid = False
 
     def BuildGrammar(self, grammar_type='bnf', grammar_content=None, params=None, callback=None):
-        """QISRBuildGrammar
+        """QISRBuildGrammar, 构建语法，生成语法ID。
 
         Args:
             grammar_type (str, optional): grammarType. Defaults to 'bnf'.
@@ -232,7 +229,7 @@ def BuildGrammar(self, grammar_type='bnf', grammar_content=None, params=None, ca
         return self.asr_data
 
     def UpdateLexicon(self, lex_name, lex_content, params=None, callback=None):
-        """QISRUpdateLexicon
+        """QISRUpdateLexicon, 更新本地语法词典。
 
         Args:
             lex_name (str): lexiconName, 词典名称
@@ -266,7 +263,7 @@ def UpdateLexicon(self, lex_name, lex_content, params=None, callback=None):
         return self.asr_data
 
     def AudioWrite(self, audio_data, audio_status):
-        """QISRAudioWrite
+        """QISRAudioWrite, 写入本次识别的音频。
 
         Args:
             audio_data (bytes or None): 音频字节流或 None
@@ -294,7 +291,7 @@ def AudioWrite(self, audio_data, audio_status):
         return ep_status, rslt_status
 
     def GetResult(self):
-        """QISRGetResult
+        """QISRGetResult, 获取识别结果。
 
         Raises:
             RuntimeError: QISRGetResult failed

QIVW.py

@@ -52,7 +52,7 @@ def py_ivw_callback(sessionID, msg, param1, param2, info, userData):
             # 标记为已被唤醒
             self.awoken = True
 
-        self.pIVWCallbackFunc = py_ivw_callback
+        self.ivw_cb = py_ivw_callback
         self.set_arg_types()
         self.set_res_type()
 
@@ -66,7 +66,7 @@ def set_res_type(self):
         self.dll.QIVWSessionBegin.restype = c_char_p
 
     def SessionBegin(self, params=None):
-        """QIVWSessionBegin 的实现
+        """QIVWSessionBegin, 唤醒功能，并在参数中指定唤醒(唤醒+识别时)用到的语法列表，本次唤醒所用的参数等。
 
         Args:
             params (dict or str, optional): params 参数. 默认使用 self.begin_params
@@ -75,7 +75,7 @@ def SessionBegin(self, params=None):
             RuntimeError: QIVWSessionBegin failed.
 
         Returns:
-            bytes: SessionID
+            str: SessionID
         """
         if params is None:
             params = self.begin_params
@@ -89,24 +89,52 @@ def SessionBegin(self, params=None):
         if MSP_SUCCESS != error_code.value:
             raise RuntimeError("QIVWSessionBegin failed, error code %d" % error_code.value)
         self._session_valid = True
-        return self.sessionID
+        return self.sessionID.decode('utf8')
 
     def RegisterNotify(self, sessionID=None, msg_proc_cb=None, user_data=None):
+        """QIVWRegisterNotify, 注册回调。
+
+        Args:
+            sessionID (bytes, optional): sessionID. 默认使用 self.sessionID
+            msg_proc_cb (c_void_p, optional): 回调函数. 默认使用 self.ivw_cb
+            user_data (UserData, optional): 用户数据. Defaults to None.
+
+        Raises:
+            RuntimeError: [description]
+        """
         if not sessionID:
             sessionID = self.sessionID
         assert sessionID is not None, 'SessionID is None'
         if not msg_proc_cb:
-            msg_proc_cb = self.pIVWCallbackFunc
+            msg_proc_cb = self.ivw_cb
         ret = self.dll.QIVWRegisterNotify(sessionID, msg_proc_cb, user_data)
         if MSP_SUCCESS != ret:
             raise RuntimeError("QIVWRegisterNotify failed, error code: %d" % ret)
 
-    def AudioWrite(self, audioData, audioLen, audio_status=2):
-        ret = self.dll.QIVWAudioWrite(self.sessionID, audioData, audioLen, audio_status)
+    def AudioWrite(self, audio_data, audio_status=2):
+        """QIVWAudioWrite, 写入本次唤醒的音频，本接口需要反复调用直到音频写完为止。
+
+        Args:
+            audioData (bytes): 要写入的音频数据
+            audio_status (int, optional): 用来告知MSC音频发送是否完成. Defaults to 2.
+
+        Raises:
+            RuntimeError: [description]
+        """
+        audio_len = len(audio_data)        
+        ret = self.dll.QIVWAudioWrite(self.sessionID, audio_data, audio_len, audio_status)
         if MSP_SUCCESS != ret:
             raise RuntimeError("QIVWAudioWrite failed, errCode: %d", ret)
 
     def SessionEnd(self, hints="Done wakeup"):
+        """QIVWSessionEnd, 结束本次语音唤醒。
+
+        Args:
+            hints (str, optional): 结束本次语音唤醒的原因描述，为用户自定义内容. Defaults to "Done wakeup".
+
+        Raises:
+            RuntimeError: QIVWSessionEnd failed
+        """
         if type(hints) is str:
             hints = hints.encode('utf8')
         ret = self.dll.QIVWSessionEnd(self.sessionID, hints)
@@ -128,7 +156,7 @@ def wakeup(self):
             while not self.awoken:
                 audioData = self.recorder.get_record_audio()
                 audioLen = len(audioData)
-                self.AudioWrite(audioData, audioLen)
+                self.AudioWrite(audioData)
             self.awoken = False
 
             self.SessionEnd()