Getting Started

cuttledoc is a speech-to-text library and CLI for Node.js. It supports local CoreML transcription on Apple Silicon, cloud transcription through OpenAI, and optional LLM correction or Markdown formatting.

Installation

pnpm add cuttledoc

You need Node.js 22 or newer. Local Parakeet and Whisper transcription requires macOS on Apple Silicon and disk space for the selected speech model. Linux and Windows deployments can use the OpenAI backend.

Transcribe from the CLI

# LLM correction is enabled by default
npx cuttledoc video.mp4

# Return raw speech-to-text output
npx cuttledoc video.mp4 --no-correct

# Add Markdown structure and write to a file
npx cuttledoc podcast.mp3 --format --output transcript.md

# Select a local backend and language
npx cuttledoc meeting.m4a --backend parakeet --language de

The first local run needs the corresponding speech model. Download it explicitly when preparing a machine:

npx cuttledoc models download parakeet

See the CLI Reference for every option and Model Management for speech and LLM downloads.

Use OpenAI transcription

OpenAI works on macOS, Linux, and Windows. It requires network access and an API key, but no local speech model.

export OPENAI_API_KEY=sk-...
npx cuttledoc meeting.m4a --backend openai

The default OpenAI speech model is gpt-4o-transcribe. See Backends for model selection, platform constraints, privacy considerations, and automatic backend behavior.

Transcribe from Node.js

import { transcribe } from 'cuttledoc'

const result = await transcribe('audio.mp3', {
  backend: 'auto',
  language: 'en'
})

console.log(result.text)
console.log(result.durationSeconds)
console.log(result.segments)

The API returns speech-to-text output without LLM correction. For OpenAI, pass backend: 'openai'; the API reads OPENAI_API_KEY when apiKey is omitted.

See the API Reference for result types, backend helpers, and model-management functions.

Enhance a transcript

Install the separate LLM package when using enhancement from application code:

pnpm add @cuttledoc/llm

import { transcribe } from 'cuttledoc'
import { enhanceTranscript } from '@cuttledoc/llm'

const transcript = await transcribe('podcast.mp3')
const enhanced = await enhanceTranscript(transcript.text, {
  provider: 'ollama',
  model: 'phi4:14b',
  mode: 'correct'
})

console.log(enhanced.plainText)

Correction fixes transcription errors while preserving structure. Format mode additionally adds Markdown paragraphs, headings, and lists. See LLM Enhancement for providers, models, cache paths, and long-transcript behavior.

Choose your next step