---
name: Transcribe Audio File
description: Transcribe an audio file to text over your own whisper.cpp server, no model turn per file.
category: Media
version: 1
mode: script
inline: true
language: typescript
tags:
  - audio
  - transcription
skills:
  - transcribe
inputs:
  - name: file_path
    description: Path to the audio file to transcribe. Auto-filled from the file browser.
    required: true
  - name: output_dir
    description: >-
      Where to write the transcript. Absolute, or relative to the recording. Leave it out and the text
      lands beside the recording, which is what a person clicking a file wants. A commander passes its own
      directory so its results never land in the folder it watches.
    required: false
    hidden: true
trigger:
  - type: file
    extensions:
      - mp3
      - wav
      - m4a
---

# Transcribe Audio File

Sends the audio file to the `transcribe` plugin's own route — `POST /api/transcribe/transcribe` — and
files the result next to the original.

A **script** task, deliberately: the plugin already does its own language detection and transcription
server-side, so there is nothing here worth a model turn for. Running one per audio file would be a
model call spent re-deriving what the plugin already returns.

## What it does

1. Read the audio file at `file_path` and the caller's spoken-language preferences
   (`GET /api/user/settings`).
2. `POST` the file to `/api/transcribe/transcribe`. The plugin detects the language and transcribes
   faithfully in it — see `plugins/transcribe/skills/transcribe/SKILL.md` for the contract.
3. Write the transcription as `.md` with the same base name — beside the recording by default, or into
   `output_dir` when one is given. The directory is created if it does not exist.

It overwrites a previous transcription of the same file, deliberately: a transcription is derived, and
running it again means you wanted it again.

## Before it runs

The plugin has to be configured — `PUT /api/transcribe/config` with a reachable whisper.cpp URL. If it
is not, this fails with that told plainly rather than a generic error.

## What it deliberately does not do

The worked example this was adapted from (an agentic task) ran its own detect-language pass before
transcribing, and generated a title from the transcription's contents. Both are dropped here: the
detect-then-transcribe step is already what the plugin's route does internally, so repeating it would be
redundant work against the same server. And a generated title needs a model turn, which is exactly what
this task exists to avoid spending per file.