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.

Variable	Required	Default	Meaning
DEEPGRAM_API_KEY	yes		Deepgram API key
DEEPGRAM_MODEL	no	nova-3	Transcription model
DEEPGRAM_USD_PER_MINUTE	no	0.0043	Price per audio minute, used for the estimate
MAX_COST_PER_JOB_USD	no	1.00	Hard per-job ceiling. Over it is a refusal, never a prompt
TRANSCRIPTION_OUTPUT_DIR	no	./output	Where job folders are written. Relative paths resolve against the package root
OPENROUTER_API_KEY	only to format		Key for the formatting pass. Transcription never needs it
OPENROUTER_MODEL	no	openai/gpt-4o-mini	Model the formatting pass asks for structure from
FORMAT_HEADINGS_MIN_SENTENCES	no	120	Below this many sentences, formatting adds paragraphs and tags but no sections

MCP server

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

transcribe

Input	Type	Default	Notes
source	string	required	Local file path, or any URL yt-dlp can fetch
diarize	boolean	false	Experimental. Speaker-labelled ## Speaker N [mm:ss] blocks
model	string	configured model	Deepgram model override
language	string	en	Spoken language code
force	boolean	false	Re-transcribe even on a cache hit. Costs money again

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

Input	Type	Default	Notes
target	string	required	The job_dir from a transcribe result, or the original local file path
force	boolean	false	Re-ask the model for structure. Costs money again

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

Flag	Default	Meaning
--diarize	off	Experimental. Label speakers
--model <name>	DEEPGRAM_MODEL, else nova-3	Deepgram model
--language <code>	en	Spoken language
--out <dir>	TRANSCRIPTION_OUTPUT_DIR, else ./output	Output directory
--force	off	Re-transcribe even on a cache hit
--estimate	off	Print duration and estimated USD, then exit
--json	off	Print one JSON object and nothing else on stdout
--help		List every flag

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.