• “파이썬 설치해야 해?”
• “pip로 뭐 설치해야 해?”
• “실행했더니 검은 창만 뜨고 꺼지는데?”

그래서 결국 많이 선택하는 방법이 EXE로 패키징하는 겁니다.
이번 글은 제가 실제로 가장 많이 쓰는 도구인 PyInstaller 기준으로, “초보도 따라 할 수 있게” 정리했습니다.

1) EXE 만들기 전에 꼭 알아야 할 것

✅ EXE로 만들면 좋은 점

• 파이썬이 설치되지 않은 PC에서도 실행 가능(대부분의 경우)
• 배포/공유가 편해짐
• 파일 1개(또는 폴더 1개)로 정리 가능

⚠️ 현실적으로 생기는 문제

• 용량이 커짐(수십~수백 MB도 흔함)
• 백신 오탐(특히 새로 만든 exe)
• 경로 문제(파일 저장/설정 파일 위치)
• GUI(Tkinter 등)에서는 괜찮은데, 콘솔 출력은 안 보이기도 함

이걸 미리 알고 가면 삽질이 크게 줄어요.

2) 준비물: 파이썬/폴더 구조 추천

권장 폴더 구조 예시

my_app/
  main.py
  core/
  assets/
  data/
  requirements.txt

• assets/ : 이미지, 아이콘 등 리소스
• data/ : 설정 파일, 저장 파일(앱 실행 중 생성되는 데이터)
• requirements.txt : 의존성 목록

3) PyInstaller 설치

가장 먼저 가상환경을 추천합니다. (빌드가 깔끔해져요)

(선택) 가상환경 만들기

cd my_app
python -m venv .venv
.venv\Scripts\activate

PyInstaller 설치

python -m pip install --upgrade pip
pip install pyinstaller

설치 확인:

pyinstaller --version

4) 가장 기본 빌드: onefile로 EXE 만들기

콘솔 프로그램(터미널 창 필요)

pyinstaller --onefile main.py

GUI 프로그램(창만 띄우고 콘솔 숨김)

pyinstaller --onefile --noconsole main.py

빌드가 끝나면 보통 아래 폴더가 생깁니다.

• dist/ : 실제 배포 파일(exe)
• build/ : 빌드 캐시
• main.spec : 빌드 설정 파일

결과 EXE는 dist/main.exe 에서 확인합니다.

5) 아이콘 넣기(윈도우 exe 느낌 살리기)

아이콘은 .ico 파일이 필요합니다. (png 그대로는 안됨)

pyinstaller --onefile --noconsole --icon=assets/app.ico main.py

6) 이미지/설정파일 등 “외부 파일” 포함하기

여기서 많이 막힙니다.
파이썬에서는 상대경로로 잘 읽히는데, exe로 묶이면 경로가 달라져요.

6-1) 빌드 옵션으로 파일 포함

예: assets/ 폴더를 함께 포함

pyinstaller --onefile --noconsole ^
  --add-data "assets;assets" ^
  main.py

윈도우에서 --add-data "원본;대상" 형태로 세미콜론(;)을 사용합니다.

6-2) exe 환경에서 경로 처리(핵심)

파이썬 코드에서 “실행 위치”를 잡는 함수를 넣어두면 안정적입니다.

import os, sysdef resource_path(relative_path: str) -> str:
    # PyInstaller로 묶이면 _MEIPASS 경로에 리소스가 풀림
    base_path = getattr(sys, "_MEIPASS", os.path.dirname(os.path.abspath(__file__)))
    return os.path.join(base_path, relative_path)

사용 예:

icon_path = resource_path("assets/app.ico")

7) “exe 실행하면 저장이 안돼요/초기화돼요” 문제 해결

이 현상은 거의 대부분 저장 위치가 잘못 잡혀서 생깁니다.

• 개발 중: 프로젝트 폴더에 저장
• exe 실행: 사용자 PC의 다른 위치에서 실행 → 상대경로가 달라짐
• 또는 Program Files 아래라면 쓰기 권한 문제로 저장 실패

추천: 사용자 폴더(AppData) 아래에 저장 폴더 만들기

import osdef get_app_data_dir(app_name="MyApp"):
    base = os.getenv("APPDATA")  # C:\Users\...\AppData\Roaming
    path = os.path.join(base, app_name)
    os.makedirs(path, exist_ok=True)
    return path

저장 예:

cfg_path = os.path.join(get_app_data_dir("HStockGuard"), "config.json")

이렇게 하면 exe로 배포해도 설정/저장 데이터가 유지됩니다.

8) 자주 겪는 에러/해결 체크리스트

✅ 실행하자마자 창이 꺼짐

• 콘솔 모드로 빌드해서 에러 확인
  --noconsole 빼고 실행해보기

✅ 모듈 못 찾는다고 나옴

• 누락된 모듈을 hidden-import로 추가

pyinstaller --onefile --hidden-import=패키지명 main.py

✅ 백신이 위험하다고 막음

• 새 exe는 오탐이 흔함
• 코드서명까지는 현실적으로 어렵고, 최소한 배포 파일을 자주 바꾸지 않는 게 도움
• 가능하면 onedir 배포도 고려(오탐이 덜 나는 경우가 있음)

✅ 용량이 너무 큼

• 가상환경을 깨끗하게 유지
• 불필요한 패키지 제거
• --exclude-module 사용 고려(상황에 따라)

9) 배포 방식 추천: onefile vs onedir

onefile

• 장점: 파일 1개로 배포 끝
• 단점: 실행 시 임시폴더에 풀리는 과정 때문에 첫 실행이 느릴 수 있음

onedir

pyinstaller --noconsole main.py

• 장점: 실행 빠르고 문제 추적이 쉬움
• 단점: 폴더째로 배포해야 함

개인적으로는 처음엔 onedir로 안정화 → 마지막에 onefile로 마무리하는 경우가 많았습니다.

FAQ

Q1. PyInstaller 말고 다른 방법도 있나요?
A. 네. cx_Freeze, Nuitka 같은 대안도 있습니다. 다만 가장 대중적이고 자료가 많은 건 PyInstaller입니다.

Q2. 32비트/64비트는 어떻게 맞추나요?
A. 빌드에 사용하는 파이썬이 64비트면 보통 64비트 exe가 됩니다. 배포 대상 PC 환경과 맞추세요.

Q3. exe로 만들면 소스가 완전히 숨겨지나요?
A. 완전한 보안은 아닙니다. “배포 편의” 목적에 가깝다고 보는 게 현실적입니다.

부록) 그대로 복사해서 쓰는 샘플 코드(저장 유지 + 리소스 경로)

core/paths.py

import os
import sysdef resource_path(relative_path: str) -> str:
    """
    PyInstaller(onefile)에서 리소스 경로를 안전하게 가져온다.
    """
    base_path = getattr(sys, "_MEIPASS", os.path.dirname(os.path.abspath(__file__)))
    return os.path.join(base_path, relative_path)def appdata_dir(app_name: str = "MyApp") -> str:
    """
    AppData\Roaming 아래에 앱 폴더를 생성해 저장 경로로 사용한다.
    """
    base = os.getenv("APPDATA") or os.path.expanduser("~")
    path = os.path.join(base, app_name)
    os.makedirs(path, exist_ok=True)
    return path

core/config.py

import json
import os
from .paths import appdata_dirdef load_config(app_name: str = "MyApp", filename: str = "config.json") -> dict:
    path = os.path.join(appdata_dir(app_name), filename)
    if not os.path.exists(path):
        return {}
    with open(path, "r", encoding="utf-8") as f:
        return json.load(f)def save_config(cfg: dict, app_name: str = "MyApp", filename: str = "config.json") -> str:
    path = os.path.join(appdata_dir(app_name), filename)
    with open(path, "w", encoding="utf-8") as f:
        json.dump(cfg, f, ensure_ascii=False, indent=2)
    return path

main.py (테스트용)

from core.config import load_config, save_configAPP_NAME = "HowinfoPyExeDemo"def main():
    cfg = load_config(APP_NAME)
    run_count = int(cfg.get("run_count", 0)) + 1
    cfg["run_count"] = run_count    saved_path = save_config(cfg, APP_NAME)
    print(f"[OK] 실행 횟수: {run_count}")
    print(f"[OK] 설정 저장 위치: {saved_path}")if __name__ == "__main__":
    main()

빌드 명령어(윈도우)

pyinstaller --onefile main.py

GUI + 아이콘 + assets 포함 예시:

pyinstaller --onefile --noconsole ^
  --icon=assets/app.ico ^
  --add-data "assets;assets" ^
  main.py

게시물 파이썬 프로그램을 윈도우 EXE로 만드는 방법 (PyInstaller 실전 가이드)이 하우인포-IT·테크에 처음 등장했습니다.

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

이번 글에서는 오렌지파이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가지를 “운영 가능한 수준”으로 묶는 게 포인트입니다.

1. EdgeTTS 캐시: 같은 문장은 mp3를 저장해 재사용
2. 중복방지: YYYY-MM-DD_HH:MM 키로 “이미 울림” 기록
3. 자동실행: 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·테크에 처음 등장했습니다.

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를 통해 비동기적으로 음성을 생성합니다.

Python

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}")

코드 설명: ko-KR-SunHiNeural은 한국어 여성 목소리입니다. 이 외에도 다양한 목소리가 있으니 edge-tts --list-voices 명령어로 확인 후 변경해 볼 수 있습니다.

4. 실제 구동 팁: 나만의 환경에 최적화하기

환경에 따라 설정을 미세하게 조정하면 훨씬 똑똑해집니다. 코드 상단의 환경 변수를 통해 조절할 수 있습니다.

• 민감도 조절 (MOTION_RATIO_THRESH): 기본값 0.03은 실내에서 적합합니다. 바람에 흔들리는 나뭇잎이 보이거나 외부 환경이라면 0.05 ~ 0.1 정도로 높여 오탐을 줄일 수 있습니다.
• 관심 영역 지정 (ROI_X, ROI_Y, ROI_W, ROI_H):
  • ROI="0,0,0,0" (기본값) : 전체 화면을 감지합니다.
  • ROI="100,50,400,300" : X좌표 100, Y좌표 50에서 시작하여 가로 400, 세로 300 픽셀 영역만 감지합니다. 이 기능은 문이나 창문 쪽만 집중적으로 감시하게 설정할 수 있어 효율적입니다.
• 쿨다운 시간 (ALERT_COOLDOWN_SEC): 한 번 알림이 울린 후 지정된 시간 동안은 재알림을 하지 않습니다. 반복적인 알림으로 인한 소음 공해를 방지해 줍니다.
• 연속 감지 프레임 (CONFIRM_FRAMES): 짧은 순간의 노이즈로 인한 오탐을 줄이기 위해, 움직임이 N 프레임 이상 연속될 때만 실제 움직임으로 간주합니다.

5. 마치며: 나만의 스마트 홈 시큐리티

💡 직접 구현해보니: 처음에는 cv2.medianBlur나 CONFIRM_FRAMES를 적용하지 않아 바람에 흔들리는 커튼, 혹은 갑작스러운 조명 변화 때문에 알람이 계속 울려 고생했습니다. 하지만 이러한 ‘오탐 방지’ 로직을 추가하니 시스템의 신뢰도가 비약적으로 향상되었습니다. 여러분도 환경에 맞춰 임계값이나 ROI를 조금씩 바꿔보며 최적의 보안 환경을 구축해 보세요!

이 프로젝트는 간단하지만 매우 실용적인 라즈베리파이 활용 예시입니다. 여기에서 더 나아가 감지된 영상을 텔레그램으로 전송하거나, 특정 시간대에만 작동하도록 스케줄링하는 등 다양한 기능으로 확장할 수 있습니다.

전체소스 참고

“이 코드는 별도의 유료 API 키 없이도 작동하며, 환경 변수만으로 간편하게 설정할 수 있도록 설계했습니다.”

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

import os
import time
import asyncio
import tempfile
import subprocess

import cv2
import numpy as np
import edge_tts

# =========================
# 설정(튜닝 포인트)
# =========================
CAM_INDEX = int(os.environ.get("CAM_INDEX", "0"))     # /dev/video0
FRAME_W   = int(os.environ.get("FRAME_W", "640"))
FRAME_H   = int(os.environ.get("FRAME_H", "480"))

# 모션 감지 ROI (전체 화면이면 기본값 그대로 두세요)
# x,y,w,h
ROI = (
    int(os.environ.get("ROI_X", "0")),
    int(os.environ.get("ROI_Y", "0")),
    int(os.environ.get("ROI_W", str(FRAME_W))),
    int(os.environ.get("ROI_H", str(FRAME_H))),
)

# 모션 민감도: "변화한 픽셀 비율"
# - 너무 잘 울리면 ↑ (0.08~0.20)
# - 잘 안 울리면 ↓ (0.01~0.06)
MOTION_RATIO_THRESH = float(os.environ.get("MOTION_RATIO_THRESH", "0.03"))

# 픽셀 차이 임계치(조명 변화에 민감하면 ↑)
DIFF_THRESH = int(os.environ.get("DIFF_THRESH", "25"))

# 모션을 몇 프레임 연속 감지해야 트리거할지(오탐 줄임)
MOTION_CONFIRM_FRAMES = int(os.environ.get("MOTION_CONFIRM_FRAMES", "3"))

# 경고 후 쿨다운(연속 재생 방지)
ALERT_COOLDOWN_SEC = float(os.environ.get("ALERT_COOLDOWN_SEC", "15.0"))

# 프레임 처리 간격(부하 조절)
SLEEP_SEC = float(os.environ.get("SLEEP_SEC", "0.01"))

# TTS
TTS_VOICE  = os.environ.get("TTS_VOICE", "ko-KR-SunHiNeural")
TTS_RATE   = os.environ.get("TTS_RATE", "+0%")
TTS_VOLUME = os.environ.get("TTS_VOLUME", "+0%")

ALERT_TEXT = "여기 들어오시면 안됩니다. 허가된 주인님만 입장 가능합니다."

# 비프 패턴: "3초짜리 삐삐삐"를 3번 반복
BEEP_FREQ = int(os.environ.get("BEEP_FREQ", "1100"))     # Hz
BEEP_MS   = int(os.environ.get("BEEP_MS", "180"))        # beep 1회 길이
BEEP_GAP_MS = int(os.environ.get("BEEP_GAP_MS", "120"))  # beep 사이 간격
BEEP_CYCLE_SEC = float(os.environ.get("BEEP_CYCLE_SEC", "3.0"))  # 3초
BEEP_REPEAT = int(os.environ.get("BEEP_REPEAT", "3"))    # 3회 반복

# =========================
# 오디오 유틸
# =========================
def require_bins():
    for binname, pkg in [("mpg123", "mpg123"), ("aplay", "alsa-utils")]:
        try:
            subprocess.run([binname, "--version"], stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, check=False)
        except FileNotFoundError:
            raise RuntimeError(f"{binname}가 없습니다. 설치: sudo apt-get install -y {pkg}")

def play_mp3(path: str):
    subprocess.run(["mpg123", "-q", path], check=False)

async def tts_save_mp3(text: str, mp3_path: str):
    communicate = edge_tts.Communicate(text=text, voice=TTS_VOICE, rate=TTS_RATE, volume=TTS_VOLUME)
    await communicate.save(mp3_path)

def speak(text: str):
    text = " ".join(text.split()).strip()
    if not text:
        return
    with tempfile.NamedTemporaryFile(suffix=".mp3", delete=True) as tf:
        asyncio.run(tts_save_mp3(text, tf.name))
        play_mp3(tf.name)

def gen_beep_wav(path: str, freq_hz: int, ms: int, volume: float = 0.4, sr: int = 16000):
    t = np.linspace(0, ms/1000.0, int(sr*ms/1000.0), endpoint=False)
    wave = (np.sin(2*np.pi*freq_hz*t) * volume).astype(np.float32)
    pcm_i16 = (np.clip(wave, -1.0, 1.0) * 32767).astype(np.int16)

    import wave as _wave
    with _wave.open(path, "wb") as wf:
        wf.setnchannels(1)
        wf.setsampwidth(2)
        wf.setframerate(sr)
        wf.writeframes(pcm_i16.tobytes())

def play_wav(path: str):
    subprocess.run(["aplay", "-q", path], check=False)

def beep_3sec_triple_repeat3():
    """
    3초 사이클 안에 '삐삐삐'(3회) 후 남는 시간 쉬기.
    그 3초 사이클을 3번 반복.
    """
    with tempfile.NamedTemporaryFile(suffix=".wav", delete=True) as tf:
        gen_beep_wav(tf.name, BEEP_FREQ, BEEP_MS)

        for _ in range(BEEP_REPEAT):
            start = time.time()

            # 삐삐삐
            for i in range(3):
                play_wav(tf.name)
                if i < 2:
                    time.sleep(BEEP_GAP_MS / 1000.0)

            # 3초 맞추기
            elapsed = time.time() - start
            remain = max(0.0, BEEP_CYCLE_SEC - elapsed)
            time.sleep(remain)

# =========================
# 모션 감지 유틸
# =========================
def motion_ratio(prev_gray: np.ndarray, gray: np.ndarray) -> float:
    diff = cv2.absdiff(prev_gray, gray)
    _, th = cv2.threshold(diff, DIFF_THRESH, 255, cv2.THRESH_BINARY)

    # 작은 노이즈 제거(조금만)
    th = cv2.medianBlur(th, 5)

    changed = np.count_nonzero(th)
    total = th.size
    return changed / max(1, total)

# =========================
# main
# =========================
def main():
    require_bins()

    cap = cv2.VideoCapture(CAM_INDEX)
    if not cap.isOpened():
        raise RuntimeError(f"카메라 열기 실패: CAM_INDEX={CAM_INDEX} (/dev/video{CAM_INDEX})")

    cap.set(cv2.CAP_PROP_FRAME_WIDTH, FRAME_W)
    cap.set(cv2.CAP_PROP_FRAME_HEIGHT, FRAME_H)

    x, y, w, h = ROI

    print("=== Motion Guard (Camera) ===")
    print("CAM_INDEX:", CAM_INDEX)
    print("FRAME:", FRAME_W, "x", FRAME_H)
    print("ROI:", ROI)
    print("MOTION_RATIO_THRESH:", MOTION_RATIO_THRESH, "DIFF_THRESH:", DIFF_THRESH)
    print("CONFIRM_FRAMES:", MOTION_CONFIRM_FRAMES, "COOLDOWN:", ALERT_COOLDOWN_SEC)
    print("종료: Ctrl+C\n")

    prev_gray = None
    motion_hits = 0
    last_alert = 0.0

    try:
        while True:
            ok, frame = cap.read()
            if not ok or frame is None:
                time.sleep(0.05)
                continue

            roi = frame[y:y+h, x:x+w]
            gray = cv2.cvtColor(roi, cv2.COLOR_BGR2GRAY)

            # 조명변화 완화(살짝 블러)
            gray = cv2.GaussianBlur(gray, (5, 5), 0)

            if prev_gray is None:
                prev_gray = gray
                time.sleep(SLEEP_SEC)
                continue

            ratio = motion_ratio(prev_gray, gray)
            prev_gray = gray

            if ratio >= MOTION_RATIO_THRESH:
                motion_hits += 1
            else:
                motion_hits = max(0, motion_hits - 1)

            now = time.time()

            # 트리거 조건: 모션 연속 감지 + 쿨다운 지난 후
            if motion_hits >= MOTION_CONFIRM_FRAMES and (now - last_alert) > ALERT_COOLDOWN_SEC:
                last_alert = now
                motion_hits = 0

                print(f"[ALERT] motion detected! ratio={ratio:.4f}")

                # 1) 경고 멘트
                speak(ALERT_TEXT)

                # 2) 삐삐삐(3초) x 3회
                beep_3sec_triple_repeat3()

            time.sleep(SLEEP_SEC)

    except KeyboardInterrupt:
        print("\n종료합니다.")
    finally:
        cap.release()

if __name__ == "__main__":
    main()

게시물 [라즈베리파이] 나만의 스마트 보안 카메라 만들기 (Python + OpenCV + Edge-TTS)이 하우인포-IT·테크에 처음 등장했습니다.

​

포트는 9999

FLASK를 설치 PIP INSTALL FLASK

​

아래 파일.

CSV, JSON 파일 다운로드 받기 .

1-포트 설정하여 스캔

스캔도 멀티테스킹 처리 .

============ 소스 ===================

import subprocess

import platform

import re

import time

import socket

from datetime import datetime

​

from flask import Flask, request, render_template_string, jsonify

​

app = Flask(__name__)

​

# —————- HTML 템플릿 —————-

PAGE_TEMPLATE = “””

<!doctype html>

<html lang=”ko”>

<head>

<meta charset=”utf-8″>

<title>Ping + Port Scan 테스트</title>

<style>

body {

font-family: Arial, sans-serif;

max-width: 900px;

margin: 40px auto;

}

h1 {

text-align: center;

}

form {

margin-bottom: 20px;

text-align: center;

}

input[type=”text”] {

width: 280px;

padding: 8px;

font-size: 14px;

}

input[type=”number”] {

width: 80px;

padding: 6px;

font-size: 14px;

}

input[type=”submit”], button {

padding: 8px 16px;

font-size: 14px;

cursor: pointer;

margin-left: 6px;

}

.result-box {

border: 1px solid #ddd;

padding: 15px;

border-radius: 8px;

background: #f9f9f9;

margin-top: 20px;

}

.status-ok {

color: green;

font-weight: bold;

}

.status-fail {

color: red;

font-weight: bold;

}

pre {

background: #222;

color: #eee;

padding: 10px;

overflow-x: auto;

border-radius: 6px;

font-size: 12px;

}

table {

border-collapse: collapse;

width: 100%;

margin-top: 10px;

}

table th, table td {

border: 1px solid #ccc;

padding: 6px;

text-align: center;

font-size: 13px;

}

table th {

background: #eee;

}

.small-text {

font-size: 12px;

color: #666;

}

#continuous-area {

margin-top: 20px;

}

#continuous-log {

max-height: 260px;

overflow-y: auto;

border: 1px solid #ddd;

border-radius: 6px;

padding: 6px;

background: #111;

color: #eee;

font-size: 12px;

}

#continuous-log div {

margin-bottom: 2px;

}

#port-scan-area {

margin-top: 20px;

}

#port-scan-log {

font-size: 12px;

margin-top: 4px;

white-space: pre-wrap;

}

#port-progress {

font-size: 12px;

margin-top: 4px;

}

#open-port-summary {

font-size: 13px;

margin-top: 8px;

}

</style>

</head>

<body>

<h1>Ping + Port Scan 테스트 (포트 9999)</h1>

​

<!– 폼: 타깃 + 실행횟수 + 계속모드 + 포트 문자열 –>

<form id=”ping-form” method=”POST” action=”/run_test”>

<div style=”margin-bottom: 8px;”>

<input type=”text” name=”target” id=”target”

placeholder=”도메인 또는 IP 입력 (예: 8.8.8.8)”

value=”{{ target or ” }}”>

</div>

<div style=”margin-bottom: 8px;”>

<label>

실행 횟수 (Ping):

<input type=”number” name=”count” id=”count” min=”1″ value=”{{ count or 4 }}”>

</label>

<label style=”margin-left: 10px;”>

<input type=”checkbox” name=”continuous” id=”continuous”

{% if continuous %}checked{% endif %}>

계속 (1초마다 Ping)

</label>

</div>

<div style=”margin-bottom: 10px;”>

<label>

포트 스캔 (예: 80,443 또는 1-100):

<input type=”text” name=”ports” id=”ports” value=”{{ ports or ” }}”>

</label>

</div>

<input type=”submit” value=”Ping 실행”>

<button type=”button” id=”stop-btn” disabled>계속 모드 정지</button>

</form>

​

<div class=”small-text”>

• Ping 실행: 지정한 횟수만큼 서버에서 ping 실행 후 결과 요약<br>

• 계속 모드: 브라우저에서 1초마다 /api/ping_once 호출하여 실시간 Ping 로그<br>

• 포트 스캔: 아래 별도 버튼으로 진행 (멀티스레드처럼 여러 포트를 동시에 스캔, 진행률/요약/다운로드 제공)

</div>

​

{% if summary %}

<!– Ping 실행 결과 –>

<div class=”result-box”>

<h3>Ping 실행 결과 요약 ({{ summary.total }}회)</h3>

<p>대상: <b>{{ target }}</b></p>

<p>

성공: <b>{{ summary.success }}</b> 회,

실패: <b>{{ summary.fail }}</b> 회,

패킷 손실: <b>{{ summary.loss_rate }}%</b>

</p>

<p>

핑 시간(ms) (성공 패킷 기준):<br>

최소: <b>{{ summary.min_ms }}</b>,

최대: <b>{{ summary.max_ms }}</b>,

평균: <b>{{ summary.avg_ms }}</b>

</p>

<table>

<thead>

<tr>

<th>순번</th>

<th>시간</th>

<th>상태</th>

<th>핑 시간(ms)</th>

</tr>

</thead>

<tbody>

{% for row in detail %}

<tr>

<td>{{ loop.index }}</td>

<td>{{ row.timestamp }}</td>

<td>

{% if row.success %}

<span class=”status-ok”>성공</span>

{% else %}

<span class=”status-fail”>실패</span>

{% endif %}

</td>

<td>

{% if row.latency_ms is none %}

PING 실패

{% else %}

{{ “%.1f”|format(row.latency_ms) }}

{% endif %}

</td>

</tr>

{% endfor %}

</tbody>

</table>

​

{% if raw_output %}

<details>

<summary>마지막 ping 원본 출력 보기</summary>

<pre>{{ raw_output }}</pre>

</details>

{% endif %}

</div>

{% endif %}

​

<!– 포트 스캔 영역 –>

<div id=”port-scan-area” class=”result-box”>

<h3>포트 스캔 (멀티스레드 진행상황 + 요약 + 다운로드)</h3>

<p class=”small-text”>

• 타깃 / 포트 목록 입력 후 [포트 스캔 시작] 클릭<br>

• 여러 포트를 동시에 스캔하면서 진행률과 결과 테이블을 실시간 갱신합니다.<br>

• 스캔 완료 후 열린 포트 요약 + CSV / JSON 다운로드 가능

</p>

<div style=”margin-bottom: 8px;”>

<label>

동시 스캔 수:

<input type=”number” id=”concurrency” min=”1″ max=”200″ value=”{{ concurrency or 20 }}”>

</label>

<span class=”small-text”> (한 번에 동시에 처리할 최대 포트 수, 기본 20 / 최대 200)</span>

</div>

<button type=”button” id=”port-scan-start-btn”>포트 스캔 시작</button>

<button type=”button” id=”port-scan-stop-btn” disabled>포트 스캔 정지</button>

<button type=”button” id=”download-csv-btn” disabled>CSV 다운로드</button>

<button type=”button” id=”download-json-btn” disabled>JSON 다운로드</button>

<div id=”port-progress”></div>

<div id=”port-scan-log”></div>

<div id=”open-port-summary”></div>

<table>

<thead>

<tr>

<th>포트</th>

<th>상태</th>

<th>비고</th>

</tr>

</thead>

<tbody id=”port-table-body”>

</tbody>

</table>

</div>

​

<!– 계속 모드용 영역 –>

<div id=”continuous-area”>

<h3>계속 모드 실시간 Ping 로그</h3>

<div class=”small-text”>

• 위에서 “계속” 체크 후 Ping 실행 버튼을 누르면 1초마다 자동으로 ping 결과가 아래에 추가됩니다.<br>

• “계속 모드 정지” 버튼을 누르면 중단됩니다.

</div>

<div id=”continuous-log”></div>

</div>

​

<script>

let pingIntervalId = null;

​

const form = document.getElementById(‘ping-form’);

const continuousCheckbox = document.getElementById(‘continuous’);

const stopBtn = document.getElementById(‘stop-btn’);

const targetInput = document.getElementById(‘target’);

const countInput = document.getElementById(‘count’);

const logDiv = document.getElementById(‘continuous-log’);

​

const portScanStartBtn = document.getElementById(‘port-scan-start-btn’);

const portScanStopBtn = document.getElementById(‘port-scan-stop-btn’);

const portsInput = document.getElementById(‘ports’);

const portProgressDiv = document.getElementById(‘port-progress’);

const portScanLogDiv = document.getElementById(‘port-scan-log’);

const portTableBody = document.getElementById(‘port-table-body’);

const concurrencyInput = document.getElementById(‘concurrency’);

const openPortSummaryDiv = document.getElementById(‘open-port-summary’);

const downloadCsvBtn = document.getElementById(‘download-csv-btn’);

const downloadJsonBtn = document.getElementById(‘download-json-btn’);

​

let portScanAbort = false;

let portResults = []; // {port, open, note}

​

function addLogLine(text, isOk) {

const line = document.createElement(‘div’);

if (isOk === true) {

line.style.color = ‘#7CFC00’;

} else if (isOk === false) {

line.style.color = ‘#FF6347’;

} else {

line.style.color = ‘#FFFFFF’;

}

line.textContent = text;

logDiv.appendChild(line);

logDiv.scrollTop = logDiv.scrollHeight;

}

​

function startContinuousPing(target) {

if (!target) {

alert(‘타겟을 입력해주세요.’);

continuousCheckbox.checked = false;

return;

}

​

if (pingIntervalId !== null) {

clearInterval(pingIntervalId);

}

​

addLogLine(‘— 계속 모드 시작: ‘ + target + ‘ —‘, null);

​

pingIntervalId = setInterval(function() {

fetch(‘/api/ping_once?target=’ + encodeURIComponent(target))

.then(function(response) { return response.json(); })

.then(function(data) {

const ts = data.timestamp || ”;

const ok = data.success;

const latency = data.latency_ms;

let msg = ‘[‘ + ts + ‘] ‘ + data.target + ‘ -> ‘;

​

if (ok) {

if (latency === null) {

msg += ‘✅ 성공 | PING 시간: -‘;

} else {

msg += ‘✅ 성공 | PING 시간: ‘ + latency.toFixed(1) + ‘ ms’;

}

} else {

msg += ‘❌ 실패 | PING 시간: 알 수 없음’;

}

addLogLine(msg, ok);

})

.catch(function(err) {

addLogLine(‘에러: ‘ + err, false);

});

}, 1000);

​

stopBtn.disabled = false;

}

​

function stopContinuousPing() {

if (pingIntervalId !== null) {

clearInterval(pingIntervalId);

pingIntervalId = null;

addLogLine(‘— 계속 모드 정지 —‘, null);

}

stopBtn.disabled = true;

}

​

// Ping 폼 제출 시 동작

form.addEventListener(‘submit’, function(ev) {

const isContinuous = continuousCheckbox.checked;

const target = targetInput.value.trim();

​

if (isContinuous) {

ev.preventDefault();

startContinuousPing(target);

} else {

stopContinuousPing();

if (!countInput.value) {

countInput.value = 4;

}

}

});

​

stopBtn.addEventListener(‘click’, function() {

stopContinuousPing();

});

​

// —- 포트 스캔 관련 JS —-

function parsePortsLocal(portsStr) {

portsStr = portsStr.trim();

if (!portsStr) return [];

​

const result = new Set();

const parts = portsStr.split(‘,’);

for (let part of parts) {

part = part.trim();

if (!part) continue;

​

// 혹시 전각 대시(– — −) 들어올 경우 ASCII ‘-‘ 로 치환

part = part.replace(/[–—−]/g, ‘-‘);

​

if (part.includes(‘-‘)) {

const rangeParts = part.split(‘-‘);

if (rangeParts.length !== 2) continue;

const startStr = rangeParts[0].trim();

const endStr = rangeParts[1].trim();

const s = parseInt(startStr, 10);

const e = parseInt(endStr, 10);

if (isNaN(s) || isNaN(e)) continue;

const start = Math.min(s, e);

const end = Math.max(s, e);

for (let p = start; p <= end; p++) {

if (p >= 1 && p <= 65535) result.add(p);

}

} else {

const p = parseInt(part, 10);

if (!isNaN(p) && p >= 1 && p <= 65535) result.add(p);

}

}

return Array.from(result).sort((a, b) => a – b);

}

​

async function scanPortOnce(target, port) {

const res = await fetch(

‘/api/scan_port?target=’

+ encodeURIComponent(target)

+ ‘&port=’ + encodeURIComponent(port)

);

return res.json();

}

​

function updateOpenPortSummary() {

if (portResults.length === 0) {

openPortSummaryDiv.textContent = “”;

return;

}

const openPorts = portResults

.filter(r => r.open)

.map(r => r.port)

.sort((a, b) => a – b);

​

if (openPorts.length === 0) {

openPortSummaryDiv.textContent = “열린 포트 없음.”;

} else {

openPortSummaryDiv.textContent =

“열린 포트 (” + openPorts.length + “개): ” + openPorts.join(“, “);

}

}

​

function downloadJSON() {

if (portResults.length === 0) {

alert(“다운로드할 스캔 결과가 없습니다.”);

return;

}

const target = targetInput.value.trim() || “target”;

const dataStr = JSON.stringify(portResults, null, 2);

const blob = new Blob([dataStr], { type: “application/json” });

const url = URL.createObjectURL(blob);

const a = document.createElement(“a”);

const ts = new Date().toISOString().replace(/[:.]/g, “-“);

a.href = url;

a.download = “port_scan_” + target + “_” + ts + “.json”;

document.body.appendChild(a);

a.click();

document.body.removeChild(a);

URL.revokeObjectURL(url);

}

​

function downloadCSV() {

if (portResults.length === 0) {

alert(“다운로드할 스캔 결과가 없습니다.”);

return;

}

const target = targetInput.value.trim() || “target”;

​

function escapeCsv(value) {

if (value == null) return “”;

const s = String(value);

if (s.includes(‘”‘) || s.includes(‘,’) || s.includes(‘\\n’)) {

return ‘”‘ + s.replace(/”/g, ‘””‘) + ‘”‘;

}

return s;

}

​

let csv = “port,status,note\\n”;

for (const r of portResults) {

const status = r.open ? “OPEN” : “CLOSED”;

csv += [

escapeCsv(r.port),

escapeCsv(status),

escapeCsv(r.note)

].join(“,”) + “\\n”;

}

​

// 👉 한글이 엑셀에서 안 깨지도록 UTF-8 BOM 추가

const bom = “\\uFEFF”; // JS에서 문자열 리터럴로 해석되면서 실제 BOM 문자로 변환

const blob = new Blob([bom + csv], { type: “text/csv;charset=utf-8;” });

​

const url = URL.createObjectURL(blob);

const a = document.createElement(“a”);

const ts = new Date().toISOString().replace(/[:.]/g, “-“);

a.href = url;

a.download = “port_scan_” + target + “_” + ts + “.csv”;

document.body.appendChild(a);

a.click();

document.body.removeChild(a);

URL.revokeObjectURL(url);

}

​

async function startPortScan() {

const target = targetInput.value.trim();

const portsStr = portsInput.value.trim();

​

if (!target) {

alert(“타깃(도메인 또는 IP)을 입력하세요.”);

return;

}

if (!portsStr) {

alert(“포트 목록을 입력하세요.”);

return;

}

​

const ports = parsePortsLocal(portsStr);

if (ports.length === 0) {

alert(“유효한 포트가 없습니다. (예: 80,443 또는 1-100)”);

return;

}

​

let concurrency = parseInt(concurrencyInput.value, 10);

if (isNaN(concurrency) || concurrency <= 0) {

concurrency = 10;

}

if (concurrency > 200) {

concurrency = 200;

}

concurrencyInput.value = concurrency;

​

// 초기화

portScanAbort = false;

portResults = [];

portTableBody.innerHTML = “”;

portProgressDiv.textContent = “”;

portScanLogDiv.textContent = “”;

openPortSummaryDiv.textContent = “”;

portScanStartBtn.disabled = true;

portScanStopBtn.disabled = false;

downloadCsvBtn.disabled = true;

downloadJsonBtn.disabled = true;

​

const total = ports.length;

let done = 0;

let index = 0;

​

portScanLogDiv.textContent =

`스캔 시작: ${target}, 포트 ${total}개 (동시 스캔 수: ${concurrency})`;

portScanLogDiv.textContent += “\\n포트 목록: ” + ports.join(“, “);

​

async function worker() {

while (!portScanAbort) {

let currentIndex;

if (index >= total) break;

currentIndex = index++;

const port = ports[currentIndex];

​

portProgressDiv.textContent =

`진행: ${done} / ${total} (현재 포트: ${port})`;

​

try {

const data = await scanPortOnce(target, port);

​

const tr = document.createElement(“tr”);

const tdPort = document.createElement(“td”);

const tdStatus = document.createElement(“td”);

const tdNote = document.createElement(“td”);

​

tdPort.textContent = port;

if (data.open) {

tdStatus.innerHTML = ‘<span class=”status-ok”>OPEN</span>’;

} else {

tdStatus.innerHTML = ‘<span class=”status-fail”>CLOSED</span>’;

}

tdNote.textContent = data.note || “”;

​

tr.appendChild(tdPort);

tr.appendChild(tdStatus);

tr.appendChild(tdNote);

portTableBody.appendChild(tr);

​

portResults.push({

port: port,

open: !!data.open,

note: data.note || “”

});

​

} catch (e) {

const tr = document.createElement(“tr”);

tr.innerHTML = ‘<td>’ + port + ‘</td>’ +

‘<td><span class=”status-fail”>ERROR</span></td>’ +

‘<td>’ + e + ‘</td>’;

portTableBody.appendChild(tr);

​

portResults.push({

port: port,

open: false,

note: “에러: ” + e

});

}

​

done += 1;

portProgressDiv.textContent = `진행: ${done} / ${total}`;

}

}

​

const workers = [];

const numWorkers = Math.min(concurrency, total);

for (let i = 0; i < numWorkers; i++) {

workers.push(worker());

}

​

await Promise.all(workers);

​

updateOpenPortSummary();

​

if (!portScanAbort) {

portScanLogDiv.textContent += “\\n스캔 완료.”;

} else {

portScanLogDiv.textContent += “\\n사용자에 의해 스캔 중단됨.”;

}

​

portScanStartBtn.disabled = false;

portScanStopBtn.disabled = true;

if (portResults.length > 0) {

downloadCsvBtn.disabled = false;

downloadJsonBtn.disabled = false;

}

}

​

function stopPortScan() {

portScanAbort = true;

portScanStopBtn.disabled = true;

portScanLogDiv.textContent += “\\n정지 요청됨…”;

}

​

portScanStartBtn.addEventListener(“click”, startPortScan);

portScanStopBtn.addEventListener(“click”, stopPortScan);

downloadCsvBtn.addEventListener(“click”, downloadCSV);

downloadJsonBtn.addEventListener(“click”, downloadJSON);

</script>

</body>

</html>

“””

​

# —————- Ping 관련 함수 —————-

​

def parse_latency(output: str):

“””

ping 출력에서 time=XXms / time=XX ms 패턴 찾아서 ms 값 추출

“””

pattern = r”time[=<]\s*([0-9]+(?:\.[0-9]+)?)\s*ms”

match = re.search(pattern, output, re.IGNORECASE)

if match:

try:

return float(match.group(1))

except ValueError:

return None

return None

​

​

def ping_once(target: str, timeout_ms: int = 1000):

“””

ping 1회 실행

“””

system = platform.system().lower()

​

if system.startswith(“win”):

cmd = [“ping”, “-n”, “1”, “-w”, str(timeout_ms), target]

else:

timeout_s = max(int(timeout_ms / 1000), 1)

cmd = [“ping”, “-c”, “1”, “-W”, str(timeout_s), target]

​

try:

result = subprocess.run(

cmd,

stdout=subprocess.PIPE,

stderr=subprocess.PIPE,

text=True

)

except Exception as e:

return False, None, f”ping 실행 에러: {e}”

​

success = (result.returncode == 0)

latency = parse_latency(result.stdout)

raw_output = result.stdout if result.stdout.strip() else result.stderr

​

return success, latency, raw_output

​

​

def ping_multi(target: str, count: int, timeout_ms: int = 1000, interval_sec: float = 0.2):

“””

같은 대상에 대해 여러 번 ping 실행

“””

detail_rows = []

last_output = “”

for _ in range(count):

success, latency_ms, raw_output = ping_once(target, timeout_ms=timeout_ms)

last_output = raw_output

detail_rows.append({

“success”: success,

“latency_ms”: latency_ms,

“timestamp”: datetime.now().strftime(“%H:%M:%S”),

})

if _ < count – 1:

time.sleep(interval_sec)

​

total = len(detail_rows)

success_cnt = sum(1 for r in detail_rows if r[“success”])

fail_cnt = total – success_cnt

loss_rate = round(fail_cnt / total * 100, 1) if total > 0 else 0.0

​

latencies = [r[“latency_ms”] for r in detail_rows if r[“latency_ms”] is not None]

if latencies:

min_ms = round(min(latencies), 1)

max_ms = round(max(latencies), 1)

avg_ms = round(sum(latencies) / len(latencies), 1)

else:

min_ms = max_ms = avg_ms = “-“

​

summary = {

“total”: total,

“success”: success_cnt,

“fail”: fail_cnt,

“loss_rate”: loss_rate,

“min_ms”: min_ms,

“max_ms”: max_ms,

“avg_ms”: avg_ms,

}

​

return summary, detail_rows, last_output

​

​

# —————- 포트 스캔 관련 함수 —————-

​

def scan_port(target: str, port: int, timeout: float = 1.0):

“””

TCP 포트 1개 스캔 (열림/닫힘)

“””

sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)

sock.settimeout(timeout)

try:

result = sock.connect_ex((target, port))

if result == 0:

return True, “연결 성공”

else:

return False, f”연결 실패 (코드: {result})”

except Exception as e:

return False, f”예외 발생: {e}”

finally:

sock.close()

​

​

# —————- Flask 라우팅 —————-

​

@app.route(“/”, methods=[“GET”])

def index():

return render_template_string(

PAGE_TEMPLATE,

target=””,

count=4,

continuous=False,

ports=””,

concurrency=20,

summary=None,

detail=None,

raw_output=None,

)

​

​

@app.route(“/run_test”, methods=[“POST”])

def run_test():

target = request.form.get(“target”, “”).strip()

count_str = request.form.get(“count”, “4”).strip()

continuous = bool(request.form.get(“continuous”))

ports_input = request.form.get(“ports”, “”).strip()

​

summary = None

detail = None

raw_output = None

​

if not target:

return render_template_string(

PAGE_TEMPLATE,

target=target,

count=count_str,

continuous=continuous,

ports=ports_input,

concurrency=20,

summary=None,

detail=None,

raw_output=None,

)

​

try:

count = int(count_str)

if count <= 0:

count = 1

except ValueError:

count = 4

​

summary, detail, raw_output = ping_multi(target, count=count, timeout_ms=1000)

​

return render_template_string(

PAGE_TEMPLATE,

target=target,

count=count,

continuous=False,

ports=ports_input,

concurrency=20,

summary=summary,

detail=detail,

raw_output=raw_output,

)

​

​

@app.route(“/api/ping_once”, methods=[“GET”])

def api_ping_once():

target = request.args.get(“target”, “”).strip()

if not target:

return jsonify({

“success”: False,

“latency_ms”: None,

“target”: “”,

“timestamp”: datetime.now().strftime(“%H:%M:%S”),

“error”: “target parameter is required”,

})

​

success, latency_ms, raw_output = ping_once(target, timeout_ms=1000)

return jsonify({

“success”: success,

“latency_ms”: latency_ms,

“target”: target,

“timestamp”: datetime.now().strftime(“%H:%M:%S”),

“raw_output”: raw_output,

})

​

​

@app.route(“/api/scan_port”, methods=[“GET”])

def api_scan_port():

target = request.args.get(“target”, “”).strip()

port_str = request.args.get(“port”, “”).strip()

​

if not target or not port_str:

return jsonify({

“open”: False,

“note”: “target 또는 port 파라미터가 없습니다.”,

})

​

try:

port = int(port_str)

except ValueError:

return jsonify({

“open”: False,

“note”: “포트 번호가 잘못되었습니다.”,

})

​

is_open, note = scan_port(target, port, timeout=1.0)

return jsonify({

“open”: is_open,

“note”: note,

})

​

​

if __name__ == “__main__”:

# threaded=True: 동시에 여러 /api/scan_port 요청 처리

app.run(host=”0.0.0.0″, port=9999, debug=True, threaded=True)

========== end =====================

게시물 파이썬으로 네트워크 ping, portscan 웹 화면에서 체크 프로그램이 하우인포-IT·테크에 처음 등장했습니다.