speech-to-text

Transcribe local video files into VTT subtitles and TXT transcripts using OpenAI Whisper.

Updated May 1, 2026
One-click install
npx skills add https://github.com/xiaoquqi/hermes-agent-skills --skill speech-to-text-xiaoquqi
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: speech-to-text
Source: https://github.com/xiaoquqi/hermes-agent-skills/tree/main/media/speech-to-text
Command: npx skills add https://github.com/xiaoquqi/hermes-agent-skills --skill speech-to-text-xiaoquqi

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires whisper, and includes scripts (resource) and references (resource) components.

What problem does it solve?

使用 OpenAI Whisper (本地) 对 YouTube 视频进行语音识别。 输入:视频文件路径(mp4/webm/mkv)或 yt-download 输出目录。 逻辑:已有 VTT 字幕则跳过,否则用 medium 模型运行语音识别。 输出:VTT 时间戳字幕 + TXT 纯文本,保存到视频同目录。 注意:无 GPU 的 Mac 用 medium 模型(large 太慢);有 GPU 可用 large。

Core Features & Use Cases

  • 本地离线转录视频为带时间戳的 VTT 字幕和 TXT 文本,方便后续编辑和检索。
  • 若同目录已有 VTT 文件,将跳过转录以实现幂等。
  • 根据硬件自动选择模型:无 GPU 使用 medium,若有 GPU 可用可选 large。
  • 输出文件为 {VIDEO_NAME}.vtt 与 {VIDEO_NAME}.txt,保存于视频同一目录。
  • 适用场景:视频归档、字幕生成、无网络环境下的隐私保护转录。

Quick Start

运行 speech-to-text.sh,传入视频文件或包含视频的目录,并可选指定模型。

Frequently Asked Questions about speech-to-text

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I transcribe local video files to VTT subtitles offline?

To transcribe local video files to VTT subtitles offline, run the script with a video file or directory path. It uses local Whisper to generate timestamped VTT subtitle and TXT transcript files saved in the same directory.

What is the best way to run Whisper transcription on a Mac without a GPU?

For Whisper transcription on a Mac without a GPU, the best way is using the medium model. The large model is too slow for non-GPU hardware, while GPU-enabled machines can opt for the large model.

How does Whisper handle existing VTT subtitle files during video transcription?

Whisper handles existing VTT subtitle files by skipping the video transcription process entirely. This idempotent behavior prevents redundant processing and preserves previously generated timestamped subtitles.

Does the Whisper speech-to-text tool support MKV and WebM video formats?

Yes, the Whisper speech-to-text tool supports MKV and WebM video formats. It processes local video content from these files and outputs readable transcripts alongside timestamped VTT subtitles.

Can I batch process a directory of videos for subtitle generation?

Yes, you can batch process a directory of videos for subtitle generation. Pass a directory path to the script, and it applies Whisper transcription to all contained videos, skipping any with existing VTT files.

Why does local video transcription skip some files and not others?

Local video transcription skips files that already have a VTT subtitle file in the same directory. This idempotent check avoids duplicating work and ensures only videos without existing text transcripts are processed.