로컬 AI 음성 읽기 가이드

Social Stream Ninja는 로컬 AI 음성 합성을 사용해 채팅 메시지를 소리 내어 읽을 수 있습니다. '로컬'은 두 가지 의미가 있습니다. 브라우저 안에서 음성이 실행되거나, 자신의 컴퓨터에서 작은 음성 읽기 서버를 실행하는 것입니다.

두 가지 방식이 있습니다:

대부분의 방송자에게 가장 간단한 방법입니다:

가장 흔한 로컬 음성 읽기 설정 실수입니다.

Linux, macOS, Windows에서는 방화벽이 포트를 허용하고 Docker가 다음 옵션으로 포트를 공개했는지도 확인하세요: -p 8880:8880.

확장 프로그램 팝업에서 음성 읽기 제공업체 선택기를 열고 다음을 선택하세요: 사용자 지정 / 로컬 음성 읽기 엔드포인트 (Custom / Local TTS Endpoint)을 선택하세요. OpenAI 호환 로컬 엔드포인트 입력란과 이 가이드로 돌아오는 링크가 표시됩니다.

SSN은 로컬/자체 호스팅 음성 읽기 서버를 OpenAI 호환 음성 엔드포인트처럼 취급합니다. 기본 흐름은 다음과 같습니다:

요청 형식

예를 들어 ttsprovider=customtts, localtts, 또는 openai인 경우 SSN이 설정된 엔드포인트에 JSON POST를 보냅니다:

CORS, 호스팅 페이지, 브리지

CORS는 브라우저의 권한 확인입니다. 쉽게 말해 음성 읽기 서버가 브라우저에 '이 페이지는 내게 오디오를 요청해도 된다'고 알려야 합니다. 이 허용이 없으면 Kokoro나 다른 음성 읽기 서버에 요청이 도착하기도 전에 차단될 수 있습니다.

• 다음을 로드하면 dock.html 을 Chrome 또는 OBS에서 로드하면 CORS가 영향을 줄 수 있습니다.
• 다음과 같은 호스팅 페이지를 로드하면 https://beta.socialstream.ninja/dock.html인 경우 Chrome이 로컬 또는 사설 HTTP 주소에 대한 호출도 차단할 수 있습니다.
• SSN 앱의 테스트 버튼은 작동하지만 OBS 브라우저 소스에서 소리가 나지 않으면 OBS를 별도로 시험하세요. OBS는 자체 브라우저를 사용합니다.

서버가 브라우저 요청을 허용하지 않으면 다음을 실행하세요: SSN 로컬 음성 읽기 브리지 을 실행하고 SSN이 다음을 가리키도록 하세요: http://127.0.0.1:8124/v1/audio/speech입니다. OBS에서는 OBS와 같은 컴퓨터에서 브리지를 실행하는 구성이 가장 쉽습니다.

지원되는 오디오 응답

스트리밍 오디오

SSN은 현재 사용자 지정/로컬 음성 읽기 엔드포인트의 점진적 재생을 지원하지 않습니다. 응답 blob 또는 JSON 오디오 페이로드를 기다린 뒤 재생합니다. 일부 상위 서버는 스트리밍 엔드포인트를 제공하지만 SSN의 현재 OpenAI 호환 경로는 재생 전에 버퍼링합니다.

실용적인 결론은 채팅 음성 읽기를 짧게 유지하는 것입니다. 스트리밍을 지원하려면 스트리밍 WAV/MP3 청크, MediaSource, WebCodecs 또는 서버 측 믹서를 이용하는 별도의 재생 경로가 필요합니다.

이 엔진들은 Social Stream Ninja에 포함되어 있어 설치가 필요하지 않습니다. WebAssembly(WASM) 또는 ONNX Runtime을 사용해 브라우저에서 실행됩니다.

활성화 방법

추가: &ttsprovider= 그리고 &speech= 를 Social Stream에 추가하세요: dock.html URL:

Kokoro TTS 옵션

현재 SSN에는 영어 28개, 스페인어 3개, 브라질 포르투갈어 3개의 Kokoro 음성이 있습니다. 다음 매개변수로 음성을 지정하세요: &voicekokoro=:

스페인어 예시:

포르투갈어 예시:

Piper TTS 옵션

다음으로 음성 모델을 지정하세요: &pipervoice=:

포르투갈어 및 스페인어 Piper 음성을 사용할 수 있습니다:

Kitten TTS 옵션

eSpeak-NG 옵션

Chrome 확장 프로그램, OBS 브라우저 소스, 독립 실행형 Social Stream Ninja 데스크톱 앱은 모두 동일한 dock.html 음성 읽기 URL 매개변수를 사용합니다. 중요한 차이는 소리가 생성되는 위치입니다.

더 많은 음성, 음성 복제, 여러 도구에서 재사용할 전용 서버가 필요하다면 로컬 음성 읽기 서버를 실행할 수 있습니다. Social Stream Ninja는 내장된 다음 기능으로 연결합니다: OpenAI 호환 음성 읽기 엔드포인트 기능을 사용합니다. 로컬 서버에는 API 키가 필요하지 않습니다.

권장 옵션 세 가지:

어떤 패키지가 적합할까요?

음성 복제는 별도의 SSN 모드가 아닙니다. 일부 로컬 음성 읽기 서버 내부의 기능입니다. SSN은 채팅 텍스트를 로컬 엔드포인트로 보내고, 서버는 저장된 참조 오디오 파일, 음성 프로필 또는 브리지 설정에서 복제 음성을 선택합니다.

일반적인 흐름

1. 일반적으로 배경 소음이 적은 한 사람의 목소리를 3~30초 길이로 녹음하여 깨끗한 참조 클립을 준비하세요.
2. 일부 엔진에는 참조 클립의 정확한 대본도 필요합니다.
3. 로컬 서버가 참조 오디오를 화자 프롬프트, 임베딩 또는 음성 프로필로 변환합니다.
4. SSN은 다음을 사용해 라이브 채팅 텍스트를 엔드포인트로 보냅니다: ttsprovider=customtts.
5. 서버는 보통 WAV 또는 MP3 형식의 재생 가능한 오디오 파일을 반환하고, SSN은 이를 도크/브라우저 소스에서 재생합니다.

VRAM이 6 GB 이하라면 소형 제로샷 음성 복제 모델과 OpenAI 호환 서버를 먼저 고려하세요. 더 큰 모델도 다른 곳에 호스팅하면 같은 SSN 엔드포인트를 통해 사용할 수 있습니다.

이는 실용적인 시작 기준이며 확정적인 보장은 아닙니다. 모델 버전, 양자화, 텍스트 길이, Docker 이미지, 백그라운드 앱에 따라 메모리 사용량이 달라질 수 있습니다.

SSN 호환성을 확인한 자체 호스팅 음성 복제 대상입니다. 로컬 엔드포인트 경로는 다음 두 환경에서 시험했습니다: dock.html 그리고 featured.html.

SSN은 직접 바이너리 오디오 응답, base64 오디오가 포함된 JSON 응답, 오디오 URL이 포함된 JSON 응답을 받습니다. 현재 사용자 지정/로컬 재생은 반환된 오디오를 버퍼링한 뒤 재생하며 점진적 스트리밍 재생은 아직 지원하지 않습니다.

Kokoro-FastAPI 는 OpenAI 호환 API를 제공하는 로컬 서버로 Kokoro 82M 모델을 실행합니다. CPU에서 작동하며 GPU가 필요하지 않고 음성 품질이 뛰어납니다.

Docker로 설치

터미널(명령 프롬프트, PowerShell 또는 Terminal)을 열고 다음 중 하나를 실행하세요:

CPU (모든 컴퓨터에서 작동):

GPU (NVIDIA 전용 — 더 빠른 합성):

실행 확인

브라우저를 열고 다음 주소로 이동하세요: http://localhost:8880/web/— 음성을 시험할 수 있는 웹 UI가 표시되어야 합니다.

사용 가능한 음성

67개 이상의 음성을 사용할 수 있습니다. 주요 예:

다음에서 모든 음성을 살펴보고 시험하세요: http://localhost:8880/web/ 를 서버 실행 후 여세요.

SSN URL

Kokoro-FastAPI가 OBS와 같은 컴퓨터에 있다면:

Kokoro-FastAPI가 다른 컴퓨터에 있으면 다음 값을 바꾸세요: 192.168.x.x 을 해당 컴퓨터의 LAN IP 주소로 바꾸세요:

서버 실행 유지

Kokoro-FastAPI가 백그라운드에서 자동으로 계속 실행되도록 하려면 Docker의 다시 시작 플래그를 사용하세요:

이제 재부팅할 때마다 Docker Desktop과 함께 자동으로 시작됩니다.

openedai-speech 는 OpenAI 호환 /v1/audio/speech 엔드포인트를 제공합니다. 소형 이미지는 CPU에서 Piper를 실행하며 전체 이미지는 지원 GPU에서 XTTS-v2 음성 복제를 실행할 수 있습니다.

옵션 A: 경량 Piper

1 GB 미만의 CPU 전용 음성 읽기 서버를 원한다면 이 옵션을 사용하세요. XTTS-v2나 음성 복제는 포함하지 않습니다.

Docker Compose로 설치

Windows 소스 설치 참고

Docker 대신 로컬 체크아웃에서 openedai-speech를 실행한다면 가상 환경의 스크립트 폴더를 다음에 추가하세요: PATH 에 추가한 뒤 서버를 시작하세요. 이를 하지 않으면 서버가 다음을 찾지 못해 요청에 HTTP 500이 반환될 수 있습니다: piper.exe 또는 ffmpeg.exe.

사용 가능한 음성

openedai-speech는 Piper 음성에 매핑된 OpenAI 방식 음성 이름을 사용합니다:

SSN URL

옵션 B: XTTS-v2 음성 복제

XTTS-v2 자체는 웹 API가 아닌 모델입니다. 전체 openedai-speech 서버로 모델을 로드하고 저장된 참조 음성을 선택하고 SSN의 채팅 텍스트를 받아 재생 가능한 오디오를 반환하세요. 서버 안내에 따르면 실용적인 GPU VRAM 기준은 약 4 GB이며, CPU 추론도 가능하지만 느립니다.

macOS 또는 Linux에서는 다음을 사용하세요: cp sample.env speech.env 를 사용하세요. 대체할 값: Copy-Item입니다. Docker에서 지원되는 GPU에 접근할 수 있어야 합니다. 모델은 처음 사용할 때 다운로드됩니다.

다음 항목에 이미 나열된 기존 음성을 유지하세요: tts-1-hd를 유지하세요. 변경할 값: me 을 SSN이 보낼 음성 이름으로 바꾸고 필요하면 올바른 XTTS 언어 코드를 사용하세요.

브라우저나 OBS가 직접 요청을 차단하면 다음을 실행하세요: 로컬 음성 읽기 브리지 를 OBS 컴퓨터에서 실행하고 모델 및 음성 매개변수는 유지한 채 다음 값만 변경하세요: openaiendpoint 대상: http://127.0.0.1:8124/v1/audio/speech.

브리지는 작은 로컬 보조 프로그램입니다. SSN의 브라우저 요청을 받아 음성 읽기 서버와 통신한 뒤 브라우저에 맞는 헤더와 함께 오디오를 SSN에 반환합니다.

독립 실행형 시작 폴더는 local-tts-bridge/입니다. 참고: 브리지 README 에서 모든 시작 옵션을 확인하세요.

OpenAI 호환 프록시

음성 읽기 서버가 같은 컴퓨터에 있는 경우 Windows PowerShell:

음성 읽기 서버가 다른 컴퓨터에 있는 경우 Windows PowerShell:

macOS/Linux 터미널:

그런 다음 OBS의 dock.html URL이 브리지를 가리키도록 설정하세요:

GPT-SoVITS 프록시 모드

GPT-SoVITS는 자체 /tts JSON 형식을 사용하므로 브리지가 SSN의 OpenAI 호환 요청을 GPT-SoVITS 요청 본문으로 변환할 수 있습니다.

F5-TTS 서버 프록시 모드

일부 F5-TTS 서버 래퍼는 다음을 제공합니다: /synthesize_speech/?text=...&voice=... 를 OpenAI 호환 엔드포인트 대신 제공합니다. 브리지가 SSN 요청을 해당 쿼리 형식으로 변환할 수 있습니다.

위의 모든 자체 호스팅 서버는 같은 연결 방식인 Social Stream의 내장 OpenAI 음성 읽기 엔드포인트 기능과 사용자 지정 로컬 URL을 사용합니다.

URL 매개변수

전체 예제 URL

Kokoro-FastAPI:

openedai-speech:

kokoro-web:

추가 음성 읽기 옵션

로컬 서버를 포함한 모든 음성 읽기 제공업체에서 사용할 수 있습니다:

지원할 만한 내장 브라우저 옵션

SSN은 이미 OS/브라우저의 speechSynthesis, 내장 Kokoro, Piper, Kitten, eSpeak를 이미 지원합니다. 향후 브라우저 기능으로 특히 유용한 것은 다음 기능을 사용할 수 있을 때의 오디오 출력 장치 선택기입니다: setSinkId 를 지원하는 환경, 더 다양한 Piper 음성, 오디오 청크를 스트리밍하는 서버용 전용 점진적 스트리밍 재생 경로입니다.

OBS에서 음성 읽기 오디오를 캡처하는 방법은 Social Stream Ninja의 실행 방식에 따라 다릅니다.

방법 1 — OBS 브라우저 소스 추천

가장 간단한 방법이며 다음에 사용할 수 있습니다: 모든 음성 읽기 제공업체 (내장 및 자체 호스팅 서버).

방법 2 — SSN 데스크톱 앱 + 데스크톱 오디오

OBS 브라우저 소스가 아닌 Social Stream Ninja 독립 실행형 데스크톱 앱을 사용한다면:

Windows 오디오 라우팅 링크

Windows 10 앱별 라우팅

Windows 11 앱별 라우팅

Audio Router 소프트웨어

Audio Router 는 특정 앱을 가상 케이블로 라우팅할 수 있지만 오래된 소프트웨어입니다. 작동한다면 Windows 앱별 라우팅을 우선 사용하세요.

Voicemeeter 고급 라우팅

Voicemeeter 는 음성 읽기를 로컬에서 듣고 OBS로 라우팅하면서 음악/게임 오디오와 분리해야 할 때 가장 적합합니다.

* 시스템 음성 읽기를 OBS에서 캡처하려면 가상 오디오 케이블로 라우팅해야 합니다.

SSN 앱 테스트는 작동하지만 OBS에서 소리가 나지 않음

앱 테스트는 앱에서 서버에 접근할 수 있다는 것만 확인합니다. OBS 브라우저 소스도 엔드포인트에 접근하고 오디오를 재생할 수 있어야 합니다.

• OBS와 음성 읽기 서버가 서로 다른 컴퓨터에 있으면 다음 값을 바꾸세요: 127.0.0.1 을 음성 읽기 서버 컴퓨터의 LAN IP로 바꾸세요.
• OBS 브라우저 소스에서 다음을 확인하세요: OBS를 통해 오디오 제어(Control audio via OBS) 가 선택되어 있는지 확인하세요.
• 브라우저가 요청을 차단하면 OBS 컴퓨터에서 SSN 로컬 음성 읽기 브리지를 시험하세요.

첫 글자나 처음 몇 단어만 읽음

• 실제 OBS URL에서 다음을 확인하세요: ttsquick을 확인하세요. 이 옵션은 의도적으로 읽는 내용을 짧게 자릅니다.
• 다음이 표시되면 &ttsquick=14 또는 다른 작은 숫자가 있다면 제거하고 OBS 브라우저 소스를 새로고침하세요.
• 다음을 사용한다면 typewriter=를 사용한다면 테스트 중에는 잠시 제거하세요. 음성 읽기는 보통 원본 메시지를 사용하지만, 시각 효과를 제거하면 타이밍 문제 여부를 빠르게 확인할 수 있습니다.

로컬 서버가 응답하지 않음

• Docker가 실행 중이고 컨테이너도 계속 실행 중인지 확인하세요.
• 음성 읽기 서버 컴퓨터에서 다음을 여세요: http://127.0.0.1:8880/web/ 를 Kokoro-FastAPI에 사용하거나 서버에 맞는 포트를 사용하세요.
• OBS 컴퓨터에서 다음을 여세요: http://SERVER_LAN_IP:8880/web/를 여세요. 로드되지 않으면 OBS도 해당 서버를 사용할 수 없습니다.
• LAN IP가 로드되지 않으면 서버 컴퓨터의 방화벽을 확인하세요.

CORS 또는 로컬 네트워크 차단

브라우저에 CORS, 로컬 네트워크 접근, 사설 네트워크 접근 또는 fetch 실패로 요청이 차단되었다고 표시되면 음성 읽기 서버가 요청을 전혀 받지 못했을 수 있습니다.

• 실행: npm run local-tts-bridge 를 OBS 컴퓨터에서 실행하고 SSN이 다음을 사용하도록 설정하세요: http://127.0.0.1:8124/v1/audio/speech.
• 호스팅된 베타 도크 페이지를 사용한다면 브라우저가 로컬 HTTP 엔드포인트를 차단할 가능성이 더 높습니다. 대개 브리지나 로컬 앱 창을 사용하는 것이 더 쉽습니다.

잘못된 음성 또는 음성을 찾을 수 없음

• Kokoro-FastAPI: 시험할 음성 af_bella, af_sarah, am_adam또는 Kokoro 웹 UI의 다른 음성을 사용하세요.
• openedai-speech: 다음과 같은 음성 nova, echo, 그리고 alloy 등이 유효할 수 있습니다.
• 일부 서버에서는 음성 이름의 대소문자를 구분합니다.

소리는 나지만 OBS에서 캡처하지 못함

• 다음을 확인하세요: OBS를 통해 오디오 제어(Control audio via OBS) 가 브라우저 소스 속성에서 선택되어 있는지 확인하세요.
• 테스트 메시지가 재생되는 동안 OBS 오디오 믹서를 확인하세요. 브라우저 소스 미터가 움직여야 합니다.
• 시스템 음성 읽기만 사용하고 있지 않은지 확인하세요(?speech=en-US 에서 다음을 제외한 경우 &ttsprovider=). 시스템 음성 읽기는 데스크톱 오디오나 가상 케이블 캡처가 필요할 수 있습니다.

Docker 이미지를 찾을 수 없음

Docker 이미지 태그는 바뀔 수 있습니다. 이 가이드의 명령이 더 이상 작동하지 않으면 프로젝트 페이지에서 최신 태그를 확인하세요:

• Kokoro-FastAPI: github.com/remsky/Kokoro-FastAPI
• openedai-speech: github.com/matatonic/openedai-speech