← 程式碼對照

image / audio — 媒體家族

「依賴式輸出」：EXIF、LLM 描述、語音轉錄各自可選
檔案：_image_converter.py · _audio_converter.py · _llm_caption.py · _transcribe_audio.py · _exiftool.py

大方向

圖片與音訊的 converter 都「看工具存在與否決定輸出」：EXIF 中繼資料需要 exiftool； 描述/OCR 需要 llm_client；轉錄需要 SpeechRecognition。所以「空輸出」、 「降級」都是這兩個 converter 的正常行為（案例頁有實測）。

1. ImageConverter

accepts / convert / _get_llm_description 圖片輸出 EXIF 中繼資料 + 可選的 LLM 圖片描述。

convert 兩段式：

  • exiftool_metadata() 抽出 ImageSize / Title / DateTimeOriginal / GPSPosition 等。
  • 有 llm_client + llm_model 時 _get_llm_description 把圖 base64 成 data:image/...;base64,... URI，呼叫 OpenAI 相容 chat.completions 取描述，輸出 # Description:。

兩者都缺 → 回傳空 Markdown。LLM 呼叫失敗會回 None（不炸）。

2. AudioConverter

accepts / convert 音訊輸出 EXIF 中繼資料 + 可選的語音轉錄稿。

EXIF 抽取後依副檔名判斷格式（wav/mp3/mp4），呼叫 transcribe_audio()； 只有 MissingDependencyException 會被吞掉（降級成只有 metadata）。 其他例外（如 SpeechRecognition 的 UnknownValueError）會向外傳播——這是案例頁 「純音調檔失敗」的根源。

3. 共用工具

exiftool_metadata(file_stream, *, exiftool_path=None) / _parse_version 工具呼叫 exiftool 子程序取 JSON 中繼資料。

以 -j（JSON）輸出跑 exiftool - 從 stdin 讀 bytes； _parse_version 檢查版本夠新。找不到 exiftool 就安靜回 None——這就是 「沒裝 exiftool 就沒有 EXIF 輸出」的原因。

llm_caption(...) 工具圖片 → base64 data URI → OpenAI 相容 API 取描述。

PPTX 的圖片 alt 描述與 ImageConverter 共用這條路——預設 prompt 「Write a detailed caption for this image.」。

transcribe_audio(file_stream, *, audio_format="wav") 工具SpeechRecognition 轉錄；缺依賴拋 MissingDependencyException。

用 speech_recognition 的 recognize_google（預設走 Google Web Speech API）。 依賴沒裝時拋 MissingDependencyException（audio converter 會吞）；語音聽不懂時拋 UnknownValueError（不會被吞，會讓整個轉換失敗）。