Merge pull request #2131 from carlfm01/dotnet-errorcodes

Error codes for .NET bindings

examples/net_framework/DeepSpeechWPF/DeepSpeech.WPF.csproj

@@ -14,26 +14,8 @@
     <WarningLevel>4</WarningLevel>
     <AutoGenerateBindingRedirects>true</AutoGenerateBindingRedirects>
     <Deterministic>true</Deterministic>
-  </PropertyGroup>
-  <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Debug|AnyCPU' ">
-    <PlatformTarget>AnyCPU</PlatformTarget>
-    <DebugSymbols>true</DebugSymbols>
-    <DebugType>full</DebugType>
-    <Optimize>false</Optimize>
-    <OutputPath>bin\Debug\</OutputPath>
-    <DefineConstants>DEBUG;TRACE</DefineConstants>
-    <ErrorReport>prompt</ErrorReport>
-    <WarningLevel>4</WarningLevel>
-  </PropertyGroup>
-  <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Release|AnyCPU' ">
-    <PlatformTarget>AnyCPU</PlatformTarget>
-    <DebugType>pdbonly</DebugType>
-    <Optimize>true</Optimize>
-    <OutputPath>bin\Release\</OutputPath>
-    <DefineConstants>TRACE</DefineConstants>
-    <ErrorReport>prompt</ErrorReport>
-    <WarningLevel>4</WarningLevel>
-    <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
+    <NuGetPackageImportStamp>
+    </NuGetPackageImportStamp>
   </PropertyGroup>
   <PropertyGroup Condition="'$(Configuration)|$(Platform)' == 'Debug|x64'">
     <DebugSymbols>true</DebugSymbols>
@@ -59,13 +41,14 @@
   </PropertyGroup>
   <ItemGroup>
     <Reference Include="CSCore, Version=1.2.1.2, Culture=neutral, PublicKeyToken=5a08f2b6f4415dea, processorArchitecture=MSIL">
-      <HintPath>..\packages\CSCore.1.2.1.2\lib\net35-client\CSCore.dll</HintPath>
+      <HintPath>packages\CSCore.1.2.1.2\lib\net35-client\CSCore.dll</HintPath>
     </Reference>
-    <Reference Include="NAudio, Version=1.8.5.0, Culture=neutral, processorArchitecture=MSIL">
-      <HintPath>..\packages\NAudio.1.8.5\lib\net35\NAudio.dll</HintPath>
+    <Reference Include="NAudio, Version=1.9.0.0, Culture=neutral, processorArchitecture=MSIL">
+      <HintPath>packages\NAudio.1.9.0\lib\net35\NAudio.dll</HintPath>
     </Reference>
     <Reference Include="System" />
     <Reference Include="System.Data" />
+    <Reference Include="System.Windows.Forms" />
     <Reference Include="System.Xml" />
     <Reference Include="Microsoft.CSharp" />
     <Reference Include="System.Core" />
@@ -125,7 +108,7 @@
     <None Include="App.config" />
   </ItemGroup>
   <ItemGroup>
-    <ProjectReference Include="..\DeepSpeechClient\DeepSpeechClient.csproj">
+    <ProjectReference Include="..\..\..\native_client\dotnet\DeepSpeechClient\DeepSpeechClient.csproj">
       <Project>{56de4091-bbbe-47e4-852d-7268b33b971f}</Project>
       <Name>DeepSpeechClient</Name>
     </ProjectReference>

examples/net_framework/DeepSpeechWPF/DeepSpeech.WPF.sln

@@ -0,0 +1,31 @@
+
+Microsoft Visual Studio Solution File, Format Version 12.00
+# Visual Studio 15
+VisualStudioVersion = 15.0.28307.421
+MinimumVisualStudioVersion = 10.0.40219.1
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "DeepSpeech.WPF", "DeepSpeech.WPF.csproj", "{54BFD766-4305-4F4C-BA59-AF45505DF3C1}"
+EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "DeepSpeechClient", "..\..\..\native_client\dotnet\DeepSpeechClient\DeepSpeechClient.csproj", "{56DE4091-BBBE-47E4-852D-7268B33B971F}"
+EndProject
+Global
+	GlobalSection(SolutionConfigurationPlatforms) = preSolution
+		Debug|x64 = Debug|x64
+		Release|x64 = Release|x64
+	EndGlobalSection
+	GlobalSection(ProjectConfigurationPlatforms) = postSolution
+		{54BFD766-4305-4F4C-BA59-AF45505DF3C1}.Debug|x64.ActiveCfg = Debug|x64
+		{54BFD766-4305-4F4C-BA59-AF45505DF3C1}.Debug|x64.Build.0 = Debug|x64
+		{54BFD766-4305-4F4C-BA59-AF45505DF3C1}.Release|x64.ActiveCfg = Release|x64
+		{54BFD766-4305-4F4C-BA59-AF45505DF3C1}.Release|x64.Build.0 = Release|x64
+		{56DE4091-BBBE-47E4-852D-7268B33B971F}.Debug|x64.ActiveCfg = Debug|x64
+		{56DE4091-BBBE-47E4-852D-7268B33B971F}.Debug|x64.Build.0 = Debug|x64
+		{56DE4091-BBBE-47E4-852D-7268B33B971F}.Release|x64.ActiveCfg = Release|x64
+		{56DE4091-BBBE-47E4-852D-7268B33B971F}.Release|x64.Build.0 = Release|x64
+	EndGlobalSection
+	GlobalSection(SolutionProperties) = preSolution
+		HideSolutionNode = FALSE
+	EndGlobalSection
+	GlobalSection(ExtensibilityGlobals) = postSolution
+		SolutionGuid = {19C58802-CCEC-4FD1-8D17-A6EB766116F7}
+	EndGlobalSection
+EndGlobal

examples/net_framework/DeepSpeechWPF/MainWindow.xaml.cs

@@ -79,14 +79,8 @@ private void Window_Loaded(object sender, RoutedEventArgs e)
             {
                 try
                 {
-                    if (_sttClient.CreateModel("output_graph.pbmm", N_CEP, N_CONTEXT, "alphabet.txt", BEAM_WIDTH) == 0)
-                    {
-                        Dispatcher.Invoke(() => { EnableControls(); });
-                    }
-                    else
-                    {
-                        MessageBox.Show("Model load failed.");
-                    }
+                    _sttClient.CreateModel("output_graph.pbmm", N_CEP, N_CONTEXT, "alphabet.txt", BEAM_WIDTH);
+                    Dispatcher.Invoke(() => { EnableControls(); });
                 }
                 catch (Exception ex)
                 {
@@ -161,18 +155,12 @@ await Task.Run(() =>
             {
                 try
                 {
-                    if (_sttClient.EnableDecoderWithLM("alphabet.txt", "lm.binary", "trie", LM_ALPHA, LM_BETA) != 0)
-                    {
-                        MessageBox.Show("Error loading LM.");
-                        Dispatcher.Invoke(() => btnEnableLM.IsEnabled = true);
-                    }
-                    else
-                    {
-                        Dispatcher.Invoke(() => lblStatus.Content = "LM loaded.");
-                    }
+                    _sttClient.EnableDecoderWithLM("alphabet.txt", "lm.binary", "trie", LM_ALPHA, LM_BETA);
+                    Dispatcher.Invoke(() => lblStatus.Content = "LM loaded.");
                 }
                 catch (Exception ex)
                 {
+                    Dispatcher.Invoke(() => btnEnableLM.IsEnabled = true);
                     MessageBox.Show(ex.Message);
                 }
             });

examples/net_framework/DeepSpeechWPF/packages.config

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
 <packages>
   <package id="CSCore" version="1.2.1.2" targetFramework="net462" />
-  <package id="NAudio" version="1.8.5" targetFramework="net462" />
+  <package id="NAudio" version="1.9.0" targetFramework="net462" />
 </packages>

native_client/dotnet/DeepSpeechClient/DeepSpeech.cs

@@ -5,6 +5,7 @@
 using System;
 using System.IO;
 using System.Runtime.InteropServices;
+using DeepSpeechClient.Enums;
 
 namespace DeepSpeechClient
 {
@@ -35,8 +36,8 @@ public DeepSpeech()
         /// <param name="aNContext">The context window the model was trained with.</param>
         /// <param name="aAlphabetConfigPath">The path to the configuration file specifying the alphabet used by the network.</param>
         /// <param name="aBeamWidth">The beam width used by the decoder. A larger beam width generates better results at the cost of decoding time.</param>
-        /// <returns>Zero on success, non-zero on failure.</returns>
-        public unsafe int CreateModel(string aModelPath, uint aNCep,
+        /// <exception cref="ArgumentException">Thrown when the native binary failed to create the model.</exception>
+        public unsafe void CreateModel(string aModelPath, uint aNCep,
             uint aNContext, string aAlphabetConfigPath, uint aBeamWidth)
         {
             string exceptionMessage = null;
@@ -61,16 +62,53 @@ public unsafe int CreateModel(string aModelPath, uint aNCep,
             {
                 throw new FileNotFoundException(exceptionMessage);
             }
-            int result = NativeImp.DS_CreateModel(aModelPath,
+            var resultCode = NativeImp.DS_CreateModel(aModelPath,
                             aNCep,
                             aNContext,
                             aAlphabetConfigPath,
                             aBeamWidth,
                             ref _modelStatePP);
+            EvaluateResultCode(resultCode);
             _modelStateP = *_modelStatePP;
-            return result;
-
+        }
 
+        /// <summary>
+        /// Evaluate the result code and will raise an exception if necessary.
+        /// </summary>
+        /// <param name="resultCode">Native result code.</param>
+        private void EvaluateResultCode(ErrorCodes resultCode)
+        {
+            switch (resultCode)
+            {
+                case ErrorCodes.DS_ERR_OK:
+                    break;
+                case ErrorCodes.DS_ERR_NO_MODEL:
+                    throw new ArgumentException("Missing model information.");
+                case ErrorCodes.DS_ERR_INVALID_ALPHABET:
+                    throw new ArgumentException("Invalid alphabet file or invalid alphabet size.");
+                case ErrorCodes.DS_ERR_INVALID_SHAPE:
+                    throw new ArgumentException("Invalid model shape.");
+                case ErrorCodes.DS_ERR_INVALID_LM:
+                    throw new ArgumentException("Invalid language model file.");
+                case ErrorCodes.DS_ERR_FAIL_INIT_MMAP:
+                    throw new ArgumentException("Failed to initialize memory mapped model.");
+                case ErrorCodes.DS_ERR_FAIL_INIT_SESS:
+                    throw new ArgumentException("Failed to initialize the session.");
+                case ErrorCodes.DS_ERR_FAIL_INTERPRETER:
+                    throw new ArgumentException("Interpreter failed.");
+                case ErrorCodes.DS_ERR_FAIL_RUN_SESS:
+                    throw new ArgumentException("Failed to run the session.");
+                case ErrorCodes.DS_ERR_FAIL_CREATE_STREAM:
+                    throw new ArgumentException("Error creating the stream.");
+                case ErrorCodes.DS_ERR_FAIL_READ_PROTOBUF:
+                    throw new ArgumentException("Error reading the proto buffer model file.");
+                case ErrorCodes.DS_ERR_FAIL_CREATE_SESS:
+                    throw new ArgumentException("Error failed to create session.");
+                case ErrorCodes.DS_ERR_MODEL_INCOMPATIBLE:
+                    throw new ArgumentException("Error incompatible model.");
+                default:
+                    throw new ArgumentException("Unknown error, please make sure you are using the correct native binary.");
+            }
         }
 
         /// <summary>
@@ -89,8 +127,8 @@ public unsafe void Dispose()
         /// <param name="aTriePath">The path to the trie file build from the same vocabulary as the language model binary.</param>
         /// <param name="aLMAlpha">The alpha hyperparameter of the CTC decoder. Language Model weight.</param>
         /// <param name="aLMBeta">The beta hyperparameter of the CTC decoder. Word insertion weight.</param>
-        /// <returns>Zero on success, non-zero on failure (invalid arguments).</returns>
-        public unsafe int EnableDecoderWithLM(string aAlphabetConfigPath,
+        /// <exception cref="ArgumentException">Thrown when the native binary failed to enable decoding with a language model.</exception>
+        public unsafe void EnableDecoderWithLM(string aAlphabetConfigPath,
             string aLMPath, string aTriePath,
             float aLMAlpha, float aLMBeta)
         {
@@ -109,12 +147,13 @@ public unsafe int EnableDecoderWithLM(string aAlphabetConfigPath,
                 throw new FileNotFoundException(exceptionMessage);
             }
 
-            return NativeImp.DS_EnableDecoderWithLM(_modelStatePP,
+            var resultCode = NativeImp.DS_EnableDecoderWithLM(_modelStatePP,
                             aAlphabetConfigPath,
                             aLMPath,
                             aTriePath,
                             aLMAlpha,
                             aLMBeta);
+            EvaluateResultCode(resultCode);
         }
 
         /// <summary>
@@ -169,10 +208,11 @@ public unsafe void PrintVersions()
         /// One timestep is equivalent to two window lengths(20ms).
         /// If set to 0 we reserve enough frames for 3 seconds of audio(150).</param>
         /// <param name="aSampleRate">The sample-rate of the audio signal</param>
-        /// <returns>Zero for success, non-zero on failure</returns>
-        public unsafe int SetupStream(uint aPreAllocFrames, uint aSampleRate)
+        /// <exception cref="ArgumentException">Thrown when the native binary failed to initialize the streaming mode.</exception>
+        public unsafe void SetupStream(uint aPreAllocFrames, uint aSampleRate)
         {
-            return NativeImp.DS_SetupStream(_modelStatePP, aPreAllocFrames, aSampleRate, ref _streamingStatePP);
+            var resultCode = NativeImp.DS_SetupStream(_modelStatePP, aPreAllocFrames, aSampleRate, ref _streamingStatePP);
+            EvaluateResultCode(resultCode);
         }
 
         /// <summary>

native_client/dotnet/DeepSpeechClient/DeepSpeechClient.csproj

@@ -45,6 +45,7 @@
   </ItemGroup>
   <ItemGroup>
     <Compile Include="DeepSpeech.cs" />
+    <Compile Include="Enums\ErrorCodes.cs" />
     <Compile Include="Interfaces\IDeepSpeech.cs" />
     <Compile Include="Extensions\NativeExtensions.cs" />
     <Compile Include="Models\Metadata.cs" />

native_client/dotnet/DeepSpeechClient/Enums/ErrorCodes.cs

@@ -0,0 +1,29 @@
+namespace DeepSpeechClient.Enums
+{
+    /// <summary>
+    /// Error codes from the native DeepSpeech binary.
+    /// </summary>
+    internal enum ErrorCodes
+    {
+        // OK
+        DS_ERR_OK = 0x0000,
+
+        // Missing invormations
+        DS_ERR_NO_MODEL = 0x1000,
+
+        // Invalid parameters
+        DS_ERR_INVALID_ALPHABET = 0x2000,
+        DS_ERR_INVALID_SHAPE = 0x2001,
+        DS_ERR_INVALID_LM = 0x2002,
+        DS_ERR_MODEL_INCOMPATIBLE = 0x2003,
+
+        // Runtime failures
+        DS_ERR_FAIL_INIT_MMAP = 0x3000,
+        DS_ERR_FAIL_INIT_SESS = 0x3001,
+        DS_ERR_FAIL_INTERPRETER = 0x3002,
+        DS_ERR_FAIL_RUN_SESS = 0x3003,
+        DS_ERR_FAIL_CREATE_STREAM = 0x3004,
+        DS_ERR_FAIL_READ_PROTOBUF = 0x3005,
+        DS_ERR_FAIL_CREATE_SESS = 0x3006,
+    }
+}

native_client/dotnet/DeepSpeechClient/Interfaces/IDeepSpeech.cs

@@ -21,8 +21,8 @@ public interface IDeepSpeech : IDisposable
         /// <param name="aNContext">The context window the model was trained with.</param>
         /// <param name="aAlphabetConfigPath">The path to the configuration file specifying the alphabet used by the network.</param>
         /// <param name="aBeamWidth">The beam width used by the decoder. A larger beam width generates better results at the cost of decoding time.</param>
-        /// <returns>Zero on success, non-zero on failure.</returns>
-        unsafe int CreateModel(string aModelPath, uint aNCep,
+        /// <exception cref="ArgumentException">Thrown when the native binary failed to create the model.</exception>
+        unsafe void CreateModel(string aModelPath, uint aNCep,
                    uint aNContext,
                    string aAlphabetConfigPath,
                    uint aBeamWidth);
@@ -35,8 +35,8 @@ unsafe int CreateModel(string aModelPath, uint aNCep,
         /// <param name="aTriePath">The path to the trie file build from the same vocabulary as the language model binary.</param>
         /// <param name="aLMAlpha">The alpha hyperparameter of the CTC decoder. Language Model weight.</param>
         /// <param name="aLMBeta">The beta hyperparameter of the CTC decoder. Word insertion weight.</param>
-        /// <returns>Zero on success, non-zero on failure (invalid arguments).</returns>
-        unsafe int EnableDecoderWithLM(string aAlphabetConfigPath,
+        /// <exception cref="ArgumentException">Thrown when the native binary failed to enable decoding with a language model.</exception>
+        unsafe void EnableDecoderWithLM(string aAlphabetConfigPath,
                   string aLMPath,
                   string aTriePath,
                   float aLMAlpha,
@@ -88,8 +88,8 @@ unsafe Metadata SpeechToTextWithMetadata(short[] aBuffer,
         /// One timestep is equivalent to two window lengths(20ms).
         /// If set to 0 we reserve enough frames for 3 seconds of audio(150).</param>
         /// <param name="aSampleRate">The sample-rate of the audio signal</param>
-        /// <returns>Zero for success, non-zero on failure</returns>
-        unsafe int SetupStream(uint aPreAllocFrames, uint aSampleRate);
+        /// <exception cref="ArgumentException">Thrown when the native binary failed to initialize the streaming mode.</exception>
+        unsafe void SetupStream(uint aPreAllocFrames, uint aSampleRate);
 
         /// <summary>
         /// Feeds audio samples to an ongoing streaming inference.

native_client/dotnet/DeepSpeechClient/NativeImp.cs

@@ -1,4 +1,5 @@
-using DeepSpeechClient.Structs;
+using DeepSpeechClient.Enums;
+using DeepSpeechClient.Structs;
 
 using System;
 using System.Runtime.InteropServices;
@@ -15,15 +16,15 @@ internal static class NativeImp
         internal static extern void DS_PrintVersions();
 
         [DllImport("libdeepspeech.so", CallingConvention = CallingConvention.Cdecl)]
-        internal unsafe static extern int DS_CreateModel(string aModelPath,
+        internal unsafe static extern ErrorCodes DS_CreateModel(string aModelPath,
                    uint aNCep,
                    uint aNContext,
                    string aAlphabetConfigPath,
                    uint aBeamWidth,
                    ref ModelState** pint);
 
         [DllImport("libdeepspeech.so", CallingConvention = CallingConvention.Cdecl)]
-        internal static unsafe extern int DS_EnableDecoderWithLM(ModelState** aCtx,
+        internal static unsafe extern ErrorCodes DS_EnableDecoderWithLM(ModelState** aCtx,
                   string aAlphabetConfigPath,
                   string aLMPath,
                   string aTriePath,
@@ -47,7 +48,7 @@ internal static unsafe extern IntPtr DS_SpeechToTextWithMetadata(ModelState** aC
         internal static unsafe extern void DS_DestroyModel(ModelState** aCtx);
 
         [DllImport("libdeepspeech.so", CallingConvention = CallingConvention.Cdecl)]
-        internal static unsafe extern int DS_SetupStream(ModelState** aCtx,
+        internal static unsafe extern ErrorCodes DS_SetupStream(ModelState** aCtx,
                uint aPreAllocFrames,
                uint aSampleRate, ref StreamingState** retval);