Windows TTS Broadcast Service

Windows 환경에서 항상 실행되고, 종료·방송 실패 시 자동 복구되는 TTS 백그라운드 방송 서비스입니다.

🆕 NEW: 다중 지점 웹 관리 시스템

완전한 웹 기반 관리 인터페이스가 새롭게 추가되었습니다!

• 🌐 전문적인 웹 UI: 다중 지점 TTS 운영을 위한 모던하고 반응형 인터페이스
• 🔐 역할 기반 접근 제어: 슈퍼 관리자와 지점 관리자 역할 및 권한 기반 접근
• 📊 실시간 대시보드: 라이브 통계, 활동 모니터링, 시스템 상태 확인
• 🎤 웹 기반 방송: 웹 인터페이스에서 즉시 또는 예약 방송 전송
• 📱 모바일 친화적: 데스크톱, 태블릿, 모바일에서 작동하는 반응형 디자인

📖 다중 지점 가이드 보기 →

빠른 데모 설정

# 의존성 설치 및 데모 데이터 설정
npm install
npm run setup:demo

# 서비스 시작
npm start

# 웹 인터페이스 접속: http://localhost:5000
# 로그인: [email protected] / admin123 (슈퍼 관리자)
# 또는: [email protected] / demo123 (지점 관리자)

🎯 주요 기능

• 자동 복구: 서비스 종료나 실패 시 자동으로 재시작
• 이중 TTS 엔진: Google Cloud TTS (우선) + 로컬 TTS (fallback)
• Windows 서비스: node-windows를 이용한 완전한 백그라운드 서비스
• REST API: HTTP 요청으로 TTS 실행
• 한국어 지원: 한국어 TTS 최적화
• 🔥 NEW: 두 가지 공개 패키지: npm 공개 패키지 + GitHub Package Registry 모두 지원
• PC 자동 등록: 설치 시 관리자 페이지에 자동 등록 및 실시간 상태 표시
• 🌐 GitHub Pages 배포: 웹 관리자 인터페이스 자동 배포
• 📦 공개 패키지 배포: 인증 없이 누구나 설치 가능한 패키지

🌐 온라인 관리자 인터페이스

웹 관리자 인터페이스가 GitHub Pages에 자동으로 배포됩니다:

• URL: https://team-cats.github.io/windowsBroadcast
• 배포: main 브랜치 푸시 시 자동 배포

🚀 빠른 설치

⭐ 방법 1: EXE 실행 파일 (신규 추가 - 초보자 최적화) 🎯

지점 설치 직원을 위한 가장 쉬운 방법! 별도 프로그램 없이 바로 실행 가능한 EXE 파일입니다.

🎉 설치 방법 (매우 간단!)

1. install-windows.exe 다운로드
2. 파일을 우클릭 → "관리자 권한으로 실행"
3. 화면의 지시를 따르세요 (완전 자동!)

📂 다른 EXE 파일들

• quick-install.exe - Node.js가 이미 설치된 환경용
• uninstall.exe - 서비스 완전 제거용

✅ EXE 설치의 장점

• ✅ 초보자 친화적: 컴퓨터 초보자도 쉽게 사용
• ✅ 별도 프로그램 불필요: 추가 소프트웨어 설치 없이 바로 실행
• ✅ 실행 파일 형태: Windows에서 바로 더블클릭 가능
• ✅ 완전 자동화: 클릭 몇 번으로 모든 설치 완료

📋 EXE 파일 사용법 상세 가이드 →

📦 방법 2: 공개 패키지 설치 (인증 불필요!)

NPM 공개 레지스트리 (권장)

# 관리자 권한 명령 프롬프트에서 실행
npm install -g mtgmtg1-windows-tts-broadcast
npm run install-service

GitHub Package Registry

# GitHub 패키지 설정
npm config set @team-cats:registry https://npm.pkg.github.com
npm install -g @team-cats/mtgmtg1-windows-tts-broadcast
npm run install-service

공개 패키지의 장점:

• ✅ 인증 불필요: GitHub 토큰이나 로그인 과정 없음
• ✅ 전세계 접근: 누구나 설치 가능한 공개 패키지
• ✅ 두 가지 옵션: npm 공개 레지스트리 + GitHub Package Registry
• ✅ 자동 배포: 코드 변경 시 자동으로 패키지 업데이트
• ✅ 단계별 검증 및 롤백 지원

🛠️ 방법 3: 수동 설치 (개발자용)

Node.js가 이미 설치된 환경에서의 수동 설치 방법입니다.

1. Node.js 설치 (https://nodejs.org/)

2. 의존성 설치

   npm install

3. 서비스 설치

   npm run install-service

📋 사전 요구사항

• Node.js 16.0.0 이상
• Windows 10/11 또는 Windows Server
• 관리자 권한 (Windows 서비스 설치용)

🔧 Google Cloud TTS 설정 (선택사항)

고품질 TTS를 위해 Google Cloud TTS를 설정할 수 있습니다:

1. Google Cloud Console에서 프로젝트 생성
2. Text-to-Speech API 활성화
3. 서비스 계정 키 생성 (JSON 형식)
4. 환경 변수 설정:

   set GOOGLE_APPLICATION_CREDENTIALS=C:\path\to\your\service-account-key.json

Google Cloud TTS가 설정되지 않은 경우, 자동으로 Windows 내장 TTS를 사용합니다.

🎮 사용법

API 엔드포인트

1. 건강 상태 확인

GET http://localhost:5000/health

2. TTS 실행 (GET 방식)

GET http://localhost:5000/tts?txt=안녕하세요

3. TTS 실행 (POST 방식)

POST http://localhost:5000/tts
Content-Type: application/json

{
  "text": "안녕하세요"
}

사용 예제

curl 사용

# 건강 상태 확인
curl http://localhost:5000/health

# 한국어 TTS
curl "http://localhost:5000/tts?txt=안녕하세요"

# 영어 TTS
curl -X POST http://localhost:5000/tts -H "Content-Type: application/json" -d "{\"text\":\"Hello world\"}"

JavaScript 사용

// GET 방식
fetch('http://localhost:5000/tts?txt=' + encodeURIComponent('안녕하세요'))
  .then(response => response.json())
  .then(data => console.log(data));

// POST 방식
fetch('http://localhost:5000/tts', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ text: '안녕하세요' })
})
  .then(response => response.json())
  .then(data => console.log(data));

🔍 테스트

서비스가 올바르게 작동하는지 테스트:

npm test

⚙️ 설정

config.js 파일을 수정하여 서비스를 커스터마이징할 수 있습니다:

module.exports = {
  server: {
    port: 5000  // 포트 변경
  },
  googleTTS: {
    voice: {
      languageCode: 'ko-KR',
      name: 'ko-KR-Standard-A'  // 음성 변경
    }
  },
  // ... 기타 설정
};

🛠️ 서비스 관리

Windows 서비스 관리

# 서비스 상태 확인
services.msc

# 서비스 제거
npm run uninstall-service

# 서비스 재설치
npm run install-service

로그 확인

• 로그 위치: logs/ 폴더
• combined.log: 전체 로그
• error.log: 에러 로그

🔄 자동 복구 기능

서비스가 실패하거나 종료될 경우 자동으로 복구됩니다:

• 자동 재시작: 최대 3회 연속 재시도
• 지연 증가: 재시도 간격이 점진적으로 증가
• 시간당 제한: 시간당 최대 5회 재시작

📁 프로젝트 구조

windowsBroadcast/
├── server.js              # 메인 서버
├── install-service.js     # 서비스 설치 스크립트
├── uninstall-service.js   # 서비스 제거 스크립트
├── test-tts.js           # 테스트 스크립트
├── config.js             # 설정 파일
├── setup.bat             # 자동 설치 스크립트
├── uninstall.bat         # 자동 제거 스크립트
├── package.json          # 의존성 정보
├── logs/                 # 로그 파일들
└── audio/                # 임시 오디오 파일들

🐛 문제 해결

일반적인 문제들

1. "포트가 이미 사용 중"

   • 다른 프로그램이 5000번 포트 사용 중
   • config.js에서 포트 변경

2. "관리자 권한 필요"

   • 명령 프롬프트를 관리자 권한으로 실행

3. "TTS 실패"

   • Google Cloud 인증 확인
   • Windows TTS 서비스 상태 확인

4. "서비스 설치 실패"

   • Node.js 설치 확인
   • 관리자 권한 확인

로그 확인

# 최근 로그 확인
type logs\combined.log

# 에러 로그만 확인
type logs\error.log

📞 API 응답 예제

성공 응답

{
  "status": "success",
  "message": "TTS played successfully",
  "requestId": "abc123-def456",
  "duration": "1500ms"
}

에러 응답

{
  "status": "error",
  "message": "No text provided",
  "requestId": "abc123-def456",
  "usage": "GET /tts?txt=텍스트 or POST /tts with {\"text\": \"텍스트\"}"
}

🏗️ 개발자를 위한 정보

개발 모드 실행

npm start

의존성

• express: HTTP 서버
• @google-cloud/text-to-speech: Google Cloud TTS
• node-windows: Windows 서비스
• say: 로컬 TTS fallback
• play-sound: 오디오 재생
• winston: 로깅

🚀 GitHub Actions 워크플로우

이 프로젝트는 다음과 같은 자동화된 워크플로우를 제공합니다:

1. GitHub Pages 배포

• 파일: .github/workflows/deploy-pages.yml
• 트리거: main 브랜치 푸시 시 자동 실행
• 기능: public/ 디렉토리의 웹 관리자 인터페이스를 GitHub Pages에 배포
• URL: https://team-cats.github.io/windowsBroadcast

2. 공개 NPM 패키지 배포

• 파일: .github/workflows/publish-package.yml
• 트리거: 릴리즈 생성 시 또는 수동 실행
• 기능: 공개 npm registry에 패키지 배포 (인증 불필요한 설치)
• 패키지명: mtgmtg1-windows-tts-broadcast
• 설정 가이드: NPM_PUBLISHING_SETUP.md

3. CI/CD 테스트

• 파일: .github/workflows/ci.yml
• 트리거: 푸시/PR 시 자동 실행
• 기능: Node.js 16/18/20 버전에서 테스트 실행 및 패키지 검증

패키지 배포 방법

# 새 릴리즈 생성 (GitHub UI 또는 명령어)
gh release create v1.0.1 --title "Release v1.0.1" --notes "Bug fixes and improvements"

# 또는 워크플로우 수동 실행
gh workflow run publish-package.yml

📄 라이선스

MIT License

🤝 기여

버그 리포트나 기능 요청은 GitHub Issues를 이용해주세요.