SpeechPkg

## Class WinSpeech

- java.lang.Object
- - SpeechPkg.WinSpeech

-     public class WinSpeech
      extends java.lang.Object

  Windows音声解析DLL.
  Version:
    Ver1.0
  Author:
    MSLABO
  See Also:
    ・関連情報公開元
    本プログラムとドキュメント（以下、本APと呼称）の著作権はMSLABOにあります。
    本APのMSLABO作成部分は、クリエィティブ・コモンズライセンスに従い提供されています。
    また本APが利用しているJNA、PROCESSINGなどの各モジュールについては、各ソフトウェアの ライセンス規約に従うものとします。
    利用にあたっては、必ず自己責任でお願い致します。
    本APの不具合については極力善処を行う予定ですが、これを保証するものではありません。
    また本APに関する情報はすべてMSLABOのHPから一方的に公開するものとし、原則として、個別の 問い合わせや要望は受け付けません。
    上記事項に同意頂ける方のみ、利用が可能です。
    本プログラムが、みなさまのPROCESSING利用の一助になれば幸いです。

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static boolean` | `DICTATION` 自由会話解析モード
    `static boolean` | `GRAMMAR` 文法解析モード
    `static boolean` | `MULTIPLE` 連続解析
    `static boolean` | `SINGLE` シングル解析

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `WinSpeech()` コンストラクタ：クラスを初期化します. SytemSpeechNET.DLLは実行モジュールのカレント位置にあるものとして読み込まれます。 DLLが見つからない場合は、IllegalArgumentExceptionが発生します。 またDLLの読み込みに失敗するとUnsatisfiedLinkErrorが発生します。 DLLのパスは、ログファイルの出力先および文法ファイルの存在パスとしても扱われます。
    `WinSpeech(java.lang.String libPath)` コンストラクタ：クラスを初期化します. 指定されたパス配下にあるSytemSpeechNET.DLLを読み込みます。 DLLが見つからない場合は、IllegalArgumentExceptionが発生します。 またDLLの読み込みに失敗するとUnsatisfiedLinkErrorが発生します。 DLLのパスは、ログファイルの出力先および文法ファイルの存在パスとしても扱われます。

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `CloseEngine()` 解析エンジンをCloseします.
    `java.lang.String` | `GetSpeechHypothesized()` 現在までに認識された語句から、最も信頼性のあるものを取得します.
    `java.lang.String` | `GetSpeechRecognized()` 現在までに未取得の解析結果を受け取ります.
    `int` | `OpenEngine()` 解析エンジンをOpenします. 自由会話解析モードで動作します。入力には標準入力マイクを利用します。
    `int` | `OpenEngine(boolean mode)` 解析エンジンをOpenします. GRAMMARを指定すると文法解析モードで、DICTATIONを指定すると自由会話解析モードで動作します。 文法解析モード時には、文法ファイルが必要となります。 文法ファイルはインスタンス作成時に指定したパス（DLLの存在位置）にあるものみなします。 入力には標準入力マイクを利用します。
    `void` | `SetCallbackRecognizedFunc(java.lang.Object obj, java.lang.String func)` 解析終了時コールバック関数登録. 解析が正常に終了した際に呼ばれるJavaの関数を定義します。 解析が終わった際に、その結果を返却します。 コールバック関数の名前は任意ですが、publicで、String型の引数を１つだけ受け取るvoid戻り値のものにしてください。
    `int` | `SetDictationType(boolean mode)` 音声解析モードを設定します. GRAMMARを指定すると文法解析モードで、DICTATIONを指定すると自由会話解析モードで動作します。 文法解析モード時には、文法ファイルが必要となります。 文法ファイルはインスタンス作成時に指定したパス（DLLの存在位置）にあるものみなします。
    `void` | `SetGrammarName(java.lang.String fileName)` 文法ファイル名を切り替えます. デフォルトの文法ファイル名は[Grammar.txt]です。 文法ファイルはインスタンス作成時に指定したパス（DLLの存在位置）にあるものみなします。 文法ファイルは Shift-JIS で記述してください。 文法ファイル例： #半角のシャープで始まる行はコメントです あかいろ いるか オレンジ
    `void` | `SetHypothesizedCallBackFunc(java.lang.Object obj, java.lang.String func)` 解析失敗時コールバック関数登録. 解析が失敗した際に呼ばれるJavaの関数を定義します。 解析失敗時に、 現在までに認識された語句から、最も信頼性のあるものを取得し、その信頼度とともに返却します。 なにも認識された語句がない場合は、空文字と信頼度0が戻されます。 コールバック関数の名前は任意ですが、publicで、String型の引数とfloatの引数を受け取るvoid戻り値のものにしてください。
    `int` | `SetInputDefaultAudio()` 入力に標準入力マイクを利用します. マイクが接続されていない（あるいは無効）な場合は、エラーとなります。
    `int` | `SetInputWavFile(java.lang.String fileName)` 入力にWAVファイルを利用します. WAVファイルは、サンプリングレートが44100で、16bitのモノクロチャネルのものが推奨です。
    `void` | `SetLogName(java.lang.String fileName)` ログファイル名を切り替えます. デフォルトのログファイル名は[SytemSpeechNET.txt]です。 ログファイルはインスタンス作成時に指定したパス（DLLの存在位置）に作成されます。
    `void` | `SetLogSwitch(boolean logSw)` SytemSpeechNET.dllがログを出力するかどうかを切り替えます. デフォルトでは、ログは出力しません。
    `int` | `StartAsyncRecognized(boolean mode)` 非同期解析開始. 非同期による音声解析を開始します。SINGLEなら１回だけ解析し、MULTIPLEなら連続で解析します。 非同期解析はStopAsyncRecognized()が呼ばれると停止します。
    `int` | `StartRecognized(int timeOut)` 同期解析開始. 同期による音声解析を開始します。解析が終了するまでブロックされ、上位に処理が戻りません。 timeOutは音声の入力を待つ時間です。timeOut秒以上、有効な音声が入力されなかった場合、エラーと なります。0以下なら無限に音声入力を待ちます。
    `int` | `StopAsyncRecognized()` 連続した非同期解析を停止します. StartAsyncRecognized()ではじめた非同期連続解析を停止します。

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### GRAMMAR

          public static final boolean GRAMMAR

      文法解析モード
      See Also:
        Constant Field Values

    - #### DICTATION

          public static final boolean DICTATION

      自由会話解析モード
      See Also:
        Constant Field Values

    - #### SINGLE

          public static final boolean SINGLE

      シングル解析
      See Also:
        Constant Field Values

    - #### MULTIPLE

          public static final boolean MULTIPLE

      連続解析
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### WinSpeech

          public WinSpeech(java.lang.String libPath)
                    throws java.lang.IllegalArgumentException,
                           java.lang.UnsatisfiedLinkError

      コンストラクタ：クラスを初期化します.
      指定されたパス配下にあるSytemSpeechNET.DLLを読み込みます。
      DLLが見つからない場合は、IllegalArgumentExceptionが発生します。 またDLLの読み込みに失敗するとUnsatisfiedLinkErrorが発生します。 DLLのパスは、ログファイルの出力先および文法ファイルの存在パスとしても扱われます。
      Parameters:
        `libPath` - DLLパス
      Throws:
        `java.lang.IllegalArgumentException` - 指定パスにDLLが存在しません
        `java.lang.UnsatisfiedLinkError` - DLL読み込み例外

             import SpeechPkg.*;

             void setup(){
               //インスタンスを生成する
               //DLLの場所には、スケッチフォルダーのcode配下を指定
               WinSpeech ws = new WinSpeech(sketchPath("code"));
             }
             void draw(){
             }

    - #### WinSpeech

          public WinSpeech()
                    throws java.lang.IllegalArgumentException,
                           java.lang.UnsatisfiedLinkError

      コンストラクタ：クラスを初期化します.
      SytemSpeechNET.DLLは実行モジュールのカレント位置にあるものとして読み込まれます。
      DLLが見つからない場合は、IllegalArgumentExceptionが発生します。 またDLLの読み込みに失敗するとUnsatisfiedLinkErrorが発生します。 DLLのパスは、ログファイルの出力先および文法ファイルの存在パスとしても扱われます。
      Throws:
        `java.lang.IllegalArgumentException` - 指定パスにDLLが存在しません
        `java.lang.UnsatisfiedLinkError` - DLL読み込み例外

             import SpeechPkg.*;

             void setup(){
               //インスタンスを生成する
               //DLLの場所には、実行モジュールのカレント位置とみなします
               WinSpeech ws = new WinSpeech();
             }
             void draw(){
             }

  - ### Method Detail

    - #### SetLogName

          public void SetLogName(java.lang.String fileName)

      ログファイル名を切り替えます.
      デフォルトのログファイル名は[SytemSpeechNET.txt]です。
      ログファイルはインスタンス作成時に指定したパス（DLLの存在位置）に作成されます。
      Parameters:
        `fileName` - ログファイル名

              import SpeechPkg.*;

              void setup(){
                //インスタンスを生成する
                WinSpeech ws = new WinSpeech(sketchPath("code"));
                //ログファイル名を変更する
                ws.SetLogName("MyLog.txt");
              }
              void draw(){
              }

    - #### SetGrammarName

          public void SetGrammarName(java.lang.String fileName)

      文法ファイル名を切り替えます.
      デフォルトの文法ファイル名は[Grammar.txt]です。
      文法ファイルはインスタンス作成時に指定したパス（DLLの存在位置）にあるものみなします。
      文法ファイルは Shift-JIS で記述してください。
      文法ファイル例：
      #半角のシャープで始まる行はコメントです
      あかいろ
      いるか
      オレンジ
      Parameters:
        `fileName` - 文法ファイル名

              import SpeechPkg.*;

              void setup(){
                //インスタンスを生成する
                WinSpeech ws = new WinSpeech(sketchPath("code"));
                //文法ファイル名を変更する
                ws.SetGrammarName("MyGrammar.txt");
              }
              void draw(){
              }

    - #### SetLogSwitch

          public void SetLogSwitch(boolean logSw)

      SytemSpeechNET.dllがログを出力するかどうかを切り替えます.
      デフォルトでは、ログは出力しません。
      Parameters:
        `logSw` - True:ログ出力ON

             import SpeechPkg.*;

             void setup(){
               //インスタンスを生成する
               WinSpeech ws = new WinSpeech(sketchPath("code"));
               //ログを記録する
               ws.SetLogSwitch( true );
             }
             void draw(){
             }

    - #### CloseEngine

          public void CloseEngine()

      解析エンジンをCloseします.

           import SpeechPkg.*;

           void setup(){
             //インスタンスを生成する
             WinSpeech ws = new WinSpeech(sketchPath("code"));
             //解析エンジンをOpen/Closeする
             ws.OpenEngine( );
             ws.CloseEngine();
           }
           void draw(){
           }

    - #### OpenEngine

          public int OpenEngine(boolean mode)

      解析エンジンをOpenします.
      GRAMMARを指定すると文法解析モードで、DICTATIONを指定すると自由会話解析モードで動作します。
      文法解析モード時には、文法ファイルが必要となります。
      文法ファイルはインスタンス作成時に指定したパス（DLLの存在位置）にあるものみなします。
      入力には標準入力マイクを利用します。
      Parameters:
        `mode` - 解析モード(GRAMMAR/DICTATION)
      Returns:
        0以外：異常

             import SpeechPkg.*;

             void setup(){
               //インスタンスを生成する
               WinSpeech ws = new WinSpeech(sketchPath("code"));

               //解析エンジンをOpenする
               ws.OpenEngine(WinSpeech.GRAMMAR);

             }
             void draw(){
             }

    - #### OpenEngine

          public int OpenEngine()

      解析エンジンをOpenします.
      自由会話解析モードで動作します。入力には標準入力マイクを利用します。
      Returns:
        0以外：異常

             import SpeechPkg.*;

             void setup(){
               //インスタンスを生成する
               WinSpeech ws = new WinSpeech(sketchPath("code"));

               //解析エンジンをOpenする
               ws.OpenEngine();

             }
             void draw(){
             }

    - #### SetDictationType

          public int SetDictationType(boolean mode)

      音声解析モードを設定します.
      GRAMMARを指定すると文法解析モードで、DICTATIONを指定すると自由会話解析モードで動作します。
      文法解析モード時には、文法ファイルが必要となります。
      文法ファイルはインスタンス作成時に指定したパス（DLLの存在位置）にあるものみなします。
      Parameters:
        `mode` - 解析モード(GRAMMAR/DICTATION)
      Returns:
        0以外：異常

             import SpeechPkg.*;

             void setup(){
               //インスタンスを生成する
               WinSpeech ws = new WinSpeech(sketchPath("code"));

               //解析エンジンをOpenする
               ws.OpenEngine();

               //文法解析を指定
               ws.SetDictationType(WinSpeech.GRAMMAR);
             }
             void draw(){
             }

    - #### SetInputDefaultAudio

          public int SetInputDefaultAudio()

      入力に標準入力マイクを利用します.
      マイクが接続されていない（あるいは無効）な場合は、エラーとなります。
      Returns:
        0以外：異常

             import SpeechPkg.*;

             void setup(){
               //インスタンスを生成する
               WinSpeech ws = new WinSpeech(sketchPath("code"));

               //解析エンジンをOpenする
               ws.OpenEngine();
               //標準入力マイクを利用
               ws.SetInputDefaultAudio();
             }
             void draw(){
             }

    - #### SetInputWavFile

          public int SetInputWavFile(java.lang.String fileName)

      入力にWAVファイルを利用します.
      WAVファイルは、サンプリングレートが44100で、16bitのモノクロチャネルのものが推奨です。
      Parameters:
        `fileName` - WAVファイル名
      Returns:
        0以外：異常

             import SpeechPkg.*;

             void setup(){
               //インスタンスを生成する
               WinSpeech ws = new WinSpeech(sketchPath("code"));

               //解析エンジンをOpenする
               ws.OpenEngine();
               //WAVファイルを利用する
               ws.SetInputWavFile("c:\\temp\\femal.wav");
             }
             void draw(){
             }

    - #### StartAsyncRecognized

          public int StartAsyncRecognized(boolean mode)

      非同期解析開始.
      非同期による音声解析を開始します。SINGLEなら１回だけ解析し、MULTIPLEなら連続で解析します。
      非同期解析はStopAsyncRecognized()が呼ばれると停止します。
      Parameters:
        `mode` - 解析方法（SINGLE/MULTIPLE）
      Returns:
        0以外：異常

             import SpeechPkg.*;

             void setup(){
               //インスタンスを生成する
               WinSpeech ws = new WinSpeech(sketchPath("code"));

               //解析エンジンをOpenする
               ws.OpenEngine(WinSpeech.GRAMMAR);
               //非同期解析（連続）開始
               ws.StartAsyncRecognized(WinSpeech.MULTIPLE);
             }
             void draw(){
             }

    - #### StartRecognized

          public int StartRecognized(int timeOut)

      同期解析開始.
      同期による音声解析を開始します。解析が終了するまでブロックされ、上位に処理が戻りません。
      timeOutは音声の入力を待つ時間です。timeOut秒以上、有効な音声が入力されなかった場合、エラーと なります。0以下なら無限に音声入力を待ちます。
      Parameters:
        `timeOut` - 指定秒数だけ音声の入力を待つ。0以下なら無限待ち
      Returns:
        0以外：異常

             import SpeechPkg.*;

             void setup(){
               //インスタンスを生成する
               WinSpeech ws = new WinSpeech(sketchPath("code"));

               //解析エンジンをOpenする
               ws.OpenEngine(WinSpeech.GRAMMAR);
               //同期解析開始（１０秒だけ音声入力を待つ）
               ws.StartRecognized(10);
             }
             void draw(){
             }

    - #### StopAsyncRecognized

          public int StopAsyncRecognized()

      連続した非同期解析を停止します.
      StartAsyncRecognized()ではじめた非同期連続解析を停止します。
      Returns:
        0以外：異常

             import SpeechPkg.*;

             WinSpeech ws;
             void setup(){
               //インスタンスを生成する
               ws = new WinSpeech(sketchPath("code"));

               //解析エンジンをOpenする
               ws.OpenEngine();
               //非同期解析開始
               ws.StartAsyncRecognized(WinSpeech.MULTIPLE);
             }
             void draw(){
               //結果を取得
               String rec = ws.GetSpeechRecognized();
               if( !rec.equals("") ){
                 //なにか解析できたら表示する
                 println( rec );

                 if( rec.equals("終わり")){
                   //[終わり]と入力されたら、解析停止
                   ws.StopAsyncRecognized();
                   println("end");
                 }
               }
             }

    - #### GetSpeechRecognized

          public java.lang.String GetSpeechRecognized()

      現在までに未取得の解析結果を受け取ります.
      Returns:
        解析結果。なにも解析されたものが無ければ空文字が戻ります

             import SpeechPkg.*;

             WinSpeech ws;
             void setup(){
               //インスタンスを生成する
               ws = new WinSpeech(sketchPath("code"));

               //解析エンジンをOpenする
               ws.OpenEngine();
               //非同期解析開始
               ws.StartAsyncRecognized(WinSpeech.MULTIPLE);
             }
             void draw(){
               //結果を取得
               String rec = ws.GetSpeechRecognized();
               if( !rec.equals("") ){
                 //なにか解析できたら表示する
                 println( rec );

                 if( rec.equals("終わり")){
                   //[終わり]と入力されたら、解析停止
                   ws.StopAsyncRecognized();
                   println("end");
                 }
               }
             }

    - #### GetSpeechHypothesized

          public java.lang.String GetSpeechHypothesized()

      現在までに認識された語句から、最も信頼性のあるものを取得します.
      Returns:
        解析結果。なにも解析されたものが無ければ空文字が戻ります

             import SpeechPkg.*;

             WinSpeech ws;

             void setup(){
               ws = new WinSpeech(sketchPath("code"));
               ws.SetLogSwitch( true );

               //WAVを文法解析
               ws.OpenEngine( WinSpeech.GRAMMAR );
               ws.SetInputWavFile( dataPath("shop_youngman01_06_1.wav") );

               //解析開始
               int ret = ws.StartRecognized( 0 );
               if( ret != 0 ){
                 //解析エラーなら、最も信頼度の高い解析結果を得る
                 String val = ws.GetSpeechHypothesized();
                 if( !val.equals("") ){
                   println( "[" + val + "]" );
                 }
               }
             }

             void draw(){
             }

    - #### SetHypothesizedCallBackFunc

          public void SetHypothesizedCallBackFunc(java.lang.Object obj,
                                                  java.lang.String func)

      解析失敗時コールバック関数登録.
      解析が失敗した際に呼ばれるJavaの関数を定義します。
      解析失敗時に、 現在までに認識された語句から、最も信頼性のあるものを取得し、その信頼度とともに返却します。
      なにも認識された語句がない場合は、空文字と信頼度0が戻されます。
      コールバック関数の名前は任意ですが、publicで、String型の引数とfloatの引数を受け取るvoid戻り値のものにしてください。
      Parameters:
        `obj` - コールバック関数があるクラス
        `func` - コールバック関数名

             import SpeechPkg.*;
             import java.lang.reflect.InvocationTargetException;

             WinSpeech ws;
             void setup(){
               //インスタンスを生成する
               ws = new WinSpeech(sketchPath("code"));
               ws.SetLogSwitch( true );

               //解析エンジンをOpenする
               ws.OpenEngine( WinSpeech.GRAMMAR );
               //解析終了時のコールバック関数を登録する
               ws.SetHypothesizedCallBackFunc(this,"callBackFunc");

               //非同期解析開始
               ws.SetInputWavFile( dataPath("03_macho_before.wav") );
               ws.StartAsyncRecognized(WinSpeech.SINGLE);
             }
             void draw(){
             }

             //コールバックされる関数
             //void 戻り値で、引数は Stringとfloatである事
             //rec : これまでに得られた解析結果のうち最大の信頼度を持つもの
             //conf ：　解析信頼度
             public void callBackFunc(String rec, float conf){
               if( !rec.equals("") ){
                 //なにか解析できたら表示する
                 println( "[" + rec + "](" + conf + ")" );
               }
             }

    - #### SetCallbackRecognizedFunc

          public void SetCallbackRecognizedFunc(java.lang.Object obj,
                                                java.lang.String func)

      解析終了時コールバック関数登録.
      解析が正常に終了した際に呼ばれるJavaの関数を定義します。
      解析が終わった際に、その結果を返却します。
      コールバック関数の名前は任意ですが、publicで、String型の引数を１つだけ受け取るvoid戻り値のものにしてください。
      Parameters:
        `obj` - コールバック関数があるクラス
        `func` - コールバック関数名

             import SpeechPkg.*;
             import java.lang.reflect.InvocationTargetException;

             WinSpeech ws;
             void setup(){
               //インスタンスを生成する
               ws = new WinSpeech(sketchPath("code"));

               //解析エンジンをOpenする
               ws.OpenEngine();
               //解析終了時のコールバック関数を登録する
               ws.SetCallbackRecognizedFunc(this,"callBackFunc");

               //非同期解析開始
               ws.StartAsyncRecognized(WinSpeech.MULTIPLE);
             }
             void draw(){
             }

             //コールバックされる関数
             //void 戻り値で、引数は Stringである事
             //rec : 解析結果
             public void callBackFunc(String rec){
               if( !rec.equals("") ){
                 //なにか解析できたら表示する
                 println( "[" + rec + "]" );

                 if( rec.trim().equals("終わり")){
                   //[終わり]と入力されたら、解析停止
                   ws.CloseEngine();
                 }
               }
             }