Whisper字幕编程-智慧文博士

Whisper生成字幕的编程基础，核心是理解Whisper的核心API用法、字幕格式生成逻辑和常见场景的代码实现，以下内容从基础到实战，覆盖本地调用、字幕格式转换、批量处理等核心能力，所有代码可直接运行，适合编程基础扎实的你快速上手。

一、Whisper核心概念与环境准备

1. 核心概念

模型层级：Whisper提供tiny/base/small/medium/large-v3等模型，越大精度越高、速度越慢（large-v3支持多语言、实时字幕、词级时间戳）。
核心能力：语音转文字（ASR）、自动语言检测、时间戳生成（支持句级/词级）、多格式字幕输出（SRT/ASS/VTT）。
输入输出：支持音频文件（MP3/WAV/MP4等）、实时音频流；输出包含文本、时间戳、语言类型，可封装为标准字幕格式。

2. 环境安装（最简版）

# 安装核心依赖（Python 3.8+）pipinstallopenai-whisper# 核心库pipinstallffmpeg-python# 音频格式处理（可选，用于解析视频中的音频）# 安装PyTorch（GPU加速必备，CPU可跳过）pip3installtorch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

注：首次运行Whisper会自动下载模型（如large-v3约6GB），建议提前下载到本地指定路径（可通过WHISPER_CACHE_DIR环境变量配置）。

二、Whisper字幕编程核心API（基础版）

1. 最简示例：音频转SRT字幕

以下代码实现「本地音频文件→语音转写→生成SRT字幕」，是所有字幕开发的基础：

importwhisperimportosdefaudio_to_srt(audio_path:str,output_srt_path:str=None,model_size:str="base"):""" 基础功能：音频转SRT字幕 :param audio_path: 输入音频/视频路径（支持MP3/WAV/MP4等） :param output_srt_path: 输出SRT路径，默认与音频同目录 :param model_size: 模型大小（tiny/base/small/medium/large-v3） """# 1. 加载模型（首次运行自动下载）model=whisper.load_model(model_size)# 2. 语音转写（开启词级时间戳，提升字幕精度）# language="zh" 可指定语言，默认自动检测result=model.transcribe(audio_path,language="zh",# 强制指定中文，避免误检测word_timestamps=True,# 开启词级时间戳verbose=False# 关闭日志输出)# 3. 生成SRT文件（默认路径：音频文件名.srt）ifoutput_srt_pathisNone:output_srt_path=os.path.splitext(audio_path)[0]+".srt"# 4. 解析转写结果，写入SRTwithopen(output_srt_path,"w",encoding="utf-8")asf:# 遍历每一段字幕（segments是句级，words是词级）foridx,segmentinenumerate(result["segments"],1):# 格式化开始/结束时间（SRT格式：00:00:00,000 --> 00:00:05,000）start=format_timestamp(segment["start"])end=format_timestamp(segment["end"])# 字幕文本（去除首尾空格）text=segment["text"].strip()# 写入SRTf.write(f"{idx}\n{start}-->{end}\n{text}\n\n")print(f"✅ SRT字幕生成完成：{output_srt_path}")returnoutput_srt_pathdefformat_timestamp(seconds:float)->str:""" 辅助函数：将秒数转换为SRT标准时间格式 :param seconds: 时间戳（秒），如123.456 :return: 格式化字符串，如00:02:03,456 """hours=int(seconds//3600)minutes=int((seconds%3600)//60)secs=seconds%60# 格式：HH:MM:SS,mmm（注意是逗号，不是点）returnf"{hours:02d}:{minutes:02d}:{secs:06.3f}".replace(".",",")# 测试调用if__name__=="__main__":audio_to_srt(audio_path="test_audio.mp3",# 你的音频文件model_size="large-v3"# 推荐large-v3，中文精度最高)

2. 代码核心解析

核心代码	作用
`whisper.load_model("large-v3")`	加载指定大小的模型，large-v3对中文支持最好
`model.transcribe(...)`	核心转写函数，返回包含文本、时间戳的字典
`word_timestamps=True`	开启词级时间戳，可实现逐词字幕（如短视频卡点字幕）
`format_timestamp()`	转换秒数为SRT标准格式（SRT要求逗号分隔毫秒，而非点）
`result["segments"]`	句级字幕列表，每个元素包含start（开始秒数）、end（结束秒数）、text（文本）

3. 输入输出示例

输入：test_audio.mp3（内容：“你好，欢迎学习Whisper字幕编程”）

输出test_audio.srt内容：

1 00:00:00,000 --> 00:00:02,500 你好，欢迎学习Whisper字幕编程

三、进阶场景：Whisper字幕编程扩展

1. 从视频中提取音频并生成字幕

很多场景下输入是视频（MP4/AVI），需先提取音频再转写，结合ffmpeg-python实现：

importffmpegdefvideo_to_srt(video_path:str,model_size:str="large-v3")->str:""" 视频转SRT字幕（自动提取音频） """# 1. 提取视频中的音频（临时WAV文件）temp_audio="temp_audio.wav"ffmpeg.input(video_path).output(temp_audio,acodec="pcm_s16le",ac=1,ar="16k").run(overwrite_output=True)# 2. 调用基础函数生成SRTsrt_path=audio_to_srt(temp_audio,model_size=model_size)# 3. 删除临时音频os.remove(temp_audio)returnsrt_path# 测试调用video_to_srt("test_video.mp4")

2. 批量处理多个音频/视频文件

适合规模化生成字幕，如批量处理视频素材：

defbatch_generate_subtitles(input_dir:str,model_size:str="large-v3"):""" 批量生成字幕：遍历目录下所有音频/视频文件 :param input_dir: 输入目录 """# 支持的文件格式supported_formats=(".mp3",".wav",".mp4",".avi",".mov")# 遍历目录forfileinos.listdir(input_dir):file_path=os.path.join(input_dir,file)# 跳过文件夹，只处理支持的格式ifos.path.isfile(file_path)andfile.lower().endswith(supported_formats):print(f"\n正在处理：{file}")# 区分音频/视频iffile.lower().endswith((".mp3",".wav")):audio_to_srt(file_path,model_size=model_size)else:video_to_srt(file_path,model_size=model_size)# 测试调用：处理./videos目录下所有文件batch_generate_subtitles("./videos")

3. 生成词级字幕（逐字显示）

适合短视频、教程视频的逐字字幕，基于words字段实现：

defaudio_to_word_srt(audio_path:str,output_srt_path:str=None):""" 生成词级SRT字幕（逐字显示） """model=whisper.load_model("large-v3")result=model.transcribe(audio_path,language="zh",word_timestamps=True)ifoutput_srt_pathisNone:output_srt_path=os.path.splitext(audio_path)[0]+"_word.srt"withopen(output_srt_path,"w",encoding="utf-8")asf:idx=1# 遍历每一段，再遍历每个词forsegmentinresult["segments"]:forwordinsegment["words"]:start=format_timestamp(word["start"])end=format_timestamp(word["end"])text=word["word"].strip()iftext:# 跳过空文本f.write(f"{idx}\n{start}-->{end}\n{text}\n\n")idx+=1print(f"✅ 词级字幕生成完成：{output_srt_path}")returnoutput_srt_path

四、性能优化与常见问题

1. 性能优化（提速/降内存）

GPU加速：安装CUDA版PyTorch，模型加载和转写速度提升5-10倍（large-v3 GPU转写1小时音频约5分钟）。
模型选择：测试用base模型，生产用large-v3；中文场景优先large-v3，英文场景可用medium。
音频预处理：将音频转为16kHz单声道WAV（Whisper原生支持，无需额外处理）。
批量处理：避免循环加载模型（模型加载占80%时间），一次加载多次调用。

2. 常见问题与解决

问题	解决方法
中文识别错误多	1. 改用large-v3模型；2. 指定`language="zh"`；3. 提升音频清晰度（降噪）
时间戳不准	1. 开启`word_timestamps=True`；2. 音频重采样为16kHz；3. 手动调整错误时间戳
模型下载慢	1. 配置环境变量`WHISPER_CACHE_DIR`指定本地路径；2. 手动下载模型文件放到缓存目录
内存不足	1. 改用small/medium模型；2. 拆分长音频为多个短音频；3. 关闭其他占用内存的程序

五、Whisper字幕与视频框架集成

结合之前推荐的Remotion/MoviePy，可实现「字幕+视频+配音」一键合成，核心逻辑：

用Whisper生成SRT字幕文件；
视频框架（如Remotion）读取SRT文件，渲染到视频画面；
FFmpeg优化字幕样式（字体、颜色、位置）。

示例（MoviePy集成SRT字幕）：

frommoviepy.editorimportVideoFileClip,TextClip,CompositeVideoClipfrompysrtimportopenasopen_srtdefadd_srt_to_video(video_path:str,srt_path:str,output_path:str):""" MoviePy将SRT字幕叠加到视频 """video=VideoFileClip(video_path)srt=open_srt(srt_path,encoding="utf-8")clips=[video]# 基础视频# 遍历字幕，生成文本剪辑forsubinsrt:# 字幕文本text=sub.text# 字幕时长（秒）start=sub.start.seconds+sub.start.milliseconds/1000end=sub.end.seconds+sub.end.milliseconds/1000duration=end-start# 创建文本剪辑text_clip=TextClip(text,fontsize=40,color="white",font="SimHei",# 中文黑体stroke_color="black",stroke_width=2# 描边，提升可读性).set_position(("center","bottom")).set_duration(duration).set_start(start)clips.append(text_clip)# 合成视频final=CompositeVideoClip(clips)final.write_videofile(output_path,codec="libx264",audio_codec="aac")# 测试调用add_srt_to_video("test_video.mp4","test_video.srt","video_with_sub.mp4")