1. 為什么要做本地 AI 字幕工具做視頻內(nèi)容創(chuàng)作或者課程整理的朋友大概率都遇到過這樣的場景手上有幾十段訪談錄音、網(wǎng)課錄像或者會議紀要需要把它們轉(zhuǎn)成帶時間軸的字幕文件方便后續(xù)剪輯、校對或者做二次分發(fā)。最初我的做法是找在線工具一個文件一個文件上傳轉(zhuǎn)完再手動下載。遇到長視頻還要掐著時間分段處理一邊擔心平臺限額一邊擔心上傳的素材會不會被留存。后來換成本地 AI 方案之后這些問題基本都消失了。本文要分享的就是一套完全運行在本地電腦上的批量音視頻轉(zhuǎn)文字工具核心功能圍繞三點展開批量處理把整個文件夾里的音頻、視頻一次性交給程序。長音頻自動切分不需要手工剪斷文件程序會按靜音點或其他策略自動分段轉(zhuǎn)寫。斷點續(xù)跑轉(zhuǎn)寫到一半斷電、報錯或手動停止下次啟動自動跳過已完成內(nèi)容。整套方案基于開源語音識別模型實現(xiàn)不需要 GPU 也能跑重點在于工程化封裝把模型調(diào)用、音頻切分、SRT 字幕生成、任務進度記錄這幾件事整合到一起。讀完本文你不僅會得到一個能直接運行的腳本還能理解它背后的設計思路方便后續(xù)按自己的需求改造。2. 技術方案與核心概念2.1 音頻轉(zhuǎn)文字的常見路徑目前主流的語音識別開源方案有 Whisper、faster-whisper、FunASR、Kaldi 等。其中 Whisper 和 faster-whisper 是社區(qū)使用最廣泛的兩類。Whisper 是 OpenAI 開源的語音識別模型支持多語言、帶時間戳輸出可以直接生成類似 SRT 的段落信息。faster-whisper 是 Whisper 模型的加速推理版本底層使用 CTranslate2 做模型推理在 CPU 上的速度比原版快不少內(nèi)存占用也更低。對于本地批量處理來說faster-whisper 是更務實的選擇。音頻切分方面一般有兩種思路固定時長切分按 30 秒、60 秒一個片段切分實現(xiàn)簡單但可能切斷句子導致字幕語義不完整。靜音檢測切分通過分析音頻能量找到相對安靜的位置作為切分點能較好地保留完整句子邊界。本文采用靜音檢測為主、固定時長兜底的方式兼顧轉(zhuǎn)寫質(zhì)量和流程穩(wěn)定性。2.2 SRT 字幕格式SRT 是通用性最強的字幕格式之一幾乎所有播放器和剪輯軟件都支持。一個 SRT 文件的結(jié)構大致如下1 00:00:01,000 -- 00:00:05,000 大家好今天我們來聊一聊字幕工具的實現(xiàn)。 2 00:00:06,500 -- 00:00:10,200 首先需要準備 Python 環(huán)境和語音識別模型。其中數(shù)字是字幕序號第二行是時間軸第三行開始是字幕文本。時間軸格式必須嚴格遵循“小時:分鐘:秒,毫秒”毫秒部分用逗號分隔。2.3 什么是續(xù)跑所謂續(xù)跑是指在批量處理過程中記錄每個文件、每個切片的狀態(tài)。當程序異常退出或人為中斷時已經(jīng)處理完成的部分不需要重新轉(zhuǎn)寫。實現(xiàn)續(xù)跑的關鍵在于任務狀態(tài)持久化本文采用 JSON 文件記錄任務清單和完成狀態(tài)每次啟動時先讀取狀態(tài)文件再決定哪些任務需要執(zhí)行。3. 環(huán)境準備與項目結(jié)構3.1 運行環(huán)境和依賴建議使用 Python 3.9 及以上版本。操作系統(tǒng)方面Windows、macOS、Linux 均可但 ffmpeg 的安裝方式略有差異。需要安裝的 Python 庫如下pip install faster-whisper pydub numpyffmpeg 是音頻解碼和切分的關鍵工具faster-whisper 解碼音頻時依賴它。Windows 用戶可以從 ffmpeg 官網(wǎng)下載可執(zhí)行文件然后把 bin 目錄加入系統(tǒng) PATH。macOS 用戶可以用 Homebrew 安裝brew install ffmpegUbuntu/Debian 用戶執(zhí)行sudo apt update sudo apt install ffmpeg安裝完成后可以在終端執(zhí)行ffmpeg -version驗證是否生效。3.2 模型選擇說明faster-whisper 支持多種尺寸的模型包括 tiny、base、small、medium、large-v3 等。模型越大識別準確率越高但推理速度越慢內(nèi)存占用也越高。如果只是處理清晰的中文訪談或課程small或medium是比較合適的選擇。如果對準確率要求高且機器配置足夠可以嘗試large-v3。模型首次運行時需要聯(lián)網(wǎng)下載下載完成后會緩存在本地后續(xù)使用不需要再次下載。3.3 項目文件結(jié)構為了讓代碼結(jié)構清晰建議按下面的目錄組織項目audio2srt/ ├── main.py # 主入口任務調(diào)度 ├── config.py # 配置參數(shù) ├── audio_splitter.py # 音頻切分模塊 ├── transcribe.py # 轉(zhuǎn)寫模塊 ├── srt_generator.py # SRT 字幕生成模塊 ├── task_manager.py # 任務狀態(tài)管理續(xù)跑核心 ├── input/ # 存放待處理的音視頻 ├── output/ # 輸出的 SRT 字幕文件 └── progress/ # 任務狀態(tài)記錄本文后續(xù)的代碼均按該結(jié)構編寫實際操作時可以根據(jù)自己的項目習慣調(diào)整。4. 核心模塊設計與代碼實現(xiàn)4.1 配置文件先創(chuàng)建一個config.py把常用的參數(shù)集中管理方便修改。# 文件路徑config.py import os BASE_DIR os.path.dirname(os.path.abspath(__file__)) INPUT_DIR os.path.join(BASE_DIR, input) OUTPUT_DIR os.path.join(BASE_DIR, output) PROGRESS_DIR os.path.join(BASE_DIR, progress) # 支持的音視頻格式 SUPPORTED_EXTS {.mp3, .wav, .m4a, .flac, .mp4, .mkv, .avi, .mov, .webm} # Whisper 模型參數(shù) MODEL_SIZE small DEVICE cpu COMPUTE_TYPE int8 # 音頻切分參數(shù) MIN_SILENCE_DURATION 500 # 最小靜音時長毫秒 SILENCE_THRESHOLD -40 # 靜音判定閾值dBFS MAX_SEGMENT_DURATION 30 # 單段最大時長秒 KEEP_TRAILING_SILENCE True # 是否保留段尾靜音 # 轉(zhuǎn)寫參數(shù) LANGUAGE zh BEAM_SIZE 5 VAD_FILTER True # 是否啟用語音活動檢測過濾靜音段 # 輸出參數(shù) OUTPUT_FORMAT srt這里需要說明幾個關鍵參數(shù)SILENCE_THRESHOLD靜音判定閾值單位是 dBFS值越小表示要求越安靜才判定為靜音。一般-35到-45之間效果不錯可以根據(jù)實際錄音環(huán)境調(diào)整。MAX_SEGMENT_DURATION切分后單段音頻的最大時長避免某一段過長導致模型推理壓力過大。VAD_FILTER啟用后可以自動過濾掉沒有人聲的純靜音片段對訪談類音頻特別有用。4.2 音頻切分模塊音頻切分模塊的作用是把長音頻按照靜音位置切成多個小片段并返回每個片段在原音頻中的起始時間。這里用 pydub 來做靜音檢測和切分。# 文件路徑audio_splitter.py from pydub import AudioSegment from pydub.silence import detect_silence, split_on_silence import config def find_split_points(audio_segment): 找出音頻中的靜音區(qū)間確定切分點。 返回切分點的時間位置列表單位為毫秒。 silence_ranges detect_silence( audio_segment, min_silence_lenconfig.MIN_SILENCE_DURATION, silence_threshconfig.SILENCE_THRESHOLD, ) split_points [] current_position 0 for start, end in silence_ranges: # 如果當前段已經(jīng)達到最大時長則在此靜音處切分 if start - current_position config.MAX_SEGMENT_DURATION * 1000: split_points.append((start end) // 2) current_position (start end) // 2 return split_points def split_audio(input_path): 切分音頻文件返回片段列表。 每個片段是一個 dict包含 start_time、end_time 和音頻對象。 audio AudioSegment.from_file(input_path) split_points find_split_points(audio) segments [] last_point 0 for point in split_points: segment audio[last_point:point] segments.append({ start_time: last_point, end_time: point, audio: segment, }) last_point point # 最后一段 if last_point len(audio): segments.append({ start_time: last_point, end_time: len(audio), audio: audio[last_point:], }) return segments這個實現(xiàn)的核心邏輯是先檢測所有達到最小靜音時長的區(qū)間然后只選取那些“距離上一個切分點已經(jīng)超過最大單段時長”的靜音位置作為切分點。這樣做的好處是既不會把句子切得七零八落也不會讓單段音頻過長。4.3 轉(zhuǎn)寫模塊轉(zhuǎn)寫模塊封裝了 faster-whisper 的調(diào)用邏輯。為了讓批次處理更高效這里采用分段轉(zhuǎn)寫的方式將每個切分好的音頻片段導出為臨時 WAV 文件再交給 faster-whisper 轉(zhuǎn)寫并記錄該片段相對原文件的偏移量。# 文件路徑transcribe.py import tempfile import os from faster_whisper import WhisperModel import config class Transcriber: def __init__(self): self.model WhisperModel( config.MODEL_SIZE, deviceconfig.DEVICE, compute_typeconfig.COMPUTE_TYPE, ) def transcribe_segment(self, audio_segment, start_time_ms): 轉(zhuǎn)寫單個音頻片段。 audio_segment: pydub AudioSegment 對象 start_time_ms: 該片段在原音頻中的起始時間毫秒 返回字幕片段列表時間軸為原音頻絕對時間。 # 將 pydub 音頻導出為臨時 WAV 文件 with tempfile.NamedTemporaryFile(suffix.wav, deleteFalse) as tmp_file: tmp_path tmp_file.name audio_segment.export(tmp_path, formatwav) try: segments, info self.model.transcribe( tmp_path, languageconfig.LANGUAGE, beam_sizeconfig.BEAM_SIZE, vad_filterconfig.VAD_FILTER, ) subtitle_segments [] for seg in segments: subtitle_segments.append({ start: start_time_ms seg.start * 1000, end: start_time_ms seg.end * 1000, text: seg.text.strip(), }) return subtitle_segments finally: os.remove(tmp_path)這里有一個容易被忽略的細節(jié)轉(zhuǎn)寫返回的seg.start和seg.end是相對當前 WAV 文件的秒數(shù)。如果直接把這個時間寫入最終字幕時間軸會錯亂。所以必須加上start_time_ms偏移量轉(zhuǎn)成原音頻的絕對時間。4.4 SRT 文件生成模塊SRT 生成模塊把時間戳轉(zhuǎn)換成標準格式并寫入文件。# 文件路徑srt_generator.py def ms_to_srt_time(ms): 將毫秒時間轉(zhuǎn)換為 SRT 時間軸格式HH:MM:SS,mmm hours ms // 3600000 minutes (ms % 3600000) // 60000 seconds (ms % 60000) // 1000 milliseconds ms % 1000 return f{hours:02d}:{minutes:02d}:{seconds:02d},{milliseconds:03d} def write_srt(subtitle_segments, output_path): 將字幕片段列表寫入 SRT 文件。 subtitle_segments 需要按 start 時間升序排列。 subtitle_segments.sort(keylambda x: x[start]) with open(output_path, w, encodingutf-8) as f: for idx, seg in enumerate(subtitle_segments, start1): start_time ms_to_srt_time(seg[start]) end_time ms_to_srt_time(seg[end]) f.write(f{idx}\n) f.write(f{start_time} -- {end_time}\n) f.write(f{seg[text]}\n\n)4.5 任務狀態(tài)管理模塊續(xù)跑功能的實現(xiàn)依賴這個模塊。設計思路是程序處理前先生成一個待處理任務列表寫入任務文件每完成一個文件就把完成狀態(tài)寫入文件。下次啟動時加載任務文件跳過節(jié)已完成的任務。# 文件路徑task_manager.py import json import os def load_progress(progress_path): 加載任務進度文件。 如果文件不存在返回空字典。 if not os.path.exists(progress_path): return {} with open(progress_path, r, encodingutf-8) as f: return json.load(f) def save_progress(progress_path, progress_data): 保存任務進度到 JSON 文件。 with open(progress_path, w, encodingutf-8) as f: json.dump(progress_data, f, ensure_asciiFalse, indent2) def build_task_list(input_dir, supported_exts): 掃描輸入目錄生成待處理文件列表。 返回按文件名排序的列表保證處理順序穩(wěn)定。 task_list [] for root, dirs, files in os.walk(input_dir): for file in files: ext os.path.splitext(file)[1].lower() if ext in supported_exts: task_list.append(os.path.join(root, file)) return sorted(task_list) def is_task_completed(progress_data, file_path): 判斷某個文件是否已經(jīng)處理完成。 return progress_data.get(file_path) completed4.6 主程序主程序負責把上面的模塊串聯(lián)起來。核心邏輯是加載任務列表。讀取進度文件過濾已完成任務。逐個處理未完成任務處理成功后更新進度文件。所有任務完成后輸出匯總信息。# 文件路徑main.py import os import sys import time import config from audio_splitter import split_audio from transcribe import Transcriber from srt_generator import write_srt, ms_to_srt_time from task_manager import load_progress, save_progress, build_task_list, is_task_completed def process_file(transcriber, input_path, output_path): 處理單個音視頻文件生成 SRT 字幕文件。 print(f[處理] {input_path}) # 1. 按靜音切分音頻 segments split_audio(input_path) print(f[切分] 共切分為 {len(segments)} 段) # 2. 逐段轉(zhuǎn)寫 all_subtitles [] total_duration_ms sum(seg[end_time] - seg[start_time] for seg in segments) for idx, seg in enumerate(segments, start1): seg_duration seg[end_time] - seg[start_time] print(f[轉(zhuǎn)寫] 第 {idx}/{len(segments)} 段時長 {seg_duration / 1000:.1f}s) start_time time.time() subtitles transcriber.transcribe_segment(seg[audio], seg[start_time]) elapsed time.time() - start_time print(f 已用 {elapsed:.1f}s識別 {len(subtitles)} 條字幕) all_subtitles.extend(subtitles) # 3. 生成 SRT 文件 write_srt(all_subtitles, output_path) print(f[完成] 字幕已保存至 {output_path}) def main(): os.makedirs(config.OUTPUT_DIR, exist_okTrue) os.makedirs(config.PROGRESS_DIR, exist_okTrue) progress_path os.path.join(config.PROGRESS_DIR, task_progress.json) progress_data load_progress(progress_path) task_list build_task_list(config.INPUT_DIR, config.SUPPORTED_EXTS) pending_tasks [t for t in task_list if not is_task_completed(progress_data, t)] if not pending_tasks: print(沒有待處理的任務全部已完成。) return print(f待處理任務數(shù){len(pending_tasks)}) transcriber Transcriber() for task_path in pending_tasks: try: rel_path os.path.relpath(task_path, config.INPUT_DIR) base_name os.path.splitext(rel_path)[0] output_path os.path.join(config.OUTPUT_DIR, base_name .srt) os.makedirs(os.path.dirname(output_path), exist_okTrue) process_file(transcriber, task_path, output_path) # 更新任務狀態(tài) progress_data[task_path] completed save_progress(progress_path, progress_data) except Exception as e: print(f[錯誤] 處理 {task_path} 時發(fā)生異常{e}) print(跳過該文件繼續(xù)處理下一個任務。) print(所有任務處理完成。) if __name__ __main__: main()這個主程序已經(jīng)具備完整的批量處理和續(xù)跑能力。程序每處理完一個文件就會立刻把狀態(tài)寫入 JSON 文件。即使中途崩潰已完成文件的進度也不會丟失。5. 完整運行演示5.1 準備測試文件在input目錄下放入兩到三個音視頻文件比如input/ ├── 課程01.mp4 ├── 訪談02.m4a └── 會議記錄03.mp35.2 運行程序在項目根目錄執(zhí)行python main.py首次運行會下載模型網(wǎng)絡較慢時可能需要等待一段時間。模型下載完成后程序會自動開始處理。5.3 預期輸出正常情況下控制臺輸出類似這樣待處理任務數(shù)3 [處理] /path/to/input/課程01.mp4 [切分] 共切分為 12 段 [轉(zhuǎn)寫] 第 1/12 段時長 28.3s 已用 15.2s識別 6 條字幕 [轉(zhuǎn)寫] 第 2/12 段時長 30.0s 已用 17.8s識別 5 條字幕 ... [完成] 字幕已保存至 /path/to/output/課程01.srt全部完成后output目錄下會生成對應的 SRT 文件output/ ├── 課程01.srt ├── 訪談02.srt └── 會議記錄03.srt5.4 續(xù)跑驗證可以手動中斷程序來驗證續(xù)跑功能。只要程序在處理完完整文件后才更新進度那么中斷后再次運行已經(jīng)完成的任務會自動跳過只會處理剩余文件。比如上面的示例中如果課程01.srt已經(jīng)生成而訪談02.m4a處理到一半被中斷重新運行程序后控制臺會顯示待處理任務數(shù)2 [處理] /path/to/input/訪談02.m4a ...課程01.mp4不會再被重復處理這就是續(xù)跑帶來的效率提升。6. 常見問題與排查思路6.1 常見錯誤對照表問題現(xiàn)象常見原因解決思路導入 pydub 時提示找不到 ffmpegffmpeg 未安裝或未加入系統(tǒng) PATH安裝 ffmpeg執(zhí)行ffmpeg -version檢查轉(zhuǎn)寫速度很慢模型過大或 CPU 性能不足改用 small/base 模型或開啟 int8 量化字幕時間軸錯亂轉(zhuǎn)寫時間未加偏移量檢查transcribe_segment中是否加上start_time_ms識別內(nèi)容為空音頻音量太低或語言參數(shù)不對增大音量檢查LANGUAGE參數(shù)打開 VAD 過濾檢測靜音失敗沒有切分點靜音閾值設置不合理調(diào)高SILENCE_THRESHOLD到 -30 或 -25程序報錯提示磁盤空間不足臨時 WAV 文件堆積檢查臨時文件目錄確認代碼中已刪除臨時文件6.2 音頻切分效果不佳怎么辦切分效果與錄音環(huán)境密切相關。如果錄音中存在明顯的環(huán)境噪聲靜音檢測可能失效導致切分點過少或過密。遇到這種情況可以先做一個簡單的降噪預處理from pydub import AudioSegment from pydub.effects import normalize audio AudioSegment.from_file(input_path) audio normalize(audio)normalize會把音頻的峰值音量歸一化能讓后續(xù)的靜音檢測更穩(wěn)定。6.3 內(nèi)存占用過高怎么辦如果一次處理時長很長的音頻pydub 會把整個音頻加載到內(nèi)存中導致內(nèi)存占用飆升。對于超過 1 小時的音頻建議先用 ffmpeg 按固定時間窗口切割成若干中間文件再逐個調(diào)用AudioSegment.from_file加載。這個策略雖然多做了一步文件操作但內(nèi)存消耗會穩(wěn)定很多。7. 最佳實踐與工程建議7.1 合理設計任務狀態(tài)更新時機續(xù)跑不是簡單地加一個 try-except 就能實現(xiàn)。真正的關鍵點是任務狀態(tài)必須在“整個文件的字幕文件成功寫入磁盤之后”更新而不是在轉(zhuǎn)寫開始時更新。這樣即使轉(zhuǎn)寫中途崩潰下次啟動也能重新處理不會生成殘缺的字幕文件。7.2 輸出文件命名規(guī)范建議輸出 SRT 文件時保持與源文件相同的相對路徑這樣既避免重名覆蓋又方便管理。對于不同語言的翻譯需求可以在文件名后追加語言后綴例如課程01.zh.srt、課程01.en.srt。7.3 日志與可觀測性批量處理任務往往耗時較長如果缺少日志很難定位問題。建議在關鍵節(jié)點加入日志輸出并寫入獨立的日志文件。Python 的logging模塊可以很方便地實現(xiàn)控制臺和文件雙輸出。7.4 隱私與安全在本地運行 AI 模型的優(yōu)勢之一是不需要把數(shù)據(jù)上傳到第三方服務。如果你的素材涉及隱私信息或商業(yè)機密本地推理是更安全的選擇。需要注意模型文件本身是公開的輸入內(nèi)容不會離開本機這一點在向團隊推廣時可以重點說明。7.5 模型選擇與成本控制如果只是輕量使用base和small模型已經(jīng)能覆蓋大部分中文場景。medium和large-v3雖然在復雜口音、背景噪聲場景下表現(xiàn)更好但推理時間會成倍增加。建議先用少量樣本測試不同模型的效果和耗時再正式批量運行。8. 擴展方向當前版本的工具已經(jīng)具備完整的“批量處理、長音頻切分、續(xù)跑”三大能力。如果想進一步實用化可以考慮下面幾個方向多格式輸出在 SRT 之外同時輸出 VTT、純文本 TXT 或帶說話人標簽的 JSON。說話人分離接入 pyannote 等說話人分離模型讓字幕區(qū)分“人物 A / 人物 B”。并行加速在 CPU 多核環(huán)境下可以同時對多個文件啟動轉(zhuǎn)寫進程進一步縮短總耗時。定時任務把腳本封裝成可執(zhí)行文件配合系統(tǒng)自帶定時任務在夜間自動處理素材。字幕翻譯對轉(zhuǎn)寫文本調(diào)用本地翻譯模型實現(xiàn)字幕自動翻譯方便做雙語字幕。本文給出的代碼完全可以在本地直接運行。核心價值在于把“音頻切分、模型轉(zhuǎn)寫、字幕生成、狀態(tài)管理”這四個環(huán)節(jié)拆成獨立模塊每一塊都可以按你的實際場景替換或增強。如果你在做批量字幕處理時還有其他問題歡迎在評論區(qū)交流我會根據(jù)實際問題繼續(xù)補充更深入的實踐方案。