감정 분석
개요
감정 분석이란
감정 분석이란 음성에서 화자의 감정을 분석하여 출력하는 기능입니다. AmiVoice API는 ES Japan사의 ESAS (Emotional Signature Analysis Solution) 감정 분석 엔진을 사용하여 음성에서 감정 파라미터를 반환합니다. ESAS는 이스라엘의 Nemesysco사가 제공하는 최신 감정 분석 엔진 "LVA7"을 기반으로 일본 환경에 맞게 튜닝한 감정 분석 엔진입니다. 기술적 배경에 대해서는 ES Japan사의 웹사이트를 참조하십시오.
API에 대하여
AmiVoice API에서는 음성 인식 요청 시 옵션 파라미터 sentimentAnalysis
를 True
로 설정하여 ESAS가 출력하는 감정 파라미터를 얻을 수 있습니다. ESAS가 발화로 판단한 음성 구간에 대해 약 2초에 1번, 20개의 감정 파라미터 배열을 출력합니다.
결과는 응답의 sentiment_analysis
에서 얻을 수 있습니다.
"sentiment_analysis": {
"segments": [
{
"starttime": 10,
"endtime": 20,
/* 감정 파라미터 */
},
{
"starttime": 100,
"endtime": 200,
/* 감정 파라미터 */
},
/* 생략 */
]
},
감정 파라미터에 대해서는 후술할 감정 파라미터 목록이나 감정 파라미터의 의미와 해석 방법을 참조하십시오. 또한, 응답 중 파라미터 이름은 API를 사용하여 가져올 수 있습니다.
감정 분석은 비동기 HTTP 인터페이스에서만 지원됩니다.
사용 방법
요청
감정 파라미터를 얻으려면 음성 인식 요청 시 d
파라미터에 sentimentAnalysis=True
를 설정합니다.
예를 들어, 감정 분석을 사용하지 않는 경우 AmiVoice API 샘플 프로그램에 포함된 음성을 curl 명령을 사용하여 범용 엔진으로 음성 인식하는 경우 다음과 같이 명령을 실행합니다.
curl https://acp-api-async.amivoice.com/v1/recognitions \
-F d="grammarFileNames=-a-general" \
-F u={APP_KEY} \
-F a=@test.wav
감정 분석 기능을 활성화하려면 다음과 같이 변경합니다.
curl https://acp-api-async.amivoice.com/v1/recognitions \
-F d="grammarFileNames=-a-general sentimentAnalysis=True" \
-F u={APP_KEY} \
-F a=@test.wav
응답
요청이 성공하면 결과를 얻을 때까지 작업 상태를 정기적으로 확인하십시오. 자세한 내용은 비동기 HTTP 인터페이스의 "2. 음성 인식 작업 상태 확인 및 결과 가져오기"를 참조하십시오.
다음은 감정 분석 기능을 활성화했을 때의 결과 응답에 대해 설명합니다.
성공 시
감정 분석 결과는 sentiment_analysis
에서 얻을 수 있습니다.
감정 분석 엔진이 발화로 판단한 음성에 대해 약 2초에 1번, 20개의 감정 파라미터를 출력합니다. sentiment_analysis.segments
에는 이 감정 파라미터가 시간순으로 배열로 제공됩니다. 각 요소에는 음성의 시작 시간을 0으로 한 밀리초 단위의 상대적인 시간 정보로 시작 시간(starttime
), 종료 시간(endtime
)과 해당 시간에 대응하는 감정 파라미터가 있습니다.
응답 예:
{
"audio_md5": "40f59fe5fc7745c33b33af44be43f6ad",
"audio_size": 306980,
"code": "",
"message": "",
"segments": [
{
"results": [
{
"confidence": 0.998,
"endtime": 8794,
"rulename": "",
"starttime": 250,
"tags": [],
"text": "アドバンスト・メディアは、人と機械との自然なコミュニケーションを実現し、豊かな未来を創造していくことを目指します。",
"tokens": [
{
"confidence": 1,
"endtime": 1578,
"spoken": "あどばんすとめでぃあ",
"starttime": 522,
"written": "アドバンスト・メディア"
},
{
"confidence": 1,
"endtime": 1834,
"spoken": "は",
"starttime": 1578,
"written": "は"
},
/* 생략 */
]
}
],
"text": "アドバンスト・メディアは、人と機械との自然なコミュニケーションを実現し、豊かな未来を創造していくことを目指します。"
}
],
"sentiment_analysis": {
"segments": [
{
"starttime": 10,
"endtime": 20,
/* 감정 파라미터 */
},
{
"starttime": 100,
"endtime": 200,
/* 감정 파라미터 */
},
/* 생략 */
]
},
"service_id": "user01",
"session_id": "018160cbe43f0a304474a999",
"status": "completed",
"text": "アドバンスト・メディアは、人と機械との自然なコミュニケーションを実現し、豊かな未来を創造していくことを目指します。",
"utteranceid": "20220614/15/018160cc54ee0a3044b539d0_20220614_150012"
}
감정 분석 결과가 비어 있을 때
감정을 분석하기에 충분한 길이의 음성이 없는 경우 다음과 같이 sentiment_analysis
의 segments
가 빈 배열이 됩니다.
sentiment_analysis": {
"segments": []
}
전송한 데이터에 음성이 포함되어 있지 않거나 음량이 너무 작아 감정 분석 처리 대상이 되지 않은 것으로 생각됩니다. 전송한 데이터의 음량을 확인하십시오.
예를 들어, Audacity와 같은 음량을 파형으로 표시할 수 있는 애플리케이션을 사용하여 음량을 확인할 수 있습니다. 다음은 음량 레벨이 너무 낮은 예입니다. 신호의 최대값을 1로 한 스케일에서 대략 0.05에 해당하는 음량 레벨을 보여주고 있지만, 조금 더 크게 해야 합니다. 예를 들어, 0.1을 초과하는 정도를 목표로 녹음 볼륨을 조정하십시오.
실패 시
어떤 이유로 감정 분석 처리에 실패한 경우 sentiment_analysis
에 다음과 같이 code
, error_code
, error_message
가 설정됩니다.
예:
"sentiment_analysis":{"code":400,"error_code":"BAD_REQUEST","error_message":"file format is invalid"}
오류 시 응답 목록
오류 시 응답은 다음 표와 같습니다.
code | error_code | error_message | 설명 |
---|---|---|---|
400 | BAD_REQUEST | file format is invalid | 음성 파일이 존재하지 않거나 형식이 잘못됨 |
500 | INTERNAL_SERVER_ERROR | internal server error has occurred | 내부 서버 오류 |
INTERNAL_SERVER_ERROR | internal server error has occurred before processing sentiment-analyzer | 내부 서버 오류 |
감정 파라미터 목록 가져오기
응답에 포함된 20개의 감정 파라미터 목록은 https://acp-dsrpp.amivoice.com/v1/sentiment-analysis/ja/result-parameters.json
에 GET
요청을 보내 가져올 수 있습니다.
예:
$ curl -H "Authorization: Bearer {APPKEY}" \
https://acp-dsrpp.amivoice.com/v1/sentiment-analysis/ja/result-parameters.json
이 API의 자세한 내용은 참조의 감정 분석 API를 참조하십시오. 감정 파라미터의 의미는 이후 장에서 설명합니다.