← 홈으로 돌아가기

📖 설치 및 이용 매뉴얼

VtoTxt는 음성을 텍스트로 변환해 현재 커서 위치에 바로 입력하는 Windows 앱입니다.
이 매뉴얼에서 설치부터 실제 사용까지 단계별로 안내합니다.

1 시스템 요구사항

💻

운영체제

Windows 10 / 11
(64비트)

🐍

Python

3.9 이상
권장: 3.11

🌐

인터넷

서버 API 접속용
(Vosk는 오프라인 가능)

🎙️

마이크

USB 또는 내장 마이크
16kHz 이상 권장

필수 Python 패키지

패키지	버전	역할
PyQt5	5.15+	트레이 아이콘, 팝업 UI
pyaudio	0.2.14	마이크 입력
keyboard	0.13+	전역 단축키
pyperclip	1.9+	클립보드 텍스트 입력
pyautogui	0.9+	키보드 이벤트
requests	2.32+	서버 API 통신

2 설치 방법

방법 A — 포터블 버전 (권장)

포터블 버전 다운로드
이 페이지 하단 📦 포터블 버전 버튼을 클릭해 ZIP 파일을 받습니다.
압축 해제
원하는 폴더에 압축을 풀어주세요. (예: C:\VtoTxt\)
패키지 설치
압축 해제된 폴더에서 install_and_run.bat 를 우클릭 → 관리자 권한으로 실행
```
# bat 파일이 자동으로 아래 명령을 실행합니다
pip install -r requirements.txt
```
실행 확인
설치 완료 후 프로그램이 자동으로 시작됩니다. 하단 트레이 영역(^ 클릭)에서 🎤 아이콘을 확인하세요.

⚠️

pyaudio 설치 오류 시 — 아래 명령을 순서대로 실행하세요.
pip install pipwin 후 pipwin install pyaudio

방법 B — 설치 프로그램

설치 파일 다운로드
⬇️ 설치 프로그램 다운로드 버튼으로 VoiceTyping_Setup.exe 를 받습니다.
설치 실행
파일을 실행하고 안내에 따라 설치합니다. 백신 소프트웨어가 경고를 표시하면 허용(Allow)을 선택하세요.
자동 시작 등록
설치 완료 시 Windows 시작 프로그램에 자동 등록됩니다. 재부팅 후에도 자동으로 실행됩니다.

Windows 시작 시 자동 실행 등록 (수동)

# 시작 폴더에 바로가기 추가
Win + R  →  shell:startup  입력 후 Enter
# 열린 폴더에 main.pyw 바로가기를 만들어 넣으세요

3 첫 실행 설정

트레이 아이콘 확인
작업 표시줄 우측 하단 ^ 버튼을 클릭하면 🎤 아이콘이 보입니다.
설정 창 열기
🎤 아이콘을 우클릭 → ⚙️ 설정 메뉴를 선택합니다.
서버 연결 확인
기본 서버 URL https://vt.kiam.kr 이 입력되어 있는지 확인 후 연결 테스트 버튼을 클릭합니다.
STT 엔진 선택
처음에는 auto (자동 선택) 을 권장합니다. Vosk 먼저 시도하고 실패 시 Whisper로 전환합니다.
교정 AI 선택 (선택사항)
텍스트 교정이 필요하면 OnlyOne AI 또는 DeepSeek AI 를 선택합니다.
저장 후 첫 테스트
설정 저장 후 메모장을 열고 Ctrl+Shift+M 을 눌러 테스트해보세요.

4 기본 사용법

사용 흐름

입력창에
커서 클릭

→

Ctrl+Shift+M
단축키

→

팝업 표시
🎙 녹음 중

→

말하기

→

✅ 버튼
클릭

→

커서 위치에
텍스트 입력

두 가지 입력 모드

모드	단축키	동작	사용 예
🎤 새로 입력	`Ctrl+Shift+M`	현재 커서 위치에 새 텍스트 입력	빈 입력창에 처음 입력할 때
➕ 이어쓰기	`Ctrl+Shift+A`	이미 입력된 텍스트 뒤에 추가	긴 문장을 여러 번 나눠서 입력할 때

💡

이어쓰기 활용 팁 — 긴 내용을 한 번에 말하기 어려울 때, 새로 입력으로 시작하고 이어쓰기를 반복하면 자연스럽게 긴 글을 작성할 수 있습니다.

트레이 아이콘 색상 의미

아이콘	색상	상태
🎤	파랑	대기 중 (정상)
⏺	빨강	녹음 중
✅	초록	입력 완료

5 팝업 창 안내

단축키를 누르면 화면 중앙에 아래와 같은 팝업 창이 표시됩니다.

버튼	동작
❌ 취소	녹음을 중단하고 인식된 텍스트를 모두 버립니다. 커서 위치에 아무것도 입력되지 않습니다.
✅ 입력	녹음을 중단하고 인식된 텍스트를 현재 커서 위치에 입력합니다.

ℹ️

텍스트 직접 수정 가능 — 팝업의 텍스트 영역을 클릭해서 인식된 내용을 직접 수정한 후 ✅ 버튼을 누를 수 있습니다. 잘못 인식된 단어를 바로 고칠 수 있어 편리합니다.

6 엔진 선택 가이드

STT 엔진 비교

엔진	속도	정확도	인터넷	추천 상황
⚡ Vosk	빠름	보통	불필요	짧은 단어, 빠른 입력, 인터넷 불안정 환경
🎯 Whisper	보통	높음	불필요	긴 문장, 전문용어, 높은 정확도가 필요할 때
🔄 Auto	자동	자동	불필요	처음 사용 시 권장. Vosk 우선 시도 후 실패 시 Whisper 전환

텍스트 교정 AI 비교

교정 AI	특징	인터넷	추천 상황
사용 안 함	인식 결과를 그대로 사용	불필요	빠른 입력, 짧은 단어 위주
✨ OnlyOne AI	맞춤법·문장부호·자연스러운 문장 교정	필요	보고서, 이메일 등 정확한 문서 작성
🤖 DeepSeek AI	높은 언어 이해력, 문맥 기반 교정	필요	긴 글, 복잡한 문장 교정

💡

조합 추천 — 빠른 일상 입력: Vosk + 교정 없음 / 중요한 문서: Whisper + DeepSeek 교정

7 설정 변경

트레이 아이콘 우클릭 → ⚙️ 설정 으로 설정 창을 열 수 있습니다.

설정 항목 설명

항목	설명	기본값
API 서버 URL	VtoTxt 서버 주소	https://vt.kiam.kr
음성 인식 엔진	vosk / whisper / auto	auto
언어	한국어 / English / 日本語 / 中文	한국어
교정 AI	없음 / OnlyOne / DeepSeek	없음
새로 입력 단축키	전역 단축키 (다른 앱에서도 동작)	Ctrl+Shift+M
이어쓰기 단축키	전역 단축키	Ctrl+Shift+A
히스토리 저장	최근 입력 기록 최대 보관 개수	50개
요청 타임아웃	서버 응답 대기 최대 시간	30초
알림 표시	입력 완료 시 트레이 알림 표시	켜짐

설정 파일 직접 수정

설정은 settings.json 파일에 저장됩니다. 텍스트 편집기로 직접 수정할 수도 있습니다.

{
  "server_url":        "https://vt.kiam.kr",
  "stt_engine":        "auto",
  "refiner":           "none",
  "language":          "ko",
  "hotkey_new":        "ctrl+shift+m",
  "hotkey_append":     "ctrl+shift+a",
  "max_history":       50,
  "timeout_sec":       30,
  "show_notification": true
}

8 단축키 모음

단축키	동작
`Ctrl`+`Shift`+`M`	새로 입력 시작 (녹음 시작)
`Ctrl`+`Shift`+`A`	이어쓰기 시작 (녹음 시작)
팝업에서 `Enter`	✅ 입력 — 텍스트를 커서 위치에 입력
팝업에서 `Esc`	❌ 취소 — 텍스트 폐기

ℹ️

단축키는 설정 창에서 원하는 조합으로 변경할 수 있습니다. 다른 앱과 충돌하면 설정에서 변경하세요.

9 문제 해결

마이크가 인식되지 않을 때

마이크 권한 확인
Windows 설정 → 개인 정보 → 마이크 → 앱 접근 허용 ON
기본 장치 설정
작업 표시줄 스피커 우클릭 → 소리 설정 → 입력 장치에서 사용할 마이크 선택

pyaudio 재설치

pip uninstall pyaudio
pip install pipwin
pipwin install pyaudio

서버 연결 실패 시

인터넷 연결 확인
브라우저에서 https://vt.kiam.kr/api/status 접속 확인
URL 확인
설정에서 서버 URL이 https://vt.kiam.kr 인지 확인 (끝에 / 없이)
타임아웃 늘리기
설정에서 요청 타임아웃을 60초로 변경해보세요.

한글이 깨지거나 입력이 안 될 때

클립보드 방식 확인
VtoTxt는 클립보드 붙여넣기 방식으로 입력합니다. 입력창이 Ctrl+V 를 지원하는지 확인하세요.
관리자 권한 실행
일부 프로그램은 관리자 권한이 필요합니다. VtoTxt를 관리자 권한으로 실행해보세요.

인식률이 낮을 때

증상	해결
짧은 단어 인식 실패	Vosk 대신 Whisper 엔진으로 변경
배경 소음 영향	조용한 환경에서 사용 또는 마이크 볼륨 조절
전문 용어 오인식	Whisper + DeepSeek 교정 조합 사용
영어가 한글로 변환됨	설정에서 언어를 English로 변경

10 자주 묻는 질문

Q. 인터넷이 없어도 사용할 수 있나요?

엔진을 Vosk로 설정하고 교정을 사용 안 함으로 설정하면 오프라인 STT가 가능합니다. 단, API 서버(vt.kiam.kr)와의 통신은 인터넷이 필요합니다.

Q. 클립보드 내용이 바뀌지 않나요?

텍스트 입력 시 클립보드를 잠깐 사용하지만, 입력 완료 후 원래 클립보드 내용을 복원합니다. 정상적인 경우 클립보드 내용이 유지됩니다.

Q. 게임이나 특정 프로그램에서 입력이 안 돼요

DirectX 게임이나 관리자 권한 프로그램은 클립보드 입력이 차단될 수 있습니다. VtoTxt를 관리자 권한으로 실행하면 대부분 해결됩니다.

Q. 단축키가 다른 프로그램과 충돌해요

설정 → 단축키를 원하는 조합으로 변경하세요. 예: ctrl+alt+v, ctrl+alt+b

Q. 히스토리는 어디에 저장되나요?

프로그램 폴더 내 history.json 파일에 저장됩니다. 삭제하면 히스토리가 초기화됩니다.

Q. 동시에 여러 PC에서 사용할 수 있나요?

서버는 동시 요청을 처리할 수 있습니다. 각 PC에 앱을 설치해서 독립적으로 사용하면 됩니다.

← 홈으로 돌아가기 ↑ 맨 위로