# Muat data video

> [!WARNING]
> Dukungan video bersifat eksperimental dan dapat berubah.

Dataset video memiliki kolom bertipe [Video](/docs/datasets/v5.2.0/id/package_reference/main_classes#datasets.Video), yang berisi objek `torchcodec`.

> [!TIP]
> Untuk bekerja dengan dataset video, Anda perlu menginstal paket `torchcodec` dan `ffmpeg`. Lihat panduan [instalasi](https://github.com/meta-pytorch/torchcodec#installing-torchcodec) untuk mempelajari cara menginstalnya.

Saat Anda memuat dataset video dan memanggil kolom video, video akan didekode sebagai Video `torchcodec`:

```py
>>> from datasets import load_dataset, Video

>>> dataset = load_dataset("path/to/video/folder", split="train")
>>> dataset[0]["video"]
<torchcodec.decoders._video_decoder.VideoDecoder object at 0x14a61d5a0>
```

> [!WARNING]
> Gunakan indeks baris terlebih dahulu, lalu kolom `video` untuk mengakses dataset video - `dataset[0]["video"]` - guna menghindari pembuatan semua objek video dalam dataset. Jika tidak, proses ini dapat menjadi lambat dan memakan waktu jika Anda memiliki dataset yang besar.

Untuk panduan tentang cara memuat jenis dataset apa pun, lihat panduan pemuatan umum.

## Baca frame

Akses frame secara langsung dari video menggunakan `VideoReader` dengan `next()`:

```python
>>> video = dataset[0]["video"]
>>> first_frame = video.get_frame_at(0)
>>> first_frame.data.shape
(3, 240, 320)
>>> first_frame.pts_seconds  # timestamp
0.0
```

Untuk mendapatkan beberapa frame sekaligus, Anda dapat memanggil `.get_frames_in_range(start: int, stop: int, step: int)`. Ini akan mengembalikan batch frame. Ini adalah cara yang efisien untuk memperoleh daftar frame yang panjang, lihat [dokumentasi torchcodec](https://meta-pytorch.org/torchcodec/stable/generated/torchcodec.decoders.VideoDecoder.html) untuk melihat lebih banyak fungsi untuk mengakses data secara efisien:

```python
>>> import torch
>>> frames = video.get_frames_in_range(0, 6, 1)
>>> frames.data.shape
torch.Size([5, 3, 240, 320])
```

Ada juga `.get_frames_played_in_range(start_seconds: float, stop_seconds: float)` untuk mengakses semua frame yang diputar dalam rentang waktu tertentu.

```python
>>> frames = video.get_frames_played_in_range(.5, 1.2)
>>> frames.data.shape
torch.Size([42, 3, 240, 320])
```

## File lokal

Anda dapat memuat dataset dari jalur video. Gunakan fungsi [cast_column()](/docs/datasets/v5.2.0/id/package_reference/main_classes#datasets.Dataset.cast_column) untuk menerima kolom jalur file video, dan mendekodekannya menjadi video `torchcodec` dengan fitur [Video](/docs/datasets/v5.2.0/id/package_reference/main_classes#datasets.Video):

```py
>>> from datasets import Dataset, Video

>>> dataset = Dataset.from_dict({"video": ["path/to/video_1", "path/to/video_2", ..., "path/to/video_n"]}).cast_column("video", Video())
>>> dataset[0]["video"]
<torchcodec.decoders._video_decoder.VideoDecoder object at 0x14a61e080>
```

Jika Anda hanya ingin memuat jalur dasar ke dataset video tanpa mendekode objek video, atur `decode=False` pada fitur [Video](/docs/datasets/v5.2.0/id/package_reference/main_classes#datasets.Video):

```py
>>> dataset = dataset.cast_column("video", Video(decode=False))
>>> dataset[0]["video"]
{'bytes': None,
 'path': 'path/to/video/folder/video0.mp4'}
```

## VideoFolder

Anda juga dapat memuat dataset dengan builder dataset `VideoFolder` yang tidak memerlukan penulisan dataloader kustom. Hal ini menjadikan `VideoFolder` ideal untuk membuat dan memuat dataset video dengan cepat yang berisi beberapa ribu video untuk berbagai tugas visi. Struktur dataset video Anda harus seperti ini:

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

Jika dataset mengikuti struktur `VideoFolder`, maka Anda dapat memuatnya langsung dengan [load_dataset()](/docs/datasets/v5.2.0/id/package_reference/loading_methods#datasets.load_dataset):

```py
>>> from datasets import load_dataset

>>> dataset = load_dataset("username/dataset_name")
>>> # OR locally:
>>> dataset = load_dataset("/path/to/folder")
```

Untuk dataset lokal, ini setara dengan meneruskan `videofolder` secara manual di [load_dataset()](/docs/datasets/v5.2.0/id/package_reference/loading_methods#datasets.load_dataset) dan direktori di `data_dir`:

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

Lalu Anda dapat mengakses video sebagai objek `torchcodec.decoders._video_decoder.VideoDecoder`:

```
>>> dataset["train"][0]
{"video": <torchcodec.decoders._video_decoder.VideoDecoder object at 0x14a61e080>, "label": 0}

>>> dataset["train"][-1]
{"video": <torchcodec.decoders._video_decoder.VideoDecoder object at 0x14a61e090>, "label": 1}
```

Untuk mengabaikan informasi dalam file metadata, atur `drop_metadata=True` di [load_dataset()](/docs/datasets/v5.2.0/id/package_reference/loading_methods#datasets.load_dataset):

```py
>>> from datasets import load_dataset

>>> dataset = load_dataset("username/dataset_with_metadata", drop_metadata=True)
```

Jika Anda tidak memiliki file metadata, `VideoFolder` secara otomatis menyimpulkan nama label dari nama direktori. Jika Anda ingin menghapus label yang dibuat secara otomatis, atur `drop_labels=True`. Dalam kasus ini, dataset Anda hanya akan berisi kolom video:

```py
>>> from datasets import load_dataset

>>> dataset = load_dataset("username/dataset_without_metadata", drop_labels=True)
```

Terakhir, argumen `filters` memungkinkan Anda memuat hanya sebagian dari dataset, berdasarkan kondisi pada label atau metadata. Ini sangat berguna jika metadata dalam format Parquet, karena format ini memungkinkan filtering yang cepat. Disarankan juga untuk menggunakan argumen ini dengan `streaming=True`, karena secara default dataset diunduh sepenuhnya sebelum filtering dilakukan.

```python
>>> filters = [("label", "=", 0)]
>>> dataset = load_dataset("username/dataset_name", streaming=True, filters=filters)
```

> [!TIP]
> Untuk informasi lebih lanjut tentang cara membuat dataset `VideoFolder` Anda sendiri, lihat panduan [Membuat dataset video](./video_dataset).

## WebDataset

Format [WebDataset](https://github.com/webdataset/webdataset) didasarkan pada folder arsip TAR dan cocok untuk dataset video besar. Karena ukurannya, WebDataset umumnya dimuat dalam mode streaming (menggunakan `streaming=True`).

Anda dapat memuat WebDataset seperti ini:

```python
>>> from datasets import load_dataset

>>> dataset = load_dataset("webdataset", data_dir="/path/to/folder", streaming=True)
```

## Lance

[Lance](https://lance.org) adalah format tabel lakehouse multimodal terbuka. Tabel Lance dapat menyimpan secara native tidak hanya teks dan nilai skalar, tetapi juga objek biner besar (blobs) seperti gambar, audio, dan video berdampingan dengan data tabular Anda. Di dalam tabel Lance, blob besar seperti video disimpan sebagai byte dengan offset (lihat [panduan blob](https://lance.org/guide/blob/) untuk detail lebih lanjut), sehingga memudahkan pemindaian dan penyaringan metadata tanpa memuat blob video yang lebih berat, dan kemudian mengambil hanya blob video spesifik yang Anda butuhkan sesuai permintaan.

Selain itu, karena Lance adalah format kolom, Anda dapat memproyeksikan dan memfilter hanya kolom metadata yang Anda butuhkan (tanpa mengambil file video berukuran besar), lalu mengambil subset kecil baris (termasuk video) saat Anda siap. Hal ini menjaga metadata dan video Anda tetap berada di satu tempat, tanpa memerlukan penyimpanan file terpisah atau indeks eksternal.

```python
import lance

ds = lance.dataset("hf://datasets/lance-format/openvid-lance/data/train.lance")

# 1. Browse metadata without loading video blobs.
metadata = ds.scanner(
    columns=["caption", "aesthetic_score"],
    filter="aesthetic_score >= 4.5",
    limit=2,
).to_table().to_pylist()

# 2. Fetch a single video blob by row index.
selected_index = 0
blob_file = ds.take_blobs("video_blob", ids=[selected_index])[0]
with open("video_0.mp4", "wb") as f:
    f.write(blob_file.read())
```

Pada contoh ini, video disimpan secara native (sebagai byte terenkodnya) di tabel Lance, sehingga Anda dapat menuliskannya langsung ke file `mp4` pada sistem file lokal tanpa langkah konversi tambahan.

Untuk detail lebih lanjut tentang cara bekerja dengan dataset Lance, lihat [dokumentasi Lance](https://lance.org).

## Dekoding video

Secara default, video didekode secara berurutan sebagai `VideoDecoders` torchcodec saat Anda mengiterasi dataset. Metadata video didekode secara berurutan, dan frame video tidak dibaca sampai Anda mengaksesnya.

Namun, dataset dapat dipercepat secara signifikan menggunakan dekoding multithreaded:

```python
>>> import os
>>> num_threads = num_threads = min(32, (os.cpu_count() or 1) + 4)
>>> dataset = dataset.decode(num_threads=num_threads)
>>> for example in dataset:  # up to 20 times faster !
...     ...
```

Anda dapat mengaktifkan multithreading menggunakan `num_threads`. Hal ini sangat berguna untuk mempercepat streaming data jarak jauh. Namun, hal ini bisa lebih lambat daripada `num_threads=0` untuk data lokal pada disk yang cepat.

Jika Anda tidak tertarik pada video yang didekode sebagai `VideoDecoders` torchcodec dan ingin mengakses path/bytes-nya, Anda dapat menonaktifkan dekoding:

```python
>>> dataset = dataset.decode(False)
```

Catatan: [IterableDataset.decode()](/docs/datasets/v5.2.0/id/package_reference/main_classes#datasets.IterableDataset.decode) saat ini hanya tersedia untuk dataset streaming.

