tapeback

PipeWire/PulseAudio를 통해 시스템 오디오와 마이크를 기록하는 리눅스용 로컬 미팅 녹음기입니다. Whisper로 전사(transcribe)하고 (기본적으로 로컬), 화자를 식별하며, Markdown 형식으로 Obsidian 볼트에 저장합니다. 원격 STT 백엔드(현재 OpenAI)를 선택하지 않는 한 전사는 사용자의 장치에 남아 있습니다.

Google Meet, Zoom, Teams, Telegram, Discord, Slack huddles 등 모든 비디오 통화 플랫폼에서 작동합니다.

주요 기능 (Features)

• 실시간 전사(Live transcription) (선택 사항): 회의가 진행되는 동안 실시간으로 스크립트를 읽을 수 있습니다. Whisper가 60초마다 백그라운드에서 전사합니다 (TAPEBACK_LIVE=true 설정).
• 플랫폼 독립적(Platform-agnostic): OS 레벨 오디오를 캡처하여 모든 앱과 작동합니다.
• 로컬 전사(Local transcription): CPU 또는 CUDA GPU의 faster-whisper 사용 (기본값).
• 선택적 원격 STT: TAPEBACK_STT_BACKEND=openai를 설정하여 로컬 Whisper 대신 원격 전사 백엔드를 사용할 수 있습니다. 현재 OpenAI만 지원하는 원격 백엔드입니다 (필요: tapeback[stt] + TAPEBACK_STT_API_KEY; 회의 오디오는 장치를 벗어납니다). 타임아웃/일시적 오류 발생 시 업로드가 재시도되며, 완료된 청크는 캐싱되어 동일한 WAV 파일에 대한 tapeback process는 누락된 부분만 다시 업로드합니다.
• 화자 분할(Speaker diarization): pyannote가 누가 무엇을 말했는지 식별합니다.
• 스테레오 채널 분리(Stereo channel separation): 정확한

yay -S tapeback # 녹음 + 전사(transcription)
yay -S tapeback tapeback-tray # + 시스템 트레이 아이콘
yay -S tapeback tapeback-llm # + LLM 요약 기능
...

모든 시스템 의존성(ffmpeg, PipeWire)은 자동으로 설치됩니다.

Ubuntu / Debian (.deb)

사전 빌드된 .deb 패키지는 모든 GitHub 릴리스에 첨부되어 있습니다. 버전을 선택하고(현재 버전은 릴리스 페이지 참조), 다운로드한 후 설치하세요:

wget https://github.com/yastcher/tapeback/releases/download/v0.9.10/tapeback_0.9.10_amd64.deb
sudo apt install ./tapeback_0.9.10_amd64.deb

...

기본 패키지는 자체 Python 인터프리터(from python-build-standalone)를 번들로 포함하고 있어, 시스템의 Python 버전에 관계없이 모든 최신 Ubuntu 또는 Debian에서 작동합니다. 시스템 의존성은 ffmpeg와 pulseaudio-utils(parecord / pactl)만 필요합니다.

pip / uv

먼저 시스템 의존성을 설치하세요:

# Arch / Manjaro
sudo pacman -S python uv ffmpeg pipewire-pulse

...

그런 다음 tapeback을 설치하세요:

uv tool install tapeback                          # 녹음 + 전사(transcription)
uv tool install "tapeback[tray]"                  # + 시스템 트레이 아이콘
uv tool install "tapeback[stt]"                   # + 원격 OpenAI STT
...

tapeback[stt]는 원격 전사를 위해 openai SDK를 설치합니다.
tapeback[llm] 역시 해당 SDK(그리고 anthropic)를 설치하므로, 이미 LLM 확장 기능을 가지고 있다면 원격 STT가 작동합니다.

pipx 또는 Nix

# pipx
pipx install tapeback
pipx install "tapeback[tray,llm,diarize]"         # 모든 기능 포함
...

빠른 시작(Quick start)

tapeback start                     # 녹음 시작, Ctrl+C로 중지

이것으로 끝입니다. 전사본은 ~/tapeback/meetings/에 저장됩니다.

Obsidian 볼트에 저장하려면:

mkdir -p ~/.config/tapeback
echo 'TAPEBACK_VAULT_PATH=~/Documents/obsidian/vault' > ~/.config/tapeback/.env

팁: 항상 같은 언어로 회의를 한다면, 해당 언어를 고정하세요. 자동 감지 기능은 무음으로 시작하는 채널(심지어 환각을 일으킬 수도 있음)에서 오작동할 수 있습니다. 다른 언어에 포함된 영어 용어도 정상적으로 전사됩니다:

TAPEBACK_LANGUAGE=en tapeback start # 또는 .env 파일에 TAPEBACK_LANGUAGE=en 추가

시스템 트레이(System tray)

터미널 없이 실행하세요. 트레이 아이콘을 마우스 오른쪽 버튼으로 클릭하여 녹음을 시작/중지할 수 있습니다:

tapeback tray

아이콘 색상으로 현재 상태를 표시합니다:
회색(gray) = 유휴(idle), 빨간색(red) = 녹음 중(recording), 주황색(orange) = 처리 중(processing).

로그인 시 자동 시작하려면 ~/.config/autostart/tapeback-tray.desktop 파일을 생성하세요:

[Desktop Entry]
Name=tapeback
Exec=tapeback tray
...

tapeback은 StatusNotifierItem D-Bus 프로토콜을 직접 사용합니다. 따라서 pystray, GTK, XEmbed가 필요 없습니다. KDE Plasma, Hyprland (waybar 사용 시), 그리고 Sway (waybar/eww 사용 시)에서는 X11과 Wayland 모두에서 기본적으로 표시됩니다.

GNOME

GNOME Shell은 SNI(StatusNotifierItem) 항목을 네이티브로 표시하지 않습니다. AppIndicator Support 확장 기능을 설치하세요 (일회성 설정이며, Slack, Dropbox 등에서도 필요합니다):

# Ubuntu / Debian
sudo apt install gnome-shell-extension-appindicator
# Fedora
...

Extensions 앱을 열고 Ubuntu AppIndicators (또는 AppIndicator and KStatusNotifierItem Support)를 활성화한 후, 로그아웃했다가 다시 로그인하세요. tapeback tray는 영향을 받는 세션을 감지하면 시작 시 이 힌트를 stderr에 출력합니다. 자세한 내용은 issue #3을 참고하세요.

화자 분리(Speaker diarization)

화자 분리는 녹음에서 누가 무엇을 말했는지 식별합니다. 이것이 없으면, tapeback은 스테레오 채널을 사용합니다: 마이크는

1. huggingface.co에서 계정 생성
2. pyannote/speaker-diarization-3.1의 라이선스 수락
3. pyannote/segmentation-3.0의 라이선스 수락
4. huggingface.co/settings/tokens에서 토큰 생성
5. ~/.config/tapeback/.env에 추가:

TAPEBACK_HF_TOKEN=hf_your_token_here

처음 실행 시 pyannote 모델(약 1GB)이 다운로드됩니다. NVIDIA GPU를 강력히 권장합니다. CPU에서의 diarization은 매우 느립니다.

LLM 요약 (LLM summarization)

tapeback은 전사(transcription) 후, LLM을 사용하여 간략한 요약, 실행 항목(action items), 주요 결정 사항 등을 추가할 수 있습니다.

~/.config/tapeback/.env에 다음 키를 설정합니다:

TAPEBACK_LLM_PROVIDER=gemini
TAPEBACK_LLM_API_KEY=...

또는 아래 표에서 제공업체의 자체 변수를 셸(shell) 환경에 내보냅니다. tapeback은 파일이 아닌 환경 변수에서 이를 읽습니다. tapeback status를 실행하면 키가 설정되었는지 여부만 표시하며, 실제 키 값은 보여주지 않습니다.

PII 마스킹 (PII masking)

기본적으로 녹음, 전사 및 diarization은 사용자 장치에 남아 있습니다. 요약(Summarization)이 일반적으로 외부 경로입니다: LLM 제공업체로의 텍스트 요청입니다. 이것이 불편하다면, 요약을 비활성화하거나 마스킹을 활성화하세요.

선택적 원격 STT는 두 번째 외부 전송 경로입니다. TAPEBACK_STT_BACKEND=openai를 사용하면 회의 오디오가 OpenAI로 업로드됩니다. PII 마스킹은 그곳에 적용될 수 없습니다. 이는 요약 전에 텍스트를 재작성하는 역할만 합니다. 이러한 트레이드오프(trade-off)를 받아들이지 않는 한 기본값(local)을 유지하세요.

TAPEBACK_MASK_PII=true

이메일과 전화번호는 전사본을 전송하기 전에 [EMAIL_1] / [PHONE_1] 플레이스홀더로 대체되며 — 재시도 및 모든 폴백 제공업체에서도 마찬가지입니다 — 실제 값은 볼트에 저장되는 요약본에서 복원됩니다. 디스크에 있는 전사본은 절대 마스킹되지 않습니다.

이름을 직접 추가하세요. Whisper는 사람들이 말하는 것을 기록하며, 회의에서 입으로 나오는 것은 이메일 주소가 아니라 이름입니다. 따라서 일반적인 전사본에서는 두 가지 내장 규칙 모두 아무것도 일치시키지 못합니다. 핵심은 사용자가 제공하는 목록입니다:

TAPEBACK_MASK_TERMS=Ivan Petrov,Ivan,Acme Corp,Project Gemini

일치 여부는 대소문자를 구분하지 않으며 단어 경계로 제한됩니다(Anna 안에 Ann은 마스킹되지 않습니다). 또한 가장 긴 용어가 우선하므로, Ivan Petrov와 Ivan을 모두 나열하는 것은 괜찮습니다. 전사본 레이블(You, Other, Speaker 1)과 충돌하는 용어는 경고와 함께 거부됩니다 — 이를 마스킹하면 화자 할당이 깨지고 아무것도 보호할 수 없습니다.

일치 여부는 문자 그대로입니다. 용어는 사용자가 나열한 정확한 형태로만 마스킹됩니다. 굴절 언어에서는 모든 형태가 자체 항목을 필요로 합니다(Ivan, Ivana, Ivanu) — tapeback은 추측하지 않는데, 추측하면 관련 없는 단어를 조용히 다시 쓰기 때문입니다. TAPEBACK_MASK_PII=true는 제공업체가 개인적인 것을 전혀 보지 못한다는 보장이 아니라 최소한의 기준일 뿐입니다.

신뢰하기 전에 확인하세요. --show-masked는 전송될 내용을 정확하게 출력하고 거기서 멈춥니다 — 요청이나 API 키가 필요하지 않습니다:

tapeback summarize notes.md --show-masked
# stderr: Masked: EMAIL 1, TERM 4
# stdout: 제공업체로 전송될 텍스트

횟수는 발생 횟수가 아닌 고유한 값을 계산합니다. 페이로드는 stdout으로, 횟수는 stderr로 가므로 --show-masked > sent.txt를 사용하면 diff할 수 있는 내용을 얻을 수 있습니다.

CLI 참조

tapeback start [NAME]              녹음 시작 (Ctrl+C로 중지)
tapeback stop                      다른 터미널에서 녹음 중지
tapeback tray                      시스템 트레이 아이콘
...

tapeback start --no-live           # 일회성 오버라이드: TAPEBACK_LIVE=true여도 실시간 전사(transcription) 건너뛰기
tapeback start --no-diarize        # 화자 식별(speaker identification) 건너뛰기
tapeback start --no-summarize      # LLM 요약 건너뛰기
...

출력 형식 (Output format)

스테레오 녹음은 두 가지 전사 섹션을 생성합니다:

• 전사본 (Transcript) — 채널 기반 레이블(You / Other)이 포함된 원시 Whisper 출력
• 화자 분리 전사본 (Diarized Transcript) — 화자가 식별된 출력(You / Speaker 1 / Speaker 2 / ...)

Whisper가 불확실한 단어(확률 < 0.5)는 이탤릭체로 표시됩니다.

---
date: 2026-03-23
time: "14:30"
...

모든 설정은 환경 변수(TAPEBACK_ 접두사) 또는 ~/.config/tapeback/.env 파일로 관리됩니다. 사용자가 tapeback을 실행하는 디렉터리에 있는 .env 파일도 읽으며, 이 경우 사용자 파일을 덮어씁니다. tapeback이 알지 못하는 키는 경고 없이 무시되므로, 오타가 난 TAPEBACK_ 이름은 조용히 아무런 동작도 하지 않습니다.

핵심 (Core)

전사 (Transcription)

실시간 전사 (Live transcription)

오디오 (Audio)

변수 설정 (Variables)

화자 분리 (Speaker diarization)

LLM 요약 (LLM summarization)

문제 해결 (Troubleshooting)

처리 출력 읽기 (Reading the processing output)

처리 과정은 무엇을 하는지, 각 단계에 얼마나 걸렸는지, 그리고 Whisper가 실제로 어디에서 실행되었는지를 보고합니다:

Stage 'load channels' took 0.7s
Splitting channels...
Stage 'split' took 82.0s
...

모니터 채널은 먼저 전사(transcribed)되므로, 감지된 언어를 마이크에 재사용할 수 있습니다. 마이크는 사용자가 듣고 있을 때는 대부분 침묵이며, 자체적으로 추측하는 경우 정확도가 떨어집니다.

주목해야 할 줄: