API Reference

Public APIs for transcription and LLM enhancement

cuttledoc exposes two packages:

cuttledoc transcribes audio and video files.
@cuttledoc/llm corrects or formats transcript text.

The CLI combines both packages, but the library APIs remain independent.

Transcription

`transcribe()`

import { transcribe } from 'cuttledoc'

const result = await transcribe('meeting.m4a', {
  backend: 'auto',
  language: 'de'
})

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

function transcribe(audioPath: string, options?: TranscribeOptions): Promise<TranscriptionResult>

Automatic backend selection uses Parakeet or Whisper on macOS. On Linux and Windows it selects OpenAI when an API key is available and otherwise throws an actionable error.

`TranscribeOptions`

Option	Type	Default	Description
`backend`	`BackendType`	`'auto'`	Transcription backend
`language`	`string`	auto-detected	Language code such as `de` or `en-US`
`onProgress`	`(partial: PartialResult) => void`	—	Receives partial transcription results
`apiKey`	`string`	environment	OpenAI key; `OPENAI_API_KEY` is also supported
`model`	`string`	backend	Backend-specific model; currently used by OpenAI

For OpenAI, model accepts gpt-4o-transcribe or gpt-4o-mini-transcribe.

`TranscriptionResult`

interface TranscriptionResult {
  text: string
  segments: readonly TranscriptionSegment[]
  words?: readonly WordTimestamp[] // Parakeet only
  durationSeconds: number
  processingTimeSeconds: number
  language: string
  backend: BackendType
}

interface TranscriptionSegment {
  text: string
  startSeconds: number
  endSeconds: number
  confidence?: number
}

interface WordTimestamp {
  word: string
  startSeconds: number
  endSeconds: number
  confidence?: number
}

interface PartialResult {
  text: string
  isFinal: boolean
}

Backend selection

import { getAvailableBackends, getBackend, selectBestBackend, setBackend } from 'cuttledoc'

setBackend('whisper')
console.log(getBackend()) // 'whisper'

const selected = selectBestBackend('de')
const available = getAvailableBackends()

Function	Returns	Purpose
`setBackend(backend)`	`void`	Sets the process-wide default backend
`getBackend()`	`BackendType`	Gets the current process-wide default
`selectBestBackend(language?, apiKey?)`	`BackendType`	Selects a backend for the platform and input
`getAvailableBackends()`	`readonly BackendInfo[]`	Describes all supported backends

BackendInfo.isAvailable reports platform availability. OpenAI still requires a valid API key when used.

Model management

import { cleanup, downloadModel, isModelDownloaded } from 'cuttledoc'

await downloadModel('parakeet')
const ready = await isModelDownloaded('parakeet')

// Dispose cached backend instances before process shutdown when needed.
await cleanup()

downloadModel() and isModelDownloaded() accept a BackendType. Pass a concrete local backend; 'auto' cannot identify a downloadable model. OpenAI requires no local download.

Core exports

Export	Kind
`BACKEND_TYPES`	Constant
`PARAKEET_MODELS`, `WHISPER_MODELS`, `OPENAI_TRANSCRIBE_MODELS`	Constants
`COREML_MODELS`, `COREML_MODEL_TYPES`	Constants
`Backend`, `BackendInfo`, `BackendOptions`, `BackendType`	Types
`ParakeetModel`, `WhisperModel`, `OpenAITranscribeModel`	Types
`TranscribeOptions`, `TranscriptionResult`, `TranscriptionSegment`	Types
`PartialResult`, `WordTimestamp`, `CoreMLModelInfo`, `CoreMLModelType`	Types
`LOCAL_MODELS`, `LocalModelId`	LLM re-exports
`downloadLLMModel`, `isLLMModelDownloaded`	LLM aliases

The LLM aliases avoid collisions with the transcription package's own model-management functions.

LLM enhancement

`enhanceTranscript()`

import { enhanceTranscript } from '@cuttledoc/llm'

const result = await enhanceTranscript(rawTranscript, {
  provider: 'ollama',
  model: 'phi4:14b',
  mode: 'correct'
})

console.log(result.markdown)
console.log(result.stats.model)

function enhanceTranscript(transcript: string, options?: EnhanceOptions): Promise<EnhanceResult>

When provider is omitted, detection tries Ollama, then OpenAI, then the embedded local provider. Model defaults are provider-specific: Ollama uses phi4:14b, local GGUF uses gemma3n:e4b, and OpenAI uses its own default.

`EnhanceOptions`

Option	Type	Default	Description
`provider`	`LLMProvider`	auto-detected	LLM provider
`model`	`string`	provider	Provider-specific model
`mode`	`ProcessMode`	`'correct'`	Correct text or add Markdown structure
`temperature`	`number`	`0.3`	Generation temperature
`apiKey`	`string`	environment	OpenAI key
`modelPath`	`string`	cache	Custom GGUF path for the local provider
`gpuLayers`	`number`	`-1`	GGUF layers offloaded to the GPU
`contextSize`	`number`	model	GGUF context-size override

`EnhanceResult`

interface EnhanceResult {
  markdown: string
  plainText: string
  stats: {
    processingTimeSeconds: number
    inputTokens: number
    outputTokens: number
    tokensPerSecond: number
    correctionsCount: number
    paragraphCount: number
    provider: LLMProvider
    model: string
  }
  corrections: Correction[]
}

interface Correction {
  original: string
  corrected: string
}

Provider detection

import { detectProvider, isLLMAvailable } from '@cuttledoc/llm'

const provider = await detectProvider()
const available = await isLLMAvailable()

Function	Returns	Purpose
`detectProvider()`	`Promise<LLMProvider \| null>`	Finds the first available provider
`isLLMAvailable()`	`Promise<boolean>`	Reports whether any provider is usable

Provider-specific APIs

Provider	Processor	Convenience function	Availability helpers
Ollama	`OllamaProcessor`	`enhanceWithOllama`	`isOllamaRunning`, `hasOllamaModel`, `listOllamaModels`
OpenAI	`OpenAIProcessor`	`enhanceWithOpenAI`	`hasOpenAIKey`
Local	`LocalProcessor`	`enhanceWithLocal`	`hasModelsDirectory`, `isModelDownloaded`

Use LocalProcessor.initialize() before processing and dispose() afterward. enhanceTranscript() manages that lifecycle automatically.

Local model management

import { downloadModel, isModelDownloaded, LOCAL_MODELS } from '@cuttledoc/llm'

if (!isModelDownloaded('gemma3n:e4b')) {
  await downloadModel('gemma3n:e4b', {
    onProgress: (progress) => console.log(Math.round(progress * 100))
  })
}

console.log(LOCAL_MODELS['gemma3n:e4b'])

The LLM downloadModel() function downloads GGUF models to the stable per-user cache documented in the LLM guide.

LLM exports

Export	Kind
`LOCAL_MODELS`, `OLLAMA_MODELS`, `OPENAI_MODELS`, `PROCESS_MODES`	Constants
`LLMProvider`, `LocalModelId`, `OllamaModelId`, `OpenAIModelId`, `ProcessMode`	Types
`EnhanceOptions`, `EnhanceResult`, `Correction`, `ChunkedEnhanceOptions`	Types
`DEFAULT_CHUNK_SIZE`, `splitTranscriptIntoChunks`	Chunking
`TRANSCRIPT_CORRECTION_PROMPT`, `TRANSCRIPT_FORMAT_PROMPT`	Prompts
`countParagraphs`, `findCorrections`, `stripMarkdown`	Utilities