# Ekstraksi Subtitle

Gunakan alur kerja ini untuk membuat file subtitle dari video. Weydub mendukung dua jalur ekstraksi:

- Ekstraksi OCR untuk subtitle hardcode yang sudah terlihat dalam frame video.
- Ekstraksi ASR untuk dialog lisan dalam trek audio.

Ingin memeriksa kualitas keluaran sebelum mulai mengembangkan? Coba alur kerja web Weydub yang sesuai: [Buat subtitle](https://weydub.com/subtitle-generator/).

Untuk penjelasan tingkat sistem tentang Video OCR temporal, pemfilteran teks adegan, dan segmentasi ASR yang siap digunakan untuk subtitle, baca [Pembuatan subtitle AI dengan Video OCR dan ASR](https://weydub.com/technology/ai-subtitle-generation-video-ocr-asr/).

## Endpoint

```text
POST /v-w-c/gateway/ve/work/free
```

Ekstraksi subtitle bersifat asinkron. Simpan `body.idProject` dan `body.dataList[].id`, lalu gunakan [Model tugas asinkron](./async-task-model.md) untuk polling, callback, perilaku percobaan ulang, dan penandatanganan callback.

## Akses dan Batasan

| Aturan | Persyaratan |
| --- | --- |
| Akses akun | Akses API video inti harus diaktifkan. Ekstraksi OCR/ASR biasanya merupakan bagian dari kelompok tugas video, tetapi kebijakan akun tetap dapat membatasi ukuran batch atau opsi lanjutan. |
| Video sumber | Gunakan URL HTTPS publik yang stabil. Batas mutlak video saat ini adalah 15 menit per file dan 1000 MB per file. |
| Penagihan | Alur kerja video ditagih dalam unit 30 detik. Klip yang lebih pendek dari 30 detik dihitung sebagai 30 detik. |
| Tugas gagal | Jika `processStatus > 1` pada hasil akhir, tidak ada kredit yang dipotong. |
| Retensi | File subtitle dan aset hasil render mengikuti aturan retensi web Weydub. Secara default, aset sumber/hasil render untuk 30 hari terakhir disimpan. Unduh salinan yang dapat disimpan dalam jangka panjang setelah callback. |

## Pilih OCR atau ASR

| Mode | Kapan Digunakan | Sinyal Wajib | Keluaran Umum |
| --- | --- | --- | --- |
| Ekstraksi hard-sub OCR | Subtitle tertanam permanen dalam gambar, biasanya di bagian bawah frame. | `needChineseOcclude: 14`, `videoInpaintMasks`, `videoInpaintLang`, `lang`. | `srcSrtUrl`, `tgtSrtUrl`. |
| Ekstraksi ucapan ASR | Dialog tersedia dalam trek audio dan Anda memerlukan transkrip dengan penanda waktu. | `needWanyin: 1`, `wyTaskType: "ONLY_ASR"`, `wyNeedText: 0`. | `srcSrtUrl`, `tgtSrtUrl`. |

Jangan gunakan OCR untuk mentranskripsikan video yang hanya berisi ucapan. Jangan gunakan ASR untuk membaca subtitle hardcode tanpa suara.

## Payload Ekstraksi Subtitle OCR

Gunakan OCR jika subtitle sudah tertanam dalam gambar video.

```json
{
  "urls": ["https://example.com/video.mp4"],
  "needChineseOcclude": 14,
  "videoInpaintLang": "en",
  "lang": "en",
  "videoInpaintMasks": "[{\"type\":\"trans_only_ocr\",\"region\":[[0,0.8],[1,0.8],[1,1],[0,1]]}]",
  "extraOptions": "{\"extra_inpaint_config\":{\"auto_correct_on\":false,\"strip_last_punct_on\":true,\"scene_filter_on\":false}}",
  "callback": "https://your-domain.example/webhooks/weydub"
}
```

Catatan:

- `needChineseOcclude` harus bernilai `14`.
- `videoInpaintMasks` wajib untuk ekstraksi OCR dan harus berupa string JSON ringkas sebelum penandatanganan.
- `type` sebaiknya bernilai `trans_only_ocr`.
- Atur `lang` agar sama dengan `videoInpaintLang` jika terjemahan tidak diperlukan.
- Koordinat dinormalisasi dari `0` hingga `1`, dengan urutan kiri atas, kanan atas, kanan bawah, kiri bawah.

## Mask OCR

Gunakan satu atau beberapa mask jika area subtitle yang terlihat sudah diketahui. Mask berbatas waktu membantu mencegah petunjuk alur cerita sementara atau teks registrasi diekstrak sebagai dialog.

| Kolom | Tipe | Wajib | Deskripsi |
| --- | --- | --- | --- |
| `type` | string | Ya | Gunakan `trans_only_ocr` untuk ekstraksi subtitle OCR. |
| `region` | array | Ya | Empat titik yang dinormalisasi: `[[x1,y1],[x2,y2],[x3,y3],[x4,y4]]`. |
| `start` | number | Tidak | Waktu mulai dalam detik. Jangan sertakan atau gunakan `0` jika mask berlaku sejak awal. |
| `end` | number | Tidak | Waktu akhir dalam detik. Berguna jika mask hanya berlaku pada bagian pembuka. |
| `to_end` | number | Tidak | Jumlah detik sebelum video berakhir. Utamakan `end` eksplisit jika diketahui. |

Area umum:

| Skenario | Area |
| --- | --- |
| Pita subtitle vertikal 16:9 | `[[0,0.56],[1,0.56],[1,0.76],[0,0.76]]` |
| Area subtitle horizontal standar | `[[0,0.8],[1,0.8],[1,1],[0,1]]` |
| Pita bawah kustom | `[[0,0.7],[1,0.7],[1,0.95],[0,0.95]]` |

## Opsi OCR

`extraOptions.extra_inpaint_config` dapat menyesuaikan pembersihan OCR:

| Opsi | Tipe | Deskripsi |
| --- | --- | --- |
| `auto_correct_on` | boolean | Menentukan apakah teks subtitle yang dikenali akan dikoreksi secara otomatis. |
| `strip_last_punct_on` | boolean | Menentukan apakah tanda baca di akhir setiap baris subtitle akan dihapus. |
| `scene_filter_on` | boolean | Menentukan apakah teks adegan non-dialog akan difilter. Opsi ini sering dinonaktifkan untuk ekstraksi subtitle bahasa Inggris dan bahasa non-CJK lainnya jika Anda menginginkan semua teks subtitle yang terlihat. |

Pertahankan `extraOptions` sebagai string JSON ringkas untuk payload API publik, kecuali kontrak akun Anda menetapkan lain.

## Payload Ekstraksi Subtitle ASR

Gunakan ASR jika video berisi ucapan dan Anda memerlukan transkrip dengan penanda waktu.

```json
{
  "urls": ["https://example.com/video.mp4"],
  "needWanyin": 1,
  "sourceLang": "en",
  "lang": "en",
  "wyTaskType": "ONLY_ASR",
  "needWyEdit": 0,
  "wyNeedText": 0,
  "extraOptions": "{\"asr_speaker_detect_on\":true,\"extra_video_translate_config\":{\"remove_last_punct_on\":true}}",
  "callback": "https://your-domain.example/webhooks/weydub"
}
```

Catatan:

- `wyTaskType` harus bernilai `ONLY_ASR`.
- `wyNeedText: 0` berarti subtitle tidak dirender ke dalam video baru.
- `needWyEdit: 0` menonaktifkan perilaku pengeditan manual/pro-draft untuk tugas ekstraksi ini.
- `sourceLang` adalah bahasa lisan. `lang` adalah bahasa keluaran subtitle; gunakan kode yang sama jika terjemahan tidak diperlukan.

## Opsi ASR

| Opsi | Tipe | Deskripsi |
| --- | --- | --- |
| `asr_speaker_detect_on` | boolean | Mengaktifkan deteksi pembicara jika didukung. Berguna untuk dialog dengan beberapa pembicara. |
| `extra_video_translate_config.remove_last_punct_on` | boolean | Menghapus tanda baca di akhir baris subtitle yang dihasilkan. |

## Parameter

| Parameter | OCR | ASR | Deskripsi |
| --- | --- | --- | --- |
| `urls` | Wajib | Wajib | URL video publik. Gunakan URL HTTPS yang stabil dalam produksi. |
| `needChineseOcclude` | `14` | Tidak digunakan | Mode ekstraksi subtitle OCR. |
| `videoInpaintLang` | Wajib | Tidak digunakan | Bahasa teks subtitle yang terlihat. |
| `videoInpaintMasks` | Wajib | Tidak digunakan | String JSON ringkas yang menjelaskan area OCR. |
| `extraOptions` | Opsional | Opsional | String JSON ringkas untuk pembersihan OCR atau opsi ASR. |
| `needWanyin` | Tidak digunakan | `1` | Mengaktifkan pemrosesan ucapan untuk ASR. |
| `sourceLang` | Opsional | Wajib | Bahasa lisan/sumber. |
| `lang` | Wajib | Wajib | Bahasa keluaran subtitle. Gunakan nilai yang sama dengan sumber jika terjemahan tidak diperlukan. |
| `wyTaskType` | Tidak digunakan | `ONLY_ASR` | Jenis tugas khusus ASR. |
| `needWyEdit` | Tidak digunakan | `0` | Menonaktifkan alur pengeditan manual/pro-draft untuk ekstraksi. |
| `wyNeedText` | Tidak digunakan | `0` | Jangan render subtitle ke dalam video baru. |
| `callback` | Opsional | Opsional | URL webhook untuk penyelesaian asinkron. |
| `uid` | Opsional | Opsional | Pengidentifikasi pengguna/pelanggan Anda jika akun Anda menggunakan pelacakan subpengguna. |

## Keluaran

Tugas ekstraksi yang berhasil dapat mengembalikan:

- `srcSrtUrl`
- `tgtSrtUrl`
- `processStatus`
- `processProgress`
- `paidPoint`
- metadata tugas dalam item pekerjaan yang dikembalikan

Ekstraksi OCR dan ASR tidak perlu merender video baru. Lakukan polling hingga `processStatus === 1` sebelum membaca `srcSrtUrl` atau `tgtSrtUrl`.

Callback mengirimkan payload item pekerjaan secara langsung, tanpa pembungkus luar `code` / `msg` / `body` yang digunakan oleh respons polling.

## Catatan Agen

- Pilih OCR untuk teks subtitel yang tertanam permanen; pilih ASR untuk dialog lisan.
- Pastikan `videoInpaintMasks` dan `extraOptions` tetap ringkas dan diserialisasi sebagai string sebelum penandatanganan.
- Jangan kirim array mask OCR sebagai array native kecuali kontrak akun Anda menyatakan demikian.
- Gunakan kueri enum (`POST /v-w-c/enum/query2`) untuk mengambil dukungan `sourceLang` dan `Lang` saat ini; endpoint enum ini tidak memerlukan penandatanganan.
- Lakukan polling hingga `processStatus` bernilai `1` sebelum membaca `srcSrtUrl` atau `tgtSrtUrl`.
- Simpan file subtitel sebelum proses pembersihan retensi.