Skip to main content
Glama
nmbrthirteen

podcli

by nmbrthirteen
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

transcribe_podcast

Convert podcast audio or video into a word-level, speaker-labeled transcript with Whisper AI, returning metadata for clip analysis. Use it first before reading transcript and suggesting clips.

Instructions

STEP 1 — Transcribe a podcast video/audio file. This is typically the first tool you call.

What it does: Uses Whisper AI for word-level timestamps, with speaker detection (who said what) on by default. Speaker labels are what let a clip tell a question from an answer, so leave them on for any interview. Pass enable_diarization=false to skip them and save time on a single-speaker recording. Returns: Lightweight metadata only — duration, language, word/segment counts, speaker summary, and packed_ready flag. The actual transcript body is NOT returned here (it would be 500KB+ for a typical episode). Read the content via get_ui_state(include_transcript: true) which returns a compact phrase-grouped markdown view (~10x smaller than raw segments). Caching: Results are cached by file hash — same file won't be re-transcribed. Supported formats: MP4, MOV, WebM, MKV, MP3, WAV.

After transcription: call get_ui_state(include_transcript: true) to read the transcript, then analyze it for viral moments and call suggest_clips.

Input Schema

NameRequiredDescriptionDefault
engineNoTranscription engine
languageNoISO language code
file_pathYesAbsolute path to the podcast file
model_sizeNoWhisper model sizebase
num_speakersNoExact number of speakers if known (e.g. 2). Auto-detects if omitted.
start_secondsNoSample mode: only transcribe a window starting here (seconds into the source), instead of the whole file, e.g. to test a language on 40s before committing to a full run. Pair with duration_seconds. Not written to the main transcript cache.
duration_secondsNoSample mode window length in seconds. Defaults start_seconds to 0 if omitted.
enable_diarizationNoSpeaker labels (who is speaking). On by default: without them a clip cannot tell a question from an answer. Set false only for a single-speaker recording. Falls back to no labels with a warning where torch is unavailable.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changedv2.8.0
    • addedInput schema / properties / duration_seconds
      Added value: +{
+  "description": "Sample mode window length in seconds. Defaults start_seconds to 0 if omitted.",
+  "type": "number"
+}
    • changedInput schema / properties / engine / enum
      Previous value: -[
-  "whisper-py",
-  "whispercpp",
-  "assemblyai"
-]New value: +[
+  "whisper-py",
+  "whispercpp",
+  "assemblyai",
+  "omnilingual"
+]
    • addedInput schema / properties / start_seconds
      Added value: +{
+  "description": "Sample mode: only transcribe a window starting here (seconds into the source), instead of the whole file, e.g. to test a language on 40s before committing to a full run. Pair with duration_seconds. Not written to the main transcript cache.",
+  "type": "number"
+}
  2. Changed2 schema fields changedv2.7.3
    • changedInput schema / properties / enable_diarization / default
      Previous value: -falseNew value: +true
    • changedInput schema / properties / enable_diarization / description
      Previous value: -"Set true for speaker labels (who is speaking). Works where torch is available (whisper-py engine); slower. Default: false"New value: +"Speaker labels (who is speaking). On by default: without them a clip cannot tell a question from an answer. Set false only for a single-speaker recording. Falls back to no labels with a warning where torch is unavailable."
  3. Changed1 schema field changedv2.7.2
    • removedInput schema / additionalProperties
      Removed value: -false
  4. Changed2 schema fields changedv2.5.0
    • changedInput schema / properties / enable_diarization / default
      Previous value: -trueNew value: +false
    • changedInput schema / properties / enable_diarization / description
      Previous value: -"Enable speaker detection (who is speaking). Default: true"New value: +"Set true for speaker labels (who is speaking). Works where torch is available (whisper-py engine); slower. Default: false"
  5. Changed1 schema field changedv2.3.0
    • addedInput schema / properties / engine
      Added value: +{
+  "description": "Transcription engine",
+  "enum": [
+    "whisper-py",
+    "whispercpp",
+    "assemblyai"
+  ],
+  "type": "string"
+}
  6. First observedv2.0.0

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden and does so well: it discloses the returns are metadata-only, that transcript body is NOT returned, caching by file hash, format support, and a torch-unavailable fallback. This is exactly the behavioral context an agent needs to avoid a wrong post-call inference.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured with labeled sections (What it does / Returns / Caching / Supported formats / After transcription) and front-loaded purpose. Slightly long and repeats the diarization rationale, but every block is useful and skimmable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 8-param, no-output-schema, no-annotation transcription tool, the description covers the missing return-value contract, the follow-up read path, caching semantics, and format support. An agent could call this and its follow-ups correctly without inspecting anything else.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: it explains the diarization default and why it matters (question vs answer), and explains sample mode via start_seconds/duration_seconds including the cache caveat. It does not cover engine, language, or model_size tradeoffs, leaving some value on the table.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Transcribe a podcast video/audio file') and frames itself as the entry point ('typically the first tool you call'), which distinguishes it from siblings like transcribe_start and compare_transcription_engines.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit sequencing: 'After transcription: call get_ui_state(include_transcript: true) ... then ... call suggest_clips.' It also gives a when-to-disable condition for diarization ('Set false only for a single-speaker recording') and names the read step needed to access content.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools