「ST Emotion SDK（Win, Linux）」マニュアル

ST – Sensibility Technology
ST Emotion SDK API ガイド
AGI Inc.
2014.6.1
1
概要
ST Emotion SDK は、ST アプリケーションのコアとなる感情認識エンジンをライブラリ化
したものです。感情認識エンジンは、音声に含まれる感情要素を音響的に分析し、
「怒り」
「喜び」「哀しみ」「平常」「興奮」の 5 つの感情状態をそれぞれ推定します。
本資料では、ST Emotion SDK の API について解説します。
バージョン
2007.1.26 第一版
2014.6.1 第二版
2
目次
１．用語の解説
-1-
２．API 呼び出し方法
-2-
３．API 解説
-4-
3.1 CSTEmotion::CSTEmotion コンストラクタ
-5-
~
3.2 CSTEmotion:: CSTEmotion デストラクタ
-5-
3.3 CSTEmotion::initialize , 感情認識エンジンの初期化
-6-
3.4 CSTEmotion::finish , 感情認識エンジンの終了
-7-
3.5 CSTEmotion::changeAlgorithm , 感情判定ロジックを切り替える
-8-
3.6 CSTEmotion::startEngine16 , 感情認識エンジンに wave データを渡して解
-9-
析を行う
3.7 CSTEmotion::isEmotion , 指定した感情がどの程度の確度で含まれていたか
- 10 -
を取得する
3.8 CSTEmotion::getEmotion , 推定した第一候補感情の感情種類を取得する
- 11 -
3.9 CSTEmotion::getEmotionLevel , 推定した第一候補感情の確度を取得する - 12 3.10 CSTEmotion::getExcitementLevel , 推定した興奮度合いを取得する
- 13 -
3.11 CSTEmotion::getSex , 推定した性別を取得する
- 14 -
3.12 CSTEmotion::getLicenseCode , ライセンスコード情報を取得する
- 15 -
3.13 CSTEmotion::getExpireLimit , ライセンス有効期限までの日数を取得する- 16 3.14 CSTEmotion::getVersion , ライブラリのバージョン情報を取得する
- 17 -
3.15 CSTEmotion::getDate , コンパイル日を取得する
- 18 -
４．ライセンス
- 19 -
５．備考
- 20 -
付録．プログラム例
- 21 -
3
１．用語の解説
ST および ST Emotion SDK に関連する用語について解説します。
ST
Sensibility Technology 感性制御技術の略称。心理的、感性的な分野を定量的に扱
う技術の総称。相手の感情を感知する「認識」
、自らが自発的に感情を生み出す「創
発」、周囲の状況や自らの感情を総括し決定する「判断」などに大きく分類すること
ができる。
ST Emotion SDK は、このうち「認識」に含まれる、音声からの感情認識を行うエ
ンジンを提供する。
ST アプリケーション
ST によって提供される技術を使用し、感情、感性、心理にかかわる機能を実現し
たアプリケーション
感情認識エンジン
音声を解析し、感情状態を推定するプログラム部分
-1-
２．API 呼び出し方法
感情認識エンジンに音声データ（PCM WAVE 形式、11025Hz、Mono）を渡すと、音
声信号処理を通じて感情分析を行います。
データ形式は PCM WAVE フォーマットを前提としております。WAVE ファイルなど
はヘッダ情報が含まれているため、ファイルのデータをそのまま渡すと解析誤りが発
生します。ヘッダ情報を除いた上で音声部分のデータを渡すようにしてください。
音声データは、感情認識を行う音声の開始から終了までの一括データです。例えば
「なにいってんだ、このやろー」や「へー、そうなんだ！？」のような発話単位のデ
ータになります。複数の発話が連続している音声データや、多人数の発話が混ざって
いる音声データを分析しても、感情認識エンジンではそれが 1 個の発話なのか、連続
発話なのか、複数人音声なのかを区別せずに、すべて１個の発話とみなして解析を行
います。
また、音割れしている音声データを入力した場合、感情認識エンジンは十分な能力
を発揮することができません。入力音声を録音する際、音割れしないように音量調節
を行ってください。
感情認識エンジンの使用は、以下のような手順で行います。
1)
CSTEmotion::initialize()を呼び出して初期化を行います。CSTEmotion::initialize()は
内部でライセンス認証を行い、エンジンをメモリ上に準備します。
2)
認識したい音声データを用意し、CSTEmotion::startEngine16()を呼び出します。こ
れにより、音声データの分析を行うことができます。
3)
分析した結果の取得には、CSTEmotion::isEmotion()や CSTEmotion::getEmotion()を
使用します。感情認識エンジンは複数の感情の検出を同時に行います。検出した
各感情が音声に含まれているかを知るためには、CSTEmotion::isEmotion()を使用し
ます。複数検出された感情のうち、どれか一つの感情に絞り込みたい場合には、
CSTEmotion::getEmotion()を使用します。この関数により、第一候補感情を取得す
ることができます。
4)
次の音声の感情分析を行うためには、再度分析したい音声（＝次の音声）を用意
し、CSTEmotion::startEngine16()を呼び出します。
5) 音声の分析を終了するには、CSTEmotion::finish()を呼び出します。
-2-
API を呼び出す流れ
感情認識エンジン初期化
ライセンス認証
CSTEmotion::initialize()
解析アルゴリズムの選択
（省略可能）
CSTEmotion::changeAlgorithm()
音声データ解析
CSTEmotion::startEngine16()
音声データ
各種解析結果の取得
認識感情取得
第一候補感情取得
CSTEmotion::isEmotion( )
CSTEmotion::getEmotion( )
第一候補感情の確度の取得
推定性別取得
CSTEmotion::getEmotionLevel( )
CSTEmotion::getSex ( )
興奮度取得
CSTEmotion::getExcitementLevel( )
発話ごとにこのフェーズを繰り返す
感情認識エンジンの終了
CSTEmotion::finish()
-3-
３．API 解説
このセクションでは、感情認識エンジンクラスである CSTEmotion クラスを解説し
ます。このクラスの使い方については添付のプログラム例を参考にしてください。
-4-
3.1 CSTEmotion::CSTEmotion コンストラクタ
CSTEmotion::CSTEmotion(
void
);
コンストラクタで行っている動作はありません。全ての初期化は
CSTEmotion::initialize()にて行われます。感情認識エンジンを使う前には必ず initialize()
をコールして下さい。
~
3.2 CSTEmotion:: CSTEmotion デストラクタ
~
CSTEmotion:: CSTEmotion(
);
デストラクタでは CSTEmotion::finish()を呼び出しています。メモリ開放はこの finish()
にて行います。
-5-
3.3 CSTEmotion::initialize , 感情認識エンジンの初期化
int CSTEmotion::initialize(
int ver = ST_EMOTION_CURRENT_VERSION
);
感情認識エンジンを初期化します。すでに感情認識エンジンの実体が確保されていた場
合には、これを開放して、再度感情認識エンジンをメモリ上に確保します。
感情認識エンジンは CSTEmotion::startEngine16 によって音声サイズに応じたメモリ
が消費されます。
引数には ST_EMOTION_CURRENT_VERSION を与えます。これはデフォルト引数
となっているので、引数無しで呼び出すことも可能です。initialize()を呼び出した時に、
ライブラリバージョンのチェックが行われます。ヘッダファイル STEmotion.h に記載さ
れている ST_EMOTION_CURRENT_VERSION と、ライブラリのバージョン番号が異
なっている場合、感情認識エンジンは初期化されず、戻り値は 0 となります。
初期化時はライセンスチェックも行われます。ライセンスが無効の場合には戻り値は 0
以下の値となります。
戻り値は以下の表に示す値となります。
戻り値
意味
1
正常に初期化
0
DLL/LIB バージョンが異なる
-1
ライセンスファイルが見つからない
-2
ライセンスが失効している、または無効
-3
ライセンスの MAC アドレスが無効
ライセンスの日付に関するより詳細な情報を得るためには、getExpireLimit()を使用し
ます。
ライセンスのバージョン情報を取得する場合は、getVersion()を使用します。
-6-
3.4 CSTEmotion::finish , 感情認識エンジンの終了
void CSTEmotion::finish(
void
);
感情認識エンジンの使用の終了を宣言します。CSTEmotion::startEngine16()にて確保
されたメモリを開放し、感情認識エンジンの実体を開放します。そのため finish()を呼び
出した後は、感情認識エンジンの呼び出しを行うことはできません。
-7-
3.5 CSTEmotion::changeAlgorithm , 感情判定ロジックを切り替える
int CSTEmotion::changeAlgorithm(
int type
// ロジック番号
);
認識に使用する感情判定ロジックの切り替えを行います。感情認識エンジンは、内部に
２種類の感情判定ロジックを含んでおり、用途に合わせて感情判定ロジックを選択するこ
とが可能です。
ロジック番号とその特徴は以下の表のようになります。
ロジック番号
ロジックの特徴
0
デフォルトの感情判定ロジック
0 と比較し、より微細な感情を認識す
1
るロジック。相対的に平常となる率
が低くなります。
通常は 0 番を使用しますが、強い感情が表に出ていない音声は平常と認識する特徴があ
ります。一方、１番は弱い感情でも認識することができますが、平常のつもりで発話した
音声の場合でも、他の感情を認識してしまう場合があります。これらは、感情認識エンジ
ンを利用する用途に合わせて選択するようにしてください。
changeAlgorithm()を呼び出さない場合には、デフォルトでロジック番号 0 の感情判定
ロジックが使用されます。
ロジック番号に不正な値を入れた場合や、感情認識エンジンが初期化されていない場合
には実行に失敗し、戻り値は 0 となります。
戻り値は以下の表の通りです。
戻り値
意味
0
実行に失敗
1
正常に実行
-8-
3.6 CSTEmotion::startEngine16 , 感情認識エンジンに wave データを渡して解析を
行う
int CSTEmotion::startEngine16(
short *data,
// データ実体へのポインタ
int datasize
// データサイズ
);
Wave フォーマット(PCM WAVE 11025Hz 16bit)である data から始まる音声データを
解析し、感情状態を推定します。datasize はバイト数ではなく、short 型のデータがいく
つあるかという意味となります。
音声の解析には、音声波形が最低 50 ミリ秒必要です。最長値への制限はありませんが、
10 秒程度を目安としています。（一発話の長さは 1～3 秒程度が一般的といえます）
推定した感情結果は、CSTEmotion::getEmotion()などを通じて取得します。
音声波形があまりに短い場合、分析不可能になり解析に失敗します。
戻り値は以下の表の通りです。
戻り値
意味
0
解析に失敗
1
正常に実行
-9-
3.7 CSTEmotion::isEmotion , 指定した感情がどの程度の確度で含まれていたかを取
得する
int CSTEmotion::isEmotion(
STEmotion_Enum emot
);
分析した音声に、指定した感情 emot が含まれていたかどうかを調べます。emot の値と
感情については、以下の表に示す通りです。
指定感情値
意味
STE_CALM (1)
平常
STE_ANGER (2)
怒り
STE_JOY (3)
喜び
STE_SORROW (4)
哀しみ
isEmotion()では個別の感情について確度を知ることができます。最も確度が高い第一候
補感情を調べるためには getEmotion()を使用します。
戻り値は、0(含まれていない)から 10（確実）の範囲の整数値を返します。分析に失敗
した場合は、すべての emot の値に対して 0 を返します。
- 10 -
3.8 CSTEmotion::getEmotion , 推定した第一候補感情の感情種類を取得する
STEmotion_Enum CSTEmotion::getEmotion(
void
);
分析した音声に含まれる最も確度の高い感情を第一候補感情として返します。感情認識
エンジンは複数の感情を同時に検出しますが、そのうちの一つだけが必要である場合に使
用します。戻り値は感情の種類を表す値で、以下の表に示す通りです。
指定感情値
意味
STE_UNKNOWN (0)
不明または分析失敗
STE_CALM (1)
平常
STE_ANGER (2)
怒り
STE_JOY (3)
喜び
STE_SORROW (4)
哀しみ
- 11 -
3.9 CSTEmotion::getEmotionLevel , 推定した第一候補感情の確度を取得する
int CSTEmotion::getEmotionLevel(
void
);
分析した音声に含まれる最も確度の高い第一候補感情の確度（最大 10）を返します。分
析に失敗した場合には 0 を返します。
※ ST_SDK ver2.0 からの変更について
ST_SDK ver2.0 においては、getEmotionLevel()は興奮度を取得するために
使用されておりましたが、第一候補感情の確度を取得する関数に変更となり
ました。興奮度を取得するためには、getExcitementLevel()をご使用くださ
い。
- 12 -
3.10 CSTEmotion::getExcitementLevel , 推定した興奮度合いを取得する
int CSTEmotion::getExcitmentLevel(
void
);
分析した音声に含まれる興奮度合いを 1（興奮していない）～10（非常に興奮している）
の整数値で返します。分析に失敗した場合には 0 を返します。
- 13 -
3.11 CSTEmotion::getSex , 推定した性別を取得する
STSex_Enum CSTEmotion::getSex(
void
);
音声から性別を判定します。戻り値は性別とその確度に対応し、以下の表のいずれかを
返します。
戻り値
意味
STE_UNKNOWN_SEX (0)
不明
STE_MALE1 (1)
男性（確度低）
STE_MALE2 (2)
男性（確度中）
STE_MALE3 (3)
男性（確度高）
STE_FEMALE1 (4)
女性（確度低）
STE_FEMALE2 (5)
女性（確度中）
STE_FEMALE3 (6)
女性（確度高）
- 14 -
3.12 CSTEmotion::getLicenseCode , ライセンスコード情報を取得する
unsigned char *CSTEmotion::getLicenceCode(
void
);
ライセンスファイルから読み込んだライセンスコード文字列へのポインタを返します。
文字列の末尾は’¥0’でターミネートされています。
- 15 -
3.13 CSTEmotion::getExpireLimit , ライセンス有効期限までの日数を取得する
int CSTEmotion::getExpireLimit(
void
);
ライセンス有効期限までの日数を取得します。戻り値が 0 の場合、その日の 23 時 59 分
でライセンスが失効するという意味になります。ライセンス有効期限が過ぎていると、過
ぎている日数を負の値で返します。
無期限ライセンスの場合、100000 を返します。ライセンスが無効の場合、またはライ
センスファイルが存在していない場合は-100000 を返します。
- 16 -
3.14 CSTEmotion::getVersion , ライブラリのバージョン情報を取得する
long CSTEmotion::getVersion(
void
);
ライブラリがコンパイルされた時点でのバージョン情報を取得します。ヘッダファイル
STEmotion.h の ST_EMOTION_CURRENT_VERSION と、getVersion()で取得できる値
が異なっている場合、initialize()を呼び出した際に初期化に失敗します。
- 17 -
3.15 CSTEmotion::getDate , コンパイル日を取得する
const char *CSTEmotion::getDate(
void
);
ST Emotion SDK ライブラリがコンパイルされた日付を取得します。戻り値は文字列へ
のポインタです。このポインタは static クラス変数なので、解放しないで下さい。
- 18 -
４．ライセンス
ST Emotion SDK ライブラリにはライセンスシステムが組み込まれています。有効期
限と MAC アドレスをベースにした以下のようなライセンスコードが発行されます。
uo08CBWuYsT3cNr6SE6rYH8Ub7YetrEZ9T15TKC1paEW
WNcRLUmcXGLFN2Tdv0jcuKjXjMSgrgRxfTrwUHwrTm40
（実際には一行です。このコードは例であり、有効なものではありません）
このライセンスコードを STEmotion.lic ファイルに記録し、作成したアプリケーショ
ンと同一のフォルダ、Windows の System32 フォルダ、ルートフォルダのいずれかに配
置することで、ST Emotion SDK ライブラリは動作します。STEmotion.lic が複数のフォ
ルダにある場合は、アプリケーションと同一のフォルダ＞ Windows の System32 フォ
ルダ＞ルートフォルダの優先順位でライセンスファイルが使用されます。
ライセンスが無い、あるいは無効になった状態では、ST Emotion SDK ライブラリは
正常に動作しません。使用上の動作は不定となっていますが、実際には isEmotion()は
全ての感情で 0 が返り、getEmotion()では STE_UNKNOWN が返ります。
- 19 -
５．備考
雑音が多い環境では、発話の開始や終了の検出、パラメータ計算に失敗しやすくな
ります。特に突発的な雑音が音声に混入すると検出誤りを起こし、誤認識しやすくな
ります。
現バージョンでは、音声データの渡し方として「フレーム単位」をサポートしてい
ません。フレーム単位とは、例えば 100 ミリ秒毎の音声、のような細切れのデータ単
位です。また、音声データの渡し方としてはポインタ渡しのみとなっています。
STEmotion.lib、STEmotion.dll は内部的に STL::vector を使用しております。
- 20 -
付録．プログラム例
ST Emotion SDK の API を用いたサンプルプログラムを示します。ここでは別途読み
込んだ wave ファイルデータを変数 data、datasize にセットし、感情認識エンジンを呼び
出しています。このプログラムは SDK 添付されている、st3sample.cpp から一部を抜粋
したものです。
// st3sample.cpp ST Emotion SDK 動作テスト用プログラム
// copyright 2006, AGI Inc.
// ALL RIGHT RESERVED
#include “STEmotion.h”
int main (int argc, char *argv[]) {
int ret;
CSTEmotion *pTest = new CSTEmotion; //CSTEmotion クラス作成
ret = pTest->initialize(); //感情認識エンジンの初期化
// wave データを読み込む
ret = pTest->startEngine16(wave データへのポインタ,データサイズ);
// 感情認識エンジンに wav データを渡し、解析する
int ang = pTest->isEmotion(STE_ANGER); // 怒り確度の取得
int joy = pTest->isEmotion(STE_JOY); // 喜び確度の取得
int srw = pTest->isEmotion(STE_SORROW); // 哀しみ確度の取得
int clm = pTest->isEmotion(STE_CALM); // 平常確度の取得
int emo = pTest->getEmotion(); // 第一候補感情の取得
int lev = pTest->getEmotionLevel(); // 第一候補感情の確度の取得
int ext = pTest->getExcitementLevel(); // 興奮度の取得
char *emostr[] = {“UNK”,”CLM”,” ANG”,” JOY”,”SRW”,”LAUGH”,};
printf(“ ANG:%d JOY:%d SRW:%d CLM:%d LAU:%d EMO:%d(%s)
LEV:%d EXT:%d¥n”, ang, joy, srw, clm, lau, emo, emostr[emo], lev,
ext);
pTest->finish(); //感情認識エンジンの終了
delete pTest; //CSTEmotion クラスの解放
return 0;
}
- 21 -

Download Report