음성 입력 및 Web Push

두 기능 모두 기본적으로 비활성화되어 있습니다. composer에서 마이크 버튼을 활성화하고 에이전트가 입력을 기다릴 때 트리거되는 브라우저 알림을 활성화할 수 있습니다.

음성 입력 (선택 사항)

마이크 버튼, 그리고 설정 → 음성의 핸즈프리 스위치입니다. 버튼을 탭하고 말하면 변환된 텍스트가 메시지 상자에 입력되어 확인 후 전송할 수 있습니다. 핸즈프리가 켜져 있으면 입력한 메시지와 동일하게 보호된 회신 경로를 거쳐 자동으로 전송되며, 우회 경로는 사용하지 않습니다. 입력란이 비어 있는 동안 마이크 로 바뀝니다 행 끝의 둥근 버튼을 차지하며, 첫 글자를 입력하면 다시 전송 버튼으로 바뀝니다. 메시지를 말하거나 직접 입력하므로, 두 작업이 입력란 폭을 두고 경쟁하지 않고 하나의 주요 작업만 표시됩니다.

말하는 동안 녹음기가 작성 영역 전체(벨트와 상자)를 덮으며 높이를 추가하지 않으므로 위의 화면이 전혀 움직이지 않습니다. 마이크가 있던 자리에 OK이 표시되며 클립을 종료합니다. 맨 끝의 휴지통은 이를 버리며, 클립이 텍스트로 변환되는 중에도 취소할 수 있습니다. 말을 마치고 2초간 침묵이 이어지면 자동으로 클립이 종료됩니다. 링이 OK 주위를 닫히며 이를 표시하고, 다시 말하면 카운트가 다시 시작됩니다. 첫 단어를 말하기 전에는 저절로 종료되지 않습니다.

제공자를 설정하기 전까지는 존재하지 않습니다. collie stt setup을 실행하거나 아래에서 Whistle을 설정하십시오. 버튼이 렌더링되지 않고, 오디오가 휴대폰 외부로 나가지 않으며, 자격 증명이 보관되지 않고, 자식 프로세스도 실행되지 않습니다. 비활성화된 것이 아니라 존재하지 않는 상태입니다. 네 가지 제공자:

설정은 페어링이 CLI 작업인 것과 같은 이유로 CLI 작업입니다. 이 화면은 자격 증명을 입력받으므로 호스트 키보드에서 처리해야 합니다. 키, 엔드포인트 또는 명령을 입력하는 웹 양식은 없습니다. 두 가지 예외에는 이 중 어느 것도 적용되지 않습니다. Whistle은 자격 증명을 보관하지 않고, 사용자가 선택한 명령을 실행하지 않으며, 오디오를 호스트 외부로 전송하지 않으므로 쓰기 권한이 있는 기기라면 설정(이유)에서 구성할 수 있습니다. 그리고 설정 → 음성 → 호스트 음성에서 쓰기 권한이 있는 기기는 호스트를 Whistle, ChatGPT 구독(codex 제공자), 꺼짐 간에 전환할 수 있습니다. ChatGPT는 터미널에 출력되는 것과 동일한 동의 절차를 거치고 동의합니다(아래)을 탭해야만 활성화됩니다. 터미널에서 키나 명령으로 설정한 제공자, 또는 환경 변수에 지정된 제공자는 해당 위치에 표시되며 앱에서는 변경할 수 없습니다. 이 두 가지의 경우 페이지에는 양식 없이 복사 및 다시 확인와 함께 호스트에서 실행할 명령이 표시됩니다.

$ bin/collie stt setup
Which speech-to-text provider?
  openai-compatible  any endpoint that speaks POST /audio/transcriptions —
                     the public OpenAI API, or a local whisper.cpp / parakeet.cpp
                     server, which is the zero-egress choice and the one to prefer.
  codex              borrow your own `codex` sign-in. No new key, no new account —
                     and a private endpoint that may break without notice.
  local-cli          run a transcription command already on this machine, such as
                     whisper-cli or muesli-cli. Its stdout is the transcript.
provider [openai-compatible]:
The API base, INCLUDING its version prefix — the provider appends /audio/transcriptions.
  local  http://127.0.0.1:8080/v1     (whisper.cpp / parakeet.cpp — nothing leaves the host)
  cloud  https://api.openai.com/v1    (room audio leaves this machine)
base URL: http://127.0.0.1:8080/v1
The model the endpoint understands. Empty takes Collie's default, gpt-transcribe.
model [gpt-transcribe]: whisper-1
API key [none]:
The language you speak, as a two-letter ISO-639-1 code — en, de, tr, ja.
LEAVE IT EMPTY to let the model detect it, which is what you want if you mix languages in one
sentence. Name one only if short clips keep coming back in a language you did not speak: a few
seconds of accented audio is too little for the model to detect from, and it guesses.
spoken language [auto-detect]: en
✓ speech-to-text configured — /home/you/.local/state/collie/stt.json (owner-only)
  Live immediately — no restart needed. The bridge re-reads this file per request.
  Check it end to end with `collie stt test`.

위의 모든 질문에는 플래그(--provider · --url · --model · --key · --lang)가 있으므로 프로비저닝 실행 시 터미널 상호작용이 필요하지 않습니다. 키를 비워두는 것도 지원되는 모드입니다. 키가 없는 엔드포인트는 빈 헤더 대신 Authorization 헤더를 아예 포함하지 않고 호출합니다.

음성 언어 설정은 한 가지 오류 상황에서만 유용합니다. 기본값인 빈 상태로 두면 모델이 언어를 자동으로 감지하며, 이는 한 문장에 두 언어를 섞어 쓰는 사용자에게 적합합니다. 짧은 클립이 말하지 않은 언어로 계속 변환되는 경우에만 설정하십시오. 억양이 섞인 몇 초 분량의 오디오는 언어를 감지하기에 너무 짧아 모델이 잘못 추측할 수 있습니다. 2자리 코드 또는 Collie가 자동으로 축약하는 지역 태그(en-GB → en)를 사용할 수 있습니다. 이 기능은 openai-compatible 제공자에서만 작동합니다. codex 엔드포인트는 언어 설정을 받지 않으며, collie stt status 설정 시 이를 명확히 안내합니다.

녹음 시간이 길수록 허용 대기 시간도 길어집니다. 브라우저의 단일 클립 허용 시간은 고정된 수치가 아니라 해당 클립 크기에 비례합니다. 안정적인 256 kb/s 업링크를 가정하고 여기에 브릿지 자체의 제공자 대기 시간을 더하므로, 최대 8 MiB 크기에는 6분 조금 안 되는 시간이 허용됩니다. Collie가 녹음하도록 허용한 클립이라면 그만큼 기다릴 준비도 되어 있습니다. 업로드가 진행되는 동안 Collie는 폴링을 중지하고 연결 배너 상태를 악화시키지 않습니다. 휴대폰의 업링크를 오디오 파일이 점유하는 것은 장애가 아니며 장애로 보고되어서도 안 됩니다.

녹음은 5분에서 중지됩니다. Whistle을 실행하는 호스트는 4분이 걸립니다. 휴대폰이 압축된 클립 크기의 약 4배인 WAV 파일을 호스트로 보내기 때문입니다. 녹음기에는 적용되는 제한 시간이 표시됩니다.

작동을 확인하셨습니까? stt test 명령은 스마트폰이 녹음할 수 있는 컨테이너마다 한 번씩, 생성된 0.2초의 무음을 실제 제공자에게 전송합니다.

$ bin/collie stt test
provider: openai-compatible (http://127.0.0.1:8080/v1, model whisper-1, language en)
sending:  0.2 s of generated silence as audio/wav (the setup probe) … ✓ 214 ms
  transcript: (empty) — expected from silence, and the empty answer still proves the pipeline.
sending:  0.2 s of generated silence as audio/webm;codecs=opus (Chrome, Android, Firefox) … ✓ 198 ms
sending:  0.2 s of generated silence as audio/mp4 (Safari, iOS) … ✓ 190 ms

호스트에서 Whistle을 사용하는 경우, stt test은 하나의 클립인 16kHz WAV를 전송하고 webm 및 mp4는 건너뛴다고 표시합니다. 휴대폰이 해당 제공자에게 보내기 전에 녹음을 16kHz WAV로 변환하기 때문입니다.

빈 텍스트로 변환되면 성공한 것입니다. 무음은 빈 텍스트로 변환되므로 왕복 통신이 정상 작동하는지만 검증합니다. 실패하면 오류 유형(인증, 엔드포인트, 응답 형식)이 표시됩니다. 그런 다음 휴대폰에서 Collie를 새로고침하면 메시지 상자 옆에 마이크가 나타납니다. collie stt status 명령은 현재 설정된 값과 각 설정값의 출처(파일 또는 우선순위가 더 높은 환경 변수)을(를) 표시합니다. collie stt off 명령으로 stt.json을(를) 제거하면 버튼이 다시 사라지며, 두 작업 모두 재시작이 필요하지 않습니다.

Whistle: 휴대폰 또는 호스트에서 음성을 텍스트로 변환

Whistle은 Cactus Compute에서 개발한 소형 음성 모델입니다. 파일 크기는 16.9MB이고 라이선스는 Apache-2.0입니다. 영어, 독일어, 프랑스어, 스페인어, 이탈리아어, 네덜란드어, 폴란드어를 인식하며 언어를 자동으로 감지합니다. 계정, 키, 추가 프로그램이 필요하지 않습니다. Collie가 이를 실행하는 엔진을 내장하고 있어 Linux, macOS, Windows, NixOS에서 작동합니다.

Whistle은 두 곳에서 실행할 수 있습니다. 휴대폰마다 선택합니다.

두 엔진 모두 동일한 모델을 읽습니다. 호스트가 사본 하나를 보관합니다. 휴대폰에서 Whistle을 직접 실행하려는 경우 인터넷이 아니라 호스트로부터 모델을 복사합니다. 최신 휴대폰에서는 클립 처리에 약 1초가 걸립니다.

설정에서 구성하십시오. 쓰기 권한이 있는 기기(페어링됨을(를) 보유한 기기)가 필요합니다. 읽기 전용 기기에는 "쓰기 권한이 있는 기기에서 설정할 수 있습니다."라는 문구가 표시되며 다운로드를 시작할 수 없습니다.

설정 → 음성은(는) 하위에 두 개의 페이지를 둔 단일 페이지입니다.

• —
  음성은(는) 현재 사용 중인 항목을 가장 먼저 표시합니다. 상단 카드 제목에는 구성된 항목이 표시됩니다. 예를 들어 하위에 모델 ggml-base.bin 및 호스트의 사용자 지정 명령이(가) 있는 whisper-cli과 같은 호스트 실행 명령, api.groq.com의 음성 서비스이(가) 포함된 whisper-large-v3와 같은 음성 서비스 모델, 모델 ca52876 및 이 휴대폰 또는 호스트이(가) 포함된 Cactus Compute의 Whistle, 혹은 호스트의 Codex 이용이(가) 포함된 ChatGPT 구독 (OpenAI)입니다. 명령이 이전 whistle-stt 래퍼인 경우 카드에 해당 내용이 표시되고 호스트 음성 설정을 여는 내장 Whistle로 전환 옵션이 제공됩니다. 그 아래에는 기반 상태(예: "준비됨. Whistle ca52876이(가) 이 휴대폰에 있습니다." 또는 "준비되지 않음. 호스트에서 Codex 로그아웃 상태입니다."), 오디오 이동 위치, 설정 방식(설정에서 어느 기기가 언제 설정했는지, 또는 호스트의 터미널에서 설정했는지)이 표시됩니다. 카드 아래에는 핸즈프리 스위치가 있습니다. 그 외의 모든 항목은 음성 작동 방식 변경 행 하나 뒤에 배치됩니다. 음성 기능이 정상 작동하는 동안에는 페이지를 방문할 때마다 해당 행이 닫혀 있습니다. 작동하지 않을 때(아무것도 설정되지 않음, 휴대폰 일시 중지됨, 호스트 옵션 응답 없음)는 열려 있으며, 상단 카드에 단일 작업(이 휴대폰에서 음성 설정, 복원 또는 수정)이 표시됩니다. 행을 열면 이 휴대폰 자체의 선택 항목인 이 휴대폰(권장 표시됨) 또는 호스트(에이전트를 실행하는 컴퓨터)이(가) 표시되며 기기별로 유지됩니다. 사용 중인 선택 항목에는 굵은 테두리, 색조, 사용 중 배지가 적용되며, 둘 사이를 전환해도 페이지 내 다른 요소는 이동하지 않습니다. 그다음 호스트 사용 항목을 위한 행 하나, 5가지 옵션을 모두 여는 행 하나, 모델을 위한 행 하나가 표시됩니다. 각 선택 항목에는 오디오 이동 위치, 오프라인 작동 여부, 비용, 필요한 설정, 속도의 5가지 정보를 나열하는 정보 버튼이 있습니다. 정보 버튼을 눌러도 선택 상태는 변경되지 않습니다.
• —
  호스트 음성은(는) 호스트의 5가지 옵션을 나열합니다. Whistle 및 사용자 지정 명령은 오디오를 로컬 머신에 유지합니다. 음성 서비스와 ChatGPT 구독은 오디오를 호스트 외부로 전송합니다. '끄기'는 그 아래 별도로 배치됩니다. 여기서 변경한 사항은 호스트와 페어링된 모든 기기에 적용됩니다. 기존 설정보다 오디오를 더 먼 곳으로 전송하는 옵션을 선택하면 확인 메시지가 먼저 표시되며, 이전 단계로 돌아가는 변경은 탭 즉시 전송됩니다. 모든 옵션에는 번호가 매겨진 단계, 복사할 명령, 앱이 직접 동작할 수 있는 앱 버튼으로 구성된 설정 방법이(가) 포함되어 있습니다. 다음에 수행할 단계에는 다음 표시가 붙습니다. 사용 중인 옵션이 작동하지 않을 때만 해당 단계가 단독으로 열립니다. 사용 중인 옵션에는 구성된 내용도 표시됩니다(예: "구성됨: whisper-cli, 모델 ggml-base.bin").
• —
  Whistle 모델은(는) 제작사 Cactus Compute와 라이선스를 명시하고 Hugging Face 모델 페이지로 연결되는 링크를 제공합니다. 호스트에 있는 사본과 이 휴대폰에 있는 사본을 각각의 상태와 함께 표시합니다.

Whistle을 설정하려면:

1. 01
   아직 음성 기능이 동작하지 않는 스마트폰에서는 음성의 상단 카드에 있는 이 휴대폰에서 음성 설정을 누릅니다. 한 번만 누르면 모든 작업이 처리됩니다. 호스트에 모델이 없으면 호스트가 다운로드하고, 스마트폰이 호스트에서 모델을 복사한 다음 이 휴대폰이 선택됩니다. 하나의 막대로 진행 상황을 표시하며 "호스트에 다운로드 중…" 또는 "이 스마트폰에 복사 중…"과 같이 실행 중인 단계를 보여줍니다. 단계가 실패하면 그 자리에서 중단되고 이유를 설명하며 다시 시도 옵션을 제공합니다. 읽기 전용 기기는 복사가 읽기 작업이므로 복사할 수 있지만 호스트에 다운로드를 요청할 수는 없습니다. 복사본이 없는 스마트폰의 설정 (16.9 MB), 호스트에 이미 모델이 있는 경우의 이 스마트폰에 복사과 같이 음성 작동 방식 변경 아래에도 동일한 두 단계가 있습니다.
2. 02
   또는 Whistle 모델을 열고 호스트에 다운로드 (16.9 MB)을 누릅니다. 막대에 진행 상황이 표시됩니다. 실패하면 페이지에 이유가 표시됩니다. 다시 시도을 누릅니다. 모델이 준비되면 페이지에 모델 버전(Hugging Face 리비전의 처음 7자, 해당 리비전 링크)과 크기가 표시됩니다. 세부 정보에는 짧은 체크섬과 호스트가 모델을 다운로드한 시간이 표시됩니다.
3. 03
   호스트를 통해 받아쓰기하려면 호스트 음성을 열고 호스트의 Whistle을 선택한 다음 모든 기기에 적용를 선택합니다. 또는 그 아래의 설정 방법을 열고 호스트에서 사용를 누릅니다. 터미널에서 키나 명령어로 다른 공급자를 설정한 경우, 페이지에 해당 공급자가 표시되며 선택 옵션은 제공되지 않습니다. 이 경우 Whistle의 단계는 호스트의 collie stt off로 시작한 다음 collie stt whistle --host으로 이어집니다.
4. 04
   이 스마트폰의 복사본에서는 Whistle 모델에 버전이 표시되며 이 스마트폰에서 제거 옵션을 제공합니다. 또한 브라우저가 복사본을 보관하기로 동의했는지("보관됨") 아니면 공간이 부족할 때 복사본을 삭제할 수 있는지도 표시합니다. 나중에 호스트에 최신 모델이 들어오면 복사본에 해당 내용이 표시되고 업데이트 옵션이 제공됩니다.
5. 05
   음성에서 음성 작동 방식 변경을 열고 이 휴대폰 또는 호스트을 선택합니다. 스마트폰에 복사본이 생길 때까지 이 휴대폰은 비활성화됩니다. 호스트에 음성 옵션이 없으면 호스트는 비활성화됩니다. 선택 항목 아래의 줄에는 호스트가 사용하는 항목이 표시됩니다.
6. 06
   호스트에서 모델을 제거하려면 Whistle 모델에서 호스트에서 제거을 누르고 확인합니다. Whistle이 호스트 엔진이었던 경우, 모델을 다시 다운로드할 때까지 호스트의 음성 기능이 중지됩니다.

변경자. 페어링된 기기가 설정에서 호스트의 옵션을 변경하면, 호스트는 해당 기기의 이름과 시간을 기록합니다. 그러면 음성 및 호스트 음성에 "Pixel 8이 마지막으로 변경함"이라는 문구와 함께 시간이 표시됩니다. 터미널에서 변경하면 이 기록이 지워집니다.

또는 터미널에서 설정하십시오.

$ bin/collie stt whistle                 # fetch the model once
$ bin/collie stt whistle --host          # also make Whistle this host's engine
$ bin/collie stt whistle --from <path>   # use a copy you already have, same hash check
$ bin/collie stt whistle --remove        # remove the model, and the host engine if it is Whistle
$ bin/collie stt status                  # shows the model line

--host은 사용자가 의도적으로 설정한 공급자를 바꾸기 전에 확인을 요청합니다. --yes은 터미널이 없는 실행 환경에서 해당 질문에 응답합니다. 다운로드 전에 질문하므로 거부된 실행에서는 아무것도 가져오지 않습니다. --remove은 다른 종류의 공급자를 그대로 둡니다. collie stt off은 공급자를 제거하고 모델이 유지됨을 알립니다. collie doctor는 호스트의 모델이 이 릴리스에서 허용하는 모델이 아닐 때 경고합니다. 엔진은 재시작 없이 즉시 활성화됩니다. collie stt test로 확인하십시오.

다운로드 대상 및 위치. 호스트는 하나의 고정된 Hugging Face 주소에서 whistle.cact을 가져오고, CDN으로의 리디렉션(최대 5회, HTTPS 전용, 로컬 또는 사설 주소로는 이동하지 않음)을 따르며, 해당 파일의 sha256이 이 릴리스에 포함된 해시와 일치하는 경우에만 파일을 보관합니다. 불일치하면 파일을 삭제하고 두 해시를 모두 보고합니다. 다운로드는 32 MiB로 제한되며 10분의 제한 시간이 있습니다. 파일은 상태 폴더의 whistle 폴더에 저장됩니다. 엔진 코드(약 1 MB)는 모든 Collie 릴리스에 포함되어 있으며 Collie 자체 파일에서 제공됩니다.

자동으로 다운로드되지 않습니다. 설치 시에도, 업데이트 시에도, 엔진을 선택할 때도 다운로드되지 않습니다. 모델은 사용자가 호스트로 다운로드, 설정을 누르거나 collie stt whistle을 실행할 때 다운로드됩니다. 스마트폰은 소유자가 설정, 이 스마트폰에 복사 또는 복원을 누를 때 호스트로부터 모델을 복사하며, 다른 곳에서는 가져오지 않습니다. 호스트는 한 번에 최대 2대의 스마트폰에만 모델을 전송합니다. 세 번째 스마트폰에는 "잠시 후 다시 시도하십시오"가 표시됩니다.

제한 사항. WAV 파일은 압축 클립 크기의 약 4배이고 업로드 제한은 8 MiB로 유지되므로, 호스트 엔진은 최대 4분의 녹음을 처리합니다. 녹음기에는 해당 제한이 표시됩니다. 스마트폰 엔진은 최대 5분까지 처리합니다. 호스트 자식 프로세스의 제한 시간은 클립 길이의 절반이며, 최소 60초, 최대 3분입니다. 호스트에서는 동시에 최대 2개의 클립이 실행됩니다. 스마트폰에는 모델을 위한 여유 공간(파일 크기의 2배를 요구함)과 보안 연결(tailscale serve이 제공하는 것과 같은 HTTPS)이 필요합니다.

스마트폰이 처리할 수 없는 경우. 클립에서 이 휴대폰이 실패하면 음성 화면에 이유가 표시되고, 호스트에 작동하는 음성 공급자가 있을 때에만 호스트로 전송 옵션을 제공합니다. 클립은 Send to host를 누르거나 폐기할 때까지 실패한 상태로 메모리에 유지됩니다. 오디오가 기기 내에 머무르는 것이 핵심인 엔진을 선택했으므로 Collie는 절대 이를 스스로 전송하지 않습니다. 한 세션에서 엔진 충돌이 두 번 발생하면 앱을 다시 로드할 때까지 이 휴대폰이 꺼집니다.

휴대폰의 복사본이 삭제된 경우. 브라우저가 공간 확보를 위해 복사본을 지울 수 있습니다. 선택 상태는 이 휴대폰에 유지되며 받아쓰기는 일시정지됩니다. 음성에 "Dictation is paused"가 표시되고 호스트에서 모델을 다시 복사하는 복원가 제공됩니다. 마이크는 계속 녹음되며 클립은 위와 같이 호스트로 전송 상태로 휴대폰에 유지됩니다. Collie는 호스트로 알아서 전환하지 않습니다. 호스트를 사용하려면 호스트를 선택하십시오.

브라우저. 이 휴대폰에는 speech worker에 자체 보안 정책을 부여하는 브라우저가 필요합니다. Android 환경의 Chrome은 테스트되었습니다. WebKit은 WebKit 빌드에서 테스트되었습니다. iPhone 환경의 Safari는 아직 기기에서 검증되지 않았습니다. 이를 실행할 수 없는 브라우저는 사유와 함께 이 휴대폰를 비활성화 상태로 표시하며, 호스트는 계속 사용할 수 있습니다.

기존 래퍼를 사용한 경우. 이 페이지의 이전 버전에서는 네이티브 러너 기반의 local-cli 래퍼인 ffmpeg 및 jq를 안내했습니다. 해당 구성은 더 이상 사용되지 않지만, 이미 설정된 항목은 그대로 유지되며 계속 작동합니다. 기본 제공 엔진으로 전환하려면 bin/collie stt whistle --host --yes를 실행하거나, collie stt off를 먼저 실행한 뒤 bin/collie stt whistle --host를 실행하십시오. 래퍼를 계속 사용할 수도 있습니다. 래퍼의 모델 파일은 자동으로 재사용되지 않습니다. 다운로드를 건너뛰려면 --from <path>로 해당 파일을 전달하십시오.

이 엔진의 보안 측면과 Settings에서의 설정을 허용하는 이유는 보안 및 ADR 0096에 설명되어 있습니다.

컨테이너 지원 여부는 제공자마다 다릅니다

스마트폰은 WAV로 녹음하지 않습니다. Chrome, Android, Firefox에서는 WebM 컨테이너의 Opus로 녹음하고, Safari와 iOS에서는 MP4 컨테이너의 AAC로 녹음하여 해당 바이트를 그대로 전송합니다. WAV를 전사하는 제공자라도 이 두 형식에는 400으로 응답할 수 있으며, 이 경우 stt test 상태가 정상으로 보여도 모든 받아쓰기가 "refused" 오류와 함께 실패합니다. stt test 명령이 세 가지 클립을 모두 전송하는 이유가 바로 이것입니다. 거부 여부를 스마트폰이 아니라 설정 단계에서 감지합니다.

2026-09-01에 OpenRouter의 POST /v1/audio/transcriptions 모델을 대상으로 확인한 사례입니다.

해결 방법은 키가 아니라 모델을 변경하는 것입니다. 동일한 OpenRouter 키가 네 가지 형식을 모두 지원하는 openai/whisper-large-v3-turbo 모델을 가리키도록 설정하십시오.

bin/collie stt setup --provider openai-compatible \
  --url https://openrouter.ai/api/v1 --model openai/whisper-large-v3-turbo --key <key>

이제 전사가 거부되면 업스트림 상태와 전송된 컨테이너 이름이 함께 표시되므로, 스마트폰의 오류 메시지에서 제공자가 어떤 형식을 거부했는지 확인할 수 있습니다. (#148, @drewbitt 님께 감사드립니다)

외부 유출 제로, 자체 엔진 지정

openai-compatible을(를) 사용해야 하는 이유: 로컬 기본 URL을 지정하면 실내 음성이 호스트 외부로 절대 유출되지 않습니다. OpenAI 호환 텍스트 변환 엔드포인트를 제공하는 두 가지 엔진은 whisper.cpp에 번들된 server과(와) mudler/parakeet.cpp(MIT)입니다. 각 가이드에 따라 빌드하거나 설치한 후 로프백에서 실행하고 --url을(를) 해당 주소로 지정하십시오.

bin/collie stt setup --provider openai-compatible --url http://127.0.0.1:8080/v1

통합의 전부는 이것입니다. Collie는 어떤 엔진이 응답하든 관여하지 않습니다.

Mistral의 Voxtral은 자체 지원이 필요하지 않습니다이며, 이 규격을 따르는 다른 어떤 것도 마찬가지입니다. 이것이 접점의 목적입니다. vLLM은 /v1/audio/transcriptions에서 오픈 가중치 Voxtral 모델을 제공하므로, 로컬 모델은 다른 엔진과 동일한 --url입니다. 호스팅 모델은 Mistral 자체 베이스에서 동일한 요청을 사용합니다:

bin/collie stt setup --provider openai-compatible \
  --url https://api.mistral.ai/v1 --model voxtral-mini-latest --key <key> --lang en

Voxtral Mini Transcribe는 13개 언어를 지원하며 Collie가 이미 전송하는 동일한 ISO-639-1 language 필드를 사용합니다. 신뢰하기 전에 collie stt test 명령으로 확인하십시오. "OpenAI 호환"은 각 엔드포인트가 자체적으로 주장하는 내용일 뿐이며, 해당 verb는 이를 점검하기 위해 존재합니다.

codex 공급자: 수락하는 내용

녹음 파일이 사용자의 로그인으로 인증된 문서화되지 않고 지원되지 않는 ChatGPT 엔드포인트 엔드포인트로 전송되어 ChatGPT 계정에 속도 제한 및 차단 위험이 발생하고 예고 없이 중단될 수 있으므로, collie stt setup --provider codex 명령은 동의 블록을 출력하고 yes을(를) 입력할 때까지 대기합니다.

Collie는 해당 엔드포인트에 먼저 자체 이름으로 요청합니다. 본래의 식별자가 거부된 경우에만 Codex CLI의 헤더로 폴백하며, 이 폴백은 collie stt status 명령이 읽어주는 단어로 설정에 기록됩니다. Collie는 ~/.codex/auth.json을(를) 절대 읽거나 저장하지 않습니다. 이미 신뢰하고 있는 바이너리만이 이에 접근합니다.

Settings에서도 선택할 수 있습니다. 쓰기 권한이 있는 기기에서 설정 → 음성 → 호스트 음성를 엽니다. 이 페이지에는 호스트가 현재 사용하는 항목이 표시됩니다. ChatGPT subscription의 경우 기록된 ID인 honest, 또는 대체가 필요했던 경우 codex-cli도 표시됩니다. ChatGPT subscription 행은 호스트에 codex가 설치되어 있고 ChatGPT로 로그인되어 있을 때만 열립니다. Collie는 codex login status에 확인을 요청합니다. 그렇지 않으면 해당 행에 그 이유가 한 문장으로 표시되며, 설정 방법에 다음 단계가 안내됩니다. 호스트에 Codex를 설치하고, codex login로 로그인한 다음, Use ChatGPT subscription를 탭하십시오. 해당 행을 탭하면 호스트와 페어링된 모든 기기에 변경 사항이 적용된다는 문구 아래에 동일한 동의 내용이 한 글자도 빠짐없이 시트에 표시됩니다. 동의합니다를 탭하기 전까지는 호스트로 아무것도 전송되지 않습니다. 탭하면 호스트가 collie stt setup와 동일한 프로브를 실행하여 신뢰할 수 있는 ID를 먼저 확인하고 동일한 설정을 작성합니다. 프로브가 실패하면 아무것도 작성되지 않으며 시트에 이유가 표시됩니다. 같은 페이지의 끔는 프로바이더를 제거합니다. 터미널은 여전히 동일한 방식으로 작동합니다.

자체 명령 실행: local-cli 제공자

local-cli은(는) 중간에 HTTP 서버를 두지 않고 이미 보유한 전사 명령을 녹음당 한 번씩 실행합니다.

bin/collie stt setup --provider local-cli \
  --command /Applications/Muesli.app/Contents/MacOS/muesli-cli --args transcribe
bin/collie stt test

Collie는 녹음본을 비공개 임시 파일에 기록하고 <command> [args…] <file>을(를) 실행합니다. 해당 파일의 경로는 항상 마지막 인수가 됩니다. 명령의 stdout에서 공백을 잘라낸 결과가 전사 텍스트가 됩니다.

이름만 지정하면 setup 실행 시 검색되어 전체 경로가 저장됩니다. 서비스는 축소된 PATH 환경에서 실행되므로 셸에서 찾은 이름이 서비스 환경에서는 확인되지 않을 수 있습니다. ./whisper-cli와(과) 같은 상대 경로는 거부됩니다.

--args은(는) 공백으로 구분된 단어를 받습니다. 셸이 이를 해석하지 않으므로 따옴표는 입력된 그대로 유지됩니다. 공백이 포함된 인수는 JSON 형식을 대신 사용해야 합니다.

bin/collie stt setup --provider local-cli --command whisper-cli \
  --args '["-m", "/srv/my models/ggml-base.bin", "-nt"]'

명령이 충족해야 하는 조건:

• —
  현재 사용자가 실행할 수 있는 일반 파일이어야 합니다. Collie가 심볼릭 링크를 추적하므로 일반 파일을 가리키는 심볼릭 링크도 가능합니다. collie stt setup은(는) 그 외의 모든 대상을 거부하며, collie stt status에 오류 원인이 출력됩니다.
• —
  종료 코드 0으로 종료하고 stdout에 전사 내용을 출력해야 합니다. 그 외의 결과는 모두 받아쓰기 실패로 처리됩니다.
• —
  60초 이내에 완료되어야 합니다. 시간이 초과되면 Collie가 해당 명령과 명령이 시작한 모든 프로세스를 SIGKILL로 강제 종료합니다.
• —
  stdout에 최대 256 KiB까지만 출력해야 합니다. 초과 출력하는 즉시 Collie가 프로세스를 종료합니다.
• —
  실행 중인 프로세스를 남기지 않아야 합니다. 명령이 종료되면 Collie는 명령이 시작한 프로세스 중 남아 있는 프로세스를 모두 강제 종료합니다. 계속 실행되어야 하는 헬퍼 프로세스는 setsid 등을 사용하여 자체 세션을 시작해야 합니다.

Windows의 경우 Collie는 동일한 시점에 명령의 전체 프로세스 트리를 종료하며, 정상 종료 후에도 명령이 시작하여 아직 실행 중인 프로세스를 모두 종료합니다. 단 한 가지 예외가 있습니다. 이미 종료된 헬퍼가 시작한 프로세스는 명령보다 오래 지속될 수 있습니다.

명령은 동시에 최대 2개의 받아쓰기에서만 실행됩니다. 세 번째 요청은 휴대폰이 이미 인지하고 있는 동일한 "busy" 응답을 받으며, Collie는 해당 요청에 대해 아무것도 시작하지 않습니다.

입력창에 넣을 내용이 없으므로 빈 stdout은 휴대폰에서 실패로 처리됩니다. collie stt test은(는) 테스트 클립이 무음이므로 이를 통과로 간주합니다.

참고. 명령은 브릿지 자체의 사용자 및 해당 사용자의 권한으로 받아쓰기당 한 번씩 실행됩니다. 셸, stdin, COLLIE_* 환경 변수는 제공되지 않습니다. stderr는 전혀 읽히지 않으며, 휴대폰에는 명령줄이나 경로가 표시되지 않고 명령 실패 여부와 종료 코드만 전달됩니다.

임시 파일은 현재 사용자만 열 수 있는 폴더에 저장되며, 매 실행 후 Collie가 삭제합니다. 실행 도중 브릿지 자체가 강제 종료된 경우, 다음 브릿지 시작 시 생성된 지 1시간이 지난 해당 폴더들을 삭제합니다. 오디오의 다음 전송 위치는 명령에 따라 결정됩니다. 로컬 엔진을 사용하면 호스트에 그대로 유지됩니다.

위의 모든 결정에 대한 근거(두 번 거절된 이유, 변경된 점, 접점이 이렇게 구성된 이유)는 ADR 0029에 있습니다.

웹 푸시(선택 사항)

기본적으로 비활성화되어 있습니다. 설정에는 3단계가 필요합니다. 발신자 라이브러리(web-push)는 빌드 시 선택적 종속성으로 포함됩니다:

collie push-keys     # 1. generate + write the VAPID keys
collie restart       # 2. Collie reads them at start
#                      3. on your phone: Settings → Alerts

push-keys 명령은 키쌍을 생성하고 활성 .env에 파일 모드 600으로 COLLIE_VAPID_PUBLIC 및 COLLIE_VAPID_PRIVATE을(를) 작성합니다. 이는 바이너리 설치의 경우 ~/.config/collie/.env이고 Herdr 설치의 경우 Herdr의 플러그인 설정 디렉터리에 있는 것입니다.

RFC 8292 subject 클레임을 설정하려면 연락처 URI를 인수로 전달하십시오:

collie push-keys mailto:you@example.com

Herdr로 관리되는 설치 환경에서는 두 단계 모두 액션(herdr plugin action invoke push-keys --plugin herdr.collie 및 restart)으로 제공됩니다. Herdr 액션은 위치 인수를 허용하지 않으므로, subject를 설정하려면 셸에서 명령을 직접 실행해야 합니다.

키 처리 세부 정보:

이 명령은 --force을(를) 전달하지 않는 한 기존 키를 덮어쓰지 않습니다. 키를 교체하면 현재의 모든 구독이 무효화되므로 모든 기기가 알림을 다시 받으려면 재구독해야 합니다. 기존 구성에서 subject 인수를 전달하면 연락처 주소만 업데이트되고 현재 키는 유지됩니다.

참고. 0.8.0 이전 Herdr 버전에서는 액션이 초기 플러그인 설치 중 캐시된 세트(ADR 0006)로 고정된 상태로 유지됩니다. herdr plugin install를 실행할 때까지 push-keys 및 push-test 액션이 표시되지 않습니다. 대신 bash scripts/collie-ctl.sh push-keys를 직접 실행하십시오. 래퍼 스크립트가 명령을 바이너리로 직접 전달합니다.

구독된 모든 기기에서 전송 경로를 테스트합니다:

collie push-test                     # or: push-test "Title" "Body"

전송에는 1~2초가 소요됩니다. 명령에서 푸시가 비활성화되었다고 보고하면 생성된 키를 로드하도록 서비스를 다시 시작하십시오. 구독된 기기가 없다고 보고하면 휴대폰 브라우저에서 3단계를 완료하십시오.

웹 푸시에는 보안 컨텍스트(HTTPS)가 필요합니다. 이는 tailscale serve(MagicDNS 인증서) 또는 TLS를 종단하는 외부 리버스 프록시(변형 C)에 의해 제공됩니다. 일반 HTTP 설정(COLLIE_SERVE_MODE=http)에는 보안 컨텍스트가 없으므로 브라우저가 설정의 구독 제어를 비활성화합니다.

Collie는 에이전트가 blocked 또는 done 상태로 전환될 때 알림을 보내며, 본문에 에이전트 메시지를 포함합니다. 알림을 선택하면 웹 UI에서 해당 에이전트로 바로 이동합니다.

Collie가 보내는 알림 종류

설정 → 알림 → 알림 조건 아래에 각각 전용 스위치가 있는 다섯 가지 종류입니다.

에이전트가 작업 중(working)에서 유휴(idle) 상태로 바뀔 때 Finished가 트리거되므로, 사용자가 중단한 에이전트도 완료된 것으로 간주됩니다.

머신 부하는 머신 페이지에서 규칙을 설정하기 전까지 아무것도 보내지 않습니다. 스위치는 모든 규칙을 한 번에 끕니다. 값이 상승하여 높은 상태를 유지할 때마다 알림이 하나씩 전송되며, 탭하면 해당 머신의 Status 뷰가 열립니다. 머신을 참조하십시오.

각 기기는 자체 언어(으)로 알림 제목을 표시하며, 업데이트 후 Collie를 열지 않은 기기에서는 영어로 표시됩니다. 본문은 브리지가 작성한 상태 그대로 유지됩니다.

모든 스위치는 bridge 전체에 적용됩니다. 푸시는 구독된 모든 기기로 전송되므로 기기별로 설정할 항목은 없습니다.

캐시 경고는 해당 창의 자체 설정에서 한 번에 창 하나씩 설정할 수도 있습니다. 창을 열고 ⋮를 탭한 다음 창 설정을 선택하십시오. 해당 창들은 Settings의 전역 스위치 아래에 각각 Remove 버튼과 함께 나열됩니다.

두 상태는 서로를 덮어쓰지 않고 합산됩니다. 전역 스위치가 켜져 있거나 또는 해당 창이 목록에 있을 때 창 경고가 발생하므로, 전역 스위치를 꺼도 직접 주시하도록 설정한 창의 알림이 꺼지지는 않습니다.

감시 중인 창에는 웜 사이클당 한 번 경고가 발생합니다. 에이전트의 다음 요청 시 기한이 연장되며, 그 후에만 동일한 창에 다시 경고할 수 있습니다. 방해 금지 시간이 적용됩니다: 스누즈된 브리지는 아무것도 전송하지 않으며, 해당 시간 범위 내에 스누즈가 끝나면 여전히 경고가 발생합니다. 이미 비활성 상태인 창에는 경고가 발생하지 않으며, 시간이 남아 있는 상태에서 /model 전환으로 인해 비활성화된 창도 여기에 포함됩니다.

COLLIE_CACHE_WARN_SECONDS 플래그는 윈도우 시간을 변경하며, 기본값은 300초(configure.md)입니다.

참고. 이 알림은 프롬프트 캐시 판독이 필요하므로 캐시 카운트다운을 표시하는 창에만 적용되며 다른 창에는 적용되지 않습니다. harness가 Collie에서 읽을 수 있는 트랜스크립트를 유지해야 하고, 에이전트가 최소 한 번의 턴을 수행했어야 합니다. 창에서 실제로 경고가 발생하는 시간은 설정된 초 또는 해당 창 자체 캐시 수명의 절반 중 더 짧은 쪽입니다. 1시간 Claude 캐시는 300초 전체 윈도우를 유지합니다. Codex, OpenCode, pi, omp 등 5분 캐시는 만료 약 2분 30초 전에 경고합니다.

홈 화면 재설치 및 서비스 워커 초기화로 인해 항상 HTTP 410이 반환되지 않고 새 엔드포인트가 생성되므로 시간이 지남에 따라 오래된 구독이 누적될 수 있습니다. Collie는 기기가 다시 등록할 때 레코드를 업데이트합니다. 저장된 엔드포인트를 직접 확인하고 삭제할 수 있습니다:

# one line per device: service, since, user agent, endpoint tail
bin/collie push list
bin/collie push forget <substring>   # or: push forget --all

durable agent의 푸시

durable agent의 질문 카드는 휴대폰으로 푸시를 보낼 수 있으며, Collie는 하나의 durable agent가 보내는 푸시 수를 제한합니다.

푸시에는 "Permission needed in"과 사용자가 창에 지정한 이름이 표시됩니다. durable agent 자체의 질문 제목은 포함되지 않습니다. durable agent는 문구를 선택할 수 있습니다. 제목(최대 60자)은 콜론 뒤에 창 이름을 따르고, 해당 줄(최대 120자)이 본문이 됩니다. 문구는 푸시의 내용만 변경하며 전송 빈도는 변경하지 않습니다.

요약 내용에는 머신 이름을 host로 하여 "A durable agent on {host} is raising many asks"라고 표시됩니다. crew에서는 member의 이름을 지정합니다. Needs input 스위치와 일시 중지 기능도 요약 전송을 억제합니다. 푸시 제한이 질문을 숨기지는 않으며, 열려 있는 모든 질문은 휴대폰에 그대로 유지됩니다.

Collie는 질문을 한 번 푸시합니다. 머신, durable agent, 도구 호출별로 각 질문을 기억하므로, durable agent가 재시작되어 동일한 질문을 다시 하더라도 휴대폰에 표시만 되고 두 번째 푸시는 전송되지 않습니다. 질문은 닫힌 지 1시간 후에 삭제됩니다. 해당 메모리는 상태 폴더의 durable-asks.json에 저장됩니다. crew에서는 lead가 이러한 규칙을 실행하고 해당 파일을 유지하며, member는 자체 질문에 대해 푸시를 보내지 않습니다(ADR 0100).