Pocket Libre
클라우드로부터 당신의 Pocket AI 녹음기를 해방하세요.
CI
Python 3.10+
License: MIT
Pocket Libre는 Pocket AI 음성 녹음기의 제조사 앱을 대체합니다. 이 도구는 Bluetooth를 통해 기기에서 녹음을 가져와, Whisper로 로컬에서 전사(transcribe)하고, 누가 말했는지 분석하며, 사용자의 자체 API 키로 요약 기능을 수행합니다.
당신의 대화 내용은 절대로 다른 사람의 서버에 저장되지 않습니다.
pip install -e . && pocket-libre setup && pocket-libre web
<!-- Screenshot: the web UI dashboard showing device battery, storage, and the recording library. Add as docs/screenshot-dashboard.png and link here. -->
왜 필요한가 (Why)
Pocket은 구독 서비스로 포장된 좋은 하드웨어입니다. 제조사 앱은 사용자의 오디오를 업로드하고, 그들의 서버에서 전사를 수행하며, 이 특권을 위해 연간 $79~$179의 비용을 청구합니다.
하지만 기기 자체는 아무것도 하지 않습니다. MP3 파일을 저장했다가 요청받을 때 넘겨줄 뿐입니다. 그래서 본 도구는 이를 직접적으로 활용합니다.
| Pocket Pro | Pocket Libre |
|---|
| 전사(Transcription) | 그들의 서버 | 로컬 Whisper, 당신의 CPU |
| ... | | |
전사와 화자 식별은 모두 사용자의 기기에서 실행됩니다. 요약 기능만이 네트워크에 접속하는 유일한 단계이며, 이 과정은 건너뛸 수 있습니다. 그럼에도 불구하고 타임스탬프와 화자가 레이블링된 전사본을 얻을 수 있습니다.
요구 사항 (Requirements)
- Python 3.10 이상
- Pocket 녹음기 (
PKT01; 펌웨어 호환성 참조)
- Bluetooth LE 지원
- 기기의 16자리 세션 키 (아래 세션 키 받기 참조)
펌웨어 호환성 (Firmware compatibility)
펌웨어는 예상보다 더 중요합니다. 기기의 WiFi 동작 방식은 버전별로 충분히 달라져서, 한 버전에서 확인된 순서가 다른 버전을 망가뜨릴 수 있습니다. pocket-libre status를 사용하여 현재 펌웨어를 확인하세요.
| 1.3.3 | 1.7 | 1.8 |
|---|
| Scan, connect, authenticate | Works | Works | Works |
| ... | | | |
| The 1.7 결과는 WiFi 펌웨어 V9에 대한 필드 리포트(#9)에서 가져왔습니다. | | | |
펌웨어 1.7과 1.8에서는 모든 것이 작동합니다. BLE 경로는 더 느립니다 (1.8의 경우 수십 KB/s, 1.3.3의 경우 최소 3–4 KB/s)만 download, sync 및 watch가 사용하는 방식입니다. wifi-transfer는 장치의 WiFi 액세스 포인트를 통해 약 1 MB/s로 녹음을 가져옵니다. WiFi 전송을 참조하세요.
WiFi 전송은 펌웨어 1.7과 1.8에서 작동하며, wifi-transfer는 --force를 전달하지 않으면 다른 펌웨어를 거부합니다. 이 경우 알려진 두 버전 모두에 대해 액세스 포인트를 다시 시작하는데, 이는 정상적으로 작동합니다. 1.3.3의 BLE 측면은 동일해 보이지만, 아무도 시도해 본 적이 없습니다.
다른 펌웨어 버전은 테스트되지 않았습니다. 만약 가지고 계시다면, pocket-libre status와 pocket-libre explore의 출력 결과는 이슈에 매우 유용할 것입니다.
설치 (Install)
git clone https://github.com/shahcolate/pocket-libre.git
cd pocket-libre
pip install -e .
화자 식별(Speaker identification)은 선택 사항이며 PyTorch를 가져옵니다:
pip install -e
이것은 Pocket을 찾고, 페어링하며, 그 주소와 새 키를 config에 저장합니다. 대체된 config는 `config.toml.<date-time>.bak`으로 옆에 보관됩니다. 벤더 앱은 이 방식으로 페어링된 장치에 대해 초기화하고 앱에서 다시 페어링할 때까지 연결할 수 없습니다 (이 과정에서 해당 키가 잠기게 됩니다).
pocket-libre를 사용하면서도 벤더 앱을 계속 사용하려면, 대신 앱이 페어링하는 키를 사용하세요. 이 16자리 세션 키는 BLE 연결을 인증합니다. 벤더 앱은 페어링 후 첫 번째 키로 이를 전송하므로, HCI 트레이스에서 한 번 포착해야 합니다.
**macOS/iOS.** Additional Tools for Xcode에 포함된 [PacketLogger](https://developer.apple.com/bluetooth/)를 사용하세요. 캡처를 시작하고, 벤더 앱을 열고, 연결되도록 한 다음, 트레이스에서 `APP&SK&`를 검색하세요.
**Android (가장 쉬움).** 벤더 앱은 `distinct_id`라는 분석 이벤트를 작성하는데, 이는 **첫 16자리가 세션 키인** 28자리 계정 ID입니다. 패킷 캡처가 필요하지 않습니다:
```bash
adb logcat | grep -i distinct_id
Android (패킷 캡처). 개발자 옵션에서 Bluetooth HCI snoop log를 활성화하고, 벤더 앱으로 연결한 다음, btsnoop_hci.log를 가져와 Wireshark에서 여세요. 일반적인 버그 보고서 안에 있는 스눕 로그는 충분하지 않습니다 — 모든 ACL 패킷을 15바이트로 잘라내어 ATT 페이로드 3바이트만 남기므로, APP&/MCU& 프레임은 읽을 수 없습니다. Bluetooth HCI snoop log를 Full로 설정하고, 블루투스 스택을 재시작한 다음, 거기서부터 캡처를 진행하세요.
pocket-libre sniff로는 찾을 수 없습니다. 이 도구는 자체 연결에 대한 알림만 보기 때문에, 키는 앱이 쓰는 무언가입니다.
세션 키는 장치별이 아니라 계정별이며, 그 첫 8자리가 사용자의 WiFi AP 비밀번호입니다. 이에 대해 더 자세한 내용은 SECURITY.md를 참조하세요. 두 발견 모두 다음에서 가져왔습니다: #4.
전체 프로토콜 세부 정보는 PROTOCOL.md에 있습니다.
사용법
웹 인터페이스
http://127.0.0.1:8265에서 열립니다. 장치 상태, 원클릭 다운로드 및 처리, 오디오 플레이어, 스크립트(transcripts), 요약본(summaries), 마인드맵(mind maps), 그리고 모든 녹음 파일에 대해 질문할 수 있는 채팅 상자를 얻을 수 있습니다.
웹 인터페이스는 인증(authentication) 기능이 없습니다. 기본적으로 로컬호스트(localhost)에 바인딩됩니다.
그대로 두세요. --host 0.0.0.0을 전달하면 스크립트와 장치가 네트워크의 모든 사람에게 노출됩니다.
명령줄 (Command line)
pocket-libre status
pocket-libre list
pocket-libre sync
...
watch를 실행 상태로 두고 녹음 파일이 Pocket의 범위 내에 들어오면 자동으로 동기화(sync)되게 하세요. 장치가 멀리 떨어져 있을 때는 5분 간격으로 확인하는 방식으로 작동하여 하루 종일 전력을 소모하며 스캔하지 않습니다.
장치 공간 확보 (Freeing up space on the device)
pocket-libre delete --downloaded는 디스크에 완전한 사본(complete copy)이 있는 모든 녹음 파일을 장치에서 제거하고, 나머지 모든 것은 유지합니다. 삭제는 되돌릴 수 없으므로
값을 pocket-libre config --set device.address=...로 직접 설정할 수 있습니다.
해상도 순서는 CLI 플래그 → 환경 변수 → 설정 파일 → 기본값이며, 따라서 셸의 ANTHROPIC_API_KEY가 파일을 덮어씁니다.
API 키
둘 다 선택 사항입니다. Anthropic 키가 없어도 로컬 전사(transcription)는 가능합니다.
HuggingFace 토큰이 없으면, 화자 레이블링은 Claude로, 그리고 최종적으로 단일의 이름 없는 화자로 대체됩니다.
해당 비용 추정치는 요약, 개체, 마인드맵을 모두 활성화하고 30분 녹음에 대해 Claude Haiku 4.5를 입력 및 출력 토큰 당 각각 $1, $5로 가정했을 때입니다. 모든 명령어는 실제로 지출된 금액을 출력합니다.
프로토콜
Pocket은 BLE GATT(Bluetooth Low Energy Generic Attribute Profile) 위에서 일반 ASCII 명령 프로토콜을 사용하며, 오디오는 16 kHz 모노의 일반 MP3 형식이고 약 32 kbps입니다. 암호화, DRM, 독점 코덱이 없습니다. PROTOCOL.md에 전체 명령어 참조가 있습니다.
WiFi 전송
펌웨어 1.7 및 1.8에서는 장치가 WiFi 액세스 포인트를 생성하고 이를 통해 녹음을 약 1 MB/s의 속도로 제공할 수 있으며, 이는 BLE가 처리하는 수십 KB/s보다 훨씬 빠릅니다. 오디오 한 시간 분량(약 14 MB)이 몇 분이 걸리는 대신 15~20초 만에 전송됩니다.
pocket-libre wifi-transfer
...
작동 방식:
- BLE를 통해 연결하고 인증합니다. 펌웨어(1.7 또는 1.8)와 배터리(10% 이상)를 확인합니다.
- 장치의 액세스 포인트(access point, AP)를 올리고 이 기기의 WiFi를 그 위에 이동시킵니다. 네트워크는 숨겨져 있고 WPA2로 보호되며, 비밀번호는 세션 키의 처음 8자입니다.
- 각 녹음을 BLE 전송으로 요청한 다음 WiFi로 전환하여 파일에 저장합니다. 이는 공급업체 앱(vendor app)이 작동하는 방식이며, 장치는 1.8 버전에서는 액세스 포인트 세션당 두 개의 파일을, 1.7 버전에서는 하나의 파일을 제공하므로 AP를 재시작합니다 (매번 약 15초 소요).
- 액세스 포인트를 내리고 이 기기를 평소 네트워크로 다시 연결합니다. 오류가 발생하거나 Ctrl-C를 누른 후에도 이렇게 합니다.
필수 사항 및 주의사항:
- 네트워크에 자동으로 접속하려면 Linux에서는 NetworkManager, Windows에서는 netsh가 필요합니다. macOS의 경우 또는
--wifi manual 옵션을 사용하는 경우, 명령어가 네트워크 이름과 비밀번호를 출력하면 기다리는 동안 사용자가 직접 접속해야 합니다. 이 네트워크는 숨겨져 있으므로, macOS에서는 액세스 포인트 세션당 한 번씩 WiFi 메뉴에서 **기타 네트워크…(Other Network…)**로 설정해야 하며, 이는 펌웨어 1.7의 모든 파일 녹음 전에 해당됩니다.
- 작동하는 동안 이 기기는 WiFi를 통한 인터넷 연결이 없습니다. 이더넷을 연결하면 케이블을 통해 계속 인터넷을 사용할 수 있습니다. Linux에서는 임시 프로필이 기본 경로(default route)를 가져가지 않습니다.
- 임시 프로필은 존재하는 동안 AP 비밀번호를 유지합니다 (NetworkManager 또는 Windows 프로필 저장소). 명령이 끝나면 삭제됩니다.
- 먼저 공급업체 앱을 닫으세요. 장치는 한 번에 하나의 BLE 연결만 처리할 수 있습니다.
와이어 상에서 전송이 어떻게 작동하는지는 PROTOCOL.md를 참고하세요.
문제 해결 (Troubleshooting)
장치가 WiFi 명령 후 BLE에서 응답을 멈췄습니다. 이는 수동으로 액세스 포인트를 올릴 때( #4 ) 펌웨어 1.8에서 보고되었으며, APP&WIFIC로는 복구할 수 없습니다. 장치를 물리적으로 전원 주기(Power-cycle)하세요: 전원 버튼을 장치가 꺼질 때까지 누른 후 다시 켜세요. 그러면 다시 광고를 시작할 것입니다. 장치에 있는 아무것도 손실되지 않습니다. 녹음은 내부 저장소에 있습니다.
WiFi 전송 직후 장치를 찾을 수 없습니다. 다음 실행 전에 최대 1분 정도 기다려 주세요: 세션이 끝난 직후에는 새로운 BLE 연결을 놓치는 경우가 있습니다. 또한, 공급업체 앱(vendor app)이 백그라운드에서 재연결하지 않았는지 확인하세요.
wifi-transfer로 네트워크에 참여할 수 없습니다. 액세스 포인트가 숨겨져 있으므로 WiFi 스캔에 표시되지 않는 것이 정상입니다. Linux에서는 NetworkManager가 WiFi 인터페이스를 관리하는지(nmcli device) 확인하거나, --iface로 하나를 선택하세요. 대안으로, --wifi manual을 사용하면 직접 참여할 수 있습니다.
pocket-libre scan이 아무것도 찾지 못합니다. 장치가 켜져 있고 공급업체 앱에 연결되어 있지 않은지 확인하세요. 이 앱은 한 번에 하나의 BLE 연결만 허용하므로, 먼저 휴대폰 앱을 강제 종료하세요. Linux에서는 일반적으로 bluetoothd가 실행되고 사용자가 bluetooth 그룹에 속해야 BLE 스캔이 작동합니다.
