WinSAPI

## クラス WinSAPI

- java.lang.Object
- - WinSAPI.WinSAPI

-     public class WinSAPI
      extends java.lang.Object

  Java To Windows SAPI ブリッジクラス
  バージョン:
    2017/04/30 1.0
  作成者:
    MSLABO
  関連項目:
    ・関連情報公開元

- - ### コンストラクタのサマリー

    コンストラクタ
    コンストラクタと説明
    `WinSAPI(java.lang.String fileName)` コンストラクタ：クラスを初期化し、シンセサイザーを生成します。

  - ### メソッドのサマリー

    すべてのメソッド インスタンス・メソッド concreteメソッド
    修飾子とタイプ | メソッドと説明
    --- | ---
    `void` | `dispose()` シンセサイザー開放：リソースとシンセサイザーオブジェクトを開放します。
    `int` | `getSpeed()` 読み上げ速度取得：現在の読み上げ速度を取得します。
    `java.lang.String` | `getVoice()` 音声名称取得：現在選択されている音声データ名称を取得します。
    `int` | `getVolume()` 読み上げ音量取得：現在の音量を取得します。
    `boolean` | `isAsySpeak()` 非同期発声終了検査：非同期読み上げの状態を返却します。
    `void` | `setSpeed(int speed)` 読み上げ速度指定：読み上げ速度を変更します。
    `int` | `setVoice(java.lang.String voiceName)` 音声名称指定：発声に利用する音声データ名称を指定します。
    `void` | `setVolume(int volume)` 読み上げ音量指定：読み上げ時の音量を変更します。
    `void` | `speakAsyMsg(java.lang.String msg)` 非同期読み上げ：与えられた文章を非同期モードで音声化します。
    `void` | `speakAsySsmlMsg(java.lang.String msg)` SSML非同期読み上げ：与えられた文章を非同期モードで音声化します。
    `void` | `speakMsg(java.lang.String msg)` 同期読み上げ：与えられた文章を同期モードで音声化します。
    `void` | `speakSsmlMsg(java.lang.String msg)` SSML同期読み上げ：与えられた文章を同期モードで音声化します。

    - ### クラスから継承されたメソッド java.lang.Object

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

- - ### コンストラクタの詳細

    - #### WinSAPI

          public WinSAPI(java.lang.String fileName)

      コンストラクタ：クラスを初期化し、シンセサイザーを生成します。
      WinSAPICPP.DLLを読み込み、発声に利用するシンセサイザーオブジェクトを生成します。
      WAVファイルに出力する場合、指定されたフォルダが存在しないとシンセイサイザーの生成に失敗します。
      またOSが許可していない場所や、ドライブ直下にWAVファイルを出力することはできません。
      パラメータ:
        `fileName` - 発声データをWAVファイルに保存する場合に指定します。nullまたは空文字ならデフォルトデバイス（スピーカー）に出力します。

             import WinSAPI.WinSAPI;
             void setup(){
              WinSAPI  sapi = null;
              sapi = new WinSAPI(""); //生成（スピーカー出力）
              //sapi = new WinSAPI("C:\\Temp\\hoge.wav"); //生成（WAVファイル出力）
              sapi.speakMsg("Hello Processing" );
              sapi.dispose();
             }
             void draw(){
             }

  - ### メソッドの詳細

    - #### dispose

          public void dispose()

      シンセサイザー開放：リソースとシンセサイザーオブジェクトを開放します。
      開放すると、強制的に発声は中断されます。非同期発声中は注意してください。

           import WinSAPI.WinSAPI;
           void setup(){
            WinSAPI  sapi = null;
            sapi = new WinSAPI("");
            sapi.speakMsg("Hello Processing" );
            sapi.dispose();   //開放
           }
           void draw(){
           }

    - #### setSpeed

          public void setSpeed(int speed)

      読み上げ速度指定：読み上げ速度を変更します。
      パラメータ:
        `speed` - `+10 から -10。0なら等倍速で読み上げます`

             import WinSAPI.WinSAPI;
             void setup(){
               WinSAPI  sapi = null;
               sapi = new WinSAPI("");
               sapi.speakMsg("Hello");
               sapi.setSpeed(7);  //[Processing]部分は速読する
               sapi.speakMsg("Processing");
               sapi.dispose();
             }
             void draw(){
             }

    - #### setVolume

          public void setVolume(int volume)

      読み上げ音量指定：読み上げ時の音量を変更します。
      パラメータ:
        `volume` - `0 から 100。0なら無音、100ならMAX音量で読み上げます`

             import WinSAPI.WinSAPI;
             void setup(){
               WinSAPI  sapi = null;
               sapi = new WinSAPI("");
               sapi.speakMsg("Hello");
               sapi.setVolume(0); //[Processing]部分は無音になる
               sapi.speakMsg("Processing");
               sapi.dispose();
             }
             void draw(){
             }

    - #### setVoice

          public int setVoice(java.lang.String voiceName)

      音声名称指定：発声に利用する音声データ名称を指定します。
      デフォルトではOSの設定が利用されます。
      指定された音声データが該当OSに未インストールの場合、変更に失敗します。
      パラメータ:
        `voiceName` - `音声データ名称。正式名称指定の他に、名称に含まれる部分文字列指定でも可能です`
      戻り値:

             -99：変更失敗;
              0：成功;

             import WinSAPI.WinSAPI;
             void setup(){
               WinSAPI  sapi = null;
               sapi = new WinSAPI("");
               sapi.setVoice("Microsoft Zira Desktop");  //Windows10 標準英語音声データを指定
               sapi.speakMsg("Zira is english voice data");  //英語で読み上げます
               sapi.dispose();
             }
             void draw(){
             }

    - #### getSpeed

          public int getSpeed()

      読み上げ速度取得：現在の読み上げ速度を取得します。
      戻り値:
        `+10 から -10。0なら等倍速です`

             import WinSAPI.WinSAPI;
             void setup(){
               WinSAPI  sapi = null;
               sapi = new WinSAPI("");
               println( sapi.getSpeed() );  // 0 が表示される
               sapi.dispose();
             }
             void draw(){
             }

    - #### getVoice

          public java.lang.String getVoice()

      音声名称取得：現在選択されている音声データ名称を取得します。
      音声データの正式名称が戻されます。
      戻り値:
        `音声データ正式名称`

             import WinSAPI.WinSAPI;
             void setup(){
               WinSAPI  sapi = null;
               sapi = new WinSAPI("");
               println( sapi.getVoice() );  //[Microsoft Haruka Desktop]が表示される
               sapi.dispose();
             }
             void draw(){
             }

    - #### getVolume

          public int getVolume()

      読み上げ音量取得：現在の音量を取得します。
      戻り値:
        `0 から 100 。0なら無音。100ならMAX音量`

             import WinSAPI.WinSAPI;
             void setup(){
               WinSAPI  sapi = null;
               sapi = new WinSAPI("");
               println( sapi.getVolume() );  //100 が表示される
               sapi.dispose();
             }
             void draw(){
             }

    - #### speakMsg

          public void speakMsg(java.lang.String msg)

      同期読み上げ：与えられた文章を同期モードで音声化します。
      出力はデフォルトデバイス（スピーカー）か、WAVファイルに行われます。
      読み上げが終わるまで、制御が上位に戻りません。
      設定されている音声データが、該当文章を読み上げるのに適切でない場合、期待した読み上げ結果にならない事があります（例：英語音声データで日本語文章を読ませるなど）。
      事前に、読み上げたい文章のロケールに応じた音声データをOSにインストールし、必要に応じて`setVoice(java.lang.String)` で 音声データを指定しておく必要があります。
      パラメータ:
        `msg` - `読み上げる文章`

             import WinSAPI.WinSAPI;
             void setup(){
               WinSAPI  sapi = null;
               sapi = new WinSAPI("");
               sapi.setVoice("Microsoft Haruka Desktop");
               sapi.speakMsg("貴社の記者が汽車で帰社する");  //読み上げます
               sapi.dispose();
             }
             void draw(){
             }

    - #### isAsySpeak

          public boolean isAsySpeak()

      非同期発声終了検査：非同期読み上げの状態を返却します。
      本メソッドは、同期読み上げ時には意味を持ちません。
      戻り値:

             false：読み上げていない;
             true：読み上げ中;

             import WinSAPI.WinSAPI;
             void setup(){
               WinSAPI  sapi = null;
               sapi = new WinSAPI("");
               sapi.setVoice("Microsoft Haruka Desktop");
               sapi.speakAsyMsg("貴社の記者が汽車で帰社する");
               while( sapi.isAsySpeak()){  //非同期読み上げの終了を待つ
                 delay(100);
               }
               sapi.dispose();
             }
             void draw(){
             }

    - #### speakAsyMsg

          public void speakAsyMsg(java.lang.String msg)

      非同期読み上げ：与えられた文章を非同期モードで音声化します。
      出力はデフォルトデバイス（スピーカー）か、WAVファイルに行われます。
      読み上げ開始後、直ちに制御が上位に戻ります。
      読み上げ完了前に `dispose()` すると、強制的に発声が停止します。読み上げ中か否かは `isAsySpeak()` で知ることが可能です。
      設定されている音声データが、該当文章を読み上げるのに適切でない場合、期待した読み上げ結果にならない事があります（例：英語音声データで日本語文章を読ませるなど）。
      事前に、読み上げたい文章のロケールに応じた音声データをOSにインストールし、必要に応じて`setVoice(java.lang.String)` で 音声データを指定しておく必要があります。
      パラメータ:
        `msg` - `読み上げる文章`

             import WinSAPI.WinSAPI;
             void setup(){
               WinSAPI  sapi = null;
               sapi = new WinSAPI("");
               sapi.setVoice("Microsoft Haruka Desktop");
               sapi.speakAsyMsg("貴社の記者が汽車で帰社する");  //非同期読み上げ
               while( sapi.isAsySpeak()){
                 delay(100);
               }
               sapi.dispose();
             }
             void draw(){
             }

    - #### speakAsySsmlMsg

          public void speakAsySsmlMsg(java.lang.String msg)

      SSML非同期読み上げ：与えられた文章を非同期モードで音声化します。
      与えられた文章はSSML形式の文章とみなします。出力はデフォルトデバイス（スピーカー）か、WAVファイルに行われます。
      先頭の speak タグは省略可能です。省略した場合の音声ローケルには、選択中の音声データのものが採用されます。
      読み上げ開始後、直ちに制御が上位に戻ります。
      読み上げ完了前に `dispose()` すると、強制的に発声が停止します。読み上げ中か否かは `isAsySpeak()` で知ることが可能です。
      本メソッドに与える文章は SSML 1.0 形式である必要があります。
      設定されている音声データが、該当文章を読み上げるのに適切でない場合、期待した読み上げ結果にならない事があります（例：英語音声データで日本語文章を読ませるなど）。
      事前に、読み上げたい文章のロケールに応じた音声データをOSにインストールし、必要に応じて`setVoice(java.lang.String)` で 音声データを指定しておく必要があります。
      パラメータ:
        `msg` - `読み上げる文章`

             import WinSAPI.WinSAPI;
             void setup(){
               WinSAPI  sapi = null;
               sapi = new WinSAPI("");
               sapi.setVoice("Microsoft Haruka Desktop");
               sapi.speakAsySsmlMsg("<speak version=\"1.0\" xml:lang=\"ja-JP\"><sub alias=\"ピカチュウ\">光宙</sub></speak>);
               while( sapi.isAsySpeak()){
                 delay(100);
               }
               sapi.dispose();
             }
             void draw(){
             }

      関連項目:
        w3.org Speech Synthesis Markup Language (SSML) Version 1.0

    - #### speakSsmlMsg

          public void speakSsmlMsg(java.lang.String msg)

      SSML同期読み上げ：与えられた文章を同期モードで音声化します。
      与えられた文章はSSML形式の文章とみなします。出力はデフォルトデバイス（スピーカー）か、WAVファイルに行われます。
      先頭の speak タグは省略可能です。省略した場合の音声ローケルには、選択中の音声データのものが採用されます。
      読み上げが終わるまで、制御が上位に戻りません。
      本メソッドに与える文章は SSML 1.0 形式である必要があります。
      設定されている音声データが、該当文章を読み上げるのに適切でない場合、期待した読み上げ結果にならない事があります（例：英語音声データで日本語文章を読ませるなど）。
      事前に、読み上げたい文章のロケールに応じた音声データをOSにインストールし、必要に応じて`setVoice(java.lang.String)` で 音声データを指定しておく必要があります。
      パラメータ:
        `msg` - `読み上げる文章`

             import WinSAPI.WinSAPI;
             void setup(){
               WinSAPI  sapi = null;
               sapi = new WinSAPI("");
               sapi.setVoice("Microsoft Haruka Desktop");
               sapi.speakSsmlMsg("<speak version=\"1.0\" xml:lang=\"ja-JP\">今日は<say-as interpret-as=\"date\" format=\"ymd\">2017/04/30</say-as>です。</speak>");
             }
             void draw(){
             }

      関連項目:
        w3.org Speech Synthesis Markup Language (SSML) Version 1.0