# 자막 추출

이 워크플로를 사용하여 비디오에서 자막 파일을 생성하세요. Weydub에서는 두 가지 추출 경로를 지원합니다:

- OCR 추출: 비디오 프레임에 이미 표시된 하드코딩 자막.
- ASR 추출: 오디오 트랙의 음성 대화.

구축하기 전에 출력 품질을 확인하고 싶으신가요? 이에 해당하는 Weydub 웹 워크플로를 사용해 보세요: [자막 생성](https://weydub.com/subtitle-generator/).

시간 기반 비디오 OCR, 장면 텍스트 필터링 및 자막에 적합한 ASR 분할에 대한 시스템 수준의 설명은 [비디오 OCR 및 ASR을 활용한 AI 자막 생성](https://weydub.com/technology/ai-subtitle-generation-video-ocr-asr/)을 참조하세요.

## 엔드포인트

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

자막 추출은 비동기 방식으로 처리됩니다. `body.idProject` 및 `body.dataList[].id`을 저장한 다음, 폴링, 콜백, 재시도 동작 및 콜백 서명에는 [비동기 작업 모델](./async-task-model.md)을 사용하세요.

## 액세스 및 제한

| 규칙 | 요구 사항 |
| --- | --- |
| 계정 액세스 | 핵심 비디오 API 액세스가 활성화되어 있어야 합니다. OCR/ASR 추출은 일반적으로 비디오 작업 제품군에 포함되지만, 계정 정책에 따라 배치 크기나 고급 옵션이 제한될 수 있습니다. |
| 소스 비디오 | 안정적인 공개 HTTPS URL을 사용하세요. 현재 비디오의 하드 제한은 파일당 15분 및 1000MB입니다. |
| 결제 | 비디오 워크플로는 30초 단위로 과금됩니다. 30초보다 짧은 클립은 30초로 계산됩니다. |
| 실패한 작업 | 최종적으로 `processStatus > 1`이면 크레딧이 차감되지 않습니다. |
| 보존 | 자막 파일과 렌더링된 자산에는 Weydub 웹 보존 규칙이 적용됩니다. 기본적으로 최근 30일간의 소스/렌더링 자산이 보존됩니다. 콜백 후 영구 보관용 사본을 다운로드하세요. |

## OCR 또는 ASR 선택

| 모드 | 사용 조건 | 필요한 신호 | 일반적인 출력 |
| --- | --- | --- | --- |
| OCR 하드 자막 추출 | 자막이 이미지에 번인되어 있으며, 일반적으로 프레임 하단에 표시됩니다. | `needChineseOcclude: 14`, `videoInpaintMasks`, `videoInpaintLang`, `lang`. | `srcSrtUrl`, `tgtSrtUrl`. |
| ASR 음성 추출 | 오디오 트랙에 대화가 있고 시간 정보가 있는 전사본이 필요한 경우입니다. | `needWanyin: 1`, `wyTaskType: "ONLY_ASR"`, `wyNeedText: 0`. | `srcSrtUrl`, `tgtSrtUrl`. |

음성만 있는 비디오를 전사하는 데 OCR을 사용하지 마세요. 무음 하드코딩 자막을 읽는 데 ASR을 사용하지 마세요.

## OCR 자막 추출 페이로드

자막이 비디오 이미지에 이미 삽입되어 있으면 OCR 방식을 사용하세요.

```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"
}
```

참고 사항:

- `needChineseOcclude` 값은 `14`이어야 합니다.
- `videoInpaintMasks` 필드는 OCR 추출에 필요하며, 서명하기 전에 간결한 JSON 문자열이어야 합니다.
- `type` 값은 `trans_only_ocr`이어야 합니다.
- 번역이 필요하지 않으면 `lang` 값을 `videoInpaintLang`과 동일하게 설정하세요.
- 좌표는 `0`에서 `1`까지 정규화되며, 왼쪽 위, 오른쪽 위, 오른쪽 아래, 왼쪽 아래 순으로 배열됩니다.

## OCR 마스크

화면에 표시되는 자막 영역을 알고 있는 경우 하나 이상의 마스크를 사용하세요. 시간 범위가 지정된 마스크를 사용하면 일시적인 줄거리 힌트나 등록 텍스트가 대화로 추출되는 것을 방지할 수 있습니다.

| 필드 | 유형 | 필수 | 설명 |
| --- | --- | --- | --- |
| `type` | 문자열 | 예 | OCR 자막 추출에는 `trans_only_ocr`을 사용합니다. |
| `region` | 배열 | 예 | 정규화된 네 개의 점: `[[x1,y1],[x2,y2],[x3,y3],[x4,y4]]`. |
| `start` | 숫자 | 아니요 | 시작 시간(초). 마스크를 처음부터 적용하는 경우 생략하거나 `0`을 사용합니다. |
| `end` | 숫자 | 아니요 | 종료 시간(초). 마스크를 도입부에만 적용할 때 유용합니다. |
| `to_end` | 숫자 | 아니요 | 비디오 종료까지 남은 시간(초). 알고 있다면 명시적 `end` 사용을 권장합니다. |

일반적인 영역:

| 시나리오 | 영역 |
| --- | --- |
| 세로형 16:9 자막 대역 | `[[0,0.56],[1,0.56],[1,0.76],[0,0.76]]` |
| 가로형 표준 자막 영역 | `[[0,0.8],[1,0.8],[1,1],[0,1]]` |
| 사용자 지정 하단 대역 | `[[0,0.7],[1,0.7],[1,0.95],[0,0.95]]` |

## OCR 옵션

`extraOptions.extra_inpaint_config`로 OCR 정리를 조정할 수 있습니다:

| 옵션 | 유형 | 설명 |
| --- | --- | --- |
| `auto_correct_on` | 부울 | 인식된 자막 텍스트를 자동으로 수정할지 여부입니다. |
| `strip_last_punct_on` | 부울 | 각 자막 줄 끝의 문장 부호를 제거할지 여부입니다. |
| `scene_filter_on` | 부울 | 대화가 아닌 장면 텍스트를 필터링할지 여부입니다. 화면에 표시되는 모든 자막 텍스트를 추출하려는 경우 영어 및 기타 비-CJK 자막 추출에서는 이 옵션을 비활성화하는 경우가 많습니다. |

계정 계약에 달리 명시되어 있지 않다면 공개 API 페이로드에서 `extraOptions` 값은 간결한 JSON 문자열로 유지하세요.

## ASR 자막 추출 페이로드

비디오에 음성이 있고 시간 정보가 있는 전사본이 필요한 경우 ASR 방식을 사용하세요.

```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"
}
```

참고 사항:

- `wyTaskType` 값은 `ONLY_ASR`이어야 합니다.
- `wyNeedText: 0`은 자막을 새 비디오에 렌더링하지 않음을 의미합니다.
- `needWyEdit: 0`은 이 추출 작업에서 수동 편집/프로 초안 동작을 비활성화합니다.
- `sourceLang`은 음성 언어입니다. `lang`은 자막 출력 언어이며, 번역이 필요하지 않으면 동일한 코드를 사용하세요.

## ASR 옵션

| 옵션 | 유형 | 설명 |
| --- | --- | --- |
| `asr_speaker_detect_on` | 부울 | 지원되는 경우 화자 감지를 활성화합니다. 여러 화자가 참여하는 대화에 유용합니다. |
| `extra_video_translate_config.remove_last_punct_on` | 부울 | 생성된 자막 줄 끝의 문장 부호를 제거합니다. |

## 매개변수

| 매개변수 | OCR | ASR | 설명 |
| --- | --- | --- | --- |
| `urls` | 필수 | 필수 | 공개 비디오 URL입니다. 프로덕션에서는 안정적인 HTTPS URL을 사용하세요. |
| `needChineseOcclude` | `14` | 사용 안 함 | OCR 자막 추출 모드입니다. |
| `videoInpaintLang` | 필수 | 사용 안 함 | 화면에 표시되는 자막 텍스트의 언어입니다. |
| `videoInpaintMasks` | 필수 | 사용 안 함 | OCR 영역을 설명하는 간결한 JSON 문자열입니다. |
| `extraOptions` | 선택 사항 | 선택 사항 | OCR 정리 또는 ASR 옵션을 위한 간결한 JSON 문자열입니다. |
| `needWanyin` | 사용 안 함 | `1` | ASR 음성 처리를 활성화합니다. |
| `sourceLang` | 선택 사항 | 필수 | 음성/원본 언어입니다. |
| `lang` | 필수 | 필수 | 출력 자막 언어입니다. 번역이 필요하지 않으면 원본 언어와 동일한 값을 사용하세요. |
| `wyTaskType` | 사용 안 함 | `ONLY_ASR` | ASR 전용 작업 유형입니다. |
| `needWyEdit` | 사용 안 함 | `0` | 추출 시 수동 편집/프로 초안 흐름을 비활성화합니다. |
| `wyNeedText` | 사용 안 함 | `0` | 자막을 새 비디오에 렌더링하지 않습니다. |
| `callback` | 선택 사항 | 선택 사항 | 비동기 완료 알림을 위한 웹훅 URL입니다. |
| `uid` | 선택 사항 | 선택 사항 | 계정에서 하위 사용자 추적을 사용하는 경우 해당 사용자/고객 식별자입니다. |

## 출력

성공한 추출 작업에서는 다음 항목이 반환될 수 있습니다:

- `srcSrtUrl`
- `tgtSrtUrl`
- `processStatus`
- `processProgress`
- `paidPoint`
- 반환된 작업 항목 내의 작업 메타데이터

OCR 및 ASR 추출에서는 새 비디오를 렌더링할 필요가 없습니다. `srcSrtUrl` 또는 `tgtSrtUrl`을 읽기 전에 `processStatus === 1`이 될 때까지 폴링하세요.

콜백은 폴링 응답에 사용되는 외부 `code` / `msg` / `body` 래퍼 없이 작업 항목 페이로드를 직접 전송합니다.

## 에이전트 참고 사항

- 영상에 번인된 자막 텍스트에는 OCR을 선택하고, 음성 대화에는 ASR을 선택하세요.
- 서명하기 전에 `videoInpaintMasks` 및 `extraOptions`을 간결한 형식으로 유지하고 문자열화하세요.
- 계정 계약에 그렇게 명시되어 있지 않은 한 OCR 마스크 배열을 네이티브 배열로 전송하지 마세요.
- enum 쿼리(`POST /v-w-c/enum/query2`)를 사용하여 현재 `sourceLang` 및 `Lang` 지원 정보를 가져오세요. 이 enum 엔드포인트에는 서명이 필요하지 않습니다.
- `srcSrtUrl` 또는 `tgtSrtUrl`을 읽기 전에 `processStatus`이 `1`이 될 때까지 폴링하세요.
- 보존 데이터 정리 전에 자막 파일을 저장하세요.