ossicle

Transkribieren Sie lokale Mediendateien und URLs mit Deepgram, als MCP-Server für Claude Code und als eigenständige CLI. Transkripte werden als Markdown auf der Festplatte gespeichert; nichts Großes wird jemals inline zurückgegeben.

Jeder Auftrag wird anhand seiner gemessenen Dauer bevor irgendetwas gesendet wird, bepreist, und ein Auftrag, dessen Schätzung das konfigurierte Limit pro Auftrag überschreitet, wird rundweg abgelehnt. Diese Absicherung ist der Sinn des Pakets.

Voraussetzungen

• Node >= 20

• ffprobe und ffmpeg im PATH (Messung der Dauer und der 16-kHz-Mono-Opus-Upload)

• yt-dlp im PATH, wenn Sie URL-Eingaben wünschen

• Ein Deepgram-API-Schlüssel

Installation

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

Konfiguration

Die Konfiguration wird nur aus der Datei .env im Paketstammverzeichnis gelesen. Shell-exportierte Variablen und claude mcp add --env-Flags werden absichtlich ignoriert, sodass sich der Server unabhängig davon, welches Projekt ihn gestartet hat, identisch verhält.

MCP-Server

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

transcribe

Gibt den Transkriptpfad, den Auftragsordner, die Dauer, geschätzte und tatsächlich ausgegebene USD, ein cached-Flag und eine Vorschau von maximal 500 Zeichen zurück. Das vollständige Transkript bleibt auf der Festplatte.

Diarisierung

Die Diarisierung ist experimentell und standardmäßig deaktiviert. Bei echten Aufnahmen schreibt Deepgram Sprecherwechsel oft genug falsch zu, sodass die sprechergekennzeichnete Ausgabe schlechter lesbar ist als einfache Absätze. Daher wird das Flag für die Fälle beibehalten, in denen die Trennung der Sprecher dieses Risiko wert ist, anstatt es als normale Option zu empfehlen. Es bleibt Teil des Cache-Schlüssels, sodass ein Umschalten niemals ein veraltetes Transkript zurückgibt.

format_transcript

Ein zweiter, optionaler Durchlauf über ein bereits auf der Festplatte befindliches Transkript. Siehe Formatierung.

estimate_cost

Nimmt dieselbe source entgegen und gibt Dauer, geschätzte USD, die Obergrenze und zurück, ob der Auftrag erlaubt wäre. Es wird keine Deepgram-Anfrage gestellt. Eine URL wird dennoch heruntergeladen, da die Dauer sonst nicht ermittelbar ist. Dies ist also frei von Deepgram-Gebühren, aber nicht sofort.

CLI

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

Exit-Codes: 0 Erfolg, 2 wegen Überschreitung des Kostenlimits abgelehnt, 3 Konfiguration oder fehlende Binärdatei, 1 alles andere.

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

Der Unterbefehl format akzeptiert einen Auftragsordner oder die lokale Datei, die einen erzeugt hat, und akzeptiert --force und --json.

Formatierung

Ein rohes Transkript ist akkurat und nahezu unlesbar: ein einziger Textblock oder Absätze, die von einer Regel, die den Sprecher nicht hören kann, alle vier Sätze abgeschnitten werden. Der Formatierungslauf behebt das, ohne ein Sprachmodell an die Wörter zu lassen.

Das Transkript wird in nummerierte Sätze aufgeteilt und an ein billiges OpenRouter-Modell gesendet, das nur mit Struktur antwortet: die Indizes, auf die ein Absatzumbruch folgt, optionale Abschnittsüberschriften { startIndex, title } und drei bis acht Kebab-Case-Themen-Tags. Das Markdown wird dann aus dem gespeicherten Satzarray neu aufgebaut. Ein verlorener, umformulierter oder erfundener Satz ist konstruktionsbedingt unmöglich, nicht nur durch Überprüfung, da niemals Text vom Modell zurückkommt.

• Opt-in. transcribe formatiert nie für Sie. Führen Sie format_transcript oder transcribe format aus.

• Nur Teilfehler. Sätze werden in Fenstern gesendet. Ein Fenster, dessen Plan ungültig ist oder dessen Anfrage weiterhin fehlschlägt, wird erneut versucht, dann als einfache Absätze belassen und als übersprungener Bereich gemeldet. Das Transkript wird nie schlechter hinterlassen als die Rohausgabe.

• Kurze Transkripte erhalten keine Abschnitte. Unterhalb von FORMAT_HEADINGS_MIN_SENTENCES wird das Modell nur um Absätze und Tags gebeten. Eine vierminütige Sprachnotiz benötigt keine drei erfundenen Abschnitte.

• Wie die Transkription zwischengespeichert. Der Plan wird in format.json im Auftragsordner geschrieben. Ein zweiter Aufruf rendert daraus neu und kostet nichts; force ruft das Modell erneut auf. Die erneute Ausführung von transcribe auf einem formatierten Auftrag wendet den gespeicherten Plan erneut an, anstatt ihn zu überschreiben.

• Gleiche Kostensicherung. Die Formatierung wird vor jeder Anfrage bepreist und über MAX_COST_PER_JOB_USD hinaus abgelehnt. Jeder Aufruf ist für diesen Zweck ein eigener Auftrag: Er wird nie mit den bereits angefallenen Deepgram-Kosten summiert.

Ausgabelayout

<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

Zwischenspeicherung

Der Cache-Schlüssel ist die Quellidentität plus die Optionen, die das Transkript verändern: model, diarize und language. Lokale Dateien werden über einen SHA-256-Hash ihrer Bytes identifiziert; URLs über die yt-dlp-Extraktor-ID, sodass Tracking-Parameter und Kurzlink-Varianten niemals eine zweite kostenpflichtige Transkription verursachen.

Der Ordnername ist rein kosmetisch: Bei einer URL handelt es sich um den Videotitel gefolgt von der Video-ID und bei einer lokalen Datei um den Dateinamen. Ein Auftrag wird ausschließlich über das nachgestellte <key12> gefunden, sodass ein Ordner unabhängig von seiner lesbaren Hälfte wiederverwendet wird. Ein vom Uploader umbenanntes Video oder ein von einer älteren Version dieses Tools benannter Ordner trifft weiterhin auf den Cache, anstatt zweimal für dasselbe Transkript zu zahlen.

Ein Treffer rendert transcript.md aus der gespeicherten response.json neu, anstatt das alte Markdown zurückzugeben, sodass Verbesserungen am Formatierer alte Aufträge kostenlos erreichen. Nur --force / force: true ruft Deepgram erneut auf.

Entwicklung

npm test          # vitest
npm run typecheck
npm run build

Kein Test startet eine Binärdatei oder greift auf das Netzwerk zu: ffprobe, ffmpeg und yt-dlp laufen über einen injizierbaren Befehls-Runner und Deepgram über ein injizierbares fetch.