EdgeTTS 보관 - 하우인포-IT·테크

파이썬으로 음성 알람 만들기: EdgeTTS 캐시 + 중복방지 + systemd 자동실행

hong — Thu, 12 Feb 2026 02:25:07 +0000

아침에 알람이 울리긴 하는데…
“몇 시인지 말로 알려주면 진짜 바로 일어나겠는데?” 싶을 때가 있죠.

이번 글에서는 오렌지파이5 + Ubuntu 환경에서, 파이썬으로 말하는 음성 알람을 만드는 방법을 정리했습니다.

06:00부터 10분 단위로 06:30까지
“주인님 일어나세요. 현재 시간 06시 10분입니다.” 같은 문장을 TTS로 말해주고
설정파일 1개로 매일/평일/1회 + 공휴일 제외까지 제어하고
EdgeTTS 캐시(재생 빠름) + 중복 재생 방지(안전) + **systemd 자동 실행(운영 편함)**까지 묶었습니다.

목표 동작 요약

알람 시간: 06:00, 06:10, 06:20, 06:30
출력: 스피커로 음성 재생(mp3)
스케줄 방식: 설정파일(JSON) 기반
운영 안정성:
- 같은 분에 두 번 울리는 것 방지(상태파일 기록)
- TTS는 캐시(mp3 재사용)로 속도/안정성 개선
- systemd로 부팅 후 자동 실행

준비물

Orange Pi 5 (또는 Ubuntu 머신)
Ubuntu 22.04/24.04 계열
스피커(3.5mm/USB/블루투스 등)

설치(필수 패키지)

sudo apt update
sudo apt install -y python3-pip mpg123
pip3 install edge-tts holidays

edge-tts : 텍스트 → 음성(mp3) 생성
mpg123 : mp3를 바로 재생(가볍고 안정적)
holidays : 한국 공휴일 제외(선택처럼 보이지만 “휴일 제외”를 쓰려면 필요)

1) 설정파일 1개로 알람 규칙 관리하기

프로젝트 폴더를 만들고, 설정파일을 준비합니다.

mkdir -p ~/edge_alarm
cd ~/edge_alarm
nano alarm_config.json

`alarm_config.json`

{
  "mode": "weekdays",
  "times": ["06:00", "06:10", "06:20", "06:30"],
  "message_template": "주인님 일어나세요. 현재 시간 {hh}시 {mm}분입니다.",
  "voice": "ko-KR-SunHiNeural",
  "rate": "+0%",
  "volume": 100,
  "exclude_public_holidays": true,
  "country_holidays": "KR",
  "once_date": "2026-02-12"
}

핵심 옵션 설명

mode
- daily : 매일
- weekdays : 평일만(토/일 제외)
- once : 특정 날짜 once_date에만 1회 실행
times : 울릴 시간을 배열로 관리
message_template : {hh}, {mm}가 현재 시각으로 자동 치환
exclude_public_holidays : 공휴일 제외 여부
country_holidays : 한국은 "KR"

2) 파이썬 실행 코드(alarm_tts.py)

이 코드는 아래 3가지를 “운영 가능한 수준”으로 묶는 게 포인트입니다.

EdgeTTS 캐시: 같은 문장은 mp3를 저장해 재사용
중복방지: YYYY-MM-DD_HH:MM 키로 “이미 울림” 기록
자동실행: systemd로 부팅 시 자동 기동

아래 파일을 저장하세요.

nano alarm_tts.py
chmod +x alarm_tts.py

`alarm_tts.py` (한글 상세 주석 포함)

#!/usr/bin/env python3
# -*- coding: utf-8 -*-

"""
[EdgeTTS 음성 알람 스크립트]
- 설정 파일(alarm_config.json) 하나만 수정해서 운영 가능
- EdgeTTS로 MP3 생성 후 스피커로 재생(mpg123 사용)
- MP3 캐시 저장(같은 문장 재사용) -> 빠르고 안정적
- 상태 파일 기록(같은 분 중복 재생 방지)
- systemd 서비스로 등록하면 부팅 후 자동 실행 가능
"""

import asyncio
import json
import os
import sys
import time
import hashlib
import subprocess
from datetime import datetime, date, timedelta

# EdgeTTS 라이브러리 import
try:
    import edge_tts
except ImportError:
    print("edge-tts가 설치되어 있지 않습니다. `pip3 install edge-tts`를 실행하세요.")
    sys.exit(1)

# 공휴일 제외 기능을 위한 라이브러리(없으면 공휴일 판단 기능이 비활성)
try:
    import holidays as holidays_lib
except ImportError:
    holidays_lib = None

# -----------------------------
# 파일 경로(환경변수로 오버라이드 가능)
# -----------------------------
CONFIG_PATH = os.environ.get("ALARM_CONFIG", "./alarm_config.json")  # 설정 파일
STATE_PATH  = os.environ.get("ALARM_STATE", "./alarm_state.json")    # 중복방지 상태 파일
CACHE_DIR   = os.environ.get("ALARM_CACHE", "./tts_cache")           # TTS mp3 캐시 폴더


def load_json(path: str, default):
    """JSON 파일 로딩. 파일이 없으면 default 반환"""
    if not os.path.exists(path):
        return default
    with open(path, "r", encoding="utf-8") as f:
        return json.load(f)


def save_json(path: str, obj):
    """
    JSON 저장을 안전하게 하기 위한 방식
    - 임시 파일(.tmp)에 먼저 저장한 뒤 os.replace로 교체
    - 저장 중 전원 문제 등으로 파일이 깨질 위험을 줄임
    """
    tmp = path + ".tmp"
    with open(tmp, "w", encoding="utf-8") as f:
        json.dump(obj, f, ensure_ascii=False, indent=2)
    os.replace(tmp, path)


def ensure_dir(p: str):
    """폴더가 없으면 생성"""
    os.makedirs(p, exist_ok=True)


def is_public_holiday(d: date, country_code: str) -> bool:
    """
    특정 국가 공휴일 여부 판단
    - holidays 라이브러리가 없으면 False 처리(공휴일 제외 비활성)
    """
    if holidays_lib is None:
        return False

    try:
        h = holidays_lib.country_holidays(country_code)
        return d in h
    except Exception:
        return False


def should_run_today(cfg: dict, today: date) -> bool:
    """
    오늘 알람을 동작시킬지 판단
    - mode(daily/weekdays/once)
    - 공휴일 제외 옵션
    """
    mode = cfg.get("mode", "daily").lower()

    # once 모드: 특정 날짜에만 동작
    if mode == "once":
        once_date = cfg.get("once_date")
        if not once_date:
            return False
        try:
            od = datetime.strptime(once_date, "%Y-%m-%d").date()
            return today == od
        except ValueError:
            return False

    # weekdays 모드: 토/일이면 동작 안 함
    if mode == "weekdays":
        if today.weekday() >= 5:
            return False

    # 공휴일 제외 옵션
    if cfg.get("exclude_public_holidays", False):
        cc = cfg.get("country_holidays", "KR")
        if is_public_holiday(today, cc):
            return False

    return True


def parse_times(cfg: dict):
    """
    설정 times(["06:00","06:10"...])를 (hh,mm) 튜플 리스트로 변환
    - 잘못된 값은 무시
    - 중복 제거 + 정렬
    """
    times = cfg.get("times", [])
    parsed = []
    for t in times:
        try:
            hh, mm = t.split(":")
            parsed.append((int(hh), int(mm)))
        except Exception:
            pass
    return sorted(set(parsed))


def make_message(cfg: dict, now: datetime) -> str:
    """설정 템플릿에서 멘트 생성({hh},{mm} 치환)"""
    tpl = cfg.get("message_template", "주인님 일어나세요. 현재 시간 {hh}시 {mm}분입니다.")
    return tpl.format(hh=now.strftime("%H"), mm=now.strftime("%M"))


def tts_cache_path(text: str, voice: str, rate: str) -> str:
    """
    같은 텍스트/목소리/속도 조합은 mp3를 재사용하기 위해 해시 파일명으로 캐시 저장
    """
    key = f"{voice}|{rate}|{text}".encode("utf-8")
    h = hashlib.sha256(key).hexdigest()[:24]
    return os.path.join(CACHE_DIR, f"{h}.mp3")


async def synthesize_mp3(text: str, voice: str, rate: str, out_path: str):
    """EdgeTTS로 mp3 생성(비동기)"""
    communicate = edge_tts.Communicate(text=text, voice=voice, rate=rate)
    await communicate.save(out_path)


def play_mp3(path: str, volume: int = 100):
    """
    mpg123로 mp3 재생
    - volume(0~100)을 gain으로 완만하게 반영
    """
    gain = max(0, min(32768, int(volume) * 80))
    subprocess.run(["mpg123", "-q", "-f", str(gain), path], check=False)


def minute_key(d: date, hh: int, mm: int) -> str:
    """중복방지 키: YYYY-MM-DD_HH:MM"""
    return f"{d.isoformat()}_{hh:02d}:{mm:02d}"


def next_trigger_datetime(now: datetime, times):
    """
    현재 시각 기준으로 다음 알람 시각 찾기
    - 오늘~모레까지 탐색(안전장치)
    """
    for day_offset in range(0, 3):
        base = now.date() + timedelta(days=day_offset)
        for hh, mm in times:
            dt = datetime.combine(base, datetime.min.time()).replace(hour=hh, minute=mm)
            if dt > now:
                return dt
    return None


async def main():
    """메인 루프"""
    ensure_dir(CACHE_DIR)

    cfg = load_json(CONFIG_PATH, default={})
    state = load_json(STATE_PATH, default={"fired": {}})

    times = parse_times(cfg)
    if not times:
        print("times 설정이 비어 있거나 형식이 잘못되었습니다.")
        return

    voice = cfg.get("voice", "ko-KR-SunHiNeural")
    rate = cfg.get("rate", "+0%")
    volume = int(cfg.get("volume", 100))

    print(f"[alarm] 시작 mode={cfg.get('mode')} times={cfg.get('times')} voice={voice}")

    while True:
        now = datetime.now()
        today = now.date()

        # 오늘 동작 조건이 아니면 내일 새벽까지 대기
        if not should_run_today(cfg, today):
            tomorrow = datetime.combine(today + timedelta(days=1), datetime.min.time()).replace(minute=1)
            sleep_sec = max(5, int((tomorrow - now).total_seconds()))
            print(f"[alarm] 오늘({today}) 스킵. {sleep_sec}초 후 재확인")
            time.sleep(sleep_sec)
            continue

        # 다음 알람 시각 계산
        nxt = next_trigger_datetime(now, times)
        if not nxt:
            time.sleep(10)
            continue

        # 다음 알람까지 대기(너무 길게 한번에 sleep하지 않도록 최대 60초 단위로 쪼갬)
        sleep_sec = (nxt - now).total_seconds()
        if sleep_sec > 1:
            time.sleep(min(60, sleep_sec))
            continue

        # 중복방지: 같은 분에 이미 울렸으면 스킵
        k = minute_key(nxt.date(), nxt.hour, nxt.minute)
        if state.get("fired", {}).get(k):
            time.sleep(1)
            continue

        # 현재 시간 안내가 정확하도록 "울리는 순간"의 시간을 기준으로 멘트 생성
        speak_time = datetime.now()
        text = make_message(cfg, speak_time)

        # 캐시 mp3가 있으면 재사용, 없으면 새로 생성
        cache_path = tts_cache_path(text, voice, rate)
        if not os.path.exists(cache_path):
            try:
                await synthesize_mp3(text, voice, rate, cache_path)
            except Exception as e:
                print("[alarm] TTS 생성 실패:", e)
                time.sleep(2)
                continue

        print(f"[alarm] 울림 {k} => {text}")
        play_mp3(cache_path, volume=volume)

        # 상태 기록(이 분에는 이미 울렸음)
        state.setdefault("fired", {})[k] = True
        save_json(STATE_PATH, state)

        # once 모드면 오늘 남은 알람이 없을 때 종료
        if cfg.get("mode", "").lower() == "once":
            remaining = []
            for hh, mm in times:
                dt = datetime.combine(today, datetime.min.time()).replace(hour=hh, minute=mm)
                if dt > speak_time:
                    remaining.append(dt)
            if not remaining:
                print("[alarm] once 모드 완료. 종료")
                return

        time.sleep(1)


if __name__ == "__main__":
    try:
        asyncio.run(main())
    except KeyboardInterrupt:
        print("\n[alarm] 사용자에 의해 종료됨")

3) 실행 방법(수동 테스트)

cd ~/edge_alarm
python3 alarm_tts.py

당장 테스트하고 싶으면 times를 현재 시간 기준으로 1~2분 뒤로 잠깐 바꿔보면 바로 확인됩니다.

4) systemd 자동 실행(부팅 시 자동 시작)

1) 서비스 파일 생성

sudo nano /etc/systemd/system/edge-alarm.service

2) 아래 내용 입력(경로는 본인 계정에 맞게 수정)

[Unit]
Description=Edge TTS Alarm (EdgeTTS cache + dedup + systemd)
After=network.target sound.target

[Service]
Type=simple
WorkingDirectory=/home/orangepi/edge_alarm
ExecStart=/usr/bin/python3 /home/orangepi/edge_alarm/alarm_tts.py
Restart=always
RestartSec=3

[Install]
WantedBy=multi-user.target

3) 적용 및 실행

sudo systemctl daemon-reload
sudo systemctl enable --now edge-alarm.service
sudo systemctl status edge-alarm.service

운영 팁(실제로 써보면 도움이 되는 부분)

네트워크가 잠깐 끊겨도 이미 만들어둔 mp3 캐시가 있으면 재생은 계속 됩니다.
“같은 시간에 두 번 울림”이 싫다면 상태파일(alarm_state.json) 방식이 꽤 든든합니다.
멘트/시간/평일여부는 코드가 아니라 설정파일 하나로 운영하면 나중에 유지보수가 편해요.

FAQ

Q. 공휴일 제외는 어떻게 동작해요?
A. holidays 라이브러리에서 KR 공휴일을 체크해서 해당 날짜면 스킵합니다.

Q. 스피커가 USB/블루투스면 안 나올 때가 있어요.
A. 대부분 “기본 출력 장치”가 다르게 잡혀서 생깁니다. 먼저 Ubuntu 사운드 출력 장치를 확인해 주세요.

Q. 멘트를 바꾸려면 코드를 수정해야 하나요?
A. 아니요. message_template만 바꾸면 됩니다.

게시물 파이썬으로 음성 알람 만들기: EdgeTTS 캐시 + 중복방지 + systemd 자동실행이 하우인포-IT·테크에 처음 등장했습니다.

터미널에서 바로 쓰는 한국어 음성 비서 만들기: GPT + Edge TTS (실무용)

hong — Tue, 10 Feb 2026 11:58:53 +0000

회의 준비하다가 갑자기 문득 이런 순간이 있어요.

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

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

터미널에 질문을 치면 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가 적용 안 된 거예요.

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

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

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

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

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

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

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

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

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

파이썬 소스코드 아래

gpt_edge_tts 다운로드

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

참고하세요.

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

[라즈베리파이] 나만의 스마트 보안 카메라 만들기 (Python + OpenCV + Edge-TTS)

hong — Mon, 09 Feb 2026 06:45:24 +0000

집을 비울 때 누군가 들어오는지 궁금하신가요? 시중의 비싼 홈캠 대신, 라즈베리파이와 파이썬을 활용해 움직임을 감지하고 목소리로 경고를 날리는 스마트 감시 시스템을 직접 만들어보았습니다. AI를 활용한 고품질 TTS 기능까지 더해 더욱 강력해진 ‘모션 가드’ 제작기를 공유합니다.

1. 주요 기능 및 특징: 이 프로젝트가 특별한 이유

단순히 녹화만 하는 카메라가 아닙니다. 상황에 맞춰 즉각 대응하는 지능형 시스템입니다.

실시간 모션 감지: OpenCV를 활용해 지정된 ROI(관심 영역) 내의 움직임을 픽셀 단위로 분석하여 작은 변화도 놓치지 않습니다.
고품질 AI 음성 안내: edge-tts를 연동하여 기계음이 아닌 자연스러운 한국어 목소리로 침입 경고 멘트를 송출합니다.
오탐 방지 알고리즘: 연속 프레임 감지(Confirm Frames)와 쿨다운 타임을 적용해 조명 변화나 미세한 노이즈로 인한 오작동을 최소화했습니다.
강력한 비프음 발생: 경고 멘트 후 강렬한 ‘삐삐삐’ 패턴의 비프음을 재생해 청각적인 보안 효과를 극대화합니다.

2. 준비물 및 환경 설정: 시작하기 전에

이 프로젝트를 실행하기 위해 라즈베리파이에 몇 가지 하드웨어와 라이브러리 설치가 필요합니다.

하드웨어:
- Raspberry Pi (Zero W, 3, 4 등 모든 모델 가능)
- USB 웹캠 또는 라즈베리파이 카메라 모듈
- 스피커 (3.5mm 오디오 잭 또는 USB 스피커)
소프트웨어 설치:Bash# 1. 시스템 의존성 설치 (음성 재생을 위한 mpg123, alsa-utils) sudo apt-get update && sudo apt-get install -y mpg123 alsa-utils # 2. 파이썬 라이브러리 설치 (OpenCV, NumPy, Edge-TTS, Asyncio) pip install opencv-python numpy edge-tts asyncio 💡 Tip: pip 명령어가 오류난다면 pip3 install ...을 시도해 보세요.

3. 핵심 코드 분석: 어떻게 움직임을 감지할까?

코드의 핵심은 이전 프레임과 현재 프레임 간의 픽셀 차이를 계산하여 움직임을 수치화하는 것입니다.

🔍 모션 감지 알고리즘 (`motion_ratio` 함수)

Python

import cv2
import numpy as np
import os
import asyncio
import edge_tts
import time

# --- 환경 변수 설정 (값을 변경하여 감지 민감도를 조절할 수 있습니다) ---
MOTION_RATIO_THRESH = float(os.environ.get("MOTION_RATIO_THRESH", "0.03")) # 움직임 감지 임계값 (0.01~0.1 사이 권장)
CONFIRM_FRAMES = int(os.environ.get("CONFIRM_FRAMES", "5"))                 # 연속 감지 확인 프레임 수
ALERT_COOLDOWN_SEC = int(os.environ.get("ALERT_COOLDOWN_SEC", "30"))        # 경고 후 쿨다운 시간(초)
TTS_MP3_PATH = os.environ.get("TTS_MP3_PATH", "/tmp/alert.mp3")            # TTS 음성 파일 저장 경로
ALERT_MESSAGE = os.environ.get("ALERT_MESSAGE", "경고! 움직임이 감지되었습니다.") # 경고 음성 메시지
ROI_X, ROI_Y, ROI_W, ROI_H = map(int, os.environ.get("ROI", "0,0,0,0").split(',')) # 관심 영역 (x,y,width,height)

async def tts_save_mp3(text, mp3_path, voice="ko-KR-SunHiNeural"):
    """
    Edge-TTS를 사용하여 텍스트를 mp3 파일로 변환하여 저장합니다.
    """
    try:
        communicate = edge_tts.Communicate(text=text, voice=voice)
        await communicate.save(mp3_path)
    except Exception as e:
        print(f"TTS 생성 중 오류 발생: {e}")

def motion_ratio(prev_gray, gray):
    """
    두 회색조 이미지 간의 움직임 비율을 계산합니다.
    """
    diff = cv2.absdiff(prev_gray, gray) # 이전 프레임과 현재 프레임의 픽셀 차이 계산
    _, th = cv2.threshold(diff, 25, 255, cv2.THRESH_BINARY) # 임계값 처리 (차이가 25 이상인 픽셀만 흰색으로)
    th = cv2.medianBlur(th, 5) # 노이즈 제거를 위한 미디언 블러 적용
    changed_pixels = np.count_nonzero(th) # 변경된 픽셀 수 계산
    return changed_pixels / th.size # 전체 픽셀 대비 변경된 픽셀 비율 반환

def play_alert_sound(tts_path, beep_count=3, beep_duration=0.2):
    """
    경고 음성 메시지와 비프음을 재생합니다.
    """
    print("경고음 재생...")
    if os.path.exists(tts_path):
        os.system(f"mpg123 {tts_path}") # TTS 음성 재생
    
    # 비프음 재생
    for _ in range(beep_count):
        os.system(f"aplay -q -c 1 -t raw -f S16_LE -r 44100 /dev/zero") # 기본 비프음 (라즈비안에서 작동 확인)
        time.sleep(beep_duration)
        os.system(f"aplay -q -c 1 -t raw -f S16_LE -r 44100 /dev/zero") # 종료 비프음
        time.sleep(beep_duration)
    print("경고음 재생 완료.")

async def main():
    cap = cv2.VideoCapture(0) # 웹캠 (0번 장치) 초기화
    if not cap.isOpened():
        print("카메라를 열 수 없습니다.")
        return

    ret, frame = cap.read()
    if not ret:
        print("첫 프레임을 읽을 수 없습니다.")
        cap.release()
        return

    # ROI 설정이 유효하면 해당 영역으로 프레임을 자름
    if ROI_W > 0 and ROI_H > 0:
        frame = frame[ROI_Y:ROI_Y+ROI_H, ROI_X:ROI_X+ROI_W]
        
    prev_gray = cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY)
    
    motion_detected_count = 0
    last_alert_time = 0

    # TTS 파일 미리 생성
    await tts_save_mp3(ALERT_MESSAGE, TTS_MP3_PATH)

    print(f"모션 감지 시작. 임계값: {MOTION_RATIO_THRESH}, 확인 프레임: {CONFIRM_FRAMES}, 쿨다운: {ALERT_COOLDOWN_SEC}초")
    print(f"관심 영역(ROI): X={ROI_X}, Y={ROI_Y}, W={ROI_W}, H={ROI_H}")

    try:
        while True:
            ret, frame = cap.read()
            if not ret:
                break

            display_frame = frame.copy() # 화면 표시용 원본 프레임 복사

            # ROI 설정이 유효하면 해당 영역으로 프레임을 자르고 ROI 표시
            if ROI_W > 0 and ROI_H > 0:
                frame_for_detection = frame[ROI_Y:ROI_Y+ROI_H, ROI_X:ROI_X+ROI_W]
                cv2.rectangle(display_frame, (ROI_X, ROI_Y), (ROI_X+ROI_W, ROI_Y+ROI_H), (0, 255, 0), 2) # ROI 박스 그리기
            else:
                frame_for_detection = frame

            gray = cv2.cvtColor(frame_for_detection, cv2.COLOR_BGR2GRAY)
            
            ratio = motion_ratio(prev_gray, gray)
            
            current_time = time.time()

            if ratio > MOTION_RATIO_THRESH:
                motion_detected_count += 1
                if motion_detected_count >= CONFIRM_FRAMES and (current_time - last_alert_time) > ALERT_COOLDOWN_SEC:
                    print(f"!!! 움직임 감지됨 (비율: {ratio:.4f}) !!!")
                    play_alert_sound(TTS_MP3_PATH)
                    last_alert_time = current_time
                    motion_detected_count = 0 # 알림 후 카운트 초기화
            else:
                motion_detected_count = 0 # 움직임이 없으면 카운트 초기화

            # 프레임에 감지 정보 표시 (선택 사항, 라즈베리파이 성능 고려하여 주석 처리 가능)
            # cv2.putText(display_frame, f"Motion Ratio: {ratio:.4f}", (10, 30), cv2.FONT_HERSHEY_SIMPLEX, 1, (0, 0, 255), 2)
            # cv2.putText(display_frame, f"Alerts: {current_time - last_alert_time:.0f}s cooldown", (10, 70), cv2.FONT_HERSHEY_SIMPLEX, 1, (0, 255, 0), 2)

            # cv2.imshow('Motion Guard Cam', display_frame) # 화면에 표시 (GUI 환경에서만 작동)
            
            prev_gray = gray # 현재 프레임을 다음 반복의 이전 프레임으로 저장

            if cv2.waitKey(1) & 0xFF == ord('q'):
                break

    finally:
        cap.release()
        cv2.destroyAllWindows()
        print("프로그램 종료.")

if __name__ == '__main__':
    asyncio.run(main())

코드 설명: 단순 픽셀 차이 외에도 cv2.medianBlur를 적용해 미세한 노이즈를 제거하여 오작동을 줄였습니다. 또한 CONFIRM_FRAMES로 여러 프레임에 걸쳐 움직임이 지속될 때만 감지하도록 설정하여 신뢰도를 높였습니다.

🗣 AI 음성 경고 (`edge_tts` 활용)

구글 TTS(gTTS)보다 훨씬 자연스러운 Microsoft Edge의 TTS 엔진을 활용하여 고품질의 한국어 음성 경고를 구현했습니다. asyncio를 통해 비동기적으로 음성을 생성합니다.