Say, Pi Browser Extension

자연스러운 핸즈프리 음성 상호작용으로 AI 대화를 변환하세요.

Say, Pi는 다국어 음성 기능을 AI 챗봇에 가져다주는 브라우저 확장 프로그램입니다. 엔터프라이즈급 아키텍처와 최신 웹 표준으로 구축되어 Pi.ai, Claude.ai, ChatGPT 전반에서 정확한 음성 인식과 자연스러운 Text-to-Speech를 제공합니다.

Firefox Add-ons

License

데모 시청하기 • Chrome용 설치하기 • Firefox용 설치하기 • 문서화

Say, Pi란 무엇인가?

Say, Pi는 정교한 음성 상호작용으로 AI 채팅 경험을 향상시키는 3계층 시스템입니다:

┌─────────────────────────────────────────────────────────────┐
│                                                             │
│  Browser Extension (saypi-userscript)                       │
...

이 저장소(repository) (saypi-userscript)는 브라우저 확장 프로그램, 즉 사용자가 AI 비서와 음성 채팅을 활성화하기 위해 설치하는 클라이언트 측 구성 요소를 담고 있습니다.

주요 기능

🎙️ Voice Activity Detection (VAD)

• 실시간 음성 감지: Silero VAD (ONNX 모델) 사용
• 자연스러운 대화 흐름을 위한 지능형 분할(segmentation)
• 듀얼 모드 작동: Chrome/Edge용 비표시(Offscreen), Firefox/Safari용 표시(Onscreen) 폴백 지원
• 모든 지원 브라우저 및 챗봇 플랫폼에서 작동

🗣️ 음성-텍스트 변환 (TTS)

• 다양한 목소리 옵션을 갖춘 자연스러운 음성 합성
• Chrome Offscreen Documents API를 통한 CSP 준수 오디오 재생
• 챗봇 전용 통합: Pi.ai, Claude.ai(데스크톱 Chrome/Edge), ChatGPT(모든 브라우저)에 대한 네이티브 지원
• 플랫폼별 세부 정보는 브라우저 호환성 매트릭스 참조

🎯 정확한 음성 인식

• 고품질 전사(transcription)를 위한 OpenAI Whisper 통합
• 자동 언어 감지를 통한 다국어 지원
• 음성 입력 중 실시간 피드백

🔌 원활한 챗봇 통합

• 플러그인 구현을 갖춘 챗봇 추상화 계층(Chatbot abstraction layer)
• SPA 호환성을 위한 백오프를 사용한 점진적 DOM 관찰(Progressive DOM observation)
• 컴포넌트 간의 느슨한 결합을 위한 이벤트 기반 아키텍처(Event-driven architecture)

아키텍처 및 엔지니어링

설계 원칙

본 확장 프로그램은 브라우저 확장 프로그램에 적용된 엔터프라이즈 개발 표준을 구현합니다:

• 관심사 분리(Separation of Concerns): 명확한 경계(오디오, VAD, TTS, DOM, 인증)를 가진 모듈식 아키텍처
• 점진적 향상(Progressive Enhancement): 브라우저 및 CSP 환경 전반에 걸친 우아한 저하(Graceful degradation)
• 타입 안정성(Type Safety): 엄격한 컴파일을 갖춘 전체 TypeScript 커버리지
• 상태 관리(State Management): 예측 가능한 오디오/UI 흐름을 위한 XState 유한 상태 기계(finite state machines)
• 이벤트 기반 설계(Event-Driven Design): 디커플링된 모듈 통신을 위한 EventBus
• 테스트 용이성(Testability): 80%+ 커버리지를 갖춘 이중 테스트 프레임워크 (JavaScript용 Jest, TypeScript용 Vitest)

기술 스택

모듈 아키텍처

src/
├── chatbots/               # 챗봇별 구현체
│   ├── ChatbotService.ts   # 챗봇 감지용 팩토리
...

빌드 출력 및 성능

빌드 시스템은 바이너리 에셋을 제외하고 2MB 미만의 최적화된 번들을 생성합니다:

• 핵심 번들 (Core bundles): 8개 파일, 총 약 1.2MB 크기 (main: 450KB, vendors: 700KB)
• 동적 청크 (Dynamic chunks): 챗봇별 기능에 맞춰 지연 로딩(Lazy-loaded)됩니다.
• 이진 자산 (Binary assets): ONNX Runtime WASM 파일 1개 (14MB)와 Silero VAD 모델 1개 (2.3MB)가 포함되어 있으며, 이는 Firefox AMO 크기 제한에서 제외됩니다.
• 코드 분할 (Code splitting): 최적의 캐싱을 위해 공급자 라이브러리(Vendor libraries)가 분리되었습니다.

상세 번들 분석은 CLAUDE.md를 참조하세요.

크로스 브라우저 호환성 (Cross-Browser Compatibility)

이 확장 프로그램은 Chrome, Edge, Firefox, 및 Safari에 대해 플랫폼별 적응(adaptations)을 구현했습니다:

• Chrome/Edge (데스크톱): Offscreen Documents API를 통해 모든 기능 지원
• Firefox (데스크톱/모바일): 모든 사이트에서 VAD + STT 제공; Pi.ai와 ChatGPT에서는 TTS 제공
• Safari/모바일 Chromium: 점진적 저하(graceful degradation)가 적용된 부분적 지원

완벽한 플랫폼/기능 그리드는 Browser Compatibility Matrix를 참조하세요.

테스트 전략 (Testing Strategy)

다층적인 테스트는 브라우저와 챗봇 플랫폼 전반에 걸쳐 신뢰성을 보장합니다:

npm test              # 모든 테스트 실행 (Jest + Vitest)
npm run test:jest     # JavaScript 통합 테스트
npm run test:vitest   # TypeScript 단위 테스트

• 단위 테스트 (Unit tests): 개별 모듈의 동작 검증 (TS는 Vitest, JS는 Jest 사용)
• 통합 테스트 (Integration tests): 오디오 파이프라인, VAD/STT 흐름, DOM 관찰(DOM observation) 등
• 모의 구현 (Mock implementations): Chrome 확장 프로그램 API, 챗봇 DOM 구조 등을 모킹
• JSDOM 환경: 브라우저 없이 DOM 조작 테스트를 수행하는 환경

설치 (Installation)

사용자용 (For Users)

사용하시는 브라우저의 확장 프로그램 스토어에서 설치하세요:

• Chrome/Edge: Chrome Web Store
• Firefox: Firefox Add-ons

환경 관리(Environment Management):

# 로컬 및 원격 API 서버 간 빠른 전환
npm run switch             # 로컬/원격 토글
npm run switch local       # localhost:3000, 127.0.0.1:5001
...

Python 도구(ONNX 모델 가지치기용):

# 기기당 일회성 설정 ('.venv/' 생성)
npm run setup:python

...

완전한 개발 워크플로우 및 빌드 명령어는 CLAUDE.md를 참조하세요.

프로젝트 문서(Project Documentation)

기여자 및 개발자용 (For Contributors & Developers)

• CLAUDE.md - 아키텍처 개요, 빌드 명령어, 테스트, 모듈 구성
• CONTRIBUTING.md - 프로젝트 상태, 기여 정책, 피드백 채널
• 브라우저 호환성 매트릭스(Browser Compatibility Matrix) - 기술적 설명이 포함된 플랫폼/기능 지원 그리드

Mozilla 검토자용 (For Mozilla Reviewers)

빌드 검증(Build Verification):

이 확장 프로그램은 Webpack을 사용하여 번들링됩니다. 빌드가 제출된 코드와 일치하는지 확인하려면:

# 의존성 설치
npm install
...

빌드 환경(Build Environment):

• Node.js v22 LTS (Mozilla 검토 환경과 호환)
• npm v10
• 자세한 지침은 README:94-136를 참조하세요.

dist/ 출력물은 제출된 XPI와 정확히 일치합니다. 모든 번들링은 결정론적(deterministic)입니다.

브라우저 호환성 요약(Browser Compatibility Summary)

범례: ✅ 전체 지원 • ⚠️ 부분 지원 (음성 입력 작동, TTS 제한적일 수 있음) • ❌ 미지원

기술적 세부 정보 및 해결 방법(workarounds)은 브라우저 호환성 매트릭스를 참조하세요.

개발 및 테스트 (Development & Testing)

공통 명령어 (Common Commands)

# 개발
npm run dev               # 핫 리로드가 있는 Chrome 개발 서버
npm run dev:firefox       # Firefox 개발 (임시 프로필 열림)
...

디버그 기능 (Debug Features) (개발 전용)

VAD 세그먼트를 디스크에 저장 (음성 감지 디버깅용):

# .env 파일에 작성 (프로덕션 환경의 .env.production이 아님):
KEEP_SEGMENTS=true

...

참고: downloads 권한은 개발 빌드에서만 추가되며, 프로덕션 환경에서는 이 설정을 무시합니다.

국제화 (Internationalization, i18n)

이 확장 프로그램은 유연한 번역 워크플로우를 통해 30개 이상의 언어를 지원합니다:

전체 번역 (Quick Translation)

# 모든 콘텐츠 번역 (UI 문자열 + 스토어 설명):
npm run translate

...

특정 항목 대상 번역 (Targeted Translation) (빠른 반복 작업용)

마케팅 문구 업데이트 등 특정 키만 번역해야 할 때:

# messages.json에서 특정 키 번역:
python3 tools/i18n/i18n-translate-keys.py appName appDescription

...

어떤 도구를 언제 사용할지:

• npm run translate: 주요 릴리스 전 전체 번역 (느리지만 포괄적)
• i18n-translate-keys.py: 특정 UI 문자열 업데이트 (빠르고, 대상 지정 가능)
• i18n-translate-release-text.py: 스토어 설명만 업데이트

번역 파일 (Translation Files)

번역되는 항목:

• _locales/{locale}/messages.json: UI 문자열 (전체 동기화는 translate-cli를 통해, 대상 지정은 OpenAI를 통해)
• _locales/{locale}/description.txt: 브라우저 스토어 목록 (OpenAI API를 통해)

필수 사항:

• translate-cli (Go): go install github.com/quailyquaily/translate-cli@latest
• OpenAI API 키: `export OPENAI_API_KEY=

문의 및 지원

질문이나 피드백이 있으신가요? 여러분의 의견을 듣고 싶습니다:

• 이메일: [email protected]
• 트위터/X: @saypi_ai
• 페이스북: Say, Pi
• 디스코드: Pi Party 서버에서 저희를 찾아주세요 🥧

면책 조항

Say, Pi는 Pi.ai, Claude.ai 및 ChatGPT의 비공식 개선 기능입니다. Inflection AI, Anthropic 또는 OpenAI와 제휴하지 않습니다. 책임감 있게 사용하고 각 플랫폼의 서비스 약관을 존중해 주십시오. 향후 플랫폼 업데이트와의 호환성은 보장되지 않습니다.

Say, Pi 팀이 ❤️를 담아 제작했습니다 • www.saypi.ai