|
| 1 | +# Video Dataset |
| 2 | + |
| 3 | +This guide will show you how to configure your dataset repository with video files. You can find accompanying examples of repositories in this [Video datasets examples collection](https://huggingface.co/collections/datasets-examples/video-dataset-6568e7cf28639db76eb92d65). |
| 4 | + |
| 5 | +A dataset with a supported structure and [file formats](./datasets-adding#file-formats) automatically has a Dataset Viewer on its page on the Hub. |
| 6 | + |
| 7 | +Additional information about your videos - such as captions or bounding boxes for object detection - is automatically loaded as long as you include this information in a metadata file (`metadata.csv`/`metadata.jsonl`/`metadata.parquet`). |
| 8 | + |
| 9 | +Alternatively, videos can be in Parquet files or in TAR archives following the [WebDataset](https://github.com/webdataset/webdataset) format. |
| 10 | + |
| 11 | + |
| 12 | +## Only videos |
| 13 | + |
| 14 | +If your dataset only consists of one column with videos, you can simply store your video files at the root: |
| 15 | + |
| 16 | +``` |
| 17 | +my_dataset_repository/ |
| 18 | +├── 1.mp4 |
| 19 | +├── 2.mp4 |
| 20 | +├── 3.mp4 |
| 21 | +└── 4.mp4 |
| 22 | +``` |
| 23 | + |
| 24 | +or in a subdirectory: |
| 25 | + |
| 26 | +``` |
| 27 | +my_dataset_repository/ |
| 28 | +└── videos |
| 29 | + ├── 1.mp4 |
| 30 | + ├── 2.mp4 |
| 31 | + ├── 3.mp4 |
| 32 | + └── 4.mp4 |
| 33 | +``` |
| 34 | + |
| 35 | +Multiple [formats](./datasets-adding#file-formats) are supported at the same time, including PNG, JPEG, TIFF and WebP. |
| 36 | + |
| 37 | +``` |
| 38 | +my_dataset_repository/ |
| 39 | +└── videos |
| 40 | + ├── 1.mp4 |
| 41 | + ├── 2.png |
| 42 | + ├── 3.tiff |
| 43 | + └── 4.webp |
| 44 | +``` |
| 45 | + |
| 46 | +If you have several splits, you can put your videos into directories named accordingly: |
| 47 | + |
| 48 | +``` |
| 49 | +my_dataset_repository/ |
| 50 | +├── train |
| 51 | +│ ├── 1.mp4 |
| 52 | +│ └── 2.mp4 |
| 53 | +└── test |
| 54 | + ├── 3.mp4 |
| 55 | + └── 4.mp4 |
| 56 | +``` |
| 57 | + |
| 58 | +See [File names and splits](./datasets-file-names-and-splits) for more information and other ways to organize data by splits. |
| 59 | + |
| 60 | +## Additional columns |
| 61 | + |
| 62 | +If there is additional information you'd like to include about your dataset, like text captions or bounding boxes, add it as a `metadata.csv` file in your repository. This lets you quickly create datasets for different computer vision tasks like [video generation](https://huggingface.co/tasks/text-to-video) or [object detection](https://huggingface.co/tasks/object-detection). |
| 63 | + |
| 64 | +``` |
| 65 | +my_dataset_repository/ |
| 66 | +└── train |
| 67 | + ├── 1.mp4 |
| 68 | + ├── 2.mp4 |
| 69 | + ├── 3.mp4 |
| 70 | + ├── 4.mp4 |
| 71 | + └── metadata.csv |
| 72 | +``` |
| 73 | + |
| 74 | +Your `metadata.csv` file must have a `file_name` column which links video files with their metadata: |
| 75 | + |
| 76 | +```csv |
| 77 | +file_name,text |
| 78 | +1.mp4,an animation of a green pokemon with red eyes |
| 79 | +2.mp4,a short video of a green and yellow toy with a red nose |
| 80 | +3.mp4,a red and white ball shows an angry look on its face |
| 81 | +4.mp4,a cartoon ball is smiling |
| 82 | +``` |
| 83 | + |
| 84 | +You can also use a [JSONL](https://jsonlines.org/) file `metadata.jsonl`: |
| 85 | + |
| 86 | +```jsonl |
| 87 | +{"file_name": "1.mp4","text": "an animation of a green pokemon with red eyes"} |
| 88 | +{"file_name": "2.mp4","text": "a short video of a green and yellow toy with a red nose"} |
| 89 | +{"file_name": "3.mp4","text": "a red and white ball shows an angry look on its face"} |
| 90 | +{"file_name": "4.mp4","text": "a cartoon ball is smiling"} |
| 91 | +``` |
| 92 | + |
| 93 | +And for bigger datasets or if you are interested in advanced data retrieval features, you can use a [Parquet](https://parquet.apache.org/) file `metadata.parquet`. |
| 94 | + |
| 95 | +## Relative paths |
| 96 | + |
| 97 | +Metadata file must be located either in the same directory with the videos it is linked to, or in any parent directory, like in this example: |
| 98 | + |
| 99 | +``` |
| 100 | +my_dataset_repository/ |
| 101 | +└── train |
| 102 | + ├── videos |
| 103 | + │ ├── 1.mp4 |
| 104 | + │ ├── 2.mp4 |
| 105 | + │ ├── 3.mp4 |
| 106 | + │ └── 4.mp4 |
| 107 | + └── metadata.csv |
| 108 | +``` |
| 109 | + |
| 110 | +In this case, the `file_name` column must be a full relative path to the videos, not just the filename: |
| 111 | + |
| 112 | +```csv |
| 113 | +file_name,text |
| 114 | +videos/1.mp4,an animation of a green pokemon with red eyes |
| 115 | +videos/2.mp4,a short video of a green and yellow toy with a red nose |
| 116 | +videos/3.mp4,a red and white ball shows an angry look on its face |
| 117 | +videos/4.mp4,a cartoon ball is smiling |
| 118 | +``` |
| 119 | + |
| 120 | +Metadata files cannot be put in subdirectories of a directory with the videos. |
| 121 | + |
| 122 | +More generally, any column named `file_name` or `*_file_name` should contain the full relative path to the videos. |
| 123 | + |
| 124 | +## Video classification |
| 125 | + |
| 126 | +For video classification datasets, you can also use a simple setup: use directories to name the video classes. Store your video files in a directory structure like: |
| 127 | + |
| 128 | +``` |
| 129 | +my_dataset_repository/ |
| 130 | +├── green |
| 131 | +│ ├── 1.mp4 |
| 132 | +│ └── 2.mp4 |
| 133 | +└── red |
| 134 | + ├── 3.mp4 |
| 135 | + └── 4.mp4 |
| 136 | +``` |
| 137 | + |
| 138 | +The dataset created with this structure contains two columns: `video` and `label` (with values `green` and `red`). |
| 139 | + |
| 140 | +You can also provide multiple splits. To do so, your dataset directory should have the following structure (see [File names and splits](./datasets-file-names-and-splits) for more information): |
| 141 | + |
| 142 | +``` |
| 143 | +my_dataset_repository/ |
| 144 | +├── test |
| 145 | +│ ├── green |
| 146 | +│ │ └── 2.mp4 |
| 147 | +│ └── red |
| 148 | +│ └── 4.mp4 |
| 149 | +└── train |
| 150 | + ├── green |
| 151 | + │ └── 1.mp4 |
| 152 | + └── red |
| 153 | + └── 3.mp4 |
| 154 | +``` |
| 155 | + |
| 156 | +You can disable this automatic addition of the `label` column in the [YAML configuration](./datasets-manual-configuration). If your directory names have no special meaning, set `drop_labels: true` in the README header: |
| 157 | + |
| 158 | +```yaml |
| 159 | +configs: |
| 160 | + - config_name: default # Name of the dataset subset, if applicable. |
| 161 | + drop_labels: true |
| 162 | +``` |
| 163 | +
|
| 164 | +## Large scale datasets |
| 165 | +
|
| 166 | +### WebDataset format |
| 167 | +
|
| 168 | +The [WebDataset](./datasets-webdataset) format is well suited for large scale video datasets. |
| 169 | +It consists of TAR archives containing videos and their metadata and is optimized for streaming. It is useful if you have a large number of videos and to get streaming data loaders for large scale training. |
| 170 | +
|
| 171 | +``` |
| 172 | +my_dataset_repository/ |
| 173 | +├── train-0000.tar |
| 174 | +├── train-0001.tar |
| 175 | +├── ... |
| 176 | +└── train-1023.tar |
| 177 | +``` |
| 178 | + |
| 179 | +To make a WebDataset TAR archive, create a directory containing the videos and metadata files to be archived and create the TAR archive using e.g. the `tar` command. |
| 180 | +The usual size per archive is generally around 1GB. |
| 181 | +Make sure each video and metadata pair share the same file prefix, for example: |
| 182 | + |
| 183 | +``` |
| 184 | +train-0000/ |
| 185 | +├── 000.mp4 |
| 186 | +├── 000.json |
| 187 | +├── 001.mp4 |
| 188 | +├── 001.json |
| 189 | +├── ... |
| 190 | +├── 999.mp4 |
| 191 | +└── 999.json |
| 192 | +``` |
| 193 | + |
| 194 | +Note that for user convenience and to enable the [Dataset Viewer](./datasets-viewer), every dataset hosted in the Hub is automatically converted to Parquet format up to 5GB. Since videos can be quite large, the URLs to the videos are stored in the converted Parquet data without the video bytes themselves. Read more about it in the [Parquet format](./datasets-viewer#access-the-parquet-files) documentation. |
0 commit comments