# Criar um conjunto de dados de vídeo

Este guia mostrará como criar um conjunto de dados de vídeo com `VideoFolder` e alguns metadados. Esta é uma solução sem código para criar rapidamente um conjunto de dados de vídeo com vários milhares de vídeos.

> [!TIP]
> Você pode controlar o acesso ao seu conjunto de dados exigindo que os usuários compartilhem primeiro suas informações de contato. Consulte o guia [Conjuntos de dados com controle de acesso](https://huggingface.co/docs/hub/datasets-gated) para mais informações sobre como habilitar esse recurso no Hub.

## VideoFolder

O `VideoFolder` é um construtor de dataset projetado para carregar rapidamente um conjunto de dados de vídeo com vários milhares de vídeos, sem exigir que você escreva qualquer código.

> [!TIP]
> 💡 Dê uma olhada na [hierarquia de padrões de divisão](repository_structure#split-pattern-hierarchy) para saber mais sobre como o `VideoFolder` cria as divisões do conjunto de dados com base na estrutura do repositório do seu conjunto de dados.

`VideoFolder` infere automaticamente os rótulos de classe do seu dataset com base no nome do diretório. Armazene seu dataset em uma estrutura de diretórios como:

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

Se o conjunto de dados seguir a estrutura `VideoFolder`, você pode carregá-lo diretamente com [load_dataset()](/docs/datasets/v5.2.0/pt/package_reference/loading_methods#datasets.load_dataset):

```py
>>> from datasets import load_dataset

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

Isso é equivalente a passar `videofolder` manualmente em [load_dataset()](/docs/datasets/v5.2.0/pt/package_reference/loading_methods#datasets.load_dataset) e o diretório em `data_dir`:

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

Você também pode usar `videofolder` para carregar conjuntos de dados que envolvem múltiplos splits. Para isso, o diretório do seu conjunto de dados deve ter a seguinte estrutura:

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

> [!WARNING]
> Se todos os arquivos de vídeo estiverem em um único diretório ou se não estiverem no mesmo nível da estrutura de diretórios, a coluna `label` não será adicionada automaticamente. Se você precisar dela, defina `drop_labels=False` explicitamente.

Se houver informações adicionais que você deseja incluir sobre seu conjunto de dados, como legendas de texto ou caixas delimitadoras, adicione-as como um arquivo `metadata.csv` na sua pasta. Isso permite criar rapidamente conjuntos de dados para diferentes tarefas de visão computacional, como legendagem de texto ou detecção de objetos. Você também pode usar um arquivo JSONL `metadata.jsonl` ou um arquivo Parquet `metadata.parquet`.

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

O arquivo `metadata.csv` deve ter um campo `file_name` ou `*_file_name` que vincule os arquivos de vídeo aos seus metadados:

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

Aqui, o `file_name` deve ser o nome do arquivo de vídeo ao lado do arquivo de metadados. Mais geralmente, deve ser o caminho relativo do diretório que contém os metadados até o arquivo de vídeo.

É possível apontar para mais de um vídeo em cada linha do seu conjunto de dados, por exemplo, se tanto a sua entrada quanto a sua saída forem vídeos:

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

Você também pode definir listas de vídeos. Nesse caso, é necessário nomear o campo `file_names` ou `*_file_names`. Aqui está um exemplo:

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

### Legendação de vídeo

Os conjuntos de dados de legendas de vídeo possuem texto descrevendo um vídeo. Um exemplo de `metadata.csv` pode ser:

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

Carregue o conjunto de dados com `VideoFolder` e ele criará uma coluna `text` para as legendas dos vídeos:

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

### Enviar o conjunto de dados para o Hub

Depois de criar um conjunto de dados, você pode compartilhá-lo usando, por exemplo, o `huggingface_hub`. Certifique-se de que a biblioteca [huggingface_hub](https://huggingface.co/docs/huggingface_hub/index) está instalada e de que você está conectado à sua conta do Hugging Face (veja o [tutorial de upload com Python](upload_dataset#upload-with-python) para mais detalhes).

Envie seu conjunto de dados com `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

O formato [WebDataset](https://github.com/webdataset/webdataset) é baseado em arquivos TAR e é adequado para grandes conjuntos de dados de vídeo. De fato, você pode agrupar seus vídeos em arquivos TAR (por exemplo, 1 GB de vídeos por arquivo TAR) e ter milhares de arquivos TAR:

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

Nos arquivos, cada exemplo é composto por arquivos que compartilham o mesmo prefixo:

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

Você pode usar arquivos JSON ou de texto, por exemplo, para armazenar os rótulos/legendas/recursos dos seus vídeos.

Para mais detalhes sobre o formato WebDataset e a biblioteca python, consulte a [documentação do WebDataset](https://webdataset.github.io/webdataset).

Carregue seu WebDataset e ele criará uma coluna por sufixo de arquivo (aqui, "mp4" e "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) é um formato de tabela de lakehouse multimodal aberto. As tabelas Lance podem armazenar nativamente não apenas texto e valores escalares, mas também objetos binários grandes (blobs), como imagens, áudio e vídeo, junto com seus dados tabulares.

O Lance oferece uma [API de blobs](https://lance.org/guide/blob/) que facilita o armazenamento e a recuperação de blobs grandes em datasets Lance. O exemplo a seguir mostra como navegar eficientemente pelos metadados sem carregar os blobs de vídeo mais pesados e, em seguida, buscar os blobs de vídeo relevantes sob demanda.

Aqui está uma visão representativa de como seria uma tabela Lance que armazena vídeos (a coluna `video_blob` usa a codificação de blob do 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}       |
+------------------------------------------+-----------------+-----+------------------------------------------+
```

### Escreva um dataset Lance a partir de arquivos de vídeo brutos

A partir de arquivos de vídeo brutos em disco e dos metadados associados (por exemplo, legendas e pontuações), você pode gravar um dataset Lance autossuficiente em um diretório local `*.lance` (um dataset Lance é um diretório em disco, e é comum nomeá-lo com o sufixo `.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",
)
```

Isso armazena seus metadados e bytes de vídeo juntos dentro de `videos.lance/`, permitindo mover/copiar um único diretório sem precisar manter arquivos `*.mp4` separados sincronizados.

Aqui está uma visão representativa de como seria uma tabela Lance que armazena vídeos (a coluna `video_blob` contém dados armazenados nativamente como blobs dentro do dataset 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}       |
+------------------------------------------+-----------------+-----+------------------------------------------+
```

Você pode enviar o diretório `videos.lance/` resultante para o Hub (por exemplo, com `huggingface_hub.HfApi.upload_folder`) e compartilhá-lo como um repositório de dataset, mantendo os metadados e os vídeos juntos como um único artefato.

> [!TIP]
> Os datasets Lance escalam para tamanhos muito grandes (terabytes e além), pois os dados são armazenados em um formato colunar no disco. Consulte o guia da [API de blobs](https://lance.org/guide/blob/) para as informações mais recentes sobre as melhores práticas para armazenar e recuperar blobs grandes no Lance.

Ao gravar grandes conjuntos de dados, é geralmente melhor limitar o tamanho de cada arquivo individual `*.lance` a alguns gigabytes no máximo. Basta coletar os dados por meio de um iterador e especificar o parâmetro `max_bytes_per_file` ao gravar o conjunto de dados:

```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,
)
```

Para mais detalhes sobre o trabalho com conjuntos de dados Lance, consulte a [documentação do Lance](https://lance.org).

