# คู่มือแก้ปัญหา Clipora

## สารบัญ

1. ตรวจพื้นฐาน
2. Python และ Tkinter
3. FFmpeg และ PATH
4. Input และ stream
5. Output และ permission
6. Progress และ performance
7. Codec/encoder
8. เก็บ Error Log
9. เปิด Issue ที่มีประโยชน์

## 1. ตรวจพื้นฐาน

หากติดตั้งจาก `Clipora-Setup.exe` ให้เปิดปุ่ม **เครื่องมือ** ในโปรแกรมก่อน แล้วเลือกติดตั้งหรือซ่อมใหม่ ผู้ใช้ Setup ไม่ต้องใช้ Python หรือแก้ PATH

นักพัฒนาที่รันจาก source ให้เปิด PowerShell ในโฟลเดอร์ที่มี `app.py`:

```powershell
python scripts/check_environment.py
python -m unittest discover -s tests -v
```

จดหัวข้อที่ FAIL และแก้จากบนลงล่าง อย่าติดตั้ง package แบบสุ่ม

### Setup Assistant ดาวน์โหลดไม่สำเร็จ

- ตรวจอินเทอร์เน็ต firewall, proxy และพื้นที่ว่าง
- กด **เครื่องมือ → ติดตั้งใหม่ / ซ่อมเครื่องมือ**
- โปรแกรมดาวน์โหลดผ่าน HTTPS และไม่ยอมติดตั้งไฟล์ที่ checksum ไม่ตรง
- หากขึ้น `checksum ไม่ตรง` อย่าฝืนรันไฟล์ ให้เปิด issue พร้อมชื่อเครื่องมือและข้อความผิดพลาด แต่ห้ามแนบไฟล์ executable ที่สงสัย
- ไฟล์ชั่วคราวของงานที่ล้มเหลวจะถูกล้าง เครื่องมือเดิมที่ใช้งานได้จะไม่ถูกแทนที่ก่อนตรวจครบ

## 2. Python และ Tkinter

### `python` ไม่เป็นคำสั่ง

สาเหตุ: ยังไม่ติดตั้ง หรือ Python ไม่อยู่ใน PATH

ตรวจ:

```powershell
Get-Command python
py --version
```

หาก `py` ใช้ได้แต่ `python` ไม่ได้ สามารถลอง:

```powershell
py app.py
```

ติดตั้ง Python 3.10+ และเปิด terminal ใหม่ อย่าดาวน์เกรด source code เพื่อหลบ requirement โดยไม่แก้เอกสารและ test matrix

### Python ต่ำกว่า 3.10

`check_environment.py` จะแสดง FAIL ให้ติดตั้งเวอร์ชันที่รองรับและตรวจว่า `Get-Command python` ชี้ executable ที่ถูกต้อง

### `No module named tkinter`

ติดตั้ง Python distribution ที่รวม Tcl/Tk หรือแก้ Python installation แล้วเปิด terminal ใหม่ ตรวจด้วย:

```powershell
python -c 'import tkinter; print(tkinter.TkVersion)'
```

## 3. FFmpeg และ PATH

### `ไม่พบ FFmpeg`

รุ่น Setup: เปิด **เครื่องมือ** แล้วกดติดตั้ง/ซ่อม Clipora จะเก็บ `ffmpeg.exe` และ `ffprobe.exe` ใน `%LOCALAPPDATA%\Clipora\tools`

รุ่น source ตรวจ PATH:

ตรวจ:

```powershell
Get-Command ffmpeg
Get-Command ffprobe
```

ติดตั้ง:

```powershell
winget install Gyan.FFmpeg
```

ปิดทั้ง PowerShell และ Clipora แล้วเปิดใหม่ เพราะ process เดิมไม่เห็น PATH ที่เพิ่งเปลี่ยน

### พบ ffmpeg แต่ไม่พบ ffprobe

Clipora ต้องใช้ทั้งคู่จาก FFmpeg distribution เดียวกัน ตรวจว่า directory `bin` มี `ffmpeg.exe` และ `ffprobe.exe` และ directory นั้นอยู่ใน PATH

### มี FFmpeg หลายเวอร์ชัน

```powershell
Get-Command ffmpeg -All
Get-Command ffprobe -All
ffmpeg -version
ffprobe -version
```

จัด PATH ให้คู่ที่ต้องการมาก่อน หลีกเลี่ยง ffmpeg กับ ffprobe คนละ distribution/version

### `ไม่พบ yt-dlp`

รุ่น Setup: ใช้เมนู **เครื่องมือ** โดยไม่ต้องเปิด PowerShell

รุ่น source ตรวจและติดตั้ง:

ตรวจและติดตั้ง:

```powershell
Get-Command yt-dlp
winget install yt-dlp.yt-dlp
winget install DenoLand.Deno
yt-dlp --version
deno --version
```

เปิด PowerShell และ Clipora ใหม่หลังติดตั้ง หากเว็บไซต์ที่เคยใช้ได้เริ่มล้มเหลว ให้อัปเดตจากช่องทางติดตั้งเดิม หรือใช้ `yt-dlp -U` เมื่อเป็น official release binary

หาก WinGet ใช้งานไม่ได้ สามารถวาง official `yt-dlp.exe` ไว้ที่ `%LOCALAPPDATA%\\Clipora\\bin\\yt-dlp.exe` ได้ Clipora จะตรวจตำแหน่งนี้โดยไม่ต้องแก้ PATH ควรดาวน์โหลดจากหน้า release ทางการและตรวจ checksum ก่อนใช้งาน

หากไฟล์ `yt-dlp.exe` ใน `%LOCALAPPDATA%\\Clipora\\tools` ถูกแก้ไขหรือเขียนทับจนตรวจไม่ตรงกับระเบียนติดตั้ง Clipora จะงดใช้ไฟล์นั้นเพื่อความปลอดภัย กด **อัปเดต yt-dlp (Ctrl+U)** หนึ่งครั้งเพื่อดาวน์โหลดใหม่และตรวจ SHA-256 ก็กลับมาใช้ได้

หาก YouTube แจ้งว่าไม่พบ JavaScript runtime ให้ติดตั้ง Deno หรือ Node.js แล้วเปิดโปรแกรมใหม่ Clipora จะส่ง runtime ที่พบให้ yt-dlp โดยอัตโนมัติ

### ดาวน์โหลดลิงก์ไม่สำเร็จ

- ตรวจว่าลิงก์เปิดแบบสาธารณะได้และเป็นรายการเดียว ไม่ใช่ playlist/live
- Clipora ไม่รับ login, cookies, private/paid media หรือ DRM
- อัปเดต yt-dlp เพราะเว็บไซต์เปลี่ยน extractor บ่อย
- ลองลิงก์สาธารณะที่ผู้ใช้เป็นเจ้าของหรือได้รับอนุญาต
- อย่าโพสต์ private URL, signed URL, token หรือข้อมูลบัญชีใน issue

### เว็บไซต์เปลี่ยนระบบจนตัวดาวน์โหลดตามไม่ทัน (เช่น TikTok `Unexpected response from webpage request`)

หากข้อความแจ้งว่า "เว็บไซต์เปลี่ยนระบบจนตัวดาวน์โหลดตามไม่ทัน" หมายความว่า yt-dlp อ่านหน้าเว็บนั้นไม่ได้แล้ว (เช่น TikTok เปลี่ยนหน้า challenge) ไม่ใช่ลิงก์ผิดเสมอไป:

- กด **อัปเดต yt-dlp (Ctrl+U)** ในแอปแล้วลองใหม่เป็นอันดับแรก
- หากอัปเดตแล้วยังไม่ได้ ให้รอ yt-dlp ออกเวอร์ชันใหม่แล้วลองอีกครั้ง Clipora จะไม่ retry ซ้ำเพราะต้องแก้ extractor ต้นทางก่อน
- ตรวจว่าลิงก์ยังเปิดแบบสาธารณะได้อยู่ และอย่าใช้ login/cookies/private media ซึ่งอยู่นอกขอบเขตของ Clipora

### โดนบล็อก (HTTP 403 / "not a bot" / 429)

Clipora จะลองดาวน์โหลดซ้ำอัตโนมัติด้วยวิธีที่เพิ่มขึ้น: เพิ่ม header เฉพาะเว็บไซต์ (เช่น Referer ของ TikTok), สลับ player client ของ YouTube (android/web_embedded/tv) แล้วใช้การจำลองเบราว์เซอร์ (`--impersonate`) ก่อนจะรายงานว่าล้มเหลว:

- หากข้อความแจ้งว่า "เครือข่าย/ISP บล็อกการเข้าถึงเว็บไซต์นี้ (resolve โดเมนไม่ได้)" หมายความว่าถูกบล็อกที่ระดับเครือข่าย/ISP (เช่น DNS ถูกสลับหรือดัก) ไม่ใช่ตัวโปรแกรม ให้ลองเปลี่ยน DNS เป็น `1.1.1.1` หรือ `8.8.8.8` หรือใช้ VPN/proxy แล้วลองใหม่ Clipora จะไม่พยายาม retry ซ้ำเพราะวิธีจำลองเบราว์เซอร์ช่วยไม่ได้
- หากข้อความแจ้งว่า "เว็บไซต์บล็อกการดาวน์โหลดอัตโนมัติ" หลังลองทุกวิธีแล้ว หมายความว่าเว็บนั้นบล็อกด้วยวิธีที่แรงกว่า (เช่น ตรวจ IP หรือต้องใช้คุกกี้/เข้าสู่ระบบ) ซึ่งอยู่นอกขอบเขตของ Clipora
- ตรวจว่าเครือข่ายเข้าถึงเว็บไซต์ได้จริง เช่น `nslookup www.youtube.com` — ถ้า DNS resolve ไม่ได้ หมายความว่าถูกบล็อกที่ระดับเครือข่าย/ISP ไม่เกี่ยวกับตัวโปรแกรม ให้ลองใช้เครือข่ายหรือ VPN อื่น
- อัปเดต yt-dlp ก่อนลองใหม่ เพราะ extractor ถูกปรับบ่อยตามที่เว็บเปลี่ยน

## 4. Input และ stream

### โปรแกรมบอกว่าไม่พบไฟล์ต้นฉบับ

- ตรวจว่าไฟล์ยังอยู่หลังเลือก
- อย่าย้าย/เปลี่ยนชื่อ/ถอด external drive ระหว่างงาน
- ลองคัดลอกไฟล์ไปยังโฟลเดอร์ local ที่พาธสั้น

### `ไฟล์นี้ไม่มีเสียงให้แยก`

ไฟล์ไม่มี audio stream หรือ probe อ่านไม่ได้ ตรวจ:

```powershell
ffprobe -v error -show_streams -of json 'C:\path\to\input.mp4'
```

มองหา `codec_type` ที่เป็น `audio` อย่าเปลี่ยน extension เพื่อทำให้ไฟล์ดูเหมือนมีเสียง

### `ไฟล์นี้ไม่มีภาพวิดีโอสำหรับแปลง`

ไฟล์อาจเป็น audio-only, เสียหาย หรือ codec ไม่รองรับ ตรวจ stream ด้วย ffprobe เช่นเดียวกัน

### ไฟล์เปิดใน player ได้แต่ Clipora ไม่ได้

Player อาจมี decoder ที่ FFmpeg build นี้ไม่มี เก็บ ffprobe output และ FFmpeg version แล้วเปิด issue โดยตัดพาธส่วนตัวออก

## 5. Output และ permission

### เขียนไฟล์ไม่ได้

- เลือก Downloads, Videos หรือโฟลเดอร์ของผู้ใช้
- หลีกเลี่ยง `C:\Windows`, `Program Files` และ network drive ที่ไม่มีสิทธิ์
- ตรวจว่า destination ยังเชื่อมต่ออยู่
- ตรวจว่า output ไม่ถูกเปิดล็อกโดยโปรแกรมอื่น
- ไม่ควรแก้ด้วยการเปิด Administrator เป็นวิธีแรก

### พื้นที่ไม่พอ

```powershell
Get-PSDrive -PSProvider FileSystem
```

เพิ่มพื้นที่หรือเลือก drive อื่น Output High อาจใหญ่กว่าที่คาดตามความซับซ้อนของวิดีโอ

### มี output เดิม

Clipora จะถามให้เลือก **เขียนทับ**, **เก็บทั้งสองไฟล์** หรือ **ยกเลิก** ก่อนเริ่มงาน — เลือกเก็บทั้งสองไฟล์เพื่อให้ได้ชื่อ `(1)`, `(2)` โดยไม่ลบไฟล์เดิม

หลังแปลง Clipora จะตรวจไฟล์ชั่วคราวด้วย ffprobe ก่อนย้ายเป็น output จริง หากตรวจไม่ผ่าน งานจะถูกรายงานว่าล้มเหลวและไฟล์เดิมจะยังอยู่ ให้ตรวจ input, พื้นที่ว่าง และรายละเอียด error แล้วลองใหม่

### เปิดไฟล์ผลลัพธ์ไม่ได้ "คุณไม่มีสิทธิ์เข้าถึงไฟล์นี้" (0x80070005)

กรณีไฟล์ที่ดาวน์โหลดจากลิงก์เปิดไม่ได้ด้วย error `0x80070005` (E_ACCESSDENIED) — เกิดจากไฟล์ถูกสร้างด้วย ACL ที่ผู้ใช้ปัจจุบันไม่มีสิทธิ์ (owner SID ต่าง / ไม่อนุญาตอ่าน):

- Clipora ตั้งแต่รุ่นนี้จะรีเซ็ตสิทธิ์ของไฟล์ผลลัพธ์ให้ผู้ใช้ปัจจุบันทุกครั้ง (ผ่าน `icacls`) จึงไม่เกิดซ้ำกับไฟล์ใหม่
- ไฟล์ที่ดาวน์โหลดมาก่อนหน้านี้แล้วเปิดไม่ได้ ให้แก้ ACL ด้วยคำสั่ง (รัน PowerShell แบบ Administrator):

```powershell
takeown /f "C:\Users\<ชื่อผู้ใช้>\Downloads\ชื่อไฟล์.mp4"
icacls "C:\Users\<ชื่อผู้ใช้>\Downloads\ชื่อไฟล์.mp4" /grant "$env:USERDOMAIN\$env:USERNAME:(F)"
```

- หรือลบไฟล์นั้นแล้วดาวน์โหลดใหม่ด้วย Clipora เวอร์ชันนี้

### มีไฟล์ output หลังงานล้มเหลว

Clipora เขียนลงไฟล์ชั่วคราวที่มี `.clipora-` ในชื่อและลบไฟล์นั้นหลังยกเลิกหรือเกิด error หากยังเหลือไฟล์ชั่วคราว แสดงว่า cleanup ถูกขัดขวาง เช่น permission หรือโปรแกรมหยุดแบบไม่ปกติ ปิดโปรแกรมที่ล็อกไฟล์แล้วลบเฉพาะไฟล์ `.clipora-` ที่ตรวจแล้วว่าเป็น partial output ห้ามลบ source หรือทั้ง destination directory

## 6. Progress และ performance

### Progress ไม่ขยับ

- บางไฟล์ไม่มี duration ที่เชื่อถือได้
- ตรวจ Task Manager ว่า FFmpeg ใช้ CPU/disk อยู่หรือไม่
- รอไฟล์ยาว/ความละเอียดสูง
- หาก UI ค้างทั้งหมด ให้เก็บ input metadata และขั้นตอนทำซ้ำ

### เครื่องช้าหรือร้อน

Encoding ใช้ CPU สูงเป็นปกติ ปิดงานหนักอื่น วางเครื่องให้ระบายอากาศ และใช้ Balanced/Small ตามความต้องการ รุ่นนี้ประมวลผลทีละไฟล์

### Progress ถึง 100 แต่ไม่มีไฟล์

Core ปัจจุบันตรวจ target existence และขนาดก่อน success หากยังพบ ให้เก็บ exact message, FFmpeg version, destination type และ test results

## 7. Codec และ encoder

### `Unknown encoder libx264`

FFmpeg build ไม่มี `libx264` ซึ่งจำเป็นต่อ MP4 ปัจจุบัน ตรวจ:

```powershell
ffmpeg -hide_banner -encoders | Select-String libx264
```

ใช้ FFmpeg build ที่มี encoder นี้ อย่าเปลี่ยน command ไป codec อื่นโดยไม่เพิ่ม quality mapping และ integration tests

### `Unknown encoder libmp3lame`

ตรวจ:

```powershell
ffmpeg -hide_banner -encoders | Select-String libmp3lame
```

ติดตั้ง build ที่รองรับ หรือใช้ M4A ชั่วคราวหาก AAC encoder พร้อม

### Hardware encode ใช้ไม่ได้ (nvenc / qsv / amf)

ถ้าเปิด **ใช้ Hardware encode** แล้วขึ้น error เช่น `Cannot load nvEncodeAPI64.dll`, `No capable devices found`, `Error while opening encoder` หรือ `Unknown encoder h264_qsv`:

- Clipora จะพยายามถอยกลับไปใช้ `libx264` ให้อัตโนมัติหนึ่งครั้ง ถ้ายังล้มเหลวให้ปิดสวิตช์ **ใช้ Hardware encode (เร็วขึ้น ถ้ารองรับ)** ในตัวเลือกเพิ่มเติมแล้วเริ่มงานใหม่
- ตรวจว่า FFmpeg ในเครื่องมี encoder นั้นจริง: `ffmpeg -hide_banner -encoders | Select-String h264`
- NVENC/QSV/AMF ต้องมีไดรเวอร์การ์ดจอที่อัปเดตและ GPU ที่รองรับ; เครื่องเสมือน (VM) หรือ Remote Desktop มักใช้งานไม่ได้
- ตัวเลือกนี้มีเฉพาะงานไฟล์ในเครื่อง (MP4) — งานดาวน์โหลดลิงก์ไม่ใช้ hardware encode

### ปรับเสียงพอดแคสต์แล้วได้ไฟล์เสียงเงียบ/เคยขึ้น `Failed to find two consecutive MPEG audio frames`

เกิดเมื่อช่วงที่เลือก**เงียบทั้งช่วง** (เช่น อัดหน้าจอแต่ไม่ได้เก็บเสียง) แล้ว `silenceremove` ตัดทุกเฟรมทิ้ง:

- ทั้งงานไฟล์ในเครื่องและงานดาวน์โหลดลิงก์ (โหมดเสียง) จะแปลงช่วงนั้นซ้ำแบบไม่ปรับเสียงให้อัตโนมัติ จึงได้ไฟล์เสียงที่เปิดได้ (แต่จะเงียบตามต้นฉบับ)
- ถ้าอยากได้เสียงจริง ให้ตรวจว่าตอนอัดเปิดไมโครโฟน/เสียงระบบไว้ แล้วอัดใหม่
- ตรวจว่าไฟล์มีเสียงจริง: `ffmpeg -hide_banner -i "ไฟล์.mp4" -af volumedetect -f null NUL` — ถ้า `max_volume` ต่ำกว่า -45 dB ถือว่าเงียบทั้งช่วง

### Output คุณภาพต่ำกว่าต้นฉบับ

MP3, M4A และ MP4 ปัจจุบันมีการ re-encode จึงมีการสูญเสีย เลือก High สำหรับ MP4 แต่ไม่สามารถคืนรายละเอียดที่ต้นฉบับไม่มีได้

## 8. เก็บ Error Log

เมื่องานล้มเหลว หน้าต่าง error มีปุ่ม **คัดลอก Error Log** กดแล้ววางลง issue ได้ทันที นอกจากนั้นให้เก็บ:

```powershell
python --version
ffmpeg -version
ffprobe -version
python scripts/check_environment.py
python -W error::ResourceWarning -m unittest discover -s tests -v
```

บันทึกเพิ่มเติม:

- Operation: MP3, M4A หรือ MP4
- Quality ที่เลือก
- Container/codec/stream จาก ffprobe
- ขั้นตอนทำซ้ำทีละข้อ
- ข้อความ error แบบเต็ม
- ปัญหาเกิดทุกไฟล์หรือไฟล์เดียว

ลบหรือแทนที่ข้อมูลต่อไปนี้ก่อนโพสต์สาธารณะ:

- ชื่อจริง ชื่อผู้ใช้ และพาธ home
- ชื่อไฟล์ที่เปิดเผยลูกค้า/งานส่วนตัว
- URL ส่วนตัว token cookie หรือ credential
- media ที่ไม่มีสิทธิ์เผยแพร่

อย่าอัปโหลดไฟล์ต้นฉบับที่เป็นความลับ ใช้ fixture ที่สร้างใหม่หรือคลิปสั้นที่อนุญาตแทน

## 9. เปิด Issue ที่มีประโยชน์

ใช้รูปแบบ:

```text
Summary:
Expected:
Actual:
Steps to reproduce:
Python version:
FFmpeg/ffprobe version:
Operation and settings:
Input stream summary:
Exact error:
Tests run:
Sensitive data removed: yes/no
```

หนึ่ง issue ควรมีหนึ่งปัญหาหลัก ระบุสิ่งที่ลองแล้ว และอย่าแนบ screenshot เพียงอย่างเดียวหากสามารถคัดลอก error text ได้
