VoiceStudio는 로컬 환경에서 음성 합성 및 복제 작업을 처리할 수 있는 오픈소스 도구입니다. 이 시스템은 사용자가 조작하는 데스크톱 인터페이스와 실제 음성 생성 모델을 연산하는 로컬 백엔드 서버로 나뉘어 동작합니다. 즉, 데스크톱 앱을 열면 내부적으로 백엔드 프로세스가 함께 초기화되면서 모델을 메모리에 로드하고 API 요청을 처리하는 구조입니다.
처음 VoiceStudio를 도입하려는 사용자는 설치 스크립트 구동부터 백엔드가 지정된 포트에서 정상적으로 응답하는지 확인하는 단계까지 명확한 기준이 필요합니다. 공식 단일 설치 스크립트를 통한 Electron 데스크톱 앱 배포 절차와 기본 포트 기반의 헬스체크 및 모델 준비 검증 방법을 정리합니다.
VoiceStudio 아키텍처와 데스크톱 앱 현황
VoiceStudio의 데스크톱 실행 환경은 최근 아키텍처 전환을 거쳤습니다. 초기 릴리스에서 사용되었던 구형 Tauri 기반 데스크톱 애플리케이션은 v0.5.3을 마지막으로 개발 및 지원이 공식 종료되어 아카이브 상태로 전환되었습니다. 현재 커뮤니티와 공식 저장소에서 단독으로 유지 관리되는 데스크톱 앱은 Electron 기반 패키지입니다.
따라서 기존에 Tauri 버전을 사용하던 환경이더라도 내부 자동 업데이트 기능을 통해 Electron 버전으로 갱신되지 않습니다. 설치 스크립트 역시 동결된 구형 피드를 배제하고 검증된 Electron 빌드만을 대상으로 동작하므로, 새로운 환경에 맞춰 클린 설치를 진행해야 합니다.
사전 하드웨어 요구 사양과 엔진 라이선스 확인
음성 합성 및 클로닝 연산은 시스템 하드웨어 가속 방식에 직접적인 영향을 받습니다. VoiceStudio의 기본 음성 합성 엔진은 k2-fsa/OmniVoice를 기반으로 작동하며, 플랫폼별 가속 사양을 감지하여 적합한 런타임을 구성합니다.
- NVIDIA GPU (Linux/Windows): CUDA 가속을 기본 지원합니다.
- Apple Silicon (macOS): Metal(MPS) 가속을 통해 모델 추론을 수행합니다.
- 외장 GPU가 없는 환경 (Intel/AMD 내장 그래픽 또는 구형 PC): CPU 전용 PyTorch 빌드를 자동으로 설치하여 가동합니다. 이 경우 연산 속도는 상대적으로 느려질 수 있으며, 환경 구성을 위해 약 5GB 이상의 디스크 여유 공간이 필요합니다.
라이선스 규칙 역시 확인이 필요합니다. 애플리케이션 소프트웨어 자체는 AGPL-3.0 라이선스로 배포되지만, 음성 모델 가중치, 토크나이저, 그리고 생성 음성에 대한 이용 조건은 소프트웨어 라이선스와 별도로 분리되어 있습니다. 기본 엔진인 OmniVoice를 비롯한 모델 다운로드 시에는 화면에 표시되는 모델별 라이선스 및 사용 조건을 확인하고 동의해야 합니다.
공식 curl 단일 스크립트로 VoiceStudio 설치하기
macOS와 Linux 환경에서는 공식 저장소에서 제공하는 원라인 셸 스크립트를 통해 최신 Electron 데스크톱 앱을 단일 명령어로 설치할 수 있습니다. 스크립트는 최신 릴리스 태그를 확인하고 SHA256SUMS.txt 파일과 체크섬을 대조하여 무결성을 검증한 후 시스템에 배치합니다.
# 최신 안정화 Electron 데스크톱 릴리스 설치
curl -fsSL https://voicestudio.sh/install | sh
# 특정 릴리스 버전을 지정하여 설치하는 경우
curl -fsSL https://voicestudio.sh/install | sh -s -- --version X.Y.Z
# 최신 main 브랜치 소스를 복제하고 패키지를 직접 빌드하여 설치하는 경우
curl -fsSL https://voicestudio.sh/install | sh -s -- --main
# 기존 데이터를 유지한 상태로 애플리케이션만 제거하는 경우
curl -fsSL https://voicestudio.sh/install | sh -s -- --uninstall- 터미널 실행 및 설치 명령어 입력: 터미널을 열고 기본 설치 명령인
curl -fsSL https://voicestudio.sh/install | sh를 실행합니다. - 패키지 다운로드 및 체크섬 검증: 스크립트가 운영체제에 맞는 패키지(macOS의 경우 .dmg, Linux의 경우 .AppImage 또는 .deb)와 체크섬 파일을 내려받아 검증합니다.
- 설치 경로 확인: macOS 환경에서는
/Applications에 설치되며, 권한이 없을 경우~/Applications로 자동 대체됩니다. Linux 환경에서는~/.local/bin/VoiceStudio경로에 실행 파일이 배치되므로 해당 경로가 PATH 환경 변수에 포함되어 있는지 확인해야 합니다.
설치 과정에서 pgrep 명령을 통해 이미 실행 중인 VoiceStudio 프로세스가 감지되면 파일 교체가 중단됩니다. 앱 업데이트나 재설치 시에는 macOS 기준 단축키 Command + Q 등을 사용해 기존 프로세스를 완전히 종료한 뒤 스크립트를 실행해야 정상적으로 설치가 완료됩니다.
로컬 백엔드 서버 가동 상태 및 헬스체크 판정법
설치된 VoiceStudio Electron 앱을 실행하면 데스크톱 UI가 로컬 백엔드 서버 프로세스를 자동으로 감독하고 구동합니다. 따라서 백엔드를 별도의 터미널 창에서 중복 구동하지 않도록 유의해야 합니다. 백엔드의 기본 수신 주소는 http://localhost:3900입니다.
# 1. 로컬 백엔드 헬스체크 확인
curl -I http://localhost:3900/health
# 2. 백엔드 초기화 진행 상태 확인
curl http://localhost:3900/startup/progress
# 3. 모델 등록 및 설치 상태 목록 조회
curl http://localhost:3900/models- 헬스체크 엔드포인트 점검: 브라우저나 터미널에서
http://localhost:3900/health로 요청을 보내 백엔드 HTTP 서비스가 응답하는지 확인합니다. 또한/startup/progress경로를 통해 백엔드 런타임 종속성과 초기화 작업이 정상 완료 단계에 진입했는지 파악합니다. - API 명세 확인: 백엔드 라우트 명세는
http://localhost:3900/openapi.json경로를 통해 확인할 수 있습니다. - 모델 설치 상태 확인 및 작업 수행:
GET /models호출 시 기본 OmniVoice 엔진 모델의 상태가"installed": false로 표시된다면, UI의 모델 관리자나POST /models/install엔드포인트를 통해 모델 패키지 설치 작업을 승인하고 완료해야 합니다.GET /models/install/status를 조회하여 설치 작업이 정상 종료되고 모델 목록에서"installed": true로 전환되었는지 검증합니다. - 테스트 오디오 생성 및 최종 판정: VoiceStudio UI의 Voice cloning 메뉴에서 번들 음성 또는 준비된 레퍼런스 녹음을 선택하고 텍스트를 입력해 테스트 오디오 생성을 진행합니다. 생성된 음성 파일이 오류 없이 재생되면 로컬 백엔드와 Electron 프론트엔드가 온전히 연결된 상태로 판정할 수 있습니다.
