ossicle

Deepgram으로 로컬 미디어 파일과 URL을 전사하고, Claude Code용 MCP 서버 및 독립형 CLI로 사용합니다. 전사 결과는 Markdown으로 디스크에 기록되며, 큰 내용이 인라인으로 반환되는 일은 없습니다.

모든 작업은 전송 전에 측정된 길이로 가격이 산정되며, 예상 비용이 설정된 작업당 상한을 초과하면 작업 자체가 거부됩니다. 이 보호 장치가 이 패키지의 핵심입니다.

요구 사항

• Node >= 20

• PATH에 ffprobe 및 ffmpeg (길이 측정 및 16kHz 모노 opus 업로드용)

• URL 입력을 원한다면 PATH에 yt-dlp

• Deepgram API 키

설치

npm install
npm run build
cp .env.example .env    # then fill in DEEPGRAM_API_KEY

구성

구성은 패키지 루트의 .env 파일에서 만 읽습니다. 셸에 내보낸 변수와 claude mcp add --env 플래그는 의도적으로 무시되므로, 어떤 프로젝트가 서버를 실행했는지와 관계없이 서버는 동일하게 동작합니다.

MCP 서버

claude mcp add ossicle -- node "<absolute path to this repo>/dist/index.js"

transcribe

전사 파일 경로, 작업 폴더, 길이, 예상 및 실제 사용 USD, cached 플래그, 500자로 제한된 미리보기를 반환합니다. 전체 전사본은 디스크에 남습니다.

화자 분리 (Diarization)

화자 분리는 실험적이며 기본적으로 꺼져 있습니다. 실제 녹음에서 Deepgram은 발언 전환을 잘못 귀속시키는 경우가 충분히 많아서, 화자 라벨이 붙은 출력이 일반 문단보다 읽기 나쁜 경우가 많습니다. 따라서 이 플래그는 화자 분리가 그 위험을 감수할 가치가 있는 경우를 위해 유지되며, 일반 옵션으로 권장되지는 않습니다. 이 플래그는 캐시 키의 일부이므로, 이 플래그를 켜거나 꺼도 오래된 전사본이 반환되지 않습니다.

format_transcript

이미 디스크에 있는 전사본에 대한 두 번째 선택적 패스입니다. 포맷팅을 참조하세요.

estimate_cost

동일한 source를 받아 길이, 예상 USD, 상한, 그리고 작업이 허용될지 여부를 반환합니다. Deepgram 요청은 이루어지지 않습니다. URL은 여전히 다운로드되는데, 그렇지 않으면 길이를 알 수 없기 때문입니다. 따라서 Deepgram 요금은 없지만 즉각적이지는 않습니다.

CLI

transcribe ./interview.mp4 --diarize   # experimental, labels are often wrong
transcribe ./lecture.mp3 --estimate
transcribe ./clip.mp4 --json | jq .transcript_path

종료 코드: 0 성공, 2 비용 상한 초과로 거부, 3 구성 오류 또는 바이너리 누락, 1 그 외 모든 경우.

transcribe format ./output/interview-final-8a2c1d0b7e64
transcribe format ./interview.mp4 --force

format 하위 명령은 작업 폴더 또는 그 작업을 생성한 로컬 파일을 받으며, --force와 --json을 허용합니다.

포맷팅

원시 전사본은 정확하지만 읽기 어렵습니다. 한 덩어리의 텍스트이거나, 화자를 들을 수 없는 규칙에 따라 4문장마다 잘린 문단입니다. 포맷팅 패스는 언어 모델이 단어에 접근하지 못하게 하면서 이 문제를 해결합니다.

전사본은 번호가 매겨진 문장으로 분할되어 저렴한 OpenRouter 모델로 전송되며, 모델은 구조만 응답합니다. 문단 나눔이 뒤따르는 인덱스, 선택적 { startIndex, title } 섹션 제목, 그리고 3~8개의 kebab-case 주제 태그입니다. 그런 다음 저장된 문장 배열에서 Markdown이 재구성됩니다. 누락되거나, 바뀌거나, 지어낸 문장은 검토가 아니라 구조적으로 불가능합니다. 모델에서 텍스트가 절대 돌아오지 않기 때문입니다.

• 선택적. transcribe는 절대 자동으로 포맷팅하지 않습니다. format_transcript 또는 transcribe format을 실행하세요.

• 부분 실패만 가능. 문장은 창 단위로 전송됩니다. 계획이 유효하지 않거나 요청이 계속 실패하는 창은 재시도된 후 일반 문단으로 남고 건너뛴 범위로 보고됩니다. 전사본이 원시 렌더링보다 나빠지는 일은 없습니다.

• 짧은 전사본에는 섹션이 없습니다. FORMAT_HEADINGS_MIN_SENTENCES 미만이면 모델에 문단과 태그만 요청됩니다. 4분짜리 음성 메모에 세 개의 지어낸 섹션이 필요하지 않습니다.

• 전사와 동일하게 캐시됨. 계획은 작업 폴더의 format.json에 기록됩니다. 두 번째 호출은 그 계획에서 다시 렌더링하며 비용이 들지 않습니다. force는 모델을 다시 호출합니다. 포맷팅된 작업에 transcribe를 다시 실행하면 저장된 계획을 덮어쓰지 않고 다시 적용합니다.

• 동일한 비용 보호. 포맷팅은 요청 전에 가격이 산정되며 MAX_COST_PER_JOB_USD를 초과하면 거부됩니다. 각 호출은 그 목적에 있어 별도의 작업입니다. Deepgram이 이미 부과한 비용과 합산되지 않습니다.

출력 레이아웃

<TRANSCRIPTION_OUTPUT_DIR>/<slug>-<key12>/

  URL sources:   never-gonna-give-you-up-dQw4w9WgXcQ-1f3b9c2d4e5a/
  Local files:   interview-final-8a2c1d0b7e64/
  audio.opus       the 16 kHz mono upload
  audio.<ext>      the yt-dlp download, for URL sources, kept so re-runs never re-fetch
  response.json    Deepgram's raw response
  format.json      the structure plan, once the transcript has been formatted
  transcript.md    YAML front matter plus the rendered transcript

캐싱

캐시 키는 소스 식별자에 전사본을 변경하는 옵션(model, diarize, language)을 더한 것입니다. 로컬 파일은 바이트의 SHA-256으로 식별되고, URL은 yt-dlp 추출기 ID로 식별되므로 추적 매개변수와 단축 링크 변형이 두 번째 유료 전사를 유발하지 않습니다.

폴더 이름은 장식용입니다. URL의 경우 비디오 제목 뒤에 비디오 ID가 붙고, 로컬 파일의 경우 파일 이름입니다. 작업은 끝의 <key12>만으로 찾으므로, 읽을 수 있는 절반이 무엇이든 폴더는 재사용됩니다. 업로더가 이름을 바꾼 비디오나 이 도구의 이전 버전이 이름을 붙인 폴더도 캐시에 적중하여 동일한 전사본에 두 번 비용을 지불하지 않습니다.

적중 시 저장된 response.json에서 transcript.md를 다시 렌더링하므로, 포맷터의 개선 사항이 비용 없이 이전 작업에 도달합니다. Deepgram을 다시 호출하는 것은 --force / force: true뿐입니다.

개발

npm test          # vitest
npm run typecheck
npm run build

어떤 테스트도 바이너리를 실행하거나 네트워크에 접촉하지 않습니다. ffprobe, ffmpeg, yt-dlp는 주입 가능한 명령 실행기를 거치고, Deepgram은 주입 가능한 fetch를 거칩니다.