외국인의 한국어 발음 및 말하기 평정을 위한 채점자 보정(calibration) 시스템과, 응답을 수집·분석하는 서버 코드입니다. (과제: 외국인의 효율적인 한국어 말하기 학습을 위한 AI 활용 한국어 진단 시스템 개발)
평정자는 기준 음성으로 척도를 익힌 뒤 본 시행을 수행하고, 전문가 기준 점수와 비교한 보정 지표(편향, MAE, 상관)를 얻습니다.
두 보정 시스템이 하나의 진입점을 공유합니다.
| 시스템 | 채점 구인 | 상태 |
|---|---|---|
| 발음 평정 보정 | 발음 정확성 · 유창성 (0~4점) | 운영 중 |
| 말하기 평정 보정 | 내용 · 언어 사용 · 전달 (0~4점, 문항 유형 6종) | 구현 완료, 자극 음성 대기 중 |
| 문서 | 내용 |
|---|---|
Readme_speaking.md |
말하기 보정 시스템의 설계와 채점 기준 전문 |
README_Speaking_waves.md |
말하기 자료 연동 안내 — 자극 음원 · 전문가 기준 점수 · 문항 지문의 위치와 규칙 |
server/README.md |
응답 수집 서버 운영과 DB 스키마 |
server/README_development.md |
서버 개발 메모 |
audio/README.md |
음성 전처리와 화자별 기준 점수 |
참여자 정보(ID·참가 코드·소속·연령·성별·평정 경험)를 한 번 입력받아 참가 코드를 확인한 뒤,
발음 / 말하기 보정 시스템을 선택하는 화면으로 넘어갑니다. 입력한 정보는 브라우저의
localStorage 에 저장되어 각 과제에서 다시 입력하지 않습니다. 진입점을 거치지 않고 과제
주소로 바로 들어간 경우에는 그 화면에서 직접 입력할 수도 있습니다.
평정자들이 공용 PC 를 쓰는 경우가 있어, 두 보정 과제를 모두 마치면 완료 화면에서 안내와 함께 참여자 정보를 자동으로 삭제합니다. 「참여자 정보 지우기」로 언제든 즉시 삭제할 수도 있습니다. 삭제된 뒤에도 정보를 다시 입력하면 그대로 참여할 수 있습니다.
과제 안내와 참가자 정보 입력을 거쳐, 음량 조절 → 연습 3시행 → 본 시행 17시행으로 진행됩니다.
목표 지문, 0~4점 루브릭 요약표, 그리고 평가요소별로 각 등급의 기준 음성을 들어볼 수 있는 예시 카드로 구성됩니다.
문항 유형 6종 안내 → 음량 조절 → 평가 기준(문항을 골라 확인) → 연습·본 시행 → 완료로 진행됩니다. 시행마다 문항 유형과 그 화자가 실제로 받은 지시문 · 문항 지문(문항 4는 그림 자료 포함)을 함께 제시하고 응답을 최대 3회까지 들려주며, 내용 · 언어 사용 · 전달을 각각 0~4점으로 평정합니다. 등급 기술이 문항마다 다르므로 점수 버튼에 뜨는 설명도 그 문항의 기준으로 바뀌고, 「이 문항의 채점 기준 보기」로 표 전체를 펼칠 수 있습니다.
평정 자극은 문항 6 × 화자 급 6 × 화자 10 = 360개이고, 전문가 기준 점수(ref)는
360개 전부 assets/kocca_speaking_data.js 의 REF_RAW 에 들어 있습니다. 연습 시행 3개는
낮음 · 중간 · 높음 앵커로 고정되어 평정 직후 기준 점수와의 차이를 알려 줍니다.
다만 자극 음성과 문항 지문은 이 저장소에 없습니다(아래 두 절 참조). 없어도 흐름은
그대로 동작하며 — 재생만 실패하고 지문 칸은 숨겨집니다 — 평정과 저장은 정상적으로
이루어집니다. 음원을 넣는 방법은 README_Speaking_waves.md
에 있습니다.
채점 구인 정의, 문항 유형표, 평정 시 유의사항, 그리고 문항 6종의 채점 기준 (배점 4~0 × 구인 3종)을 모두 펼쳐 싣습니다. 각 칸에는 해당 문항 · 구인 · 배점의 예시 음성을 들을 수 있는 자리가 마련되어 있습니다.
| 디렉터리 | 내용 |
|---|---|
web/ |
평정 과제와 루브릭 가이드 (정적 HTML, 의존성 없음) |
server/ |
응답 수집 백엔드 (Python 표준 라이브러리만 사용) |
audio/ |
음성 전처리·검증·음향 지표 산출 스크립트 |
| 파일 | 설명 |
|---|---|
kocca_speaking_diagnosis.html |
진입점. 참여자 정보 입력 → 보정 시스템 선택 |
kocca_pronunciation_calibration.html |
발음 평정 과제. 연습 3시행(피드백 제공) + 본 시행 17시행 |
kocca_pronunciation_calibration_guide.html |
발음 루브릭과 등급별 기준 음성 안내 |
kocca_speaking_calibration.html |
말하기 평정 과제 |
kocca_speaking_calibration_guide.html |
말하기 평가 기준 안내 |
assets/kocca_speaking_data.js |
말하기 문항 유형 · 채점 구인 · 문항별 채점 기준 · 평정 자극 · 예시 음성 목록 |
assets/kocca_calib_participant.js |
참여자 정보 저장소와 과제 완료 추적 (발음 · 말하기 공용) |
assets/kocca_speaking_calibration/items/ |
화자별 문항 지문 자료(assets/kocca_speaking_prompts.js)를 만드는 스크립트와 설명. 지문 자료 자체는 포함하지 않습니다 |
외부 라이브러리를 쓰지 않는 정적 파일입니다. 웹 루트에 그대로 두면 동작합니다.
발음 쪽 평정 척도와 화자별 전문가 기준 점수는 과제와 가이드 두 파일의
DIMENSIONS·SPEAKERS 상수에 있으며, 두 파일의 값은 항상 같아야 합니다.
말하기 쪽은 같은 실수를 막기 위해 자료를 assets/kocca_speaking_data.js 한 곳에 모았고,
과제와 안내 페이지가 이 파일을 함께 읽습니다. 이 파일을 고칠 때는 두 HTML 의
?v= 쿼리 번호도 함께 올려 주십시오 — 브라우저가 예전 버전을 캐시하면
화면이 어긋납니다.
응답을 SQLite 에 저장하는 작은 HTTP 서버입니다. 설치는 install.sh,
nginx 리버스 프록시 설정은 nginx-snippet.conf, systemd 유닛은 kocca-calib.service
를 참고하십시오. 운영 방법과 DB 스키마는 server/README.md,
개발 메모는 server/README_development.md에 있습니다.
두 과제를 한 서버에서 받습니다. 페이로드의 task 로 구분하며, 과제마다 채점 구인 수가
달라(발음 2종, 말하기 3종) 구인 점수는 열이 아니라 response_scores 에 구인 하나당
한 행으로 저장합니다. 새 과제는 server.py 의 TASKS 에 구인 목록만 추가하면
검증 · 저장 · 내보내기가 함께 따라갑니다.
시작하려면 설정 파일을 만듭니다.
cd server
cp config.example.json config.json
# config.json 을 열어 participant_code 와 ip_hash_salt 를 채웁니다원본 녹음은 40초 고정 길이라 무음이 최대 19초 붙어 있고 파일 간 음량 차가 24dB에
달해 평정 자극으로 쓸 수 없었습니다. process_audio.py 가 무음을 제거하고 음량을
정규화하며, verify_audio.py 가 그 결과를 독립적인 방법으로 재검증합니다
(처리 코드의 판단을 그대로 믿지 않기 위해서입니다 — 이 검증으로 실제 버그 두 개를
찾았습니다). 자세한 내용은 audio/README.md를 보십시오.
이 저장소는 코드만 공개합니다. 화자의 목소리는 개인 식별이 가능한 정보이므로
.wav 파일과 여기서 파생된 산출물(전사, 음향 지표, 리포트)은 제외했습니다.
따라서 web/ 의 페이지를 그대로 열면 음성이 재생되지 않습니다. 실행하려면
assets/kocca_pronunciation_calibration/normalized/ 에 다음 규칙으로 음성을 두십시오.
<화자ID>_set31_pronunciation_1.wav 지문 A
<화자ID>_set32_pronunciation_1.wav 지문 B
화자 ID 목록과 각 화자·지문 조합의 전문가 기준 점수는 audio/README.md
의 표에 정리되어 있습니다.
말하기 쪽은 두 가지입니다.
-
평정 자극 —
assets/kocca_speaking_calibration/아래에 화자별 폴더로 둡니다.<급>급/<급>급-<번호 2자리>/말하기<문항번호>.wav 예) 4급/4급-06/말하기1.wav전문가 기준 점수는 이미
kocca_speaking_data.js의REF_RAW에 360개 전부 들어 있으므로, 이 규칙대로 음원만 두면 자료 파일은 손댈 것이 없습니다. -
등급별 예시 음성 — 따로 두지 않습니다. 안내 페이지의 (문항 × 구인 × 배점) 칸에 붙는 예시는 위 자극과 기준 점수에서 자동으로 생성됩니다. 그 배점을 받은 응답이 없는 칸은 '예시 없음' 으로 표시됩니다.
자극 목록 · 기준 점수 · 문항 지문이 어디에 어떤 규칙으로 들어가는지는
README_Speaking_waves.md 에 자세히 정리되어 있습니다.
화자별 문항 지문(지시문 · 질문 · 문항 4 그림)은 실제 시험에 쓰인 문항이므로 음성과 같은
이유로 배포하지 않습니다. 화면이 읽는 assets/kocca_speaking_prompts.js 와 그림
(assets/kocca_speaking_calibration/items/img/)이 여기에 없다는 뜻입니다. 지문 자료가
없으면 평정 화면은 지문 칸을 자동으로 숨기고 나머지는 그대로 동작합니다.
지문 자료를 갖고 계시면 assets/kocca_speaking_calibration/items/ 의 스크립트로
직접 만드실 수 있습니다. 형식과 절차는 그 폴더의
Readme.md 에 있습니다.
기여하거나 배포할 때 다음 파일이 커밋되지 않도록 하십시오. .gitignore 에 넣어
두었지만, 확인은 직접 하시는 편이 안전합니다.
| 파일 | 담긴 정보 |
|---|---|
config.json |
ip_hash_salt — 유출되면 저장된 IP 해시를 역산할 수 있습니다 |
responses.db |
참가자 실명·소속·연령·성별·IP 해시 |
내보낸 *.csv |
위와 동일 |
*.wav |
화자 음성 |
연구에 사용하셨다면 CITATION.cff 를 참고해 인용해 주십시오.
GitHub 우측 "Cite this repository" 에서 BibTeX 형식으로 받을 수 있습니다.
코드와 문서는 MIT 라이선스를 따릅니다. 자유롭게 사용·수정·재배포하실 수 있으며, 저작권 표시만 유지하시면 됩니다.
다만 MIT 는 이 저장소에 담긴 코드에만 적용됩니다. 다음은 여기에 포함되어 있지 않으며 라이선스 대상이 아닙니다.
| 대상 | 사유 |
|---|---|
화자 음성 (.wav) |
개인 식별이 가능한 정보. 원 데이터 이용 조건과 화자 동의 범위가 별도로 적용됩니다 |
| 음성 파생 산출물 | 전사·음향 지표·분석 리포트 |
| 말하기 문항 지문·그림 | 실제 시험에 쓰인 문항. 원 자료의 이용 조건이 별도로 적용됩니다 |
| 참가자 응답 데이터 | 실명·소속 등 개인정보 포함 |
음성이나 데이터 이용이 필요하시면 저장소 소유자에게 문의하십시오.