• “이거 한 줄만 물어보면 되는데… 다시 브라우저 열기 귀찮다”
• “답변은 길어질 것 같은데, 화면 보는 대신 그냥 읽어줬으면 좋겠다”
• “업무 중에 손은 키보드/마우스에 묶여 있는데, 짧게 대화하듯 확인하고 싶다”

그래서 저는 아주 단순한 목표로 시작했어요.

터미널에 질문을 치면 GPT가 답하고, 그 답을 바로 한국어 음성으로 읽어주는 작은 비서

이번 글에서는 제가 실제 소스를 기준으로, 설치부터 운영 팁까지 한 번에 정리해볼게요.

1) 이 스크립트가 하는 일 (한 줄 요약)

나> 질문 입력 → GPT 답변 생성 → Edge TTS로 mp3 생성 → mpg123로 즉시 재생

핵심은 “대화가 끊기지 않게” 만드는 거예요.
기존 버전에서는 답변이 길어지면 500자에서 뚝 잘려서 읽히는 문제가 있었는데, 이 소스에서는 문장 단위로 나눠서 끝까지 읽는 방식으로 개선했습니다.

2) 왜 이소스가 실무에 더 편하냐면

제가 실제로 써보니, 딱 두 가지가 중요했어요.

✅ (1) 답변이 길어져도 끝까지 읽어줌

업무 질문은 생각보다 길게 답이 나오는 경우가 많아요.
“요약 + 근거 + 단계별 명령어” 같은 답변이 나오면 500자 제한으로 끊기는 순간 흐름이 무너집니다.

답변을 문장 단위로 쪼개서 자연스럽게 이어 읽어요.

✅ (2) asyncio.run() 반복 호출 제거

환경에 따라(특히 이벤트 루프가 이미 돌아가는 환경) asyncio.run()을 반복하면 충돌이 날 때가 있어요.
이 소스에서는 이벤트 루프를 한 번만 만들고 계속 재사용하는 방식이라 안정성이 좋아집니다.

3) 준비물 (Ubuntu/Orange Pi 기준)

• Python 3.9+ (대부분 OK)
• 패키지: openai, edge-tts
• 재생기: mpg123
• 그리고 가장 중요한 OpenAI API Key

4) 설치 (실제로 이대로 하면 됩니다)

4-1) mpg123 설치

sudo apt-get update
sudo apt-get install -y mpg123

4-2) 파이썬 라이브러리 설치

pip install -U openai edge-tts

4-3) API 키 설정

export OPENAI_API_KEY="sk-여기에_키_입력"

실무 팁: 매번 export 치기 귀찮으면
~/.bashrc 또는 ~/.profile에 넣어두면 편합니다.

5) 실행 (가장 기본 세팅)

python3 text_gpt_edge_tts_v4.py

실행하면 터미널에 이렇게 뜹니다.

• 나> 프롬프트가 나오고,
• 입력하면 GPT> 답변이 출력되고,
• 이어서 바로 음성으로 재생됩니다.

6) 자주 쓰는 튜닝 포인트 (환경변수로 조절)

실무에서 “한 번 만들어두고 계속 쓰는 도구”가 되려면, 튜닝이 쉬워야 해요.
이 스크립트는 대부분 환경변수로 바꿀 수 있게 해놨습니다.

✅ 모델 바꾸기

export GPT_MODEL="gpt-4o-mini"

✅ 목소리 바꾸기 (한국어)

export TTS_VOICE="ko-KR-SunHiNeural"

✅ 말하기 속도/볼륨

export TTS_RATE="+10%"
export TTS_VOLUME="+0%"

✅ “한 번에 읽는 길이” 조절 (청크 크기)

export MAX_SPEAK_CHARS="450"

• 너무 자주 끊기면 값을 올리고(500~700)
• 문장 끝이 어색하게 잘리면 조금 낮추는 게(350~500) 안정적이었습니다.

✅ TTS 모드 선택

export TTS_MODE="chunk"   # 기본: 끝까지 읽기
# export TTS_MODE="clamp" # 기존처럼 잘라 읽기

7) 운영하면서 “진짜 도움이 됐던” 사용 패턴

제가 실제로 써보면서 효과 있었던 사용 패턴을 몇 개 공유할게요.

(1) 짧은 업무 확인

• “이 로그 메시지 의미가 뭐야?”
• “nginx에서 502 나올 때 점검 순서 정리해줘”
• “이 에러는 보통 어디서 터지지?”

이런 것들은 화면으로 읽기보다 음성으로 들으면 손이 자유로워서 편합니다.

(2) 문서 초안/메일 초안 만들기

• “고객에게 보낼 공지 초안 부탁해”
• “실무적인 체크리스트 형태로 정리해줘”

이럴 때 답이 길어지는데 v4는 중간에 끊기지 않아서 좋았어요.

(3) “내가 지금 뭘 해야 하지?” 정리용

업무가 복잡해질수록, 오히려 이런 질문이 유용합니다.

• “지금 내가 해야 할 일을 5개로 줄여줘”
• “우선순위를 정해줘(긴급/중요 기준)”

음성으로 들으면 리듬이 생겨서 실행이 빨라져요.

8) 트러블슈팅 (운영하다 보면 꼭 만나는 것들)

✅ mpg123: command not found

→ 설치 안 된 상태입니다.

sudo apt-get install -y mpg123

✅ OPENAI_API_KEY 오류 / 401

→ 키가 없거나 잘못된 값입니다.

echo $OPENAI_API_KEY

출력이 비어 있으면 export가 적용 안 된 거예요.

✅ 음성은 생성되는데 소리가 안 난다

이건 환경이 다양해서 원인이 여러 개인데, 경험상 체크 순서는 이렇습니다.

1. 서버/장비에서 실제 오디오 출력 장치가 맞는지
2. mpg123가 소리를 낼 수 있는 상태인지 (권한/장치)
3. 헤드리스 환경이면 기본 오디오 장치가 비정상일 수 있음

9) 실무에서 꼭 챙길 보안 포인트

이런 스크립트는 “내 PC에서만 쓰는 작은 도구”처럼 보여도, 실무에서는 습관이 중요해요.

• API 키를 코드에 하드코딩하지 않기
  → 환경변수로 관리하는 게 기본입니다.
• 가능하면 .bashrc에 넣되, 공유/백업 파일에 키가 올라가지 않도록 주의
• 회사 자산/업무망 장비에서 돌릴 때는 로그/히스토리 저장 여부도 고려

10) 다음 단계 아이디어 (여기서부터가 확장 포인트)

여기까지는 “키보드 입력 기반 음성 비서”였고, 다음 단계는 이쪽이 재밌습니다.

• 마이크 입력(녹음) → Whisper(STT) → GPT → TTS
  완전한 음성 비서 형태로 확장 가능
• 답변을 읽는 동안 중간에 끊기(Stop) 기능 추가
• 질문/답변을 파일로 저장해서 업무 로그처럼 쌓기
• (저는 이걸 Note Station 자동 정리 파이프라인과 연결해서 “회의 음성 → STT → 요약 → 노트 자동 삽입”까지도 확장 중입니다)

파이썬 소스코드 아래

오렌지파이5에서 돌려봤는데 답변이 조금 늦습니다. 좀더 성능좋은 컴퓨터에서는 대화가 어느정도 되었습니다.

참고하세요.

게시물 터미널에서 바로 쓰는 한국어 음성 비서 만들기: GPT + Edge TTS (실무용)이 하우인포-IT·테크에 처음 등장했습니다.