案例：媒體 + 封裝 · MarkItDown 繁中教學站

1. 圖片（photo.jpg）

輸入為 PIL 產生、帶 EXIF（Make/Model/DateTimeOriginal）的 JPEG。有 exiftool 時輸出 EXIF 中繼資料；沒有時輸出為空。LLM 描述需要 llm_client + llm_model（本站無 key，未示範）。

ImageSize: 640x360
DateTimeOriginal: 2026:08:12 10:00:00

EXIFTOOL_PATH=<exiftool> markitdown worked/conversions/media/photo.jpg -o worked/conversions/media/photo.md

2. 音訊（tone.wav）——真實失敗示範

輸入是本站自製的 440Hz 純音調 WAV。用含 [all] 依賴（SpeechRecognition）的 markitdown 轉換時，Google Web Speech API「聽不懂」純音調 → 拋 UnknownValueError， AudioConverter 沒接住（它只捕獲 MissingDependencyException）→ 整個轉換失敗。

File "...\markitdown\packages\markitdown\src\markitdown\_markitdown.py", line 649, in _convert
  raise FileConversionException(attempts=failed_attempts)
markitdown._exceptions.FileConversionException: File conversion failed after 1 attempts:
 - AudioConverter threw UnknownValueError with message:

對照：優雅降級路徑。若 markitdown「不含 audio-transcription 依賴」（例如只 pip install markitdown）， transcribe_audio() 改拋 MissingDependencyException → 被接住略過 → 轉換成功、只輸出 metadata：

NumChannels: 1
SampleRate: 22050
AvgBytesPerSec: 44100
BitsPerSample: 16

完整錯誤檔與解讀收在 worked/conversions/media/tone-error.txt。

教學要點：音訊轉錄需要「真人語音 + 網路 + Google API 可用」三者齊備。伺服器/容器環境建議按需安裝 extras（不要無腦 [all]），讓失敗路徑變成優雅降級。

3. ZIP（archive.zip）

ZIP 是「遞迴容器」——解壓到暫存目錄，依副檔名用對應 converter 逐檔轉換，保留結構、結束清理。

Content from the zip file `worked\conversions\archive\archive.zip`:

## File: readme.txt

Hello from a ZIP file!

## File: data/notes.md

# Notes

ZIP 內含多個檔案，會被逐一轉換。

## File: data/todo.txt

1. Convert zip
2. Profit

markitdown worked/conversions/archive/archive.zip -o worked/conversions/archive/archive.md

4. EPUB（book.epub）

解析 container.xml → content.opf → spine，輸出中繼資料 + 逐章（HtmlConverter）轉換。

**Title:** MarkItDown 迷你電子書
**Authors:** markitdown-zh-tw
**Language:** zh-Hant
**Identifier:** urn:uuid:markitdown-zh-tw-sample

# 第一章：什麼是 MarkItDown？

MarkItDown 是微軟出品的檔案轉 Markdown 工具，適合餵給 LLM 使用。

markitdown worked/conversions/archive/book.epub -o worked/conversions/archive/book.md

重現方式

# 圖片（需 exiftool）
EXIFTOOL_PATH=/path/to/exiftool markitdown worked/conversions/media/photo.jpg -o out.md

# 音訊（優雅降級：不含 audio-transcription 依賴的 markitdown）
markitdown worked/conversions/media/tone.wav -o out.md

# ZIP / EPUB
markitdown worked/conversions/archive/archive.zip -o out.md
markitdown worked/conversions/archive/book.epub  -o out.md