# Extraction des sous-titres

Utilisez ce workflow pour créer des fichiers de sous-titres à partir d’une vidéo. Weydub prend en charge deux méthodes d’extraction :

- OCR pour extraire les sous-titres incrustés déjà visibles dans l’image vidéo.
- ASR pour extraire les dialogues prononcés dans la piste audio.

Vous souhaitez vérifier la qualité du résultat avant de générer les fichiers ? Essayez le workflow web Weydub correspondant : [Générer des sous-titres](https://fr.weydub.com/subtitle-generator/).

Pour une explication au niveau système de l’OCR vidéo temporel, du filtrage du texte des scènes et de la segmentation ASR prête pour les sous-titres, consultez [Génération de sous-titres par IA avec OCR vidéo et ASR](https://fr.weydub.com/technology/ai-subtitle-generation-video-ocr-asr/).

## Point de terminaison

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

L’extraction des sous-titres est asynchrone. Enregistrez `body.idProject` et `body.dataList[].id`, puis utilisez le [modèle de tâche asynchrone](./async-task-model.md) pour l’interrogation, les rappels, le comportement en cas de nouvelle tentative et la signature des rappels.

## Accès et limites

| Règle | Exigence |
| --- | --- |
| Accès au compte | L’accès à API vidéo Core doit être activé. L’extraction OCR/ASR fait généralement partie de la famille de tâches vidéo, mais la politique du compte peut tout de même limiter la taille des lots ou les options avancées. |
| Vidéo source | Utilisez une URL HTTPS publique et stable. Les limites strictes actuelles pour les vidéos sont de 15 minutes par fichier et de 1000 MB par fichier. |
| Facturation | Les workflows vidéo sont facturés par unités de 30 secondes. Les clips de moins de 30 secondes sont comptabilisés comme 30 secondes. |
| Tâche échouée | Si le `processStatus > 1` final échoue, aucun crédit n’est déduit. |
| Conservation | Les fichiers de sous-titres et les ressources rendues suivent les règles de conservation du site web Weydub. Par défaut, les ressources sources et rendues des 30 derniers jours sont conservées. Téléchargez des copies durables après le rappel. |

## Choisir OCR ou ASR

| Mode | À utiliser lorsque | Signal requis | Résultat habituel |
| --- | --- | --- | --- |
| Extraction OCR des sous-titres incrustés | Les sous-titres sont incrustés dans l’image, généralement en bas de l’image. | `needChineseOcclude: 14`, `videoInpaintMasks`, `videoInpaintLang`, `lang`. | `srcSrtUrl`, `tgtSrtUrl`. |
| Extraction ASR de la parole | Le dialogue figure dans la piste audio et vous avez besoin d’une transcription horodatée. | `needWanyin: 1`, `wyTaskType: "ONLY_ASR"`, `wyNeedText: 0`. | `srcSrtUrl`, `tgtSrtUrl`. |

N’utilisez pas OCR pour transcrire des vidéos contenant uniquement de la parole. N’utilisez pas ASR pour lire des sous-titres incrustés dans une vidéo silencieuse.

## Charge utile d’extraction des sous-titres OCR

Utilisez OCR lorsque les sous-titres sont déjà incrustés dans l’image vidéo.

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

Remarques :

- `needChineseOcclude` doit être `14`.
- `videoInpaintMasks` est requis pour l’extraction OCR et doit être une chaîne JSON compacte avant la signature.
- `type` doit être `trans_only_ocr`.
- Définissez `lang` sur `videoInpaintLang` lorsqu’aucune traduction n’est nécessaire.
- Les coordonnées sont normalisées de `0` à `1`, dans l’ordre suivant : coin supérieur gauche, coin supérieur droit, coin inférieur droit, coin inférieur gauche.

## Masques OCR

Utilisez un ou plusieurs masques lorsque la zone visible des sous-titres est connue. Les masques limités dans le temps permettent d’éviter d’extraire comme dialogues des indices narratifs temporaires ou du texte d’enregistrement.

| Champ | Type | Obligatoire | Description |
| --- | --- | --- | --- |
| `type` | string | Oui | Utilisez `trans_only_ocr` pour l’extraction des sous-titres OCR. |
| `region` | array | Oui | Quatre points normalisés : `[[x1,y1],[x2,y2],[x3,y3],[x4,y4]]`. |
| `start` | number | Non | Heure de début en secondes. Omettez ce champ ou utilisez `0` lorsque le masque s’applique dès le début. |
| `end` | number | Non | Heure de fin en secondes. Utile lorsqu’un masque ne s’applique qu’à l’introduction. |
| `to_end` | number | Non | Nombre de secondes avant la fin de la vidéo. Préférez `end` explicite lorsque cette valeur est connue. |

Régions courantes :

| Scénario | Région |
| --- | --- |
| Bande de sous-titres verticale 16:9 | `[[0,0.56],[1,0.56],[1,0.76],[0,0.76]]` |
| Zone de sous-titres horizontale standard | `[[0,0.8],[1,0.8],[1,1],[0,1]]` |
| Bande inférieure personnalisée | `[[0,0.7],[1,0.7],[1,0.95],[0,0.95]]` |

## OCR Options

`extraOptions.extra_inpaint_config` permet d’ajuster le nettoyage de OCR :

| Option | Type | Description |
| --- | --- | --- |
| `auto_correct_on` | boolean | Indique s’il faut corriger automatiquement le texte reconnu des sous-titres. |
| `strip_last_punct_on` | boolean | Indique s’il faut supprimer la ponctuation finale de chaque ligne de sous-titres. |
| `scene_filter_on` | boolean | Indique s’il faut filtrer le texte de scène qui ne correspond pas aux dialogues. Cette option est souvent désactivée pour l’extraction de sous-titres en anglais et dans d’autres langues qui ne sont pas CJK, lorsque vous souhaitez récupérer tout le texte visible des sous-titres. |

Conservez `extraOptions` sous la forme d’une chaîne JSON compacte pour les charges utiles API publiques, sauf indication contraire dans le contrat de votre compte.

## ASR Charge utile d’extraction de sous-titres

Utilisez ASR lorsque la vidéo contient des paroles et que vous avez besoin d’une transcription horodatée.

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

Remarques :

- `wyTaskType` doit être `ONLY_ASR`.
- `wyNeedText: 0` signifie qu’il ne faut pas incruster les sous-titres dans une nouvelle vidéo.
- `needWyEdit: 0` désactive la modification manuelle et le mode brouillon professionnel pour cette tâche d’extraction.
- `sourceLang` est la langue parlée. `lang` est la langue de sortie des sous-titres ; utilisez le même code lorsqu’aucune traduction n’est nécessaire.

## ASR Options

| Option | Type | Description |
| --- | --- | --- |
| `asr_speaker_detect_on` | boolean | Active la détection des locuteurs lorsqu’elle est prise en charge. Utile pour les dialogues à plusieurs locuteurs. |
| `extra_video_translate_config.remove_last_punct_on` | boolean | Supprime la ponctuation finale des lignes de sous-titres générées. |

## Paramètres

| Paramètre | OCR | ASR | Description |
| --- | --- | --- | --- |
| `urls` | Obligatoire | Obligatoire | URL publiques de vidéos. Utilisez des URL HTTPS stables en production. |
| `needChineseOcclude` | `14` | Non utilisé | Mode d’extraction des sous-titres OCR. |
| `videoInpaintLang` | Obligatoire | Non utilisé | Langue du texte visible des sous-titres. |
| `videoInpaintMasks` | Obligatoire | Non utilisé | Chaîne JSON compacte décrivant les régions OCR. |
| `extraOptions` | Facultatif | Facultatif | Chaîne JSON compacte pour le nettoyage de OCR ou les options ASR. |
| `needWanyin` | Non utilisé | `1` | Active le traitement de la parole pour ASR. |
| `sourceLang` | Facultatif | Obligatoire | Langue parlée ou langue source. |
| `lang` | Obligatoire | Obligatoire | Langue de sortie des sous-titres. Utilisez la même valeur que pour la langue source lorsqu’aucune traduction n’est nécessaire. |
| `wyTaskType` | Non utilisé | `ONLY_ASR` | Type de tâche ASR- uniquement. |
| `needWyEdit` | Non utilisé | `0` | Désactive le processus de modification manuelle et de brouillon professionnel pour l’extraction. |
| `wyNeedText` | Non utilisé | `0` | N’incruste pas les sous-titres dans une nouvelle vidéo. |
| `callback` | Facultatif | Facultatif | URL de webhook pour signaler la fin du traitement asynchrone. |
| `uid` | Facultatif | Facultatif | Identifiant de votre utilisateur ou client lorsque votre compte utilise le suivi des sous-utilisateurs. |

## Sorties

Les tâches d’extraction réussies peuvent renvoyer :

- `srcSrtUrl`
- `tgtSrtUrl`
- `processStatus`
- `processProgress`
- `paidPoint`
- métadonnées de la tâche dans l’élément de travail renvoyé

L’extraction de OCR et de ASR ne nécessite pas de générer une nouvelle vidéo. Interrogez l’API jusqu’à `processStatus === 1` avant de lire `srcSrtUrl` ou `tgtSrtUrl`.

Les callbacks envoient directement la charge utile de l’élément de travail, sans l’enveloppe externe `code` / `msg` / `body` utilisée par les réponses aux interrogations.

## Notes de l’agent

- Choisissez OCR pour le texte des sous-titres incrustés dans la vidéo ; choisissez ASR pour les dialogues parlés.
- Conservez `videoInpaintMasks` et `extraOptions` sous une forme compacte et sérialisée en chaîne avant de les signer.
- N’envoyez pas les tableaux de masques OCR en tant que tableaux natifs, sauf si le contrat de votre compte le prévoit.
- Utilisez la requête d’énumération (`POST /v-w-c/enum/query2`) pour récupérer la prise en charge actuelle de `sourceLang` et de `Lang` ; ce point de terminaison d’énumération ne nécessite pas de signature.
- Interrogez l’API jusqu’à ce que `processStatus` soit `1` avant de lire `srcSrtUrl` ou `tgtSrtUrl`.
- Stockez les fichiers de sous-titres avant le nettoyage lié à la durée de conservation.