{"id":26367536,"url":"https://github.com/raideno/video-dataset","last_synced_at":"2025-10-29T11:42:58.410Z","repository":{"id":280291780,"uuid":"941525990","full_name":"raideno/video-dataset","owner":"raideno","description":"An easy to use pytorch compatible video dataset that is fully customizable.","archived":false,"fork":false,"pushed_at":"2025-03-11T20:11:57.000Z","size":68,"stargazers_count":1,"open_issues_count":5,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-11T21:23:06.410Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/raideno.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-03-02T14:02:29.000Z","updated_at":"2025-03-06T14:00:33.000Z","dependencies_parsed_at":"2025-03-02T15:27:02.969Z","dependency_job_id":"cf705930-295b-4eba-b1d1-f3bb46a94b7d","html_url":"https://github.com/raideno/video-dataset","commit_stats":null,"previous_names":["raideno/video-dataset"],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raideno%2Fvideo-dataset","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raideno%2Fvideo-dataset/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raideno%2Fvideo-dataset/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raideno%2Fvideo-dataset/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/raideno","download_url":"https://codeload.github.com/raideno/video-dataset/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243933449,"owners_count":20370988,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-03-16T21:17:37.045Z","updated_at":"2025-10-29T11:42:53.331Z","avatar_url":"https://github.com/raideno.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Video Dataset\n\nThis is a python library to create a video dataset. The project is inspired from [Video-Dataset-Loading-Pytorch\n](https://github.com/RaivoKoot/Video-Dataset-Loading-Pytorch) but with a lot of additional features and modifications.\n\nThe goal is to have a very moldable and customizable video dataset that can be reused in all possible video dataset situations.\n\n## Installation\n\n```bash\npip install video-dataset\n```\n\n## Dataset Structures\n\nThe General dataset structure is the one specified below. One global directory where there is a sub directory for the videos and another one for the annotations, ids files are optional.\n\n```txt\n- your-dataset\n- - videos\n- - - video-1\n- - - video-2\n- - - ...\n- - annotations\n- - - video-1\n- - - video-2\n- - - ...\ntraining_ids.txt\ntesting_ids.txt\nvalidation_ids.txt\n```\n\nAn important thing is that each the video must be named (except for the extension) the same way as it's corresponding annotation in order for the VideoDataset to correctly detect it.\n\nWhen defining a video-dataset multiple components need to be defined:\n\n- **videos_dir:** The path were the videos are stored.\n- **annotations_dir** The path were the annotations are stored.\n- **segment_size:** The desired number of frames per video $*_1$.\n- **video_processor:** Will be in charge to read the video $*_2$.\n- **annotations_processor:** Will be in charge to read the annotations $*_2$.\n\n$*_1$: Suppose your videos contain 100 frames and you put `segment_size=10`; from each video you'll have 10 sub videos of 10 frames each. You an also consider the whole video by putting `segment_size=-1`.\n\n$*_2:$ In the package, a number of predefined video and annotations processor are available and cover practically any case you can encounter, but it is also possible to defined a custom video or annotation processor and use it with the video-dataset.\n\n## Video Processors\n\nThe Dataset supports multiple video formats, all the supported formats are presented below:\n\n### Raw Video Representation\n\nIn this format each element in the videos directory need to be a video file (with any of the supported video extensions).\n\nFor example:\n\n```txt\n- your-dataset\n- - videos\n- - - video-1.mp4\n- - - video-2.mp4\n- - - ...\n- - annotations\n- - - ...\n```\n\nThe corresponding VideoDataset:\n\n```python\nfrom video_dataset import VideoDataset\nfrom video_dataset.video import VideoFromVideoFile\nfrom video_dataset.annotations import AnnotationsFromFrameLevelTxtFileAnnotations\n\nvideo_processor: Type[Video]\nannotations_processor: Type[Annotations]\n\ndataset = VideoDataset(\n    videos_dir=\"./dataset/videos\",\n    annotations_dir=\"./dataset/annotations\",\n    segment_size=32,\n    video_processor=VideoFromVideoFile,\n    annotations_processor=AnnotationsFromFrameLevelTxtFileAnnotations,\n)\n```\n\n### Frame Level Video Representation\n\nHaving the elements of the videos directory as raw videos can be quite slow when loading the videos, an alternative approach is that each element of the videos directory is a directory it self with the name of the video and the content of the directory is images where each image represent a single frame of the video.\n\n```txt\n- your-dataset\n- - videos\n- - - video-1\n- - - - img_00001.jpg\n- - - - img_00002.jpg\n- - - - img_00003.jpg\n- - - - ...\n- - - video-2\n- - - ...\n- - annotations\n- - - ...\n```\n\nThe corresponding VideoDataset:\n\n```python\nfrom video_dataset import VideoDataset\nfrom video_dataset.video import VideoFromVideoFramesDirectory\nfrom video_dataset.annotations import AnnotationsFromFrameLevelTxtFileAnnotations\n\nvideo_processor: Type[Video]\nannotations_processor: Type[Annotations]\n\ndataset = VideoDataset(\n    videos_dir=\"./dataset/videos\",\n    annotations_dir=\"./dataset/annotations\",\n    segment_size=32,\n    video_processor=VideoFromVideoFramesDirectory,\n    annotations_processor=AnnotationsFromFrameLevelTxtFileAnnotations,\n)\n```\n\nThis significantly reduces video loading time but at the cost of storage space.\n\n### Custom Processor\n\nIn order to create a custom video processor you basically need to create a class that implements the `Video` class as follow:\n\n```python\nfrom video_dataset.video import Video\n\nclass CustomVideoProcessor(Video):\n    def __init__(self, videos_dir_path: str, id: str):\n        ...\n\n    def get_id(self):\n        return self.id\n\n    def __len__(self):\n        ...\n\n    def __getitem__(self, index: int | slice):\n        \"\"\"\n        Return the corresponding video frame(s) requested by the index.\n        \"\"\"\n        ...\n```\n\n## Annotations Processors\n\nYour video annotations files can be in multiple formats.\n\n### Whole Video Annotations\n\nA single csv or txt file describing the classes / labels of all the videos.\n\n- [ ] Implementation. Coming Soon..\n\n### Frame By Frame Annotations\n\nEach video have a corresponding txt file where each line in the file correspond to a class / label / annotation of a frame in the video.\n\n```txt\neating\neating\neating\neating\neating\neating\neating\n...\n```\n\nThe corresponding VideoDataset:\n\n```python\nfrom video_dataset import VideoDataset\nfrom video_dataset.video import VideoFromVideoFile\nfrom video_dataset.annotations import AnnotationsFromFrameLevelTxtFileAnnotations\n\nvideo_processor: Type[Video]\nannotations_processor: Type[Annotations]\n\ndataset = VideoDataset(\n    videos_dir=\"./dataset/videos\",\n    annotations_dir=\"./dataset/annotations\",\n    segment_size=32,\n    video_processor=VideoFromVideoFile,\n    annotations_processor=AnnotationsFromFrameLevelTxtFileAnnotations,\n)\n```\n\n### Segment Level Annotations\n\nEach video has a corresponding csv file with the following structure:\n\n| acton   | starting-timestamp | duration |\n| ------- | ------------------ | -------- |\n| eating  | 0                  | 4000     |\n| dancing | 4000               | 6000     |\n| eating  | 10000              | 8000     |\n\nThe corresponding VideoDataset:\n\n```python\nfrom video_dataset import VideoDataset\nfrom video_dataset.video import VideoFromVideoFile\nfrom video_dataset.annotations import AnnotationsFromSegmentLevelCsvFileAnnotations\n\nvideo_processor: Type[Video]\nannotations_processor: Type[Annotations]\n\ndataset = VideoDataset(\n    videos_dir=\"./dataset/videos\",\n    annotations_dir=\"./dataset/annotations\",\n    segment_size=32,\n    video_processor=VideoFromVideoFile,\n    annotations_processor=AnnotationsFromSegmentLevelCsvFileAnnotations,\n)\n```\n\n### Custom Processor\n\nIn order to create a custom annotations processor you basically need to create a class that implements the `Annotations` class as follow:\n\n```python\nfrom video_dataset.annotations import Annotations\n\nclass CustomAnnotationsProcessor(Annotations):\n    def __init__(self, annotations_dir_path: str, id: str):\n        ...\n\n    def get_id(self):\n        return self.id\n\n    @abstractmethod\n    def __getitem__(self, index: int | slice):\n        \"\"\"\n        Get the annotation(s) of the video file corresponding to the given frame(s) index / indices.\n        Note that even if an index is given the annotations will be returned in a batch format (Number of frames, Height, Width, Channels).\n        \"\"\"\n        ...\n```\n\n## Contributions\n\nAll contributions are welcome, just open a pull request.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fraideno%2Fvideo-dataset","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fraideno%2Fvideo-dataset","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fraideno%2Fvideo-dataset/lists"}