ossicle

Transcribe local media files and URLs with Deepgram, as an MCP server for Claude Code and as a standalone CLI. Transcripts are written to disk as Markdown; nothing large is ever returned inline.

Every job is priced from its measured duration before anything is sent, and a job whose estimate exceeds the configured per-job cap is refused outright. That guard is the point of the package.

Requirements

• Node >= 20

• ffprobe and ffmpeg on PATH (duration measurement and the 16 kHz mono opus upload)

• yt-dlp on PATH, if you want URL input

• A Deepgram API key

Install

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

Configuration

Configuration is read only from the .env file in the package root. Shell-exported variables and claude mcp add --env flags are ignored on purpose, so the server behaves identically no matter which project launched it.

MCP server

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

transcribe

Returns the transcript path, the job folder, duration, estimated and actually-spent USD, a cached flag, and a preview capped at 500 characters. The full transcript stays on disk.

Diarization

Diarization is experimental and off by default. On real recordings Deepgram misattributes turns often enough that the speaker-labelled output reads worse than plain paragraphs, so the flag is kept for the cases where speaker separation is worth that risk rather than recommended as a normal option. It stays part of the cache key, so flipping it never returns a stale transcript.

format_transcript

A second, optional pass over a transcript already on disk. See Formatting.

estimate_cost

Takes the same source and returns duration, estimated USD, the cap, and whether the job would be allowed. No Deepgram request is made. A URL is still downloaded, because duration is unknowable otherwise, so this is free of Deepgram charges but not instant.

CLI

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

Exit codes: 0 success, 2 refused for exceeding the cost cap, 3 configuration or missing binary, 1 everything else.

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

The format subcommand takes a job folder or the local file that produced one, and accepts --force and --json.

Formatting

A raw transcript is accurate and close to unreadable: one wall of text, or paragraphs cut every four sentences by a rule that cannot hear the speaker. The formatting pass fixes that without letting a language model near the words.

The transcript is split into numbered sentences and sent to a cheap OpenRouter model, which replies with structure only: the indices a paragraph break follows, optional { startIndex, title } section headings, and three to eight kebab-case topic tags. The Markdown is then rebuilt from the stored sentence array. A dropped, reworded, or invented sentence is impossible by construction rather than by review, because no text ever comes back from the model.

• Opt in. transcribe never formats for you. Run format_transcript or transcribe format.

• Partial failure only. Sentences are sent in windows. A window whose plan is invalid or whose request keeps failing is retried, then left as plain paragraphs and reported as a skipped range. The transcript is never left worse than the raw render.

• Short transcripts get no sections. Below FORMAT_HEADINGS_MIN_SENTENCES the model is asked for paragraphs and tags only. A four-minute voice note does not need three invented sections.

• Cached like transcription. The plan is written to format.json in the job folder. A second call re-renders from it and spends nothing; force re-calls the model. Re-running transcribe on a formatted job reapplies the stored plan instead of clobbering it.

• Same cost guard. Formatting is priced before any request and refused over MAX_COST_PER_JOB_USD. Each invocation is its own job for that purpose: it is never summed with what Deepgram already cost.

Output layout

<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

Caching

The cache key is the source identity plus the options that change the transcript: model, diarize, and language. Local files are identified by a SHA-256 of their bytes; URLs by the yt-dlp extractor id, so tracking parameters and short-link variants never cause a second paid transcription.

The folder name is cosmetic: for a URL it is the video title followed by the video id, and for a local file the filename. A job is found by the trailing <key12> alone, so a folder is reused whatever its readable half says. A video renamed by its uploader, or a folder named by an older version of this tool, still hits the cache rather than paying for the same transcript twice.

A hit re-renders transcript.md from the stored response.json rather than returning the old Markdown, so improvements to the formatter reach old jobs at zero cost. Only --force / force: true re-calls Deepgram.

Development

npm test          # vitest
npm run typecheck
npm run build

No test spawns a binary or touches the network: ffprobe, ffmpeg, and yt-dlp go through an injectable command runner, and Deepgram goes through an injectable fetch.