OmniVoice Error-to-Docs Guide

คลิกจากหน้า WebApp แล้วจะกระโดดมาที่ section ตาม error_class โดยตรง

clone_consent_required clone_ref_audio_required design_instruct_required invalid_mode queue_stream_disconnected websocket_transport_error queue_job_failed hf_token_missing hf_token_invalid ffmpeg_runtime_error model_runtime_error engine_not_registered watermark_detect_unsupported_format unknown_error

clone_ref_audio_required

Clone mode ต้องมีไฟล์เสียงอ้างอิง

  1. อัปโหลดไฟล์ในช่อง Reference audio
  2. ใช้ไฟล์เสียงที่อ่านได้ เช่น wav/mp3/m4a
  3. ส่งคำขอใหม่

design_instruct_required

Design mode ต้องมีข้อความ Instruct

  1. กรอก Instruct เช่น thai female calm warm
  2. ตรวจว่า mode เป็น design
  3. ส่งคำขอใหม่

invalid_mode

ค่า mode ไม่อยู่ในชุดที่รองรับ

  1. ตั้ง mode เป็น auto, clone หรือ design
  2. หากเรียก API ภายนอกให้ตรวจ field mode ใน payload

queue_stream_disconnected

SSE stream ของ queue/log อาจถูกตัดการเชื่อมต่อ

  1. เริ่ม stream ใหม่ หรือรีเฟรชหน้า
  2. ตรวจ endpoint /api/jobs/{job_id}/stream และ /api/logs/stream
  3. ตรวจ network/firewall ที่อาจปิด SSE connection

websocket_transport_error

WebSocket ปิดก่อนเสร็จหรือเชื่อมต่อไม่สำเร็จ

  1. ตรวจ protocol ว่าใช้ ws:// หรือ wss:// ให้ตรงกับหน้าเว็บ
  2. เปิด Live Logs ดู event tts_ws_error
  3. ทดสอบ HTTP/Queue เพื่อแยกปัญหาฝั่ง transport

queue_job_failed

งานใน Queue ล้มเหลวระหว่าง pipeline

  1. ดู Job Progress และ Live Logs หา stage ล่าสุด
  2. เปิด /api/jobs/{job_id} และ /api/jobs/{job_id}/events
  3. แก้สาเหตุแล้ว submit ใหม่

hf_token_missing

ไม่พบ token จาก app/env/hf-cli

  1. ตั้ง app token ผ่าน POST /api/hf/token
  2. หรือตั้ง environment variable HF_TOKEN
  3. หรือล็อกอิน huggingface-cli ให้มี token file

hf_token_invalid

HF token ไม่ผ่านการตรวจสอบ (เช่น 401)

  1. ตรวจว่า token ถูกต้องและยังไม่หมดอายุ
  2. ทดสอบผ่าน POST /api/hf/token/validate
  3. อัปเดต token แล้วลองใหม่

ffmpeg_runtime_error

ffmpeg แปลงไฟล์เสียงไม่สำเร็จ

  1. ติดตั้ง ffmpeg และให้เรียกจาก PATH ได้
  2. เช็กด้วยคำสั่ง ffmpeg -version
  3. ทดสอบ format wav เพื่อแยกปัญหาแปลงไฟล์

model_runtime_error

Model load/runtime ผิดพลาด

  1. ตรวจ dependency torch และ omnivoice
  2. ตรวจสิทธิ์ model repository + HF token
  3. ตรวจหน่วยความจำ GPU หรือสลับ OMNIVOICE_MODE=mock เพื่อเทียบ

engine_not_registered

ตั้งค่า engine ที่ยังไม่อยู่ใน registry

  1. ตรวจค่า OMNIVOICE_ENGINE ให้ตรงกับ engine_id จริง
  2. ตรวจค่า OMNIVOICE_PLUGIN_SPECS และดู load result
  3. เรียก /api/plugins/engines เพื่อดู engines ที่ลงทะเบียนแล้ว

watermark_detect_unsupported_format

ตรวจ watermark ด้วยไฟล์ที่ endpoint ยังไม่รองรับ

  1. แปลงไฟล์ให้เป็น WAV (RIFF) ก่อนส่ง
  2. ส่งผ่าน POST /api/provenance/watermark/detect แบบ multipart
  3. ตรวจว่าไฟล์ไม่ว่างและเปิดเล่นได้ปกติ

unknown_error

ยังจัด class ไม่ได้ ให้ตามจาก log และข้อความเต็ม

  1. เปิด Live Logs เพื่อดู traceback/event เพิ่มเติม
  2. เก็บข้อความ error เต็มพร้อมขั้นตอนที่ทำ
  3. แจ้งทีมพร้อม error_class=unknown_error และหลักฐาน
กลับหน้า OmniVoice WebApp