API一覧

getCast

機能

現在設定されている読み上げに使用する音声の種類を返す。

引数

なし

戻り値

音声の種類（文字列）

音声の種類が文字列で得られる。

使用例

voice = vds.getCast();
switch(voice){
        case "TakashiJPm":
            vds.speak("私の名前は、たかしです。");
            break;
        case "KeikoJPf":
            vds.speak("私の名前は、けいこです。");
            break;
}

• 上の例では、設定されている音声名によって、しゃべる内容を切り替えています。

getCastList

機能

現在使用可能な音声の種類の一覧を配列で返す。

引数

なし

戻り値

文字列の配列

現在使用可能な音声の種類一覧。

使用例

var myCast;
var castList = new Array();

castList = vds.getCastList();
for (var i = 0; i < castList.length; i++) {
    var value = castList[i];
    if( value.match(/^Keiko/) ){
        myCast = value;
    }
}

• 上の例では、音声名の一部から音声を検索して、setCastメソッドに検索結果を渡しています。
• 利用可能な音声の中からユーザに1つを選ばせるようなインタフェースを動的に生成する時などに、使用できるでしょう。
• 音声の種類や数、それぞれの名称は、今後変更される可能性があります。

getRate

機能

現在設定されている音声の読み上げ速度を返す。

引数

なし

戻り値

音声の読み上げ速度

設定されている読み上げ速度の値（数値）

使用例

var currentRate;
currentRate = getRate();
alert("現在の読み上げ速度は：" + currentRate + "です。");

getServerError

機能

サーバでの音声合成時に発生したエラーを確認するためのメソッドです。このセクションの最初にある「vdsのエラー処理」を併せて参照してください。

引数

なし

戻り値

-301

1ヶ月あたりの再生文字数が規定値を超えた場合。

-501

セッションが失われた場合。

使用例

vds.speak("この文字列を読み上げます。");
switch( vds.getServerError() ){
    case -301:
        alert("残念ながら、1ヶ月あたりの再生文字数が規定数を超えました。");
        break;
    case -501:
        alert("ページをリロードして、もう一度再生ボタンを押してみてください。");
        break;
}

• 上の例では、speakメソッドを呼んだ後、正しく再生出来たかどうか確認して、必要に応じてエラーを出力しています。
• このセクションの最初のエラー処理でも述べましたが、「メソッドの戻り値チェック」、「try-catch文による例外処理」、そしてこの「getServerError」がvdsで発生するエラーに対処する3つの方法です。

getString

機能

読み上げ対象として設定されている文字列を返す。

引数

なし

戻り値

読み上げ文字列

setStringメソッドで設定された文字列、またはspeakメソッドの引数で指定された文字列。

使用例

var currentString;
currentString = getStringe();
alert("現在の読み上げ文字列は：[" + currentString + "]です。");

getStringLimit

機能

speakメソッドに渡すことができる文字列の長さを返す。

引数

なし

戻り値

文字列の長さ（数値）

サーバ側で許可されている一回のspeakメソッド呼び出しで読み上げられる最大の文字数。

使用例

var currentString;
currentString = getStringe();
if( currentString.lenght > vds.getStringLimit() ){
        alert("読み上げ文字列が長過ぎます。");
}

• ユーザに入力させた文字列を読み上げさせる場合には、上のような方法で、文字列の長さをチェックすることできます。
• 1回のspeakメソッド呼び出しで渡すことができる文字列の長さは、予告なく変更されることがあります。よって、スタティックな値をプログラム内で持つのではなく、getStringLimitを使って取得することをお勧めします。

setCast

機能

読み上げに使用する音声の種類を指定します。デフォルトでは、「TakashiJPm」が設定されています。

引数

音声種別

音声合成に使用する音声名を文字列で渡します。

戻り値

0

正しい値が設定された場合。

-101

無効な音声が指定された場合。

使用例

vds.setCast("TakashiJPm");
vds.speak("この声は、Takashiの声です");

• 音声種別の指定は、大文字と小文字を正確に入力する必要があります。

setFinishCallback

機能

サーバ側で音声の生成が終了した際に呼び出される関数名を指定します。音声の準備中であることをユーザに伝えるローダアイコンなどの制御に使用できます。

引数

関数呼び出し文

当該関数を呼び出す際の文を文字列として渡す。

戻り値

なし

引数で指定された関数が実際に存在しているか否かは、一切関知しません。

使用例

function serverProcessFinished(){
        alert("Server Process is Finished.");
}
vds.setFinishCallback("severProcessFinished()");
vds.speak("この文字列が読み上げられます。");

• setFinishCallbackの引数には、関数の呼び出し形式を記述します（カッコのつけ忘れに注意）。
• 引数を取る関数を呼び出す場合には、その引数も併せて記述します。
• 「読み上げが終了したタイミング」ではありません。

setRate

機能

合成される音声の速度を設定します。音声の速度を速く設定すると、早口言葉のようになります。デフォルト値は0に設定されています。

引数

音声の速度

-10(遅い)から10(速い)の21段階の値を整数で渡します。デフォルト値は0です。

戻り値

0

正しい値が設定された場合。

-102

無効な値が指定された場合。有効範囲外の値が指定されてもこのエラーは戻されません。-11以下の値が渡された場合は、-10として処理をします。同様に、11以上の値が渡された場合は、10として処理をします。

使用例

vds.setRate(-5);
vds.speak("ゆっくりとしゃべることができます。");

vds.setRate(5);
vds.speak("早口言葉も得意です。生麦、生米、生卵");

• 設定できる値は、整数です。
• しゃべっている途中で、音声の速度を変えることはできません。
• speakメソッドを呼ぶ前に、音声の速度を指定しておく必要があります。

setString

機能

読み上げる文字列を設定します。

引数

読み上げ文字列

読み上げの内容を引数に取ります。読み上げに使用できる言語は音声種別によってことなります。現在は日本語のみの対応です（一部の英単語はカタカナ読みで読み上げます）。

戻り値

0

正しい値が設定された場合。

-103

引数で渡された文字列が許可されている長さを超えている場合。

-105

引数で渡された文字列の長さが0の場合。

使用例

vds.setString("事前に文字列を設定できます");
vds.speak();

• 文字コードはvdsが自動認識して処理します。
• speakメソッドの前にsetStringで文字列を指定しておくことで、speakメソッドの引数を省略することができます。
• setStringで文字列を設定した後、speakメソッドを引数付きで呼び出すと、setStringで設定された値は破棄されます。

speak

機能

音声で読み上げを行うメソッド。

引数

読み上げ文字列（省略可能）

省略する場合は、setStringメソッドで事前に読み上げ文字列を設定しておきます。

戻り値

0

正常に読み上げのリクエストが受理された場合。

-103

読み上げ文字列が許可されている長さを超えた場合。

-105

読み上げ文字列が設定されていない場合。文字列が、スペースや改行コードなどのみの場合も、このエラーを返します。

getServerErrorによる戻り値

0

正常に読み上げのリクエストが受理された場合。

-301

1ヶ月あたりの再生文字数を超えたリクエストを受け付けた場合。

-501

セッションが失われた場合。

使用例

vds.speak("vdsは、音声配信するためのWebAPIです。");

vds.setString("vdsは、音声配信するためのWebAPIです。");
vds.speak();

• 文字コードはvdsが自動認識して処理します。
• 音声は、サーバで生成され配信されるため、speakメソッドを呼んでから実際に音声の再生が始まるまでには、若干のタイムラグが生じます。
• 連続してspeakメソッドを呼ぶ場合
  • speakメソッドが呼ばれると、読み上げ音声はvds Playerのキューに追加されます。キューの内容は自動的に再生処理にまわされます。複数回speakメソッドを呼んだ場合、先に呼ばれたspeakメソッドの音声から順に読み上げが行われます。
  • 先に呼んだspeakメソッドの音声読み上げが始まってから、次のspeakメソッドを呼ぶようにします。呼ばない場合、最初のspeakメソッドが無視されることがあります。
  • 音声読み上げが実際に始まっているかどうかは、VoiceDeliveryPlayerのisSpeakingメソッドで確認することができます。例えば、以下のようなコードを使うことで、タイミングをとることができます。

var waitId
vds.setString("vdsは、音声配信するためのWebAPIです。");
vds.speak();
waitId = setInterval("if(vdsp.isSpeaking()==1){
　　clearInterval(waitId);
　　vds.speak("この声は、2番目に読み上げられます。");
}" , 100);

• rubyタグについて（有償版のみ）rubyタグを指定するとrubyタグ中の rtタグの内容で文字列を読み上げます。

  このとき、読み上げ文字数はルビ（rtタグの内容）の文字数でカウントされます。

  固有名詞など特別な読み方をする文字に rubyタグを使用すると正しく読み上げることができます。

  rubyタグを使用しているサンプルは
  こちら

  (2009年12月1日機能追加)

getPan

機能

現在設定されている音声の左右バランスの値を取得します。

引数

なし

戻り値

バランスの数値

-10(左)から10(右)まで21段階

使用例

var panValue = vdsp.getPan();
if(panValue < 0){
    alert("左寄り");
} else if(panValue > 0){
    alert("右寄り");
} else {
    alert("まんなか");
}

• getPanメソッドの戻り値を基に、左右の音量バランス、つまり音声の定位が分かります。

getVolume

機能

現在設定されているボリュームの値を取得します。

引数

なし

戻り値

音量の数値

0(ミュート)から100までの設定が可能です。デフォルト値は1です。

使用例

var volValue = vdsp.getVolume();
if(volValue == 0){
    alert("注意：音量設定が0です。ミュートされています。")
}

• getValueメソッドを呼ぶことで、現在の音量が分かります。
• 上の例では、音量の値を基にユーザに警告を与えています。

isSpeaking

機能

音声の出力中であるか否かを調べるメソッド。

引数

なし

戻り値

出力の状態を表す数値

音声出力中(１)もしくは、停止中(０)

使用例

var waitId;
vds.speak("最初に読み上げます");
waitId = setInterval("if(vdsp.isSpeaking()==1){
    clearInterval(waitId);
    vds.speak("2番目に読み上げます");
}" , 100);

• speakメソッドを2つ続けて呼び出す場合、2番目のspeakメソッドの呼び出しは、音声読み上げが始まった後に行う必要があります。上の例では、isSpeakingメソッドをsetIntervalの中で使用してタイミングを計っています。

setPan

機能

左右のスピーカから出力される音声のバランスを設定します。

引数

バランスの数値

-10(左)から10(右)まで21段階の設定が可能です。-10より小さい値や、10より大きな値を設定しようとした場合、自動的に最小値-10、最大値10に設定されます。

戻り値

なし

使用例

var waitId;
vds.setCast("KeikoJPf");
vdsp.setPan(-10);
vds.speak("私は左から読み上げます。");
waitId = setInterval( "if(vdsp.isSpeaking()==1){
    clearInterval(waitId);
    vds.setCast('TakashiJPm');
    vdsp.setPan(10);
    vds.speak("私は右から読み上げます。");
}" , 100);

• 上の例では、「KeikoJPf」の音声を右から出力し、その後「TakashiJPm」の音声で右から出力します。
• タイミングの調整には、VoiceDeliveryオブジェクトのspeakメソッド紹介した方法を使っています。

setVolume

機能

出力音声の音量を調節するメソッド。

引数

音量の数値

0(ミュート)から100までの設定が可能です。デフォルト値は1です。

戻り値

なし

使用例

vdsp.setVolume(5);
vds.speak("大きな声で読み上げます。");

• 上の例では、ボリューム5で読み上げを行います。
• 10より大きな数値は、かなり大きな音に感じられますので注意が必要です。

speakPause

機能

音声出力の一時停止・再開するメソッド。トグルになっています。つまり、再生中には一時停止し、一時停止中には音声読み上げを再開します。

引数

なし

戻り値

なし

使用例

<input type="button" onclick="vdsp.speakPause()" />

• 上のようなコードで、一時停止ボタンを設置することができます。

vdsSpeakFinishCallback

機能

音声の読み上げが終了したタイミングで呼び出されるコールバック関数です。プログラム内にこの名前の関数があると、読み上げが終了したタイミングで呼び出されます。

引数

なし

戻り値

なし

使用例1

var vdsp;
var vds;

window.onload=function(){
 try{
   vdsp = new VoiceDeliveryPlayer("vdsp");
   vds = new VoiceDelivery(vdsp, "vds");
   vds.setRate(2);
 } catch(e) {
   alert("Cannot Create Object");
 }
}

function readOut(){
 text_current = 0;
 buf = (document.getElementById("readOutHere")).innerHTML;
 vds.speak(buf);
}

function vdsSpeakFinishCallback(){
 alert("今、読み終わりました");
}

• 読み上げさせたい文字列を「readOutHere」というid属性のついたブロックに用意しておきます。
• ボタンなど用意し、そのイベントハンドラに上記のreadOut関数を指定します。
• 読み上げが終了すると、この項目で紹介しているvdsSpeakFinishCallbackが呼び出されて、alertのダイアログが表示されます。

使用例2

このコールバック関数を使うと，読み上げの進行に合わせて、読み上げ部分を視覚的に示すようなことができるようになります。

• 使用例デモ
• 「read it」というボタンをクリックすると読み上げが始まります
• 読み上げ中の文の背景色が変化します。