A11y Task Recorder

NVDA를 사용한 웹 과업 평가에서 키 입력과 당시 접근성 객체, NVDA 발화, 페이지 이동, DOM 변화, 힌트와 불편 구간을 하나의 타임라인으로 기록하는 로컬 우선 연구 도구입니다. 이 문서에서 Android TalkBack의 “announcement”에 대응하는 NVDA 데이터는 NVDA 발화 또는 **스크린 리더 발화(speech output)**라고 표현합니다.

평가 기관용 빠른 시작 (SNC LAB)

NVDA가 설치되어 있지 않은 새 컴퓨터 기준입니다. Python 같은 개발 도구는 필요 없습니다.

준비물: 64비트 Windows 10 또는 11, 인터넷 연결, 소리를 들을 수 있는 스피커나 이어폰

1. NVDA 설치 — 처음 한 번

NVDA 다운로드 페이지에서 Download NVDA를 눌러 설치 파일을 받습니다.
받은 nvda_….exe를 실행합니다. 보안 확인 창이 나오면 예를 누릅니다.
사용권 계약에 동의하고 이 컴퓨터에 NVDA 설치를 선택해 설치를 마칩니다.
설치 후 NVDA 음성이 나오면 정상입니다.

2. 평가 키트 받기 — 처음 한 번

Releases에서 A11yTaskRecorder-….zip(약 200MB)을 받습니다.
받은 ZIP에서 마우스 오른쪽 버튼 → 압축 풀기를 선택합니다. C:\ 바로 아래처럼 짧은 경로를 권장합니다.

3. 평가 시작 — 평가할 때마다

압축을 푼 폴더의 평가시작.bat을 더블클릭합니다. 처음 실행할 때 보안 경고가 나오면 추가 정보 → 실행을 누릅니다.
Recorder 애드온 설치·NVDA 재시작·평가용 Chrome 실행은 자동으로 진행됩니다. 검은색 서버 창과 기록 대시보드가 열릴 때까지 잠시 기다립니다.
화면 상단에 NVDA 연결됨이 표시되는지 확인합니다. 서버 창은 평가가 끝날 때까지 닫지 마세요.

4. 시나리오 진행

대시보드에서 시나리오 제목과 참여자 코드를 입력해 세션을 만들고 기록 시작을 누릅니다.
평가용 브라우저에서 참여자가 NVDA로 과업을 수행합니다.
불편한 순간에는 NVDA+Control+I를 누릅니다. 높은 확인음이 납니다.

5. 평가를 마치면

대시보드에서 완료하고 종료를 누르고, 타임라인에서 불편 지점을 확인해 문제를 등록합니다.
기록 보관함의 결과 패키지 만들기를 누르면 결과 폴더가 열리고 ZIP 파일 하나가 생깁니다.
그 ZIP을 연구 담당자에게 보낸 뒤 서버 창과 브라우저를 닫습니다.

기록 상태는 언제든 NVDA+Control+L로 확인할 수 있습니다(상승음: 기록 중, 낮은음: 대기 중). 문제가 생기면 키트 폴더의 설치안내.html 문제 해결 절을 참고하세요.

어떤 데이터가 기록되나요?

참여자 동의를 받을 때 아래 내용을 그대로 안내하면 됩니다. 기록은 세션이 "기록 중"인 동안에만 이루어집니다.

출처	기록 내용
NVDA	누른 모든 키와 입력한 글자(예: Tab, H, 입력란에 친 문자), 그 순간 포커스된 요소의 이름·역할·고유 식별자(IA2UniqueID), NVDA가 읽어 준 안내 문구 전문(입력란 내용·문자 에코 포함)과 읽기 시작·중단 시각, 불편 표시 시점(대시보드에서 표시하면 강도 1~5 포함)
평가용 브라우저	방문한 페이지 주소 전체(검색어 등 매개변수와 해시 포함)와 이동 방향, 페이지 제목, 화면 변화의 횟수·시각(변화된 내용 자체는 저장하지 않음)
연구자 입력	시나리오 제목·참여자 코드, step 정의와 시작·종료 시각, step별 수행 결과(성공/힌트 후 성공/막힘)와 사유, 힌트 내용과 제공 시각, 문제 라벨, 참여자 종합 의견
환경 정보	NVDA 버전·합성기·발화 속도, 브라우저·확장 버전

0.3.3부터 키보드로 입력한 글자, 비밀번호, 폼에 적은 내용, NVDA 문자 에코, 주소의 검색어(query)와 해시(#)도 가림 없이 기록합니다. 과업 입력값은 연구진이 제공한 가상 값입니다.

수집하지 않는 것

음성·오디오 녹음과 화면 녹화 — 발화는 텍스트로만 남습니다.
자동 외부 전송 — 모든 기록은 이 컴퓨터의 data 폴더(SQLite)에만 저장되며, 연구자가 결과 패키지 만들기로 ZIP을 만들어 직접 보낼 때만 컴퓨터 밖으로 나갑니다.

개발 환경 수동 설치

코드를 수정하거나 직접 빌드하려는 개발자를 위한 순서입니다. 평가만 진행한다면 위의 빠른 시작을 따르세요.

준비물

64비트 Windows 10 또는 Windows 11
NVDA 공식 다운로드 페이지에서 설치한 NVDA 2024.1 이상
Google Chrome 또는 Microsoft Edge
Python Windows 다운로드 페이지에서 설치한 Python 3.9 이상

Python 설치 화면에서는 Add python.exe to PATH를 선택하는 것을 권장합니다. 설치 확인은 시작 메뉴에서 명령 프롬프트를 열고 다음 명령으로 할 수 있습니다.

py --version

Python 3.9 이상의 버전이 나오면 준비가 끝난 것입니다.

1. 프로그램 받기

GitHub 저장소 상단의 Code → Download ZIP을 선택하고 받은 파일의 압축을 풉니다. OneDrive 동기화 폴더보다는 C:\A11yTaskRecorder처럼 짧고 단순한 경로를 권장합니다.

2. 로컬 서버 실행

압축을 푼 폴더의 start-recorder.bat을 실행합니다. 명령 프롬프트 창이 열리고 브라우저에 다음 주소가 표시됩니다.

http://127.0.0.1:8765

Windows 방화벽 안내가 나타나더라도 외부 네트워크 공개는 필요하지 않습니다. 이 서버는 현재 컴퓨터에서만 접근 가능한 127.0.0.1 주소를 사용합니다.

창이 바로 닫히면 명령 프롬프트에서 압축을 푼 폴더로 이동한 뒤 직접 실행해 오류를 확인합니다.

py -3 run.py

3. Chrome 또는 Edge 확장 설치

Chrome은 주소창에 chrome://extensions, Edge는 edge://extensions를 입력합니다.

개발자 모드를 켭니다.
압축해제된 확장 프로그램을 로드합니다를 선택합니다.
압축을 푼 폴더 안의 browser-extension 폴더를 선택합니다.
브라우저 도구 모음에 A11y Task Recorder 확장을 고정합니다.

세션을 시작하면 확장 아이콘에 REC 배지가 표시됩니다.

Chrome 134부터 압축해제 확장은 개발자 모드가 꺼지면 함께 비활성화되고, 브라우저 업데이트 후 꺼져 있을 수 있습니다. 평가 전에 확장이 켜져 있는지 확인하고, 장기·다기관 평가에는 이 문제가 없는 올인원 키트 방식을 권장합니다.

4. NVDA 애드온 설치

dist\a11yTaskRecorder-….nvda-addon 파일을 실행합니다. NVDA가 설치 여부를 물으면 승인하고 NVDA를 재시작합니다.

설치 파일이 없거나 소스를 수정한 경우 다음 명령으로 다시 만들 수 있습니다.

py -3 scripts\build_nvda_addon.py

NVDA 재시작 후 NVDA+Control+L을 누릅니다.

상승음 두 번: 대시보드에서 세션을 기록 중
낮은음 한 번: 서버가 꺼져 있거나 진행 중인 세션이 없음

5. 첫 평가 시작

대시보드에서 시나리오 제목, 참여자 코드, 시작 URL, 사이트 사전 경험과 평가 환경을 입력합니다.
세션을 만들고 과업을 분석할 단위별로 step을 추가합니다.
기록 시작 후 첫 step의 이 step 시작을 누릅니다.
대상 웹사이트에서 NVDA로 과업을 수행하고 step이 바뀔 때 다음 step을 시작합니다.
힌트를 주었다면 내용을 입력하고 힌트 시점 기록을 누릅니다.
불편한 순간 NVDA+Control+I를 누릅니다.
과업을 마치면 완료하고 종료를 누릅니다.
이벤트 타임라인에서 불편·힌트 칩으로 해당 지점에 바로 이동해 참여자와 함께 확인하고, 구간의 시작·끝 이벤트를 선택해 문제 설명을 등록합니다.
참여자 종합 의견을 저장하고 JSON 또는 CSV로 내보냅니다.

서버의 명령 프롬프트 창을 닫으면 수집 서버가 종료됩니다. 다음 평가 때 start-recorder.bat을 다시 실행하면 기존 세션이 그대로 표시됩니다.

구현된 기능

평가 세션 생성, 시작, 완료 및 중단
완료한 과업의 다음 회차 생성(설정·step 복사)과 세션 화면의 회차 탭 전환
Tab/Shift+Tab, 뒤로가기, 단축키 종류별 집계
NVDA inputCore 입력 제스처와 그 순간의 accessible name, role, state, IA2UniqueID를 한 이벤트로 기록
합성 대기열의 여러 조각을 요소별 발화 에피소드로 병합하고 원문과 보수적으로 전처리한 텍스트를 함께 보존
실제 합성 완료 시각 speech_end_ts와 다음 입력/취소에 의한 발화 중단 여부 기록
Chrome/Edge 확장은 URL·페이지 전환과 집계된 DOM 변화만 기록
시나리오 step 시작/종료, 힌트 제공 시점과 모든 이벤트의 현재 step 자동 연결
step별 수행 결과(성공 · 힌트 후 성공 · 막힘)와 사유 기록. step 종료 시 힌트 연결 여부로 기본값을 채우고 회고에서 수정
평가 중 불편 지점 마커. 대시보드에서 표시하면 강도 1~5를 함께 기록
NVDA 애드온 연결 감시: 애드온의 실제 통신을 서버가 확인해 대시보드에 연결 상태를 표시하고, 미연결 상태로 기록이 시작되지 않도록 경고. 키트 실행 시에는 NVDA를 자동 재시작해 복구
종료 후 타임라인 검토: 불편·힌트 지점 빠른 이동, 선택 구간 시각화, 상호작용 단위 · 원시 이벤트 보기 전환
세션별 수집 품질 자동 점검(data_quality)
이벤트 구간과 step 구간에 문제 설명, 심각도, 기대 발화와 태그 연결
사용자 종합 의견 저장
전체 세션 JSON(원본 이벤트 + 행동 단위 해석본), 이벤트 CSV, 행동 CSV 내보내기
완료 세션 전체를 결과 패키지(세션별 JSON·CSV + 복구용 전체 기록 백업이 담긴 ZIP 하나)로 일괄 내보내기
SQLite 로컬 저장, 입력 문자·입력란 발화·URL 전체를 가림 없이 기록(0.3.3부터)

수집 구조와 연구 근거

이 구현은 A11yNavigator 논문의 구조를 참고합니다. NVDA 애드온이 inputCore와 speech 경로를 관찰해 입력과 접근성 객체를 한 시점에 결합하고, 브라우저 확장은 NVDA가 직접 제공하지 않는 URL 전환과 DOM 변화만 보완합니다. 발화 완료 판정은 NVDA 공식 소스의 synthDoneSpeaking 알림을 사용합니다.

NVDA inputCore ── 키 + accessible name/role/state/IA2UniqueID ─┐
NVDA speech ───── 원문 조각 → 요소별 발화 에피소드 → 종료/중단 ├─ SQLite/JSON
브라우저 확장 ── URL 전환 + 집계된 DOM 변화 ──────────────────┘
대시보드 ─────── step + 힌트 + 타임라인 검토 + 불편 구간 라벨 ──┘

구성

.
├── recorder/                Python 표준 라이브러리 기반 API와 SQLite 저장소
├── static/                  접근 가능한 세션 대시보드
├── browser-extension/       Chrome/Edge Manifest V3 확장
├── nvda-addon/              NVDA Global Plugin 소스
├── scripts/                 NVDA 애드온 패키징·평가 키트 생성 도구
├── docs/                    로그 기록 계획과 수집 데이터·결과물 계획
├── tests/                   저장소와 HTTP API 자동 테스트
├── run.py                   로컬 서버 진입점
└── start-recorder.bat       Windows 실행 파일

상세 설치 정보

1. 로컬 서버

Python 3.9 이상을 설치한 다음 이 폴더에서 start-recorder.bat을 실행합니다. 또는 터미널에서 다음을 실행합니다.

py -3 run.py

대시보드는 http://127.0.0.1:8765에서 열립니다. 외부 네트워크에는 바인딩하지 않습니다. 세션 데이터는 data/recorder.sqlite3에 저장됩니다.

2. Chrome 또는 Edge 확장

Chrome은 chrome://extensions, Edge는 edge://extensions를 엽니다.

개발자 모드를 켭니다.
압축해제된 확장 프로그램을 로드합니다를 선택합니다.
이 저장소의 browser-extension 폴더를 선택합니다.
도구 모음에 A11y Task Recorder를 고정합니다.

확장은 평가 대상 페이지의 URL 전환과 DOM 변화를 얻기 위해 모든 사이트 읽기 권한을 요청합니다. 데이터는 127.0.0.1:8765로만 전송합니다. URL은 쿼리와 해시까지 전체를 기록하고(0.3.3부터), 화면 변화는 내용 없이 횟수만 보냅니다.

3. NVDA 애드온

개발 PC에서 설치 파일을 만듭니다.

py -3 scripts\build_nvda_addon.py

생성된 dist\a11yTaskRecorder-….nvda-addon 파일을 실행하고 NVDA의 안내에 따라 설치한 후 NVDA를 재시작합니다.

지원 기준은 NVDA 2024.1 이상이며 manifest의 마지막 시험 대상으로 NVDA 2026.1을 표시했습니다. 실제 평가 환경에는 NV Access가 배포하는 최신 공식 안정 버전을 권장합니다. Windows 11 + NVDA 2026.1.1 + Chrome 조합에서 실제 평가로 전체 파이프라인 동작을 검증했습니다(2026-08). 애드온이나 NVDA 버전을 바꾼 뒤에는 아래 수동 시험 체크리스트로 다시 확인하세요.

NVDA 2025.1 이상에서는 음성 합성 직전의 처리된 대기열을 기록합니다. NVDA 2024.x는 동일한 확장 지점이 없어, NVDA가 음성 출력을 시도하는 한 단계 앞의 이벤트를 기록하도록 자동 폴백합니다.

세션이 시작되면 애드온은 NVDA 버전, 합성기와 발화 속도를, 확장은 브라우저와 확장 버전을 세션 환경에 자동 병합합니다. 대시보드에서 미리 입력한 값은 해당 컴퓨터에서 실제 감지한 값으로 갱신될 수 있습니다.

평가 기관 배포용 올인원 키트

평가를 진행할 기관(예: 협력 연구실)에 Python 설치, 확장 개발자 모드 로드 같은 개발 단계를 요구하지 않으려면 올인원 키트를 만들어 전달합니다.

py -3 scripts\build_release_kit.py

배포 재현성과 Windows 실행 정책 호환성을 위해 기본 Chrome for Testing 버전은 검증된 버전으로 고정됩니다. 최신판을 별도로 시험할 때만 --chrome-version latest를 사용합니다.

dist\A11yTaskRecorder-<버전>-chrome<버전>.zip이 생성됩니다. 키트에는 기록 서버, 임베디드 Python, Chrome for Testing, 브라우저 확장, NVDA 애드온과 설치안내.html이 들어 있습니다. 전달받은 평가자는 압축을 푼 뒤 평가시작.bat만 더블클릭하면 됩니다.

평가시작.bat은 서버를 띄운 뒤 Chrome for Testing을 --load-extension으로 실행해 확장을 자동 로드합니다. 브랜드 Chrome은 137부터 이 플래그를 지원하지 않지만 Chrome for Testing에서는 계속 지원되므로 스토어 등록이나 개발자 모드가 필요 없습니다. 평가용 브라우저는 키트 안의 전용 프로필을 사용해 평가자의 평소 브라우저와 분리되며, 자동 업데이트가 없어 모든 평가자가 같은 버전을 사용하게 됩니다. 보안 패치 반영을 위해 평가 라운드마다 키트를 새로 생성해 배포하세요. Chrome for Testing에는 일부 상용 코덱(H.264 등)이 없으므로 동영상 재생이 핵심인 과업에는 사전 확인이 필요합니다.

생성한 ZIP은 이 저장소의 Releases에 올려 배포하면 평가 기관이 링크 하나로 받을 수 있습니다. 평가 결과는 대시보드의 결과 패키지 만들기 버튼으로 만든 ZIP 하나를 회수하면 됩니다.

사용 방법

로컬 서버와 브라우저 확장, NVDA 애드온을 실행합니다.
대시보드에서 과업과 참여자 코드, 평가 환경을 입력해 세션을 만듭니다.
기록 시작을 누릅니다. 시작 URL이 있으면 새 탭에서 열립니다.
사용자는 평소처럼 NVDA로 과업을 수행합니다.
불편을 느낀 순간 NVDA+Control+I를 누릅니다. 높은 확인음이 납니다. 확장 프로그램에서는 Alt+Shift+M도 사용할 수 있습니다.
과업 완료 후 대시보드에서 세션을 종료합니다.
종료 후 타임라인 상단의 불편·힌트 칩으로 표시 지점에 바로 이동해 참여자와 함께 확인합니다. 구간의 시작과 끝 이벤트를 선택하면 해당 범위가 문제 양식에 연결됩니다.
문제 설명과 기대 발화를 등록하고 종합 의견을 저장한 뒤 JSON 또는 CSV로 내보냅니다. 여러 세션을 한꺼번에 전달할 때는 기록 보관함의 결과 패키지 만들기로 완료 세션 전체와 복구용 전체 기록 백업이 담긴 ZIP 하나를 만들어 보냅니다.
같은 과업을 반복 측정하려면 완료된 세션의 + 다음 회차를 누릅니다. 과업 설정과 step 구성이 복사된 새 회차가 만들어지고, 세션 화면 상단의 회차 탭(1회차·2회차…)으로 각 회차 결과를 오가며 볼 수 있습니다.

NVDA+Control+L을 누르면 애드온 기록 상태를 소리로 확인할 수 있습니다. 상승음은 기록 중, 낮은음은 대기 중을 뜻합니다.

I는 Issue(불편 지점), L은 Logger(기록 상태)를 뜻합니다. NVDA 기본 명령과의 충돌을 피하기 위해 NVDA+Control+M/R은 사용하지 않습니다. 이전 버전의 NVDA+Control+Shift+M/R도 호환 단축키로 계속 동작합니다.

데이터 의미

내보내기 JSON에는 원본 events와 함께 파생 뷰 interactions가 들어갑니다. interactions는 키 입력 하나에 도착 요소(뒤따르는 focus)와 그때의 NVDA 안내(speech_episode)를 묶은 행동 단위로, 한 줄이 한 행동입니다. 페이지 URL은 직전 브라우저 이벤트에서 이월해 모든 행동에 붙습니다. 각 행동의 event_ids로 원본 이벤트를 되짚을 수 있어 정보 손실이 없습니다. 분석은 interactions(또는 행동 CSV)로 시작하고, 발화 취소·DOM 변화 같은 저수준 근거가 필요할 때 events를 보세요.
data_quality는 NVDA·브라우저 이벤트, 환경 정보, step 결과의 존재 여부를 자동 점검합니다. collection_check_passed: false인 세션은 경고 내용을 확인한 뒤 연구 표본 포함 여부를 결정하세요.
새 기록의 요소 scope는 평가 페이지 안의 객체를 web_content, 주소창이나 탭 검색 같은 브라우저 자체 컨트롤을 browser_ui로 구분합니다.
키를 누르는 순간의 포커스 객체는 전환 중이라 이름이 비어 있는 경우가 많습니다 (실측 5%만 이름 존재). 도착 요소는 뒤따르는 focus 이벤트에 완전하게 기록되며, interactions는 이 둘을 이미 묶어 둡니다.
speech_episode은 NVDA가 합성기에 전달한 텍스트 조각을 동일 IA2 요소와 짧은 시간 간격 기준으로 묶은 분석 단위입니다. fragments와 raw_text에는 원문을, normalized_text에는 끝부분의 heading, clickable, 버튼 같은 흔한 보조 서술자를 보수적으로 제거한 값을 저장합니다.
speech_end_ts는 NVDA 합성기의 synthDoneSpeaking 완료 알림 시각입니다. 완료 전에 다음 키가 입력되거나 NVDA가 음성을 취소하면 그 시각을 종료로 기록하고 interrupted: true로 표시합니다. 실제 오디오를 녹음하거나 몇 번째 음소까지 들었는지를 판정하지는 않습니다.
발화 횟수(speech_episode_count), 원래 조각 수(speech_fragment_count), 고유 발화 요소 수(unique_spoken_element_count)는 서로 다른 지표입니다.
NVDA 탐색 모드의 가상 커서는 DOM 포커스를 이동시키지 않을 수 있습니다. 그래서 키 입력의 요소 식별은 브라우저 DOM 포커스가 아니라 NVDA의 IA2UniqueID를 우선 사용합니다. 확장은 URL과 DOM 변화의 보조 시간축만 제공합니다.
브라우저 뒤로가기 방향은 탭별 방문 기록과 webNavigation 정보를 결합해 추론합니다. 복잡한 SPA나 같은 URL을 반복하는 페이지에서는 back_or_forward로 기록될 수 있습니다.
Tab 횟수만으로 접근성 문제를 자동 판정하지 않습니다. 과업의 기준 경로와 사용자 설명을 함께 비교해야 합니다.

개인정보 보호

0.3.3부터 수집 시점 가림을 하지 않습니다. 입력한 문자(NVDA input, input_kind=character), 편집창·보호 필드에서 나온 NVDA 음성과 문자 에코, 브라우저 URL의 query와 hash를 그대로 저장합니다. 연구 과업의 입력값(비밀번호 포함)은 연구진이 제공한 가상 값입니다.
speech_episode의 redacted 필드는 이전 데이터와의 호환을 위해 남아 있으며 항상 false입니다. 0.3.2 이하로 수집한 세션에는 [입력 문자 음성 출력 숨김]이 남아 있을 수 있습니다.
브라우저 확장 0.2.3 이후의 새 DOM 변화 기록은 최초 변화 시각, 변화 횟수와 대상 수만 저장하며 원문 텍스트, 속성값과 원시 DOM 경로는 저장하지 않습니다. 이전 버전으로 수집한 세션은 재현성을 위해 당시 원본 형식을 그대로 보존합니다.
기본 서버는 loopback 주소에만 열립니다.
실제 사용자 평가 전 동의 문구, 보존 기간과 폐기 절차를 별도로 정해야 합니다.

데이터 백업과 제거

세션 데이터는 압축을 푼 폴더의 data\recorder.sqlite3에 저장됩니다.

전달: 대시보드 기록 보관함의 결과 패키지 만들기를 누르면 완료 세션 전체의 JSON·CSV와 복구용 전체 기록 백업(recorder.sqlite3)이 결과 폴더에 ZIP 하나로 만들어집니다. 이 파일을 연구 담당자에게 보내면 됩니다.
백업: 서버를 종료한 뒤 recorder.sqlite3 파일을 안전한 위치에 복사합니다.
다른 PC로 이동: 프로그램 폴더와 data 폴더를 함께 복사합니다.
데이터 초기화: 서버를 종료하고 data\recorder.sqlite3을 별도 보관하거나 삭제한 뒤 서버를 다시 실행합니다.
브라우저 확장 제거: 브라우저 확장 관리 화면에서 삭제를 선택합니다.
NVDA 애드온 제거: NVDA 메뉴 → 도구 → 애드온 스토어 → 설치된 애드온에서 A11y Task Recorder를 제거하고 NVDA를 재시작합니다.

문제 해결

대시보드가 열리지 않음

start-recorder.bat 명령 프롬프트 창이 열려 있는지 확인합니다.
브라우저에서 http://127.0.0.1:8765/api/health를 엽니다.
{"ok": true}가 보이지 않으면 명령 프롬프트에서 py -3 run.py를 실행해 오류 메시지를 확인합니다.

확장 아이콘에 REC가 표시되지 않음

대시보드에서 세션 상태가 기록 중인지 확인합니다.
확장 관리 화면에서 A11y Task Recorder가 활성화되어 있는지 확인합니다.
확장을 다시 로드한 뒤 대상 페이지도 새로고침합니다.

NVDA 로그가 들어오지 않음 (키 입력·발화가 기록되지 않음)

가장 흔한 원인은 NVDA는 실행 중인데 애드온이 로드되지 않은 상태입니다. NVDA가 로그온 화면에서 올라왔거나 비정상 종료 후 복구된 경우에 발생하며, 프로세스만 보면 정상으로 보이기 때문에 놓치기 쉽습니다.

대시보드 상단의 NVDA 연결됨 / 미연결 표시를 확인합니다. 미연결이면 기록해도 페이지 이동만 남고 키 입력과 발화는 저장되지 않습니다.
NVDA를 재시작합니다(대부분 이것으로 복구됩니다). 키트에서는 평가시작.bat이 연결을 확인하고 자동으로 재시작을 시도합니다.
NVDA+Control+L로 기록 상태음을 확인합니다.
그래도 안 되면 NVDA 메뉴 → 도구 → 애드온 스토어에서 애드온이 활성 상태인지, 설치 후 NVDA를 재시작했는지 확인합니다.
서버 상태는 http://127.0.0.1:8765/api/health의 nvda_connected 값으로도 직접 확인할 수 있습니다.

이미 진행한 세션의 NVDA 데이터는 복구할 수 없으므로, 미연결로 기록된 세션은 다시 평가해야 합니다.

포트 8765가 이미 사용 중이라는 오류

다른 A11y Task Recorder 서버가 실행 중인지 확인합니다. 기존 명령 프롬프트 창을 찾아 사용하거나 종료한 뒤 다시 실행합니다. 확장과 NVDA 애드온은 기본 포트 8765를 사용하므로 임의의 다른 포트로 실행하면 별도 코드 설정이 필요합니다.

개발 및 검증

외부 Python 패키지는 필요하지 않습니다.

python3 -m unittest discover -v
node --check static/app.js
node --check browser-extension/background.js
node --check browser-extension/content.js
node --check browser-extension/popup.js
python3 scripts/build_nvda_addon.py

Windows/NVDA 수동 시험 체크리스트

기록 시작 전 대시보드 상단에 NVDA 연결됨이 표시되는가
세션 시작 후 2초 안에 NVDA+Control+L이 상승음을 내는가
Chrome/Edge에서 Tab과 Shift+Tab이 각각 한 번씩 집계되는가
H, K, B, NVDA+F7 같은 NVDA 탐색 명령이 종류별로 기록되는가
입력창에 타이핑한 실제 글자가 이벤트나 음성 출력에 남지 않는가
탐색 모드와 포커스 모드에서 음성 출력이 기록되는가
발화를 끝까지 들으면 speech_end_ts와 interrupted: false가 기록되는가
발화 도중 다음 키를 누르면 interrupted: true가 기록되는가
한 요소의 나뉜 발화가 하나의 speech_episode과 여러 fragments로 저장되는가
키 입력 이벤트의 요소에 ia2_unique_id와 unique_id가 들어오는가
step 시작 후 입력·발화·힌트에 같은 step_id가 연결되는가
NVDA+Control+I 마커가 현재 포커스 맥락과 함께 나타나는가
Alt+Left와 브라우저 뒤로가기 버튼이 페이지 이동으로 기록되는가
세션 종료 후 새 이벤트가 들어오지 않는가
종료 후 타임라인의 불편 칩으로 이동해 이벤트를 선택하면 구간이 문제 양식에 연결되는가
JSON/CSV에 한글이 깨지지 않는가

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
browser-extension		browser-extension
dist		dist
docs		docs
nvda-addon		nvda-addon
recorder		recorder
scripts		scripts
static		static
tests		tests
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
run.py		run.py
start-recorder.bat		start-recorder.bat

Latest commit

History

Folders and files

Repository files navigation