# Créer un jeu de données vidéo

Ce guide vous montre comment créer un jeu de données vidéo avec `VideoFolder` et quelques métadonnées. Il s’agit d’une solution sans code pour créer rapidement un jeu de données vidéo contenant plusieurs milliers de vidéos.

> [!TIP]
> Vous pouvez contrôler l'accès à votre jeu de données en exigeant que les utilisateurs partagent d'abord leurs coordonnées. Consultez le guide [Gated datasets](https://huggingface.co/docs/hub/datasets-gated) pour plus d'informations sur la manière d'activer cette fonctionnalité sur le Hub.

## VideoFolder

`VideoFolder` est un constructeur de jeu de données conçu pour charger rapidement un jeu de données vidéo contenant plusieurs milliers de vidéos, sans qu'il soit nécessaire d'écrire du code.

> [!TIP]
> 💡 Consultez la [hiérarchie des motifs de partitionnement](repository_structure#split-pattern-hierarchy) pour en savoir plus sur la manière dont `VideoFolder` crée des partitions de jeu de données en fonction de la structure de votre dépôt de jeu de données.

`VideoFolder` infère automatiquement les étiquettes de classes de votre jeu de données en fonction du nom du répertoire. Stockez votre jeu de données dans une structure de répertoires de la forme :

```
folder/train/dog/golden_retriever.mp4
folder/train/dog/german_shepherd.mp4
folder/train/dog/chihuahua.mp4

folder/train/cat/maine_coon.mp4
folder/train/cat/bengal.mp4
folder/train/cat/birman.mp4
```

Si le jeu de données suit la structure `VideoFolder`, vous pouvez le charger directement avec [load_dataset()](/docs/datasets/v5.2.0/fr/package_reference/loading_methods#datasets.load_dataset) :

```py
>>> from datasets import load_dataset

>>> dataset = load_dataset("path/to/folder")
```

Cela équivaut à passer manuellement `videofolder` dans [load_dataset()](/docs/datasets/v5.2.0/fr/package_reference/loading_methods#datasets.load_dataset) et le répertoire dans `data_dir` :

```py
>>> dataset = load_dataset("videofolder", data_dir="/path/to/folder")
```

Vous pouvez également utiliser `videofolder` pour charger des jeux de données impliquant plusieurs splits. Pour ce faire, le répertoire de votre jeu de données doit avoir la structure suivante :

```
folder/train/dog/golden_retriever.mp4
folder/train/cat/maine_coon.mp4
folder/test/dog/german_shepherd.mp4
folder/test/cat/bengal.mp4
```

> [!WARNING]
> Si tous les fichiers vidéo sont contenus dans un seul répertoire ou s'ils ne sont pas au même niveau de la structure de répertoires, la colonne `label` ne sera pas ajoutée automatiquement. Si vous en avez besoin, définissez explicitement `drop_labels=False`.

Si vous souhaitez inclure des informations supplémentaires sur votre jeu de données, telles que des légendes de texte ou des boîtes englobantes, ajoutez-les sous forme de fichier `metadata.csv` dans votre dossier. Cela vous permet de créer rapidement des jeux de données pour différentes tâches de vision par ordinateur, comme la légende de texte ou la détection d'objets. Vous pouvez également utiliser un fichier JSONL `metadata.jsonl` ou un fichier Parquet `metadata.parquet`.

```
folder/train/metadata.csv
folder/train/0001.mp4
folder/train/0002.mp4
folder/train/0003.mp4
```

Votre fichier `metadata.csv` doit contenir un champ `file_name` ou `*_file_name` qui associe les fichiers vidéo à leurs métadonnées :

```csv
file_name,additional_feature
0001.mp4,This is a first value of a text feature you added to your videos
0002.mp4,This is a second value of a text feature you added to your videos
0003.mp4,This is a third value of a text feature you added to your videos
```

ou en utilisant `metadata.jsonl` :

```jsonl
{"file_name": "0001.mp4", "additional_feature": "This is a first value of a text feature you added to your videos"}
{"file_name": "0002.mp4", "additional_feature": "This is a second value of a text feature you added to your videos"}
{"file_name": "0003.mp4", "additional_feature": "This is a third value of a text feature you added to your videos"}
```

Ici, `file_name` doit être le nom du fichier vidéo situé à côté du fichier de métadonnées. Plus généralement, il doit s’agir du chemin relatif depuis le répertoire contenant les métadonnées jusqu’au fichier vidéo.

Il est possible de pointer vers plus d'une vidéo dans chaque ligne de votre jeu de données, par exemple si votre entrée et votre sortie sont toutes deux des vidéos :

```jsonl
{"input_file_name": "0001.mp4", "output_file_name": "0001_output.mp4"}
{"input_file_name": "0002.mp4", "output_file_name": "0002_output.mp4"}
{"input_file_name": "0003.mp4", "output_file_name": "0003_output.mp4"}
```

Vous pouvez également définir des listes de vidéos. Dans ce cas, vous devez nommer le champ `file_names` ou `*_file_names`. Voici un exemple :

```jsonl
{"videos_file_names": ["0001_left.mp4", "0001_right.mp4"], "label": "moving_up"}
{"videos_file_names": ["0002_left.mp4", "0002_right.mp4"], "label": "moving_down"}
{"videos_file_names": ["0003_left.mp4", "0003_right.mp4"], "label": "moving_right"}
```

### Légende de vidéo

Les jeux de données de légende vidéo contiennent du texte décrivant une vidéo. Un exemple de `metadata.csv` peut ressembler à ceci :

```csv
file_name,text
0001.mp4,This is a golden retriever playing with a ball
0002.mp4,A german shepherd
0003.mp4,One chihuahua
```

Chargez le jeu de données avec `VideoFolder`, et il créera une colonne `text` pour les légendes des vidéos :

```py
>>> dataset = load_dataset("videofolder", data_dir="/path/to/folder", split="train")
>>> dataset[0]["text"]
"This is a golden retriever playing with a ball"
```

### Téléverser le jeu de données sur le Hub

Une fois que vous avez créé un jeu de données, vous pouvez le partager à l'aide de `huggingface_hub`, par exemple. Assurez-vous d'avoir installé la bibliothèque [huggingface_hub](https://huggingface.co/docs/huggingface_hub/index) et d'être connecté à votre compte Hugging Face (voir le [tutoriel sur le téléversement avec Python](upload_dataset#upload-with-python) pour plus de détails).

Téléchargez votre jeu de données avec `huggingface_hub.HfApi.upload_folder` :

```py
from huggingface_hub import HfApi
api = HfApi()

api.upload_folder(
    folder_path="/path/to/local/dataset",
    repo_id="username/my-cool-dataset",
    repo_type="dataset",
)
```

## WebDataset

Le format [WebDataset](https://github.com/webdataset/webdataset) est basé sur des archives TAR et convient aux grands jeux de données vidéo. En effet, vous pouvez regrouper vos vidéos dans des archives TAR (par exemple 1 Go de vidéos par archive TAR) et disposer de milliers d’archives TAR :

```
folder/train/00000.tar
folder/train/00001.tar
folder/train/00002.tar
...
```

Dans les archives, chaque exemple est constitué de fichiers partageant le même préfixe :

```
e39871fd9fd74f55.mp4
e39871fd9fd74f55.json
f18b91585c4d3f3e.mp4
f18b91585c4d3f3e.json
ede6e66b2fb59aab.mp4
ede6e66b2fb59aab.json
ed600d57fcee4f94.mp4
ed600d57fcee4f94.json
...
```

Vous pouvez fournir les étiquettes/légendes/caractéristiques de vos vidéos à l'aide de fichiers JSON ou texte, par exemple.

Pour plus de détails sur le format WebDataset et la bibliothèque python, veuillez consulter la [documentation WebDataset](https://webdataset.github.io/webdataset).

Chargez votre WebDataset et il créera une colonne par suffixe de fichier (ici « mp4 » et « json ») :

```python
>>> from datasets import load_dataset

>>> dataset = load_dataset("webdataset", data_dir="/path/to/folder", split="train")
>>> dataset[0]["json"]
{"bbox": [[302.0, 109.0, 73.0, 52.0]], "categories": [0]}
```

## Lance

[Lance](https://lance.org) est un format de table de lakehouse multimodal ouvert. Les tables Lance peuvent stocker nativement non seulement du texte et des valeurs scalaires, mais aussi de grands objets binaires (blobs) tels que des images, de l’audio et de la vidéo, aux côtés de vos données tabulaires.

Lance fournit une [API blob](https://lance.org/guide/blob/) qui facilite le stockage et la récupération de blobs volumineux dans les jeux de données Lance. L’exemple suivant montre comment parcourir efficacement les métadonnées sans charger les blobs vidéo plus lourds, puis récupérer les blobs vidéo pertinents à la demande.

Voici un aperçu représentatif de ce à quoi pourrait ressembler une table Lance stockant des vidéos (la colonne `video_blob` utilise l'encodage blob de Lance) :

```text
+------------------------------------------+-----------------+-----+------------------------------------------+
| caption                                  | aesthetic_score | ... | video_blob                               |
+------------------------------------------+-----------------+-----+------------------------------------------+
| "a breathtaking view of a mounta..."     | 5.2401          | ... | {position: 0, size: 4873879}             |
| "a captivating view of the sun, b..."    | 5.2401          | ... | {position: 4873920, size: 3370571}       |
+------------------------------------------+-----------------+-----+------------------------------------------+
```

### Écrire un jeu de données Lance à partir de fichiers vidéo bruts

À partir de fichiers vidéo bruts sur disque et des métadonnées associées (par exemple, des légendes et des scores), vous pouvez écrire un jeu de données Lance autonome dans un répertoire local `*.lance` (un jeu de données Lance est un répertoire sur disque, et il est courant de le nommer avec un suffixe `.lance`) :

```py
import lance
import pyarrow as pa

import urllib.request

schema = pa.schema(
    [
        pa.field("caption", pa.utf8()),
        pa.field("aesthetic_score", pa.float64()),
        pa.field(
            "video_blob",
            pa.large_binary(),
            metadata={"lance-encoding:blob": "true"},
        ),
    ]
)

# Provide video files alongside metadata
rows = [
    {
        "video_path": "/path/to/videos/0001.mp4",
        "caption": "a breathtaking view of a mountainous landscape ...",
        "aesthetic_score": 5.240138053894043,
    },
    {
        "video_path": "0002.mp4",
        "caption": "a captivating view of the sun, bathed in hues ...",
        "aesthetic_score": 5.240137100219727,
    },
]

video_bytes = []
for r in rows:
    with open(r["video_path"], "rb") as f:
        video_bytes.append(f.read())

table = pa.table(
    {
        "caption": [r["caption"] for r in rows],
        "aesthetic_score": [r["aesthetic_score"] for r in rows],
        "video_blob": video_bytes,
    },
    schema=schema,
)

ds = lance.write_dataset(
    table,
    "./videos.lance",
    schema=schema,
    mode="create",
)
```

Cela stocke vos métadonnées et les octets de la vidéo ensemble dans `videos.lance/`, ce qui vous permet de déplacer/copier un seul répertoire sans avoir à maintenir des fichiers `*.mp4` séparés synchronisés.

Voici un aperçu représentatif de ce à quoi pourrait ressembler une table Lance stockant des vidéos (la colonne `video_blob` contient des données stockées nativement sous forme de blobs dans le jeu de données Lance) :

```text
+------------------------------------------+-----------------+-----+------------------------------------------+
| caption                                  | aesthetic_score | ... | video_blob                               |
+------------------------------------------+-----------------+-----+------------------------------------------+
| "a breathtaking view of a mounta..."     | 5.2401          | ... | {position: 0, size: 4873879}             |
| "a captivating view of the sun, b..."    | 5.2401          | ... | {position: 4873920, size: 3370571}       |
+------------------------------------------+-----------------+-----+------------------------------------------+
```

Vous pouvez téléverser le répertoire `videos.lance/` résultant sur le Hub (par exemple avec `huggingface_hub.HfApi.upload_folder`) et le partager en tant que dépôt de jeu de données, en conservant les métadonnées et les vidéos ensemble en tant qu’artefact unique.

> [!TIP]
> Lance datasets s'étendent à des tailles très importantes (téraoctets et au-delà) car les données sont stockées sur disque au format de colonnes. Consultez le guide [API blob](https://lance.org/guide/blob/) pour les dernières informations sur les bonnes pratiques de stockage et de récupération de gros blobs dans Lance.

Lors de l’écriture de grands jeux de données, il est généralement préférable de limiter la taille de chaque fichier `*.lance` à quelques gigaoctets au maximum. Il suffit de collecter les données via un itérateur et de spécifier le paramètre `max_bytes_per_file` lors de l’écriture du jeu de données :

```python
MAX_BYTES_PER_FILE = 5 * 1024 * 1024 * 1024  # ~5 GB per file

# Write as Lance dataset with file size limits for each *.lance file
ds = lance.write_dataset(
    table,
    "./videos.lance",
    schema=schema,
    mode="create",
    max_bytes_per_file=MAX_BYTES_PER_FILE,
)
```

Pour plus de détails sur le travail avec les jeux de données Lance, consultez la [documentation Lance](https://lance.org).

