호스팅된 전사(Transcription) 서비스로 녹음 파일을 보내는 것은 편리하지만, 데이터 처리 방식에 대한 결정 사항을 수반합니다. 회의 오디오, 인터뷰, 연구 노트 및 초안 콘텐츠는 파일이 해당 파일을 소유한 컴퓨터에 머물러 있을 때 처리하기가 더 쉬울 수 있습니다.

이 튜토리얼은 Fernando Paladini가 개발한 MIT 라이선스 데스크톱 애플리케이션인 EchoTranscribe의 문서화된 개발 경로를 안내합니다. 이 앱은 Tauri 데스크톱 셸, React 및 TypeScript 프론트엔드, 그리고 faster-whisper를 통해 Whisper 모델을 로드하는 로컬 FastAPI 백엔드를 결합합니다.

목표는 로컬 전사가 자동으로 더 정확하거나 빠르다고 주장하는 것이 아닙니다. 유용한 결과물은 재현 가능한 로컬 워크플로(Workflow)를 구축하는 것입니다: 백엔드를 시작하고, 데스크톱 앱을 열고, 모델을 선택하고, 지원되는 오디오를 전사하며, 타임스탬프(Timestamp)를 검토하고, TXT, SRT 또는 JSON으로 내보내는 과정입니다.

요약 (TL;DR)

안정적인 v0.1.1 릴리스를 사용하고, 프론트엔드 의존성(Dependencies)을 설치한 다음, 백엔드를 시작하고, 두 번째 터미널에서 Tauri 개발 앱을 실행하세요.

git clone --branch v0.1.1 https://github.com/paladini/echo-transcribe.git
cd echo-transcribe
npm install

첫 번째 터미널에서 Python 백엔드를 시작합니다:

cd src-tauri/backend
python main.py

두 번째 터미널에서, 리포지토리(Repository) 루트로부터 Tauri를 시작합니다:

npm run tauri dev

백엔드는 http://localhost:8000/docs에서 API를 문서화하며, Tauri 창이 자동으로 프론트엔드를 열어야 합니다.

사전 요구 사항 (Prerequisites)

v0.1.1 README에는 다음과 같은 사전 요구 사항이 나열되어 있습니다:

• Node.js 18 이상
• Python 3.8 이상
• Tauri 컴파일을 위한 Rust
• Windows의 경우 Microsoft Visual Studio C++ Build Tools
• Ubuntu 또는 Debian에서 개발할 경우 README에 문서화된 Linux 시스템 패키지

이 프로젝트는 Homebrew를 사용하는 macOS 설정 가이드도 제공합니다. Tauri 컴파일은 플랫폼별 요구 사항을 추가하므로, Python 설치만으로는 데스크톱 애플리케이션을 빌드하기에 충분하지 않습니다.

백엔드 요구 사항은 FastAPI 0.104.1, Uvicorn 0.24.0, faster-whisper 0.9.0, Pydantic 2.5.0 및 지원 패키지들을 고정(pin)합니다. PyTorch와 torchaudio는 버전 2.0.0 이상으로 지정되어 있습니다. 안정적인 태그(stable tag) 대신 main 브랜치에서 작업하는 경우, 설치 전에 저장소의 현재 의존성 파일들을 확인하십시오.

로컬 백엔드 시작하기

README에서 각 플랫폼별 시작 스크립트를 제공하지만, 수동 경로를 사용하는 것이 프로세스를 검사하기에 더 쉽습니다. 저장소 루트에서 다음을 실행하십시오:

cd src-tauri/backend
python main.py

백엔드는 ~/.echo-transcribe 아래에 모델(model) 및 임시 디렉토리를 생성합니다. 8000번부터 8004번 포트까지 검색하며, 선택된 포트를 backend_port.txt에 기록합니다. 8000번 포트를 사용할 수 있는 경우, 문서화된 API 주소는 http://127.0.0.1:8000입니다.

데스크톱 셸(shell)을 실행하기 전에 백엔드의 헬스 체크(health) 엔드포인트를 확인하십시오:

curl http://localhost:8000/health

정상적인 응답에는 status가 healthy로 설정되어 있습니다. 또한 http://localhost:8000/docs에서 생성된 OpenAPI 문서를 열어 사용 가능한 라우트(routes)를 검사할 수 있습니다.

선택된 Whisper 모델이 이미 존재하지 않는 경우 다운로드되기 때문에, 첫 번째 전사(transcription)는 시간이 더 오래 걸릴 수 있습니다. 소스(source)는 홈 폴더의 .echo-transcribe/models 디렉토리 아래에 모델을 저장합니다.

Tauri 데스크톱 앱 실행하기

백엔드 터미널을 계속 실행 상태로 유지하십시오. 저장소 루트에서 다른 터미널을 열고 Tauri 개발을 위해 문서화된 명령어를 정확히 실행하십시오:

npm run tauri dev

Tauri 설정은 http://localhost:1420을 개발 URL로 사용하며, npm run dev로 Vite 프론트엔드를 시작합니다. 데스크톱 창은 1200x800의 초기 크기로 구성되며 크기 조절이 가능합니다.

이 애플리케이션은 원격 클라이언트가 아닙니다. 프론트엔드는 사용자의 머신에서 실행되는 백엔드와 쌍을 이루며, 백엔드의 CORS (Cross-Origin Resource Sharing) 설정은 로컬 Vite 오리진과 tauri://localhost를 허용합니다. 이러한 로컬 구성은 프라이버시 경계(privacy boundary)의 일부이지만, 인증(authentication)을 의미하지는 않습니다.

파일 전사하기 (Transcribe a file)

앱에서 하나의 오디오 파일 또는 배치(batch)를 선택합니다. README 문서에 따르면 MP3, WAV, FLAC, M4A, OGG, WebM 입력을 지원하며, 배치 전사를 위해 한 번에 최대 10개의 파일을 선택할 수 있습니다.

백엔드에서 제공하는 모델 중 하나를 선택하십시오:

• tiny: 39 MB, 속도는 빠르지만 예상 정확도는 낮음
• base: 74 MB, 속도와 정밀도 사이의 균형
• small: 244 MB, 중간 정도의 속도로 더 나은 품질 제공
• medium: 769 MB, 처리 속도는 느리지만 더 높은 품질 제공

이 크기들은 태그된 소스의 모델 메타데이터에 있는 값이며, 사용자의 머신에 대한 벤치마크가 아닙니다. 실행 시간(Runtime)은 오디오, 모델, 종속성(dependency) 버전, 그리고 환경에서 사용 가능한 가속기(accelerator)를 사용할 수 있는지 여부에 따라 달라집니다.

첫 테스트를 위해 자동 언어 감지(automatic language detection)를 활성화해 두거나, 수동으로 언어를 선택하십시오. 백엔드는 먼저 확장자와 모델 이름을 검증합니다. 그런 다음 업로드된 내용을 임시 파일로 작성하고, 선택된 Whisper 모델을 로드하며, 단어 단위 타임스탬프(word timestamps)가 활성화된 상태로 전사를 수행한 뒤, 임시 파일의 삭제를 예약합니다.

결과는 인터페이스에서 검토할 수 있으며 TXT, SRT 또는 JSON 형식으로 내보낼 수 있습니다. 전사 모델이 타임스탬프를 반환하는 경우, 백엔드 응답에 단어 수준의 타임스탬프(word-level timestamps)가 포함됩니다.

대용량 녹음 파일을 전사하지 않고 경로 확인하기

처리가 허용된 짧은 오디오 파일을 사용하십시오. 다음 순서대로 워크플로(workflow)를 확인하십시오:

1. /health가 정상(healthy) 상태를 반환하는지 확인합니다.
2. /models를 열고 4개의 모델 항목을 검사합니다.
3. 초기 다운로드 및 대기 시간을 줄이기 위해 tiny 또는 base 모델로 시작합니다.
4. 문서화된 형식 중 하나를 사용하여 짧은 파일을 전사(transcribe)합니다.
5. 결과에 텍스트와 타임스탬프(timestamps)가 나타나는지 확인합니다.
6. 결과 중 하나를 TXT, SRT 또는 JSON으로 내보내고 내보낸 파일을 엽니다.

백엔드는 또한 POST /transcribe 및 POST /transcribe-batch를 노출합니다. /docs에 있는 대화형 Swagger 페이지는 curl 명령어를 추측하는 대신 현재의 멀티파트(multipart) 필드 이름을 검사할 수 있는 가장 안전한 장소입니다. 단일 파일 라우트(route)는 업로드된 file, model, 선택 사항인 language, 그리고 auto_detect_language 플래그를 허용합니다.

로컬 아키텍처가 작동하는 이유

이 프로젝트는 세 가지 책임을 분리합니다:

1. Tauri는 데스크톱 경험을 패키징하고 프론트엔드를 로컬 애플리케이션에 연결합니다.
2. React, TypeScript, Vite는 인터페이스와 개발 서버를 제공합니다.
3. FastAPI는 업로드, 모델 로딩, 전사(transcription), 언어 감지(language detection), 타임스탬프(timestamps) 및 정리를 처리합니다.

이러한 분리를 통해 모델 실행을 브라우저 UI로부터 격리합니다. 또한 기본 네트워크 경로를 루프백(loopback)으로 유지하면서 OpenAPI를 통해 백엔드를 검사할 수 있게 합니다. 모델 캐시(model cache)는 매 요청마다 동일한 모델을 다운로드하는 것을 방지하며, 임시 디렉터리(temporary directory)는 백엔드가 처리 중에 업로드된 오디오를 기록할 수 있는 제어된 공간을 제공합니다.

실패 모드 및 보안 경계

데스크톱 창이 백엔드를 로드할 수 없습니다. Python 프로세스가 여전히 실행 중인지, 8000번 포트를 사용할 수 있는지 확인하십시오. 만약 백엔드가 다른 포트를 선택했다면, backend_port.txt와 터미널 로그를 검사하십시오.

첫 번째 요청이 멈춘 것처럼 보입니다. 모델 로딩 및 다운로드는 전사(transcription) 전에 발생합니다. 네트워크 연결과 백엔드 로그를 확인하십시오. 첫 번째 테스트로 긴 녹음 파일을 사용하지 마십시오.

파일이 거부되었습니다. 확장자가 MP3, WAV, FLAC, M4A, OGG 또는 WebM 중 하나인지 확인하십시오. 백엔드는 모든 가능한 컨테이너의 내용을 검사하는 것이 아니라 접미사(suffix)를 검증합니다.

빌드가 플랫폼 의존성 문제로 실패합니다. Rust와 필요한 Linux 패키지 또는 Windows C++ Build Tools를 포함하여 README에 나열된 플랫폼 필수 요구 사항을 설치하십시오.

API를 다른 머신에 노출하고 싶습니다. 먼저 중단하고 해당 경계(boundary)를 설계하십시오. 현재 백엔드는 두 개의 로컬 오리진(origin)에 대해 광범위한 메서드와 헤더를 허용하며, 저장소(repository)에는 사용자 인증, 할당량(quota) 또는 프로덕션용 리버스 프록시(reverse proxy)에 대한 문서가 없습니다. 로컬 실행은 기본 앱이 데이터를 보내는 위치를 제한하지만, 인증되지 않은 API를 안전한 공개 서비스로 바꿔주지는 않습니다.

타인의 녹음 파일을 처리합니다. 로컬 실행이 동의, 보유, 저작권 또는 조직의 데이터 처리 요구 사항을 대체할 수는 없습니다. 처리 권한이 있는 오디오만 전사(transcribe)하십시오.

FAQ

EchoTranscribe는 클라우드 API 키가 필요한가요?

문서화된 백엔드는 faster-whisper를 통해 Whisper 모델을 로컬에 로드하며, 누락된 모델은 로컬 모델 디렉토리로 다운로드합니다. 이 튜토리얼은 호스팅된 전사(transcription) 키를 요구하지 않습니다.

GPU 없이 사용할 수 있나요?

저장소에는 모델 선택과 로컬 실행에 대한 문서가 있지만, 특정 하드웨어 구성이나 처리 속도를 보장하지는 않습니다. tiny 또는 base 모델로 시작하여 사용 중인 머신의 백엔드 로그를 확인하십시오.

main 브랜치가 릴리스(release)와 동일한가요?

아니요. 이 튜토리얼은 안정적인 v0.1.1 태그를 사용합니다. 저장소의 기본 브랜치는 변경될 수 있으므로, 여기에 설명된 명령어와 모델 목록이 필요할 때는 태그를 고정(pin)하여 사용하십시오.

공유 서비스로 노출할 준비가 되었나요?

그것은 문서화된 보장 범위 밖의 사항입니다. 공유 액세스를 고려하기 전에 인증, 요청 제한, 저장소 제어, 로깅 결정 및 의도적인 네트워크 경계를 추가하십시오.

요약 (Takeaway)

EchoTranscribe는 로컬 AI 데스크톱 툴링을 위한 유용한 패턴입니다. 즉, Tauri 셸, 검사 가능한 FastAPI 서비스, 지속적인 모델 디렉토리, 그리고 명시적인 내보내기(export) 형식을 갖추고 있습니다. v0.1.1 버전을 고정(Pin)하고, 헬스 체크 엔드포인트(health endpoint)를 확인하며, 짧은 인증된 녹음 파일로 테스트하십시오. 그리고 인증의 부재를 실제 배포 경계(deployment boundary)로 간주하십시오.

다음 중 어떤 로컬 전사(transcription) 기능을 다음에 검증하시겠습니까: 화자 분리(speaker separation), 더 강력한 내보내기 제어, 또는 소규모 팀을 위한 인증된 액세스?

AI 지원 공개 (AI assistance disclosure)

이 튜토리얼을 구성하고 문구를 검토하는 데 AI 지원이 사용되었습니다. 릴리스, 명령, 버전, 경로(routes), 모델 이름, 파일 경로, 제한 사항 및 보안 노트는 위에 링크된 공개 v0.1.1 리포지토리 소스를 바탕으로 확인되었습니다. 어떠한 성능 벤치마크나 개인적인 사용 주장도 포함되어 있지 않습니다.