ossicle

Transcribe archivos multimedia locales y URL con Deepgram, como servidor MCP para Claude Code y como CLI independiente. Las transcripciones se escriben en disco como Markdown; nada grande se devuelve nunca en línea.

Cada trabajo se tasa a partir de su duración medida antes de enviar nada, y un trabajo cuya estimación supera el tope configurado por trabajo se rechaza de plano. Esa salvaguarda es la razón de ser del paquete.

Requisitos

• Node >= 20

• ffprobe y ffmpeg en PATH (medición de duración y subida de opus mono a 16 kHz)

• yt-dlp en PATH, si quieres entrada de URL

• Una clave de API de Deepgram

Instalación

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

Configuración

La configuración se lee solo del archivo .env en la raíz del paquete. Las variables exportadas en la shell y las opciones claude mcp add --env se ignoran a propósito, de modo que el servidor se comporta igual sin importar qué proyecto lo haya lanzado.

Servidor MCP

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

transcribe

Devuelve la ruta de la transcripción, la carpeta del trabajo, la duración, el USD estimado y el realmente gastado, una marca cached y una vista previa limitada a 500 caracteres. La transcripción completa queda en disco.

Diarización

La diarización es experimental y está desactivada por defecto. En grabaciones reales, Deepgram atribuye mal los turnos con la suficiente frecuencia como para que la salida etiquetada por hablante se lea peor que los párrafos normales, así que la opción se mantiene para los casos en los que la separación de hablantes vale ese riesgo, en lugar de recomendarse como una opción normal. Sigue formando parte de la clave de caché, de modo que cambiarla nunca devuelve una transcripción obsoleta.

format_transcript

Un segundo pase opcional sobre una transcripción ya en disco. Ver Formato.

estimate_cost

Acepta la misma source y devuelve la duración, el USD estimado, el tope y si el trabajo estaría permitido. No se hace ninguna petición a Deepgram. Una URL sí se descarga, porque de otro modo la duración es incognoscible, así que esto no tiene cargos de Deepgram, pero no es instantáneo.

CLI

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

Códigos de salida: 0 éxito, 2 rechazado por superar el tope de coste, 3 error de configuración o binario ausente, 1 cualquier otra cosa.

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

El subcomando format acepta una carpeta de trabajo o el archivo local que la produjo, y admite --force y --json.

Formato

Una transcripción en bruto es precisa y casi ilegible: un muro de texto, o párrafos cortados cada cuatro frases por una regla que no oye al hablante. El pase de formateo lo soluciona sin dejar que un modelo de lenguaje se acerque a las palabras.

La transcripción se divide en frases numeradas y se envía a un modelo barato de OpenRouter, que responde solo con estructura: los índices tras los que va un salto de párrafo, encabezados de sección opcionales { startIndex, title } y de tres a ocho etiquetas de tema en kebab-case. El Markdown se reconstruye a partir de la matriz de frases almacenada. Una frase omitida, reformulada o inventada es imposible por construcción, no por revisión, porque el modelo nunca devuelve texto.

• Adopción voluntaria. transcribe nunca formatea por ti. Ejecuta format_transcript o transcribe format.

• Solo fallos parciales. Las frases se envían en ventanas. Una ventana cuyo plan no es válido o cuya petición sigue fallando se reintenta y, si no, se deja como párrafos normales y se notifica como un rango omitido. La transcripción nunca queda peor que la representación sin formatear.

• Las transcripciones cortas no tienen secciones. Por debajo de FORMAT_HEADINGS_MIN_SENTENCES solo se le piden al modelo párrafos y etiquetas. Una nota de voz de cuatro minutos no necesita tres secciones inventadas.

• Cacheada como la transcripción. El plan se escribe en format.json dentro de la carpeta del trabajo. Una segunda llamada vuelve a renderizar a partir de él y no gasta nada; force vuelve a llamar al modelo. Volver a ejecutar transcribe sobre un trabajo formateado reaplica el plan almacenado en lugar de sobrescribirlo.

• La misma salvaguarda de coste. El formateo se tasa antes de cualquier petición y se rechaza por encima de MAX_COST_PER_JOB_USD. Cada invocación es su propio trabajo a esos efectos: nunca se suma a lo que Deepgram ya haya costado.

Estructura de salida

<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

Caché

La clave de caché es la identidad de la fuente más las opciones que cambian la transcripción: model, diarize y language. Los archivos locales se identifican por un SHA-256 de sus bytes; las URL, por el id del extractor de yt-dlp, de modo que los parámetros de seguimiento y las variantes de enlace corto nunca provocan una segunda transcripción de pago.

El nombre de la carpeta es cosmético: para una URL es el título del vídeo seguido del id del vídeo, y para un archivo local, el nombre del archivo. Un trabajo se encuentra solo por el <key12> final, así que una carpeta se reutiliza diga lo que diga su mitad legible. Un vídeo cuyo subidor haya cambiado el nombre, o una carpeta nombrada por una versión anterior de esta herramienta, sigue dando con la caché en lugar de pagar dos veces por la misma transcripción.

Un acierto vuelve a renderizar transcript.md a partir del response.json almacenado en lugar de devolver el Markdown anterior, de modo que las mejoras del formateador llegan a los trabajos antiguos sin coste. Solo --force / force: true vuelve a llamar a Deepgram.

Desarrollo

npm test          # vitest
npm run typecheck
npm run build

Ninguna prueba lanza un binario ni toca la red: ffprobe, ffmpeg y yt-dlp pasan por un ejecutor de comandos inyectable, y Deepgram pasa por un fetch inyectable.