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.

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 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.

💡 Consultez la hiérarchie des motifs de partitionnement 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() :

>>> from datasets import load_dataset

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

Cela équivaut à passer manuellement videofolder dans load_dataset() et le répertoire dans data_dir :

>>> 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

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, comme 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 :

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 :

{"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 plusieurs vidéos dans chaque ligne de votre jeu de données, par exemple si votre entrée et votre sortie sont toutes deux des vidéos :

{"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 :

{"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 :

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 :

>>> 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 et d’être connecté à votre compte Hugging Face (voir le tutoriel sur l’envoi avec Python pour plus de détails).

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

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 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.

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

>>> 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 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 qui facilite le stockage et la récupération de gros blobs 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) :

+------------------------------------------+-----------------+-----+------------------------------------------+
| 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) :

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) :

+------------------------------------------+-----------------+-----+------------------------------------------+
| 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.

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 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 :

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.