$Revision: 1.20 $ ■ UkkPlayer (ukk2.0 ファイル) 仕様書（2001-05-09） Takuya Nishimoto (nishi@vox.dj.kit.ac.jp) この文書は UkkPlayer ファイル形式を定義する。 UkkPlayer 2.0 リリースにおける仕様が [ukk2.0] となる。 UkkPlayer は起動後にファイル名を指定してコンテンツを１行ずつ実行する。 起動時にファイル名が省略された場合は index.ukk が実行される。 ukk ファイルのサブディレクトリおよび絶対パスでの指定には対応していない。 ukk ファイルの第１行でファイル形式とバージョン番号(実数値)を示す。 例： #ukk2.0 UkkPlayer は自らのバージョン番号よりも大きいバージョンの ukk ファイルを実行しようと したとき（例えば UkkPlayer 2.0 が ukk2.1 ファイルを実行しようとしたとき）には エラーとなる。 ■ 各行の書式 ukk2.0 形式ファイルでは SHIFT-JIS コードを使用する。 改行コードは MS-DOS 形式である。 したがって、シナリオは「メモ帳」などで編集することができる。 ukk ファイルの各行は [コマンド][空白][内容] コマンド：半角１文字 空白：半角１文字 内容：行末まで で記述される。 コマンドはアルファベット１文字で表現され、大文字と小文字を区別する。 ■ コメント コマンド : # 書式 : # [コメント] ■ 巻き戻し／スキップ位置の指定 コマンド : * 書式 : * [コメント] ● 巻き戻しの詳細仕様 ESC を１秒以内に連続して２回押したときに、直前の * 行まで巻き戻しを行う。 このとき効果音 rew.wav を鳴らす。 ● スキップの詳細仕様 Enter を押すと直後の * 行まで早送りする。 このとき効果音 se1.wav を鳴らす。 ただし以下の場合にはスキップをしない。 (1) t/r コマンドの入力待ちの１文字目で Enter が正解である場合 その他の t/r コマンドと d コマンドはスキップする。 例： G それでは v \rabcd G と押してください。 t \rabcd (2) メニュー (c/m) の項目選択中 (3) 直後の * よりも前に 　　・メニュー (c/m) 　　・ジャンプ (j) 　　・ファイルの終了 　 のいずれかがある場合 ● 巻き戻し／早送りにおける点数計算の扱い ・巻き戻しによって同じ t/r 行が２回以上実行された場合は、その分だけ問題数が増える。 ・早送りによって t/r 行がスキップされた場合は、その分だけ問題数が減る。 ・早送りの結果として問題数が０になった場合には、成績は０となる。 ■ ガイドとプロンプト g ガイド [内容]をテキスト音声合成で読み上げる。 割り込み操作はできない。 G プロンプト [内容]をテキスト音声合成で読み上げる。 最後まで聞かなくてもキー操作ができる。 再生中のキー操作が Enter であれば、直後の * マークまでジャンプする。 その他のキーであれば、直後の入力待ちコマンドの第1文字とみなされる。 ● 例１ G 何かキーを押してください。 d 1 動作例 1. 音声出力：「何かキーを押してください。」 2. （キー入力が一定時間なかったのでタイムアウトになった） 3. 音声出力：「あと１回押してください。」（プロンプトを繰り返す） 4. [入力=a] 5. 音声出力：エー {正解ベル} 　　 ● 例２ 　　 g まずは左手の練習です。 　　 G Ｆを押してください。 　　 t f 　　 動作例 1. 音声出力：「まずは左手の練習です。」 2. 音声出力：「Ｆを押してください。」 3. [入力=a]（間違えた） 4. エラー効果音 5. 音声出力：「次に押すキーはＦです。」（プロンプトを繰り返す） 6. [入力=f] 7. 正解効果音 ただし、何回目のエラーでプロンプトを繰り返すかは、変更可能 (s promptcount) 　　 ● 例３ 　　 g 左手の練習を続けます。 　　 G ＦＧと続けて押してください。 　　 t fg 　　 動作例 1. 音声出力：「左手の練習を続けます。」 2. 音声出力：「ＦＧと続けて...」 3. [入力=f]（プロンプトの途中でＦを押した） 4. プロンプトがさえぎられてキーエコー「エフ」 5. （Ｇの入力待ちだが、わからなくなってタイムアウト） 6. 音声出力：「次に押すキーはＧです。」（プロンプトを繰り返す） 7. [入力=g] 8. 正解効果音 　　 ● 例４ 　　 g さらに左手の練習を続けます。 　　 G ＡＳと続けて押してください。 　　 P ganbare.wav 　　 t as 　　 動作例 1. 音声出力：「さらに左手の練習を続けます。」 2. 音声出力：「ＡＳと続けて...」 3. [入力=A]（Gプロンプトの途中でＡを押した） 4. 正解効果音（Pコマンドはスキップされる） ■ ポーズ コマンド : w 書式 : w [時間(ミリ秒)] ■ キー入力待ち t (test) [内容]を一文字ずつ入力させ、キーエコーと正解判定を行う。 例："t jkjkjkjk" t コマンドでの入力待ちのときに、 ・パラメータ timeout の値（ミリ秒）を超えて入力がなかったとき ・入力ミスの回数がパラメータ promptcount の値に達したとき のいずれかでプロンプト「次に押すキーは XXX」を出力する。 このとき XXX は key-echo フォルダの録音音声を使用する。 　 [内容] では以下のエスケープシーケンスに対応する \e ESC (27) \t tab (9) \r return (13) \b backspace (8) \\ backslash (92) \L カーソル左 \R カーソル右 \U カーソル上 \D カーソル下 \(0xnn) 数字でキーコードを指定する キーコードの一覧表は keycode.txt をみてください。 d (don't care) [内容]に半角数字で字数を指定し、その文字数だけキーエコーを行う。 正解判定などは行わない。 例："d 50" d コマンドでの入力待ちのときに、 パラメータ timeout の値（ミリ秒）を超えて入力がなかったとき 　　 「あとn回押してください」を繰り返す。 r (romaji) ローマ字入力用のキーエコーと正解判定を行う。 r コマンドでの入力待ちのときに、 ・パラメータ timeout の値（ミリ秒）を超えて入力がなかったとき ・入力ミスの回数がパラメータ promptcount の値に達したとき のいずれかでプロンプト「次に押すキーはXXX」を出力する。 このとき XXX は key-echo フォルダの録音音声を使用する。 [内容] 部分は下記の書式による。 [ローマ字表記][空白][読み] または [ローマ字表記][空白][読み][空白][ローマ字表記][空白][読み] ... ローマ字表記：１文字以上の半角英字 空白：半角１文字 読み：全角文字列 例："r ka か ki き ku く" この場合、ユーザの入力が k a である場合の動作例を示す。 1. [入力=k] 2. 音声出力：ケー 3. [入力=a] 4. 音声出力：か {正解ベル} 注意：以下の例１で g の再生中に Enter を押すと、t の先行入力ではなく スキップとなる。例２では t の先行入力となる。 例１： g 縦に長いキーを押してください。 t \r g よろしいですか。 * 例２： G 縦に長いキーを押してください。 t \r g よろしいですか。 * ■ 特殊キーの処理に関するまとめ ・ukp によるジャンプコマンド 割り込み禁止状態を含むすべての状態で有効。 Home で総合メニューに戻る機能は ukp ファイル定義により実現している。 ・ESC x 2（１秒以内） 割り込み禁止状態を含むすべての状態で有効。 処理中の ukk ファイルにおける直前の * マークに実行位置を戻す。 ・Enter 割り込み禁止状態を含むすべての状態で有効。 処理中の ukk ファイルにおける直後の * マークに実行位置を戻す。 ・Pause 割り込み禁止状態を含むすべての状態で有効。 処理中の行の実行を中断し「ポーズしました」と出力する。 任意のキーを押すことによってポーズは解除される。 このとき、ukp で定義された処理を行い、中断された行から実行を再開する。 注意：中断された行の次の行ではなく、その行を再度実行する。 ポーズ中には３０秒間隔でガイド音声を出力する。 ■ 録音音声によるガイドコマンド コマンド : v (小文字v) 書式1 : v [読み上げ文字列] 書式2 : v [読み上げ文字列][空白][読み上げ文字列] .... コマンド : V (大文字V) 書式1 : V [読み上げ文字列] 書式2 : V [読み上げ文字列][空白][読み上げ文字列] .... key-echo および kana フォルダに格納された音声ファイルを用いて ガイド音声の出力を行う。 書式2の場合は、文字列と文字列の間に半角空白１文字を入れる。 大文字 V と小文字 v の違いは、文字列の間のポーズ長と、 割り込み操作を許可するかどうかの違いである。 v : （小文字）長いポーズ (500ms)　割り込み操作を禁止 V : （大文字）短いポーズ (100ms)　割り込み操作を許可 大文字 V （割り込み操作を許可）の場合は、G, P コマンドと同様に、 再生中のキー操作が Enter であれば、直後の * マークまでジャンプする。 その他のキーであれば、直後の入力待ちコマンドの第1文字とみなされる。 例： v kya kya.wav V kya.wav nn.wav pa.wav su.wav 読み上げ文字列は以下のいずれかの形式である。 (1) key-echo 文字列 t コマンドの入力待ち文字列と同じ書式を使用する。例えば、 G それでは v abcd G と押してください。 t abcd これは以下と等価になる。 G それでは w 500 P key-echo\0650.wav w 500 P key-echo\0660.wav w 500 P key-echo\0670.wav w 500 P key-echo\0680.wav w 500 G と押してください。 t abcd (2) kana 文字列 末尾が .wav （wavは小文字）である文字列は kana フォルダのファイル名とみなす。 例えば、 G きゃ、Ｋ、Ｙ、Ａ r kya きゃ は以下のように書けば key-echo および kana フォルダを使用する。 v kya.wav kya r kya kya.wav ■ 音声ファイル再生 p (play sound) [内容] をファイル名として、音声ファイルを再生する。 割り込み操作を許さない。 P (prompt sound) [内容] をファイル名として、音声ファイルを再生する。 G, V コマンドと同様に、 再生中のキー操作が Enter であれば、直後の * マークまでジャンプする。 その他のキーであれば、直後の入力待ちコマンドの第1文字とみなされる。 e (error sound list) [内容] をファイル名のリスト（空白区切り）とみなして、 エラー時に鳴らす音声ファイルを指定する。 現在は、ランダムに選択するのではなく、リストの順番に再生し、 リストの最後のファイルを鳴らした次はリストの先頭に戻る。 ファイル名の指定方法は p と同様。 　 例：onesan-faul1.wav onesan-faul2.wav onesan-faul3.wav を使用する場合 e onesan-faul1 onesan-faul2 onesan-faul3 デフォルトで ukk-faul.wav 固定になり、 　 eコマンドで指定するとそのファイルを使用する ・ファイル名とファイル形式について ファイル名は ukk ファイルからの相対パス。拡張子は省略不可。 22.05KHz 16bit mono PCM 形式 Microsoft Wave ファイル .wav を使用。 ■ ジャンプ コマンド : j 書式 : j [相対ファイル名] jコマンドは無条件ジャンプである。 例：j file2.ukk ■ メニュー選択によるジャンプ コマンド : c 書式 : c [数字２桁の項目番号][空白][ファイル名][空白][項目名] 機能 : メニュー選択項目を宣言する コマンド : m 書式 : m [ショートカット文字][空白][待ち時間(1/1000秒単位)] 機能 : メニュー選択を実行する c/m コマンドはメニュー選択によるジャンプである。 c コマンドの第２引数として２桁の整数（項目番号）を指定できる。 項目名は末尾が .wav であれば音声ファイルの再生となり、 それ以外の文字列は合成音声による読み上げとなる。 操作方法は以下のいずれかである。 (1) 「カーソル上」と「カーソル下」で選択して Enter で決定 (2) ０から９の数字２桁で項目番号を入力して Enter で決定 　　１桁＋Enter の場合は上位の０が省略されたものとみなす。 ０１の内容を知りたいときは０１と押す。 その内容を実行したいときは続けて Enter キーを押せばよい。 取り消しについては、例えば０９を選ぶつもりで０８と押してしまったときは、 続けて ０９ Enter と押せばよい。 ファイル名のかわりに以下の記述が可能である。 next : m の次の行に処理を移す exit : UkkPlayer を終了する shutdown : システムを終了する（可能なら電源を切る） また、m コマンドに引数を書くことにより、2種類の動作を選択できる。 (a) 指定した時間を超えた場合に自動的に選択される項目を指定できる 書式： m [ショートカット文字][空白][待ち時間(1/1000秒単位)] 入力待ちの間になにか操作が行われると、計時はリセットされる。 つまり、入力待ちの開始から、または最後に操作されてから、 指定時間が経過した場合に、自動選択が行われる。 「入力待ちの開始」とは ・数字のキーエコー開始 ・m コマンドの開始 ・項目名の読み上げ開始 のうち、最後に行われたものが該当する。 指定時間が経過したときに選択候補が exit または shutdown であれば、 自動実行せず、何も選択されていない状態に戻して、 再度、指定時間だけ待つ。 (b) 指定した時間を超えた場合にプロンプトを出力する。 書式： m **[空白][待ち時間(1/1000秒単位)][空白][pまたはgコマンド] 例１： m ** 3000 p prompt.wav 例２： m ** 3000 g メニューを選んでください c および m コマンドの例を示す。 使用例1: G 次に進みますか？このレッスンを繰り返しますか？ c 01 next-lesson.ukk ゼロイチ、次のレッスンへ c 02 this-lesson.ukk ゼロニ、このレッスンを繰り返す c 03 next ゼロサン、続きを実行する m 02 10000 使用例2: G このレッスンを繰り返します。次に進みたければ10秒以内に1を押してください。 c 01 next-lesson.ukk ゼロイチ、次のレッスンへ c 02 this-lesson.ukk ゼロニ、このレッスンを繰り返す m ** 10000 g １または２を選んでください ■ メニューとマークの位置関係についての注意 P/G と m の間に * をおいてはいけない。 誤った例（P/G の再生中に１桁目の入力ができない）： P title-call\topmenu.wav * c 00 00-start.ukk menu\route00.wav c 01 01-function.ukk menu\route01.wav c 02 02-home_p.ukk menu\route02.wav c 03 03-left_h.ukk menu\route03.wav m ** 8000 g ルートを選んでください 望ましい例（スキップや巻き戻しの直後に topmenu.wav を聞ける）： * P title-call\topmenu.wav c 00 00-start.ukk menu\route00.wav c 01 01-function.ukk menu\route01.wav c 02 02-home_p.ukk menu\route02.wav c 03 03-left_h.ukk menu\route03.wav m ** 8000 g ルートを選んでください ■ キープレス・イベント定義ファイル keypress_event （別名 phonetic_echo ）パラメータを３にした場合に、 拡張子 ukp (Ukk Key Press) の外部ファイルを i コマンドで読み込むことによって、 キーを押されたときに特定のメッセージを読み上げたり、 特定の音声ファイルを再生したりすることができる。 シナリオにおける i コマンドの記述例： i fruits.ukp ukp ファイルは任意の行数のテキストファイルであり、 漢字コードや改行コードなどは ukk 形式と同じである。 各行の書式は次のとおり。 　書式: [入力待ちキー][空白][コマンド][空白][内容] [入力待ちキー] t/r コマンドと同じ表記で入力待ち文字を記述する。 アルファベットについては大文字と小文字を区別しない。 [コマンド] アルファベット1文字 g/p/j を記述する。 g → [内容] は読み上げる文字列。[内容] がさらに空白を含んでもよい。 p → [内容] は再生される音声ファイル名。 j → [内容] は無条件ジャンプの移動先ファイル名。 Key Press イベントによって音声ファイルを再生した場合には、 t/r コマンドでの正解・不正解の効果音ファイルは再生されない。 （この場合も判定処理は正しく行われる） d コマンドでの使用においては差し支えない。 fruits.ukp ファイルの記述例： a g エー、アップル b g ビー、バナナ c g シー、チェリー d p doughnuts.wav （途中は省略） x g エックス、エックスセン y g ワイ、ユバ z g ゼット、ザクロ \e g エスケープキーです。２回繰り返して押すと巻き戻します。 \(0xE5) g 全角半角。かな漢字変換のオン・オフができます。 \(0xF2) g かたかな・ひらがな。普通に押すとひらがな。シフトといっしょだとカタカナ。 ■ パラメータ設定 パラメータを設定するために s (セット) コマンドを用いる。 使用可能なパラメータは以下のとおり。 phonetic_echo : Key Press イベントにおける動作を指定する。 s phonetic_echo 0 標準キーエコー（例：エー） s phonetic_echo 1 標準キーエコーと標準フォネティック読み（例：エー、アメリカ） s phonetic_echo 2 キーエコーを一切行わない s phonetic_echo 3 i コマンドで読み込まれた ukp ファイルに従って動作する。 keypress_event : phonetic_echo 変数の別名。 promptcount : 次に押すキーを指示するまでに許すエラーの回数（初期値 3 ） s promptcount 3 ３回間違えたら「次に押すキーは…」を出力 prompttime : 次に押すキーを指示するまでの待ち時間　単位ミリ秒（初期値 3000 ） s prompttime 2000 correct_wav : 正解の効果音を鳴らすかを指定する（初期値 1 ） s correct_wav 1 正解の効果音を鳴らす s correct_wav 0 正解の効果音を鳴らさない error_wav : エラーの効果音を鳴らすかを指定する（初期値 1 ） s error_wav 1 エラーの効果音を鳴らす s error_wav 0 エラーの効果音を鳴らさない speed_offset : 読み上げスピードを相対的に変化させる。（初期値 0 ) s speed_offset -30 以降は -30 にする（遅くなる） s speed_offset 0 元に戻す s speed_offset 30 以降は +30 にする（速くなる） voice_prompt_long_wait/voice_prompt_short_wait v のポーズ: s voice_prompt_long_wait (単位ミリ秒 初期値500) V のポーズ: s voice_prompt_short_wait (単位ミリ秒 初期値100) 例： s voice_prompt_long_wait 500 s voice_prompt_short_wait 100 ■ スコア シナリオに y および z コマンドを埋め込むことによって、 スコアの集計と出力を行う。 y : スコア情報をリセットする z : スコア情報を音声および画面によって出力する シナリオ例: y g ABCDE を入力してください t abcde G あなたの成績は z G です。 計算方法は「一度で正解した数／問題数」 出力は、０から１００までの数字のみを合成音声で読み上げる。 内部的には以下の値を集計している（未使用）。 ・t/r コマンドでの問題数 ・１回目の操作での正解数 ・合計エラー回数 ・応答時間の平均 ・正解に所要した時間の平均 ■ 背景 b (background) は画像をデスクトップに表示する。 640x480 または同じ縦横比率の JPEG, GIF, BMP ファイルであること。 例：b photo\title.jpg なお、Ctrl-H を押すごとに、UkkPlayer は「背景あり」／「背景なし」の 実行モード切換が可能である。 「背景なし」実行モードは開発・デバッグのためのモードである。 ■ タイトル f (form title) はフォームのタイトルを変更するために使用する。 フォームタイトルの初期値は、UkkPlayer のプログラム名とバージョン番号である。 ■ 共通設定ファイル (config.ukk) ファイル config.ukk が存在する場合には、 ukk ファイルの読み込みに先だってその内容を実行する。 config.ukk で使用できるコマンドは "c", "e", "s", "i", "b", "f", "y", "#" である。その他の命令は無視される。 「ukk ファイルの読み込み」とは以下の場合である。 ・起動時の index.ukk の実行 ・メニューからファイルを開いた直後 ・コマンド j, m によるファイル移動 config.ukk ファイルの１行目にもバージョン情報 ("#ukk2.0"）が必要である。 [EOF]