1/19 서버 Google Cloud Speech-to-Text(STT) 연동 설정 및 REST 요청/응답 확정

1. 목표

• Google Cloud Speech-to-Text API를 프로젝트에 연결하고,
• WAV 파일을 REST로 전송했을 때 어떤 JSON이 오며,
• 응답에서 최종 텍스트(transcript)를 추출하는 방법을 확정한다.
• “샘플 오디오로 STT 1회 성공”을 기준으로 기능 검증을 완료한다.

---

2. GCP 콘솔 설정 절차

2.1 프로젝트 생성 및 결제 연결

1. Google Cloud Console에서 신규 프로젝트 생성(예: medexplain-stt)
2. 결제(Billing) 계정 생성/연결

• STT API는 유료 과금 가능성이 있으므로 결제 계정 연결이 필요함

1. 비용 통제 목적의 Budget/알림 설정은 선택(추가로 설정 가능)

2.2 Speech-to-Text API 활성화

1. API 및 서비스 → 라이브러리
2. Cloud Speech-to-Text API 검색 후 “사용” 활성화

2.3 인증(키) 준비

1. API 및 서비스 → 사용자 인증 정보
2. API 키 생성
3. 보안상 권장 사항

• 생성한 키는 Cloud Speech-to-Text API만 호출 가능하도록 제한(API 제한사항 설정)
• 키 노출 위험이 있으므로 테스트 후 키 회전(재생성) 권장

---

3. 테스트 오디오 준비 및 로컬 테스트 방식

3.1 오디오 파일 준비

• Windows 기본 “음성 녹음기”로 녹음 시 기본 저장은 m4a가 많아,
• STT 테스트를 위해 온라인 변환 도구 등을 이용해 wav로 변환하였다.
• 최종 테스트 파일: test.wav

3.2 로컬에서 REST 호출 테스트 환경

• CMD에서 멀티라인 JSON 작성이 깨지는 문제가 있어(줄 이어쓰기/따옴표 이슈),
• PowerShell 기반으로 다음을 수행하였다:
  1. wav 파일을 byte로 읽기
  2. base64로 인코딩
  3. 요청 JSON을 생성
  4. Invoke-RestMethod로 POST 호출

---

4. STT REST 호출 규격 확정(요청/응답)

4.1 Endpoint

• POST <https://speech.googleapis.com/v1/speech:recognize?key=API_KEY>

4.2 Request JSON 구조

WAV 파일을 base64로 담아 전송한다.

{
"config":{
"encoding":"LINEAR16",
"languageCode":"ko-KR",
"audioChannelCount":2
},
"audio":{
"content":"<BASE64_ENCODED_WAV_BYTES>"
}
}

• languageCode: ko-KR
• encoding: LINEAR16 (PCM WAV 기준)
• audioChannelCount: 파일이 스테레오(2채널)일 경우 2 명시
• (선택) 파일 헤더가 48000Hz인 경우 sampleRateHertz: 48000을 추가할 수 있음
• (파일과 다르게 지정하면 오류 발생)

---

5. 시행착오 및 해결 과정(핵심)

5.1 문제 1) JSON payload 오류(400 Invalid JSON)

• CMD에서 줄바꿈/이스케이프가 꼬이면서 JSON이 깨지는 현상이 발생
• 해결: PowerShell로 전환하여 JSON 생성/요청을 처리함

5.2 문제 2) sample_rate_hertz 불일치 오류

• 오류 메시지 요약:
• sample_rate_hertz(16000) must match WAV header(48000)
• 원인: 변환된 WAV 파일의 실제 샘플레이트가 48000Hz인데 요청에 16000Hz를 넣어 충돌
• 해결:
  • sampleRateHertz를 파일에 맞추거나(48000),
  • 또는 sampleRateHertz 항목을 생략하여 해결 시도

5.3 문제 3) 채널 수 불일치(스테레오/모노) 오류

• 오류 메시지 요약:
• Must use single channel (mono) audio, but WAV header indicates 2 channels.
• 원인: WAV 파일이 2채널(스테레오) 인데 요청 config가 이를 반영하지 못함
• 해결: audioChannelCount: 2를 요청 config에 추가하여 성공

---

6. 성공 결과(샘플 오디오 STT 1회 성공)

6.1 PowerShell 실행 흐름(요약)

1. 파일 경로 설정 및 존재 확인
2. 파일을 base64로 변환
3. config + audio(content)로 JSON 생성
4. recognize endpoint로 POST 호출
5. 응답에서 transcript 추출

6.2 transcript 추출 결과

• 추출 경로: results[*].alternatives[0].transcript
• 실제 출력 예시:
  • Google 스피치 텍스트 테스트 음성입니다

---

7. 응답에서 최종 텍스트 추출 로직(확정)

• 기본 규칙: results 배열을 순회하며
• alternatives[0].transcript를 순서대로 이어 붙여 최종 텍스트 생성

의사코드:

final_text = join(" ", for each r in results: r.alternatives[0].transcript)

---

8. 팀 통일 포맷 제안(추후 안정화)

실제 오류의 대부분이 “파일 포맷/샘플레이트/채널수 불일치”에서 발생했으므로, 팀 내 통일 권장:

• 권장 통일안(A): mono(1채널) + 16kHz + PCM LINEAR16 WAV
  • config 단순화 가능
  • 오류 감소
• 대안(B): 원본 그대로 사용할 경우
  • 파일 헤더에 맞춰 sampleRateHertz, audioChannelCount를 반드시 맞춤

---

9. 결론

• GCP 프로젝트/결제/API 활성화/키 발급/REST 규격 확정 완료
• 샘플 wav 파일 기반으로 STT recognize 호출 성공 및 transcript 추출 성공 확인
• 보고서에 포함 가능한 수준으로 요청/응답 구조 및 파싱 로직을 확정함