platform/seed/skills/whisper-cpp/SKILL.md

name, description

name	description
whisper-cpp	Transcribe audio files to text using whisper.cpp. Use when the user wants to transcribe audio, convert speech to text, or extract text from an audio/video file.

Whisper.cpp

API reference for the whisper.cpp HTTP server running at http://macmini:8178.

whisper.cpp is a C/C++ port of OpenAI's Whisper speech recognition model. The server accepts audio files via HTTP and returns transcriptions in various formats.

Server

• Base URL: http://macmini:8178
• No authentication required

Endpoints

GET /health

Returns server status. Use to verify the server is running before making requests.

curl -s http://macmini:8178/health

{"status":"ok"}

POST /inference

Transcribes an audio file. Accepts multipart/form-data.

Example

curl -s http://macmini:8178/inference \
  -F file="@/path/to/audio.mp3" \
  -F temperature="0.0" \
  -F temperature_inc="0.2" \
  -F response_format="json"

Parameters

File (required)

Parameter	Type	Description
file	file	Audio file to transcribe. Accepts at least WAV and MP3.

Response Format

Parameter	Type	Default	Description
response_format	string	json	Output format: json, verbose_json (or vjson), text, srt, vtt

Language

Parameter	Type	Default	Description
language	string	en	Spoken language code (e.g. en, pt, es, fr). Use auto for auto-detection.
detect_language	bool	false	Exit after detecting the language (no transcription).
translate	bool	false	Translate from source language to English.

Decoding

Parameter	Type	Default	Description
temperature	float	0.0	Sampling temperature. 0.0 is deterministic.
temperature_inc	float	0.2	Temperature increment on fallback attempts.
best_of	int	2	Number of candidate decodings to keep.
beam_size	int	-1	Beam search size. -1 disables beam search.
entropy_thold	float	2.40	Entropy threshold — decoder fails and retries if exceeded.
logprob_thold	float	-1.00	Log probability threshold for decoder failure.
no_fallback	bool	false	Disable temperature fallback on decode failure.

Segmentation

Parameter	Type	Default	Description
max_len	int	0	Maximum segment length in characters. 0 for unlimited.
max_context	int	-1	Maximum text context tokens to store. -1 for unlimited.
split_on_word	bool	false	Split segments at word boundaries instead of token boundaries.
no_timestamps	bool	false	Suppress timestamps in output.
word_thold	float	0.01	Word timestamp probability threshold.

Audio Processing

Parameter	Type	Default	Description
offset_t	int	0	Time offset in milliseconds — skip this much audio from the start.
offset_n	int	0	Segment index offset.
duration	int	0	Duration of audio to process in milliseconds. 0 for all.
audio_ctx	int	0	Audio context size. 0 for all.

Speaker Diarization

Parameter	Type	Default	Description
diarize	bool	false	Enable speaker diarization (requires stereo audio).
tinydiarize	bool	false	Enable tinydiarize (requires a tdrz model).

Voice Activity Detection (VAD)

Parameter	Type	Default	Description
vad	bool	false	Enable VAD preprocessing.
vad_threshold	float	0.50	Speech confidence threshold (0.0–1.0).
vad_min_speech_duration_ms	int	250	Minimum speech segment duration in ms.
vad_min_silence_duration_ms	int	100	Minimum silence duration to split segments.
vad_max_speech_duration_s	float	FLT_MAX	Auto-split segments longer than this (seconds).
vad_speech_pad_ms	int	30	Padding added around speech segments (ms).
vad_samples_overlap	float	0.10	Overlap between segments (seconds).

Other

Parameter	Type	Default	Description
prompt	string	""	Initial prompt to condition the model (e.g. for vocabulary hints).
suppress_nst	bool	false	Suppress non-speech tokens.
no_context	bool	false	Do not use previous audio context for subsequent segments.
debug_mode	bool	false	Enable debug output.

Response Formats

json (default)

Minimal JSON with just the transcribed text.

{"text": "The transcribed content goes here."}

verbose_json (or vjson)

Extended JSON including task type, language, audio duration, per-segment timestamps, token-level timing, confidence scores, and language probability distribution.

text

Plain text transcription. Includes speaker labels if diarization is enabled.

srt

SubRip subtitle format with sequential numbering, HH:MM:SS,mmm timestamps, and text content.

1
00:00:00,000 --> 00:00:03,500
The transcribed content goes here.

vtt

WebVTT subtitle format with WEBVTT header and HH:MM:SS.mmm timestamps.

WEBVTT

00:00:00.000 --> 00:00:03.500
The transcribed content goes here.

POST /load

Loads a different model file on the server at runtime.

curl -s http://macmini:8178/load \
  -F model="/path/to/model.bin"

Parameter	Type	Description
model	string	Path to the model file on the server.

Supported Audio Formats

The server accepts at least WAV (16-bit PCM) and MP3 files directly. If the server was started with --convert, it can use ffmpeg to handle additional formats (ogg, flac, m4a, etc.).

Common Recipes

Transcribe to plain text

curl -s http://macmini:8178/inference \
  -F file="@audio.mp3" \
  -F temperature="0.0" \
  -F temperature_inc="0.2" \
  -F response_format="text"

Transcribe non-English audio

curl -s http://macmini:8178/inference \
  -F file="@audio.mp3" \
  -F language="pt" \
  -F temperature="0.0" \
  -F temperature_inc="0.2" \
  -F response_format="json"

Translate foreign audio to English

curl -s http://macmini:8178/inference \
  -F file="@audio.mp3" \
  -F language="auto" \
  -F translate="true" \
  -F temperature="0.0" \
  -F temperature_inc="0.2" \
  -F response_format="json"

Generate SRT subtitles

curl -s http://macmini:8178/inference \
  -F file="@audio.mp3" \
  -F temperature="0.0" \
  -F temperature_inc="0.2" \
  -F response_format="srt" \
  > subtitles.srt

Transcribe with VAD (skip silence)

curl -s http://macmini:8178/inference \
  -F file="@audio.mp3" \
  -F temperature="0.0" \
  -F temperature_inc="0.2" \
  -F vad="true" \
  -F response_format="json"

Transcribe with vocabulary hints

curl -s http://macmini:8178/inference \
  -F file="@audio.mp3" \
  -F temperature="0.0" \
  -F temperature_inc="0.2" \
  -F prompt="Kubernetes, kubectl, etcd, gRPC" \
  -F response_format="json"

---

Source

• Repository: https://github.com/ggml-org/whisper.cpp
• Server docs: https://github.com/ggml-org/whisper.cpp/blob/master/examples/server/README.md