긴 음성 파일의 텍스트 변환
회의나 강연 연설, 콜센터 통화 녹음 등의 긴 음성을 텍스트로 변환할 때 API의 사용 방법을 단계별로 설명합니다. 이 튜토리얼에서는 프로그램을 작성하는 대신 curl
명령어와 jq
명령어를 사용하여 설명합니다.
준비
이 튜토리얼을 실행하기 위해서는 다음이 필요합니다.
- curl
- jq
- AmiVoice API에 등록하고
APPKEY
를 취득하기 - 텍스트로 변환하고 싶은 음성 파일 준비하기
결과를 보기 좋게 정리하기 위해 jq
명령어를 사용합니다. jq
가 설치되어 있지 않아도 이후의 튜토리얼에서 음성을 텍스트로 변환할 수 있으므로 설치하지 않고 진행해도 괜찮습니다.
curl
사용 중인 시스템에 curl
명령어가 설치되어 있는지 확인하십시오.
curl -V
버전이 표시되지 않는 경우, https://curl.se/에서 사용 중인 OS의 패키지를 다운로드하거나 패키지 매니저를 사용하여 curl
을 설치하십시오.
jq
사용 중인 시스템에 jq
명령어가 설치되어 있는지 확인하십시오.
jq -V
버전이 표시되지 않는 경우, https://stedolan.github.io/jq/에서 사용 중인 OS의 패키지를 다운로드하거나 패키지 매니저를 사용하여 jq
를 설치하십시오.
APPKEY 취득
- AmiVoice API에 등록합니다.
- 마이페이지에 로그인하여 [接続情報] 탭의 [共通接続情報]에 기재된 APPKEY를 기록해 둡니다.
AmiVoice Tech Blog에서 APPKEY
를 취득하는 과정을 자세히 설명하고 있습니다. APPKEY
취득에 대해서는 AmiVoice API 사용해보기도 참조하십시오.
음성 파일
텍스트로 변환하고 싶은 음성 파일을 준비합니다.
여기서는 클라이언트 라이브러리의 샘플 프로그램에 포함된 음성 파일 test.wav
를 사용합니다.
- 음성 파일을 준비할 때, 지원되는 음성 파일 형식에 주의하십시오. 지원 형식은 음성 형식에 대하여를 참조하십시오.
- 수용 가능한 음성 파일의 길이에는 제한이 있습니다. 제한 사항을 참조하십시오.
실행
1. 음성 인식 요청
음성 인식 요청 시 지정하는 파라미터는 동기 HTTP 인터페이스와 완전히 동일합니다.
curl https://acp-api-async.amivoice.com/v1/recognitions \
-F d=-a-general \
-F u={APP_KEY} \
-F a=@test.wav
요청이 성공하면 다음과 같은 응답을 받습니다. 요청은 작업으로 큐에 들어가 순차적으로 처리됩니다.
{"sessionid":"017c25ec12c00a304474a999","text":"..."}
2. 작업 상태와 결과 가져오기
요청으로 얻은 sessionid
를 사용하여 작업 상태(status
)나 결과를 얻을 수 있습니다. 음성 인식 결과를 얻을 때까지 여러 번 실행하게 됩니다. {APPKEY}
는 Authorization 헤더
에 지정하십시오.
curl -H "Authorization: Bearer {APPKEY}" \
https://acp-api-async.amivoice.com/v1/recognitions/017c25ec12c00a304474a999
요청을 보낸 직후의 status
는 queued
상태가 됩니다.
{"service_id":"{YOUR_SERVICE_ID}","session_id":"017c25ec12c00a304474a999","status":"queued"}
큐에서 작업이 꺼내지면 status
는 started
상태가 됩니다.
{"service_id":"{YOUR_SERVICE_ID}","session_id":"017c25ec12c00a304474a999","status":"started"}
실제로 음성 인식 처리가 시작되면 status
는 processing
상태가 됩니다. API가 받은 음성의 크기나 MD5 체크섬을 사용하여 전송한 음성이 올바르게 처리되고 있는지 확인할 수 있습니다. processing
상태에 걸리는 시간은 음성의 길이에 따릅니다.
{'audio_md5': '40f59fe5fc7745c33b33af44be43f6ad', 'audio_size': 306980, 'service_id': '{YOUR_SERVICE_ID}', 'session_id': '017c25ec12c00a304474a999', 'status': 'processing'}
결과
음성 인식이 완료되면 status
는 completed
상태가 됩니다. 이때 results
에서 음성 인식 결과를 얻을 수 있습니다. 결과를 보기 좋게 정리하기 위해 jq
명령어를 사용합니다.
curl -H "Authorization: Bearer {APPKEY}" \
https://acp-api-async.amivoice.com/v1/recognitions/017c25ec12c00a304474a999 | jq
다음은 응답의 완전한 예입니다. 텍스트로 변환한 결과뿐만 아니라 단어 단위의 결과나 음성 시간, 신뢰도 등의 정보도 얻을 수 있습니다. 자세한 내용은 음성 인식 결과를 참조하십시오.
レスポンス
{
"audio_md5": "40f59fe5fc7745c33b33af44be43f6ad",
"audio_size": 306980,
"results": {
"code": "",
"message": "",
"segments": [
{
"code": "",
"message": "",
"results": [
{
"confidence": 1.0,
"endtime": 8778,
"rulename": "",
"starttime": 250,
"tags": [],
"text": "アドバンスト・メディアは、人と機械等の自然なコミュニケーションを実現し、豊かな未来を創造していくことをめざします。",
"tokens": [
{
"confidence": 1.0,
"endtime": 1578,
"spoken": "あどばんすとめでぃあ",
"starttime": 570,
"written": "アドバンスト・メディア"
},
{
"confidence": 1.0,
"endtime": 1850,
"spoken": "は",
"starttime": 1578,
"written": "は"
},
{
"confidence": 0.77,
"endtime": 2010,
"spoken": "_",
"starttime": 1850,
"written": "、"
},
{
"confidence": 1.0,
"endtime": 2314,
"spoken": "ひと",
"starttime": 2010,
"written": "人"
},
{
"confidence": 1.0,
"endtime": 2426,
"spoken": "と",
"starttime": 2314,
"written": "と"
},
{
"confidence": 1.0,
"endtime": 2826,
"spoken": "きかい",
"starttime": 2426,
"written": "機械"
},
{
"confidence": 0.76,
"endtime": 2922,
"spoken": "とう",
"starttime": 2826,
"written": "等"
},
{
"confidence": 1.0,
"endtime": 3082,
"spoken": "の",
"starttime": 2922,
"written": "の"
},
{
"confidence": 1.0,
"endtime": 3434,
"spoken": "しぜん",
"starttime": 3082,
"written": "自然"
},
{
"confidence": 1.0,
"endtime": 3530,
"spoken": "な",
"starttime": 3434,
"written": "な"
},
{
"confidence": 1.0,
"endtime": 4362,
"spoken": "こみゅにけーしょん",
"starttime": 3530,
"written": "コミュニケーション"
},
{
"confidence": 1.0,
"endtime": 4442,
"spoken": "を",
"starttime": 4362,
"written": "を"
},
{
"confidence": 1.0,
"endtime": 4906,
"spoken": "じつげん",
"starttime": 4442,
"written": "実現"
},
{
"confidence": 1.0,
"endtime": 5242,
"spoken": "し",
"starttime": 4906,
"written": "し"
},
{
"confidence": 0.83,
"endtime": 5642,
"spoken": "_",
"starttime": 5242,
"written": "、"
},
{
"confidence": 1.0,
"endtime": 5978,
"spoken": "ゆたか",
"starttime": 5642,
"written": "豊か"
},
{
"confidence": 1.0,
"endtime": 6090,
"spoken": "な",
"starttime": 5978,
"written": "な"
},
{
"confidence": 1.0,
"endtime": 6490,
"spoken": "みらい",
"starttime": 6090,
"written": "未来"
},
{
"confidence": 1.0,
"endtime": 6554,
"spoken": "を",
"starttime": 6490,
"written": "を"
},
{
"confidence": 0.92,
"endtime": 7034,
"spoken": "そうぞう",
"starttime": 6554,
"written": "創造"
},
{
"confidence": 1.0,
"endtime": 7210,
"spoken": "して",
"starttime": 7034,
"written": "して"
},
{
"confidence": 1.0,
"endtime": 7402,
"spoken": "いく",
"starttime": 7210,
"written": "いく"
},
{
"confidence": 0.8,
"endtime": 7674,
"spoken": "こと",
"starttime": 7402,
"written": "こと"
},
{
"confidence": 1.0,
"endtime": 7706,
"spoken": "を",
"starttime": 7674,
"written": "を"
},
{
"confidence": 0.78,
"endtime": 7962,
"spoken": "めざ",
"starttime": 7706,
"written": "めざ"
},
{
"confidence": 0.78,
"endtime": 8490,
"spoken": "します",
"starttime": 7962,
"written": "します"
},
{
"confidence": 0.83,
"endtime": 8778,
"spoken": "_",
"starttime": 8490,
"written": "。"
}
]
}
],
"text": "アドバンスト・メディアは、人と機械等の自然なコミュニケーションを実現し、豊かな未来を創造していくことをめざします。"
}
],
"text": "アドバンスト・メディアは、人と機械等の自然なコミュニケーションを実現し、豊かな未来を創造していくことをめざします。",
"utteranceid": "20210927/06/017c25ed38cc0a30425239d0_20210927_062436[nolog]"
},
"service_id": "{YOUR_SERVICE_ID}",
"session_id": "017c25ec12c00a304474a999",
"status": "completed"
}
다음 단계
- 여기서 사용한 AmiVoice API의 비동기 HTTP 인터페이스를 포함하여, AmiVoice API를 사용하여 음성을 텍스트로 변환하는 방법은 사용 가이드에서 설명하고 있습니다.
- 사용 가이드 중에서 특히 요청 시 설정할 수 있는 파라미터에 대해서는 요청 파라미터, 응답의 세부 사항에 대해서는 음성 인식 결과, AmiVoice API의 비동기 HTTP 인터페이스에 대해서는 비동기 HTTP 인터페이스를 참조하십시오.
- 또한, API 레퍼런스는 비동기 HTTP 인터페이스를 참조하십시오.