Muat data video

Dukungan video bersifat eksperimental dan dapat berubah.

Dataset video memiliki kolom bertipe Video, yang berisi objek torchcodec.

Untuk bekerja dengan dataset video, Anda perlu menginstal paket torchcodec dan ffmpeg. Lihat panduan instalasi untuk mempelajari cara menginstalnya.

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

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

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

>>> 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 efisien untuk memperoleh daftar frame yang panjang, lihat dokumentasi torchcodec untuk melihat lebih banyak fungsi untuk mengakses data secara efisien:

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

>>> 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() untuk menerima kolom jalur file video, dan mendekodekannya menjadi video torchcodec dengan fitur Video:

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

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

>>> 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() dan direktori di data_dir:

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

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

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

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

Untuk informasi lebih lanjut tentang cara membuat dataset VideoFolder Anda sendiri, lihat panduan Membuat dataset video.

WebDataset

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

>>> from datasets import load_dataset

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

Lance

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

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 Anda tanpa langkah konversi tambahan.

Untuk detail lebih lanjut tentang cara bekerja dengan dataset Lance, lihat dokumentasi Lance.

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:

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

>>> dataset = dataset.decode(False)

Catatan: IterableDataset.decode() saat ini hanya tersedia untuk dataset streaming.