Skip to content

MP3_CONVERSION_GUIDE.md

Latest commit

 

History

History
348 lines (262 loc) · 7.98 KB

MP3_CONVERSION_GUIDE.md

File metadata and controls

348 lines (262 loc) · 7.98 KB
Raw

🎵 音訊 MP3 轉換問題診斷與修復

📋 問題說明

使用者反饋: 音訊下載的檔案是 m4a,需要轉換成 MP3

預期行為: 當選擇「音訊」模式下載時,應該自動轉換為 MP3 格式

✅ 本地測試結果

測試執行

python web_version\test_audio_mp3.py

測試結果 (成功 ✅)

下載音訊: https://www.youtube.com/watch?v=fLyHit9OnhU
選擇串流: itag="251" mime_type="audio/webm" abr="160kbps"
✅ 音訊下載完成: 遺憾終究拾不起.m4a
🎵 開始轉換為 MP3...
✅ 轉換完成!
   原始檔案: 4.12 MB
   MP3 檔案: 5.82 MB
🗑️ 已刪除原始檔案
✅ 結果: 檔案格式 .mp3

🎉 成功! 已轉換為 MP3 格式

結論: 本地環境中,MP3 轉換功能完全正常!

🔍 潛在問題分析

1️⃣ Railway 環境問題

FFmpeg 未安裝或版本錯誤

症狀: Railway 日誌中出現 "FFmpeg 未正確安裝" 或 "找不到 FFmpeg"

原因:

  • Aptfile 未被正確讀取
  • nixpacks.toml 中的 ffmpeg-full 未安裝
  • Railway 建置系統問題

檢查方法: 查看 Railway 部署日誌,搜尋:

  • Installing ffmpeg
  • ffmpeg version

預期日誌輸出

✅ FFmpeg 可用
🎵 開始轉換為 MP3: xxx.m4a
🔄 執行轉換命令...
✅ MP3 轉換完成!
   原始大小: 4.12 MB
   MP3 大小: 5.82 MB

2️⃣ 轉換邏輯未執行

download_type 判斷錯誤

症狀: 下載音訊時沒有進入轉換邏輯

檢查點:

  • 前端是否正確傳送 type: 'audio'
  • 後端是否正確接收 download_type

修復: 已在 app_pytubefix.py 第 180-193 行增加詳細日誌

3️⃣ 轉換超時或失敗

可能原因

  • FFmpeg 執行時間過長 (>5 分鐘)
  • Railway 記憶體不足
  • 檔案權限問題

🔧 已實施的改進

改進 1: FFmpeg 可用性檢查

位置: app_pytubefix.py 第 41-52 行

功能:

# 檢查 FFmpeg 是否可用
try:
    ffmpeg_check = subprocess.run(
        ['ffmpeg', '-version'], 
        stdout=subprocess.PIPE, 
        stderr=subprocess.PIPE,
        timeout=5
    )
    if ffmpeg_check.returncode != 0:
        raise Exception('FFmpeg 未正確安裝')
    print('✅ FFmpeg 可用')
except FileNotFoundError:
    print('❌ 錯誤: 找不到 FFmpeg')
    return input_file

好處: 提前發現 FFmpeg 問題,避免轉換失敗

改進 2: 詳細錯誤日誌

位置: app_pytubefix.py 第 78-88 行

功能:

except subprocess.CalledProcessError as e:
    print(f'❌ MP3 轉換失敗 (FFmpeg 錯誤)')
    print(f'   返回碼: {e.returncode}')
    print(f'   錯誤輸出: {e.stderr.decode("utf-8", errors="ignore")[:500]}')
    return input_file

好處: 詳細記錄 FFmpeg 錯誤訊息,方便診斷

改進 3: 轉換超時保護

位置: app_pytubefix.py 第 64 行

功能:

result = subprocess.run(
    cmd, 
    stdout=subprocess.PIPE, 
    stderr=subprocess.PIPE, 
    check=True,
    timeout=300  # 5 分鐘超時
)

好處: 防止轉換卡死,超時後返回原始檔案

改進 4: 下載後轉換日誌

位置: app_pytubefix.py 第 180-197 行

功能:

# 如果是音訊,轉換為 MP3
if download_type == 'audio':
    print(f'🔄 音訊模式 - 開始轉換為 MP3...')
    download_tasks[task_id]['status'] = 'converting'
    download_tasks[task_id]['message'] = '正在轉換為 MP3...'
    download_tasks[task_id]['progress'] = 95
    
    original_file = file_path
    file_path = convert_to_mp3(file_path)
    
    # 檢查是否成功轉換
    if file_path.endswith('.mp3'):
        print(f'✅ MP3 轉換成功!')
    else:
        print(f'⚠️ 警告: 轉換失敗,返回原始檔案')

好處: 清楚追蹤轉換過程

🚀 部署和測試

Git 提交

git add app_pytubefix.py
git commit -m "🔧 改進 MP3 轉換 - 增強錯誤處理和詳細日誌"
git push origin main

狀態: ✅ 已推送 (Commit: 07c0174)

Railway 自動部署

  • Railway 會自動偵測更新並重新部署
  • 預計 2-3 分鐘完成

測試步驟

  1. 等待 Railway 部署完成

    • 前往 Railway Dashboard
    • 查看 Deployments 標籤
    • 確認狀態為 "Active"

  2. 清除瀏覽器快取

    • Windows: Ctrl + Shift + R
    • Mac: Cmd + Shift + R

  3. 測試音訊下載

    • 貼上 YouTube 網址
    • 選擇「🎵 音訊」模式
    • 點擊「開始下載」
    • 等待進度到 95% (下載完成)
    • 應該顯示「轉換為 MP3...」狀態
    • 進度到 100%
    • 點擊「📥 下載檔案」
    • 檢查下載的檔案是否為 .mp3 格式 ✅

  4. 檢查 Railway 日誌

    • 點擊 "View Logs"
    • 搜尋關鍵字: 
      ✅ FFmpeg 可用
🔄 音訊模式 - 開始轉換為 MP3...
🎵 開始轉換為 MP3
✅ MP3 轉換完成!

🐛 疑難排解

問題 1: 下載的仍是 m4a 格式

檢查:

  1. Railway 日誌中是否有 "✅ FFmpeg 可用"?

    • ❌ 沒有 → FFmpeg 未安裝
    • ✅ 有 → 繼續檢查

  2. 日誌中是否有 "🔄 音訊模式 - 開始轉換為 MP3..."?

    • ❌ 沒有 → download_type 未正確傳遞
    • ✅ 有 → 繼續檢查

  3. 日誌中是否有 "✅ MP3 轉換完成!"?

    • ❌ 沒有 → 轉換失敗,查看錯誤訊息
    • ✅ 有 → 轉換成功,問題可能在前端

解決方案:

FFmpeg 未安裝

# 確認 Aptfile 存在
cat Aptfile
# 應顯示: ffmpeg

# 確認 nixpacks.toml 配置
cat nixpacks.toml
# 應包含: nixPkgs = ["python39", "ffmpeg-full"]

重新部署:

git commit --allow-empty -m "觸發重新部署"
git push origin main

download_type 問題

檢查前端 static/js/app.js 第 156 行:

const type = document.querySelector('input[name="type"]:checked').value;

確認 POST 請求正確:

body: JSON.stringify({ url, type, quality })

問題 2: 轉換超時

症狀: 日誌顯示 "❌ MP3 轉換超時 (5 分鐘)"

原因: 影片太長或 Railway 資源不足

解決方案:

  • 限制影片長度 (建議 < 30 分鐘)
  • 升級 Railway 方案 (更多 RAM)

問題 3: FFmpeg 錯誤

症狀: 日誌顯示 "❌ MP3 轉換失敗 (FFmpeg 錯誤)"

檢查: 查看錯誤輸出中的具體訊息

常見錯誤:

  • "Invalid data found" → 下載的檔案損壞
  • "Permission denied" → 檔案權限問題
  • "No space left" → 磁碟空間不足

📊 配置檢查清單

  • Aptfile 包含 ffmpeg
  • nixpacks.toml 包含 ffmpeg-full
  • app_pytubefix.py 包含 convert_to_mp3() 函數
  • 下載執行緒中包含 if download_type == 'audio' 判斷
  • 轉換函數包含 FFmpeg 可用性檢查
  • 轉換函數包含超時保護 (5 分鐘)
  • 轉換函數包含詳細錯誤日誌
  • 前端正確傳送 type: 'audio'
  • 前端正確處理 converting 狀態

🎯 預期結果

成功標誌

  1. Railway 日誌 (按順序):

    ✅ 下載完成: xxx.m4a
   檔案大小: 4.12 MB
   檔案格式: .m4a
🔄 音訊模式 - 開始轉換為 MP3...
🎵 開始轉換為 MP3: xxx.m4a
✅ FFmpeg 可用
🔄 執行轉換命令...
✅ MP3 轉換完成!
   原始大小: 4.12 MB
   MP3 大小: 5.82 MB
✅ MP3 轉換成功!

  2. 前端顯示:

    • 進度: 0% → 90% (下載中)
    • 狀態: "下載中..."
    • 進度: 95% (轉換中)
    • 狀態: "轉換為 MP3..."
    • 進度: 100% (完成)
    • 狀態: "完成!"

  3. 下載檔案:

    • 檔案名稱: {影片標題}.mp3
    • 檔案格式: .mp3
    • 檔案大小: 約 5-6 MB (192kbps, 4 分鐘影片)
    • 音質: 192 kbps, 44.1 kHz, Stereo

📚 相關檔案

  • app_pytubefix.py - Flask 主應用 (MP3 轉換邏輯)
  • pytubefix_downloader.py - 核心下載模組
  • Aptfile - 系統套件 (ffmpeg)
  • nixpacks.toml - Nix 套件配置 (ffmpeg-full)
  • static/js/app.js - 前端邏輯

診斷建立時間: 2025-10-09
最後更新: Commit 07c0174
狀態: ✅ 改進已推送,等待 Railway 部署測試