명령어와 응답
WebSocket 인터페이스를 사용하여 음성 데이터를 스트리밍으로 전송할 때의 명령어와 응답에 대해 설명합니다.
클라이언트는 아래 표의 명령어를 사용하여 API에 음성 인식의 시작, 종료 요청 및 데이터 전송을 합니다. s와 e는 API로부터의 응답을 기다린 후 다음 명령어를 보냅니다. 오류가 발생하면 오류 응답을 반환합니다.
| 이름 | 설명 |
|---|---|
| s 명령어 | 클라이언트의 음성 인식 요청 명령어 |
| p 명령어 | 클라이언트의 음성 데이터 전송 명령어 |
| e 명령어 | 클라이언트의 음성 인식 종료 요청 명령어 |
API는 처리 진행 상황에 따라 아래 표의 이벤트를 반환합니다.
| 이름 | 설명 |
|---|---|
| S 이벤트 | 발화 감지 프로세스에 의한 발화 시작을 알리는 이벤트 |
| E 이벤트 | 발화 감지 프로세스에 의한 발화 종료를 알리는 이벤트 |
| C 이벤트 | 음성 인식 프로세스에 의한 음성 인식 시작을 알리는 이벤트 |
| U 이벤트 | 음성 인식 프로세스에 의한 음성 인식 중간 결과를 알리는 이벤트 |
| A 이벤트 | 음성 인식 프로세스에 의한 음성 인식 완료와 결과를 알리는 이벤트 |
| G 이벤트 | 서버에서 생성된 정보를 알리는 이벤트. 관련 기능을 사용하지 않는 경우에는 발생하지 않습니다. |
음성 스트리밍을 사용한 애플리케이션의 명령어와 이벤트의 일반적인 흐름은 다음과 같습니다.
S와 E는 발화 감지의 결과로, C, U, A는 음성 인식의 결과로 얻어집니다. 발화 구간의 길이나 기반 시스템의 혼잡도에 따라 이벤트의 순서가 달라질 수 있습니다. 예를 들어, 위 그림에서는 S와 E 사이에 C가 오지만, E 이후에 올 수도 있습니다.
여기서는 특정 음성 데이터에서 발화 감지에 의해 3개의 발화 구간이 감지되는 케이스를 예로 설명합니다.
WebSocket 인터페이스에서 스트리밍 데이터 소스로부터 1초씩 데이터를 API에 전송했을 때의 클라이언트의 명령어 전송과 API의 응답 이벤트의 흐름을 로그를 사용하여 설명합니다.
command>>>로 시작하는 줄은 클라이언트의 명령어 전송입니다message<<<로 시작하는 줄은 API의 응답 이벤트입니다
전체 로그는 다음과 같습니다. 가독성을 위해 API의 이벤트를 하이라이트 처리했습니다.
0:00:00.000 open> wss://acp-api.amivoice.com/v1/
0:00:00.161 open # WebSocket 연결
0:00:00.161 command>>> s 16k -a-general segmenterProperties="useDiarizer=1" resultUpdatedInterval=1000 authorization=XXXXXXXXXXXXXXXX
0:00:00.226 message<<< s # 음성 인식 요청 s 명령어의 응답
0:00:00.226 command>>> p [..(32000 bytes)..] # 1초 데이터 전송
0:00:01.232 command>>> p [..(32000 bytes)..] # 2초 데이터 전송
0:00:02.236 command>>> p [..(32000 bytes)..] # 3초 데이터 전송
0:00:03.241 command>>> p [..(32000 bytes)..] # 4초 데이터 전송
0:00:04.245 command>>> p [..(32000 bytes)..] # 5초 데이터 전송
0:00:05.250 command>>> p [..(32000 bytes)..] # 6초 데이터 전송
0:00:06.254 command>>> p [..(32000 bytes)..] # 7초 데이터 전송
0:00:07.257 command>>> p [..(32000 bytes)..] # 8초 데이터 전송
0:00:07.291 message<<< S 6200 # [발화1] 6.2초에 발화 감지
0:00:07.297 message<<< C # [발화1] 음성 인식 처리 시작
0:00:08.262 command>>> p [..(32000 bytes)..] # 9초 데이터 전송
0:00:08.315 message<<< E 7450 # [발화1] 7.45초에 발화 종료
0:00:08.315 message<<< U {...} # [발화1] 중간 결과
0:00:08.446 message<<< A {...} # [발화1] 발화 구간 결과
0:00:09.267 command>>> p [..(32000 bytes)..] # 10초 데이터 전송
0:00:10.270 command>>> p [..(32000 bytes)..] # 11초 데이터 전송
0:00:10.309 message<<< S 8600 # [발화2] 8.6초에 발화 감지
0:00:10.327 message<<< C # [발화2] 음성 인식 처리 시작
0:00:11.272 command>>> p [..(32000 bytes)..] # 12초 데이터 전송
0:00:11.337 message<<< U {...} # [발화2] 중간 결과
0:00:12.274 command>>> p [..(32000 bytes)..] # 13초 데이터 전송
0:00:12.321 message<<< U {...} # [발화2] 중간 결과
0:00:13.277 command>>> p [..(32000 bytes)..] # 14초 데이터 전송
0:00:13.301 message<<< E 11650 # [발화2] 11.65초에 발화 종료
0:00:13.304 message<<< S 12000 # [발화3] 12.00초에 발화 감지
0:00:13.311 message<<< U {...} # [발화2] 중간 결과
0:00:13.343 message<<< A {...} # [발화2] 발화 구간 결과
0:00:14.282 command>>> p [..(32000 bytes)..] # 15초 데이터 전송
0:00:14.336 message<<< C # [발화3] 음성 인식 처리 시작
0:00:15.287 command>>> p [..(32000 bytes)..] # 16초 데이터 전송
0:00:15.344 message<<< U {...} # [발화3] 중간 결과
0:00:16.289 command>>> p [..(32000 bytes)..] # 17초 데이터 전송
0:00:16.337 message<<< U {...} # [발화3] 중간 결과
0:00:17.291 command>>> p [..(22968 bytes)..] # 18초 데이터 전송
0:00:17.345 message<<< U {...} # [발화3] 중간 결과
0:00:18.297 command>>> e # 모든 음성 전송이 끝났으므로 e 명령어를 전송하여 세션 종료
0:00:18.341 message<<< U {...} # [발화3] 중간 결과
0:00:18.347 message<<< E 17700 # [발화3] 17.70초에 발화 종료
0:00:18.347 message<<< U {...} # [발화3] 중간 결과
0:00:18.512 message<<< A {...} # [발화3] 발화 구간 결과
0:00:18.574 message<<< e # 세션 종료 응답
0:00:18.574 close> # WebSocket 클라이언트의 종료
0:00:18.595 close # WebSocket 종료 응답
이하에서는 단계별로 설명합니다.
먼저, WebSocket으로 AmiVoice API의 엔드포인트에 연결하고, s 명령어로 음성 인식을 요청합니다. API는 s 명령어의 응답을 반환합니다.
0:00:00.000 open> wss://acp-api.amivoice.com/v1/
0:00:00.161 open # WebSocket 연결
0:00:00.161 command>>> s 16k -a-general segmenterProperties="useDiarizer=1" resultUpdatedInterval=1000 authorization=XXXXXXXXXXXXXXXX
0:00:00.226 message<<< s # 음성 인식 요청 s 명령어의 응답
요청 성공 후 클라이언트에서 p 명령어로 음성 데이터를 1초씩 전송합니다. 8초에 데이터 전송 후 API에서 S(발화 감지) 이벤트가 전송됩니다.
0:00:00.226 command>>> p [..(32000 bytes)..] # 1초 데이터 전송
0:00:01.232 command>>> p [..(32000 bytes)..] # 2초 데이터 전송
0:00:02.236 command>>> p [..(32000 bytes)..] # 3초 데이터 전송
0:00:03.241 command>>> p [..(32000 bytes)..] # 4초 데이터 전송
0:00:04.245 command>>> p [..(32000 bytes)..] # 5초 데이터 전송
0:00:05.250 command>>> p [..(32000 bytes)..] # 6초 데이터 전송
0:00:06.254 command>>> p [..(32000 bytes)..] # 7초 데이터 전송
0:00:07.257 command>>> p [..(32000 bytes)..] # 8초 데이터 전송
0:00:07.291 message<<< S 6200 # [발화1] 6.2초에 발화 감지
그 후, C(음성 인식 시작)이벤트부터 A(발화 구간 결과) 이벤트가 순서대로 얻어집니다. 또한, 중간에 7.45초에 발화가 끝났음을 나타내는 E(종료 감지) 이벤트가 얻어집니다. s 명령어로 연결할 때 resultUpdatedInterval=1000으로 요청했기 때문에 1초마다 U(중간 결과)가 얻어집니다.
0:00:07.297 message<<< C # [발화1] 음성 인식 처리 시작
0:00:08.262 command>>> p [..(32000 bytes)..] # 9초 데이터 전송
0:00:08.315 message<<< E 7450 # [발화1] 7.45초에 발화 종료
0:00:08.315 message<<< U {...} # [발화1] 중간 결과
0:00:08.446 message<<< A {...} # [발화1] 발화 구간 결과
이후에도 발화 감지와 음성 인식 처리가 나머지 2개의 발화에 대해 반복됩니다.
음성 데이터 전송을 완료한 후에는 e 명령어를 전송하여 세션을 종료합니다. API는 모든 발화 감지와 음성 인식 처리를 완료하면 세션 종료 응답으로 e 이벤트를 반환합니다.
0:00:18.297 command>>> e # 음성 전송이 모두 끝났으므로 e 명령어를 전송하여 세션을 종료합니다
0:00:18.341 message<<< U {...} # [발화3] 중간 결과
0:00:18.347 message<<< E 17700 # [발화3] 17.70초에 발화가 감지되었습니다
0:00:18.347 message<<< U {...} # [발화3] 중간 결과
0:00:18.512 message<<< A {...} # [발화3] 발화 구간의 결과
0:00:18.574 message<<< e # 세션 종료 응답
0:00:18.574 close> # WebSocket 클라이언트의 종료
0:00:18.595 close # WebSocket 종료 응답
이 18초간 세션 전체에 대해서는 앞서 언급한 로그의 주석을 참조하십시오.
A와 U 이벤트의 응답에는 음성인식 결과가 포함되어 있습니다. 자세한 내용은 음성 인식 결과 형식을 참조하십시오. WebSocket 명령어와 이벤트에 대해서는 WebSocket 인터페이스도 참조하십시오.
위의 로그에서 명령어와 이벤트의 시퀀스는 다음과 같습니다. 아래 그림에서는 p 명령어를 생략했습니다.
오류 응답
클라이언트가 전송한 s 명령어, p 명령어, e 명령어가 어떤 이유로 실패한 경우, 예를 들어 명령어 전송 절차에 오류가 있었거나, 제한 사항에 저촉된 경우, 또는 서버 측에 문제가 발생한 경우 등에는 응답에 오류 메시지가 포함된 오류 응답을 반환할 수 있습니다.
성공 응답
s
p
e
오류 응답
s 오류 메시지
p 오류 메시지
e 오류 메시지
오류 응답의 경우, s 명령어를 전송하기 전의 초기 상태로 돌아갑니다. 다시 s 명령어부터 요청을 전송하십시오. 자세한 내용은 패킷 및 상태 전이의 음성 공급 상태 전이도를 참조하십시오.
오류 메시지를 참조하여, 클라이언트 오류의 경우 원인을 수정한 후에, AmiVoice API 서버 측의 서버 오류의 경우 잠시 기다린 후에 다시 요청을 전송하십시오. 제한 사항으로 인한 오류에 대해서는 제한 사항을 참조하십시오. 오류 메시지의 자세한 내용은 다음을 참조하십시오.
s 명령어의 서버 오류나 예기치 못한 네트워크 전송 오류 등의 문제에 대응하기 위해, s 명령어가 성공할 때까지 재시도하는 것이 효과적입니다. 이때, 링 버퍼 등을 사용하여 스트리밍 음원으로부터의 음성을 잃지 않도록 대책을 세움으로써 보다 견고한 애플리케이션을 작성할 수 있습니다.