skillZs
★ LIVE SKILL TAGS ★
>>> LIVE SKILLS INDEX <<<
* OPEN SOURCE *
NO LOGIN, NO TRACKING
※ REAL INSTALL DATA ※
← back to all skills
maxgent-ai/maxgent-plugin56 installs

audio-transcribe

Speech-to-text transcription using Whisper with word-level timestamps. Use when users ask to transcribe audio or video to text, generate subtitles, or recognize speech.

How do I install this agent skill?

npx skills add https://github.com/maxgent-ai/maxgent-plugin --skill audio-transcribe
view source ↗

Is this agent skill safe to install?

  • Gen Agent Trust Hubpass

    The skill is functional for audio transcription but contains common security surfaces such as shell command interpolation and the potential for indirect prompt injection from transcribed audio content.

  • Socketpass

    No alerts

  • Snykpass

    Risk: LOW · No issues

  • Runlayerwarn

    2/2 files flagged

  • ZeroLeakspass

    Score: 93/100 · 2 sections analyzed

What does this agent skill do?

Audio Transcriber

Speech recognition using WhisperX with multi-language support and word-level timestamp alignment.

Prerequisites

Requires Python 3.12 (uv manages this automatically).

Usage

When the user wants to transcribe audio/video: $ARGUMENTS

Instructions

Step 1: Get input file

If the user has not provided an input file path, ask them to provide one.

Supported formats:

  • Audio: MP3, WAV, FLAC, M4A, OGG, etc.
  • Video: MP4, MKV, MOV, AVI, etc. (audio is extracted automatically)

Verify the file exists:

ls -la "$INPUT_FILE"

Step 2: Ask user for configuration

Warning: You MUST use AskUserQuestion to collect user preferences. Do not skip this step.

Use AskUserQuestion to collect the following:

  1. Model size: Choose the recognition model

    • Options:
      • "base - Balanced speed and accuracy (Recommended)"
      • "tiny - Fastest, lower accuracy"
      • "small - Faster, moderate accuracy"
      • "medium - Slower, higher accuracy"
      • "large-v2 - Slowest, highest accuracy"
  2. Language: What language is the audio?

    • Options:
      • "Auto-detect (Recommended)"
      • "Chinese (zh)"
      • "English (en)"
      • "Japanese (ja)"
      • "Other"
  3. Word-level alignment: Do you need word-level timestamps?

    • Options:
      • "Yes - Precise timing for each word (Recommended)"
      • "No - Sentence-level timing only (faster)"
  4. Output format: What format to output?

    • Options:
      • "TXT - Plain text with timestamps (Recommended)"
      • "SRT - Subtitle format"
      • "VTT - Web subtitle format"
      • "JSON - Structured data (with word-level info)"
  5. Output path: Where to save?

    • Default: same directory as input file, named <original_name>.txt (or matching format)

Step 3: Run transcription script

Use the transcribe.py script in the skill directory:

uv run /path/to/skills/audio-transcribe/transcribe.py "INPUT_FILE" [OPTIONS]

Parameters:

  • --model, -m: Model size (tiny/base/small/medium/large-v2)
  • --language, -l: Language code (en/zh/ja/...), auto-detect if not specified
  • --no-align: Skip word-level alignment
  • --no-vad: Disable VAD filtering (use if transcription has time jumps or missing segments)
  • --output, -o: Output file path
  • --format, -f: Output format (srt/vtt/txt/json)

Examples:

# Basic transcription (auto-detect language)
uv run skills/audio-transcribe/transcribe.py "video.mp4" -o "video.txt"

# Chinese transcription, output SRT subtitles
uv run skills/audio-transcribe/transcribe.py "audio.mp3" -l zh -f srt -o "subtitles.srt"

# Fast transcription, skip word alignment
uv run skills/audio-transcribe/transcribe.py "audio.wav" --no-align -o "transcript.txt"

# Use a larger model, output JSON (with word-level timestamps)
uv run skills/audio-transcribe/transcribe.py "speech.mp3" -m medium -f json -o "result.json"

# Disable VAD filtering (fix time jumps / missing segments)
uv run skills/audio-transcribe/transcribe.py "audio.mp3" --no-vad -o "transcript.txt"

Step 4: Present results

After transcription completes:

  1. Show the full output file path
  2. Display a preview of the transcription content
  3. Report total duration and segment count

Output format reference

TXT format

[00:00:00.000 - 00:00:03.500] This is the first sentence
[00:00:03.500 - 00:00:07.200] This is the second sentence

SRT format

1
00:00:00,000 --> 00:00:03,500
This is the first sentence

2
00:00:03,500 --> 00:00:07,200
This is the second sentence

JSON format (with word-level)

[
  {
    "start": 0.0,
    "end": 3.5,
    "text": "This is the first sentence",
    "words": [
      {"word": "This", "start": 0.0, "end": 0.5, "score": 0.95},
      ...
    ]
  }
]

Troubleshooting

Slow on first run:

  • WhisperX needs to download model files; first run will be slower
  • Subsequent runs use the cached model

Out of memory:

  • Use a smaller model (tiny or base)
  • Ensure the system has enough memory

Low recognition accuracy:

  • Try a larger model (medium or large-v2)
  • Explicitly specify the language instead of auto-detect

Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.

<a href="https://skillzs.dev/skills/maxgent-ai/maxgent-plugin/audio-transcribe">View audio-transcribe on skillZs</a>