Feature #670
openFeature #666: [VID] 설교 영상 자동화 시스템 (V2)
Feature #667: [VID-00] 사전 검증 (실제 예배 영상 수령 후 진행)
[VID-00-03] STT 한국어 설교 음성 변환 시험
90%
Description
담당: 양성용
목적¶
한국어 설교 음성을 STT로 얼마나 정확히 글로 바꾸는지, 시간 정보를 어떻게 얻을지 확인한다.
전제·입력¶
실제 영상에서 뽑은 5~10분 분량 샘플 음성.
작업 순서¶
- FFmpeg로 샘플 음성을 추출(예: 모노·16kHz).
- gpt-transcribe로 전사하고 결과를 저장.
- 고유명사(인명·지명)와 성경 구절 인용이 맞는지 사람이 대조해 오류 유형을 정리.
- gpt-transcribe가 구간별 시간(타임스탬프)을 직접 주는지 확인. 주지 않으면 음성을 일정 길이로 나눠 각 구간의 원본 시작 시간으로 매칭하는 방식으로 대체.
- 결과와 권장 방식을 기록.
사용 기술·도구¶
OpenAI STT API(gpt-transcribe 우선), FFmpeg
산출물¶
전사 오류 정리, 타임스탬프 생성 방식 결정
완료 기준¶
- 오류 유형과 비율이 기록되었다.
- 시간 정보를 얻는 방식이 하나로 정해졌다.
이 일감에서 하지 않는 것¶
설교 구간 판단은 하지 않는다(VID-00-04).
주의·미확정 사항¶
whisper-1은 2027-02-26 종료 예정이므로 기본 모델로 쓰지 않는다. gpt-transcribe와 Whisper의 시간 정보 지원 방식이 다르다.
수정할 파일: VID-01-01(기존 코드 확인) 완료 후 기재
연결 일감¶
선행: 없음 / 후행: VID-02-03, VID-00-04
예상 공수: VID-00 검증 결과 후 확정
성양 Updated by 성용 양 23 days ago
- Status changed from New to In Progress
- % Done changed from 0 to 60
한 줄 요약¶
설교 영상의 앞 5분을 무료로 내 컴퓨터에서 글(TXT)과 자막(SRT)으로 바꾸는 데 성공했습니다. 아직 "정확한지 사람이 확인하는 단계"는 끝나지 않아서 완료가 아니라 진행 중입니다.
왜 했나 (목적)¶
설교를 글과 자막으로 만들면 홈페이지에서 설교 내용 검색, 청각 약한 분을 위한 자막, 스크립트 게시에 쓸 수 있습니다. 본 개발에 들어가기 전에 "이게 정말 되는지, 얼마나 정확한지, 얼마나 걸리는지"를 먼저 시험한 것이 이 일감입니다(PoC = 실제 제품 전에 해보는 실험).
어떤 순서로 했나¶
- 영상 정보 확인: FFprobe로 시험 영상(설교 편집본) 길이 28분 32.56초, 영상 H.264, 음성 AAC 44.1kHz를 확인했습니다. 원본은 읽기 전용으로만 열어 파일이 바뀌지 않게 했습니다.
- 앞 5분 소리만 추출: FFmpeg로 영상 화면을 빼고 소리만 WAV로 뽑았습니다(16kHz·모노·16bit, 음성 인식 모델이 가장 잘 받는 형태). 결과 9,598,742바이트, 정확히 5분.
- 전사 프로그램 준비: 홈페이지용 파이썬과 섞이지 않도록 별도 가상환경(venv)을 만들고 faster-whisper를 설치, Whisper Small 모델(약 486MB)을 내려받았습니다.
- 1차 전사(기본): 49구간, 44.87초 소요.
- 2차 전사(용어 힌트 추가): "예수 그리스도, 십자가와 부활" 같은 용어를 미리 알려 주고 다시 실행, 48구간, 42.50초 소요.
- 결과 비교: TXT·SRT 파일을 만들고 1차·2차를 비교했습니다.
사용한 도구·모델 (초보자용 설명)¶
- FFprobe / FFmpeg 5.1.9: 영상 정보를 읽고(FFprobe), 소리만 꺼내 변환(FFmpeg)하는 무료 도구. Docker 이미지에 들어 있는 것을 재사용했습니다.
- Docker 29.6.2: 컴퓨터에 프로그램을 직접 깔지 않고 따로 격리된 환경에서 실행하게 해 주는 도구.
- faster-whisper 1.2.1 + Whisper Small 모델: 사람 말을 글로 바꾸는 무료 AI 모델과 그것을 내 컴퓨터에서 돌리는 프로그램. CPU(INT8, 계산 정밀도를 낮춰 CPU에서도 빠르게 돌리는 방식)로 실행했습니다. 한국어로 인식하도록 지정했습니다.
- Python 3.12 + wave + NumPy: 아래 "문제" 해결에 사용.
- OpenAI API(gpt-transcribe)는 이번에 쓰지 않았습니다. 유료이고 음성을 외부로 보내야 하기 때문입니다.
겪은 문제와 해결¶
- 문제 1: Windows에서 ffmpeg 명령이 안 됨. Windows에 FFmpeg가 설치되어 있지 않았습니다. → 새로 설치하지 않고, 이미 FFmpeg가 들어 있는 Docker 이미지(dbresting-website:local)를 재사용했습니다. 이유: 팀원 PC 환경이 달라도 같은 방식으로 재현되고, 내 PC를 건드리지 않기 때문입니다.
- 문제 2: 첫 전사가 오류로 실패. "TypeError: open() got an unexpected keyword argument 'metadata_errors'". 음성 파일을 여는 PyAV 라이브러리와 faster-whisper의 버전이 맞지 않았습니다(모델이 고장 난 것은 아님). → 라이브러리를 임의로 올리지 않고, Python의 wave로 WAV를 직접 읽어 숫자 배열로 바꿔 모델에 넘겼습니다. 이유: 다른 곳에 영향을 줄 수 있는 업그레이드보다 작은 우회가 안전하기 때문입니다.
- 문제 3: 용어를 틀리게 받아 적음. 1차에서 "예수 그리스도"가 "예술구리스도"로 나왔습니다. → 용어 힌트(initial_prompt)를 넣은 2차 전사로 일부 개선했습니다("예수 그리스도", "예수님의 십자가", "Love Beyond Reason"). 하지만 힌트는 만능이 아니라서 인명("존 오토브")과 일부 문장("사람/사랑", "묘사현홍")은 여전히 틀립니다.
결정한 것과 이유¶
- 기본은 "무료 로컬 전사", OpenAI API는 나중에 승인을 받은 뒤에만. 이유: (1) 비용이 들지 않고 (2) 교회 설교 음성을 외부 서비스로 보내지 않아 개인정보·저작권 부담이 적기 때문입니다. 품질이 부족하면 그때 승인 후 API 방식을 검토합니다.
- 원본·음성·전사문·모델은 GitHub에 올리지 않음. 이유: 비공개 설교 음성이고 용량도 크기 때문입니다.
- 전체가 아니라 5분만 시험. 이유: 5분은 모델의 한계가 아니라 빠르게 가능 여부만 보려는 선택입니다.
아직 안 된 것 (그래서 완료 아님)¶
- 사람이 직접 듣고 받아쓴 글과 대조(정답 전사문), 정확도 수치(WER/CER) 계산
- 자막 시작·끝 시각 검수(첫 자막 13.8초는 길어 보임)
- 다른 모델(Medium 등)과 비교, 28분 32초 전체와 실제 예배 원본 시험
- 성경 인명·장·절 인식 시험, 서버 부하·CMS 연결
근거¶
GitHub PR #63 "docs: #670 설교 영상 무료 로컬 전사 PoC 작업 기록"(열림, 리뷰 전 병합 금지 표시) 및 그 안의 docs/VIDEO_TRANSCRIPTION_POC_GUIDE.md. 이 문서의 숫자는 실제 실행 로그 기준입니다.
성양 Updated by 성용 양 22 days ago
2026-10-26 최신 상태 및 다음 실행 순서¶
최신 상태¶
- GitHub PR #63은 main에 병합되었습니다. 변경 범위는 docs/VIDEO_TRANSCRIPTION_POC_GUIDE.md 1개이며 STT 제품 코드·CMS 연동·배포 변경은 없습니다.
- 최초 5분 WAV에 대해 무료 로컬 Whisper Small 전사와 TXT/SRT 생성은 성공했습니다.
- 로컬 임시 작업에는 Medium·Large-v3, 단어 타임스탬프, 무음 기반 보정, 5분 자막 후보와 검수 큐도 존재합니다. 다만 이 결과들은 자동 생성·후속 실험 자료이며 사람 검수 완료나 품질 승인 근거로 보지 않습니다.
- WER/CER, 오류 유형별 비율, 전체 자막 시간 검수, 최종 타임스탬프 방식 선정은 아직 완료되지 않았습니다.
- 따라서 상태와 진척도는 In Progress / 60%를 유지합니다.
다음 실행 단계: 5분 기준 전사·자막 검증 동결¶
- 동일한 5분 WAV와 비교 후보를 고정하고 모델·옵션·파일 해시를 기록합니다.
- 사람이 전체 5분을 직접 듣고 정답 전사문을 작성합니다. 외부 서비스 결과는 사람 확인 전에는 정답으로 간주하지 않습니다.
- 동일한 정규화 규칙으로 후보별 WER/CER를 계산하고 삽입·누락·대치, 인명·성경 용어·숫자·띄어쓰기·환각 오류를 분류합니다.
- 전체 자막의 시작·종료 시각, 발화 절단, 겹침, 긴 표시 구간을 확인합니다.
- 구간 타임스탬프와 단어 타임스탬프+보정 중 한 방식을 근거와 함께 선택합니다.
- 결과가 합의된 기준을 통과한 뒤에만 전체 28분 32초 전사와 정식 코드 설계를 진행합니다.
현재 완료 기준에 품질 합격 수치가 없으므로 임의의 WER/CER 통과선을 만들지 않습니다. 이번 단계에서 실제 수치를 산출하고 권장 기준을 제안한 뒤 승인받습니다. 유료 API 호출, 외부 음성 업로드, CMS 구현 및 배포는 이번 단계에 포함하지 않습니다.
성양 Updated by 성용 양 21 days ago
- % Done changed from 60 to 70
2026-10-27 최신 상태: 28분 32초 전체 로컬 전사 → 텍스트 기준본 v1 확정¶
한 줄 요약
설교 영상 전체(28분 32초)를 무료로 내 컴퓨터에서 글로 바꾸고, 사람이 듣고 고쳐서 "텍스트 기준본(v1)"을 만들었습니다. 다만 이것은 글 내용의 기준선이며, 자막 시작·끝 시각은 아직 승인하지 않았고 게시용 자막 완성본도 아닙니다.
왜 했나 (목적)
5분 시험에서 가능성을 확인했으므로, 설교 전체에서 어디가 얼마나 틀리는지 보고 사람이 고치는 데 시간이 얼마나 드는지 가늠하기 위해서입니다.
어떤 순서로 했나
- 28분 32초 전체를 무료 로컬 모델로 전사했습니다(외부 서버로 음성을 보내지 않음, 유료 API 미사용).
- 첫 5분은 처음부터 끝까지 전부 사람이 검수했습니다.
- 5~15분은 글만 보고 검수했습니다.
- 15분 이후는 Large V3와 Medium 두 모델의 결과를 비교해 서로 다른(의심) 구간만 골라, 사용자가 직접 들으며 잠정 검수했습니다.
- 5분 앞부분과 나머지 구간의 결과를 병합했습니다. 병합 경계는 04:54.960 종료 후 04:55.900 시작으로 겹침이 없습니다.
결과 수치 (사용자 보고 기준)
- 텍스트 기준본 427구간, 마지막 전사 종료 시각 28:24.740
- 누적 텍스트 교정 33건, 의미 단위 분할 3건
- 검수 진행 위치: 마지막 400번까지 도달
- 파일 해시(SHA-256, 파일이 바뀌지 않았음을 확인하는 지문): SRT 64E8D850…15D64A40 / TXT 71DB2A04…9F86D8 / 병합 보고서 A6AC7105…E8C3DCE
사용한 도구·모델
faster-whisper(무료 로컬 음성 인식 프로그램), Whisper Small(5분 시험), Large V3·Medium(15분 이후 비교), 저장소 스크립트(transcribe_sermon_wav.py, build_transcript_review_batch.py, apply_transcript_review_decisions.py, merge_reviewed_transcripts.py)
결정한 것과 이유
- 한 모델의 결과를 그대로 믿지 않고, 두 모델이 다른 곳만 사람이 듣는 방식으로 검수: 28분 전체를 처음부터 끝까지 듣는 것보다 시간이 훨씬 적게 들기 때문입니다. 대신 15분 이후는 "잠정" 검수입니다.
- 자막 시작·종료 시각은 지금 승인하지 않고 자막 작업 단계에서 다듬기로 결정: 글 내용 기준선과 시간 맞추기는 별개 작업이라 섞으면 검수 기준이 흐려지기 때문입니다.
- 설교 음성·전사문·검수 자료는 GitHub에 올리지 않고 로컬(비공개)로만 보관: 비공개 설교 자료이고 용량도 크기 때문입니다.
아직 안 된 것 (그래서 완료 아님)
- 15분 이후 구간의 정식(전수) 검수, 정답 전사문 기준 WER/CER 수치 산출과 오류 유형별 비율
- 자막 시작·종료 시각 승인(긴 표시 구간·겹침·발화 절단 확인)
- 구간 타임스탬프 vs 단어 타임스탬프+보정 방식 선정
- 실제 전체 예배 영상 시험, 정식 코드 설계, CMS 연동·배포 (이번 단계 범위 아님)
- 스크립트·문서 변경의 커밋·PR 반영(별도 확인 후 진행 예정)
진척도는 5분 시험(60%)에서 전체 텍스트 기준본까지 진행된 점을 반영해 70%로 올립니다. 완료 기준(오류 비율 기록, 시간 방식 결정)은 충족되지 않았으므로 In Progress를 유지합니다.
성양 Updated by 성용 양 19 days ago
2026-10-29 GitHub 반영¶
PR #75(로컬 STT 재현 스크립트 검증 및 텍스트 기준본 v1 정리)가 main에 병합되었습니다. 포함: 설명 문서(docs/VIDEO_TRANSCRIPTION_POC_GUIDE.md), requirements/transcription-poc.txt, 스크립트 4개(전사·검수 묶음 생성·검수 결정 적용·병합). 문법 검사와 ruff 통과, 합성 데이터 소규모 실행 검증, 출력 파일 덮어쓰기 차단 확인. 비공개 원본·WAV·전사 결과·검수 결정 파일은 올리지 않았습니다.
아직 남은 것: 자막 시작·종료 시각 검수·승인, 실제 전체 예배 영상의 설교 경계·싱크 검증(#669 연계), CMS 연동(별도 승인). 상태와 진척도(70%)는 유지합니다.