supervisely 6.73.452__py3-none-any.whl → 6.73.513__py3-none-any.whl

supervisely/project/video_project.py

@@ -1,19 +1,24 @@
 # coding: utf-8
 
-# docs
 from __future__ import annotations
 
 import asyncio
+import io
+import json
 import os
+import tarfile
+import tempfile
 from collections import namedtuple
 from typing import Callable, Dict, List, NamedTuple, Optional, Tuple, Union
 
+import zstd
 from tqdm import tqdm
 
-from supervisely._utils import batched
+from supervisely._utils import batched, logger
 from supervisely.api.api import Api
 from supervisely.api.dataset_api import DatasetInfo
 from supervisely.api.module_api import ApiField
+from supervisely.api.project_api import ProjectInfo
 from supervisely.api.video.video_api import VideoInfo
 from supervisely.collection.key_indexed_collection import KeyIndexedCollection
 from supervisely.io.fs import clean_dir, mkdir, touch, touch_async
@@ -21,8 +26,13 @@ from supervisely.io.json import dump_json_file, dump_json_file_async, load_json_
 from supervisely.project.project import Dataset, OpenMode, Project
 from supervisely.project.project import read_single_project as read_project_wrapper
 from supervisely.project.project_meta import ProjectMeta
+from supervisely.project.project_settings import LabelingInterface
 from supervisely.project.project_type import ProjectType
-from supervisely.sly_logger import logger
+from supervisely.project.versioning.common import (
+    DEFAULT_VIDEO_SCHEMA_VERSION,
+    get_video_snapshot_schema,
+)
+from supervisely.project.versioning.schema_fields import VersionSchemaField
 from supervisely.task.progress import tqdm_sly
 from supervisely.video import video as sly_video
 from supervisely.video_annotation.key_id_map import KeyIdMap
@@ -30,11 +40,10 @@ from supervisely.video_annotation.video_annotation import VideoAnnotation
 
 
 class VideoItemPaths(NamedTuple):
-    #: :class:`str`: Full video file path of item
     video_path: str
-
-    #: :class:`str`: Full annotation file path of item
+    # Full video file path of item
     ann_path: str
+    # Full annotation file path of item
 
 
 class VideoDataset(Dataset):
@@ -63,6 +72,9 @@ class VideoDataset(Dataset):
     #: :class:`str`: Items info directory name
     item_info_dir_name = "video_info"
 
+    #: :class:`str`: Metadata directory name
+    metadata_dir_name = "metadata"
+
     #: :class:`str`: Segmentation masks directory name
     seg_dir_name = None
 
@@ -1036,7 +1048,7 @@ class VideoProject(Project):
         raise NotImplementedError(
             f"Static method 'get_train_val_splits_by_tag()' is not supported for VideoProject class now."
         )
-    
+
     @staticmethod
     def get_train_val_splits_by_collections(
         project_dir: str,
@@ -1193,7 +1205,7 @@ class VideoProject(Project):
         api: Api,
         project_id: int,
         dest_dir: str,
-        semaphore: asyncio.Semaphore = None,
+        semaphore: Optional[Union[asyncio.Semaphore, int]] = None,
         dataset_ids: List[int] = None,
         download_videos: bool = True,
         save_video_info: bool = False,
@@ -1213,7 +1225,7 @@ class VideoProject(Project):
         :param dest_dir: Directory to download video project.
         :type dest_dir: :class:`str`
         :param semaphore: Semaphore to limit the number of concurrent downloads of items.
-        :type semaphore: :class:`asyncio.Semaphore`, optional
+        :type semaphore: :class:`asyncio.Semaphore` or :class:`int`, optional
         :param dataset_ids: Datasets IDs in Supervisely to download.
         :type dataset_ids: :class:`list` [ :class:`int` ], optional
         :param download_videos: Download videos from Supervisely video project in dest_dir or not.
@@ -1261,6 +1273,678 @@ class VideoProject(Project):
             **kwargs,
         )
 
+    # --------------------- #
+    # Video Data Versioning #
+    # --------------------- #
+    @staticmethod
+    def download_bin(
+        api: Api,
+        project_id: int,
+        dest_dir: Optional[str] = None,
+        dataset_ids: Optional[List[int]] = None,
+        batch_size: int = 50,
+        log_progress: bool = True,
+        progress_cb: Optional[Union[tqdm, Callable]] = None,
+        return_bytesio: bool = False,
+    ) -> Union[str, io.BytesIO]:
+        """
+        Download video project snapshot in Arrow/Parquet-based binary format.
+
+        Result is a .tar.zst archive containing:
+            - project_info.json
+            - project_meta.json
+            - key_id_map.json
+            - manifest.json
+            - datasets.parquet
+            - videos.parquet
+            - objects.parquet
+            - figures.parquet
+
+        :param api: Supervisely API client.
+        :type api: Api
+        :param project_id: Source project ID.
+        :type project_id: int
+        :param dest_dir: Directory to save the resulting ``.tar.zst`` file. Required if ``return_bytesio`` is False.
+        :type dest_dir: Optional[str]
+        :param dataset_ids: Optional list of dataset IDs to include. If provided, only those datasets (and their videos/annotations) will be included in the snapshot.
+        :type dataset_ids: Optional[List[int]]
+        :param batch_size: Batch size for downloading video annotations.
+        :type batch_size: int
+        :param log_progress: If True, shows progress (uses internal tqdm progress bars) when ``progress_cb`` is not provided.
+        :type log_progress: bool
+        :param progress_cb: Optional progress callback. Can be a ``tqdm``-like callable or a function accepting an integer increment.
+        :type progress_cb: Optional[Union[tqdm, Callable]]
+        :param return_bytesio: If True, return the snapshot as :class:`io.BytesIO`. If False, write the snapshot to ``dest_dir`` and return the output file path.
+        :type return_bytesio: bool
+        :return: Either output file path (``.tar.zst``) when ``return_bytesio`` is False, or an in-memory snapshot stream when ``return_bytesio`` is True.
+        :rtype: Union[str, io.BytesIO]
+        """
+        if dest_dir is None and not return_bytesio:
+            raise ValueError(
+                "dest_dir must be specified if return_bytesio is False in VideoProject.download_bin"
+            )
+
+        snapshot_io = VideoProject.build_snapshot(
+            api,
+            project_id=project_id,
+            dataset_ids=dataset_ids,
+            batch_size=batch_size,
+            log_progress=log_progress,
+            progress_cb=progress_cb,
+        )
+
+        if return_bytesio:
+            snapshot_io.seek(0)
+            return snapshot_io
+
+        project_info = api.project.get_info_by_id(project_id)
+        os.makedirs(dest_dir, exist_ok=True)
+        out_path = os.path.join(
+            dest_dir,
+            f"{project_info.id}_{project_info.name}.tar.zst",
+        )
+        with open(out_path, "wb") as dst:
+            dst.write(snapshot_io.read())
+        return out_path
+
+    @staticmethod
+    def upload_bin(
+        api: Api,
+        file: Union[str, io.BytesIO],
+        workspace_id: int,
+        project_name: Optional[str] = None,
+        with_custom_data: bool = True,
+        log_progress: bool = True,
+        progress_cb: Optional[Union[tqdm, Callable]] = None,
+        skip_missed: bool = False,
+    ) -> "ProjectInfo":
+        """
+        Restore a video project from an Arrow/Parquet-based binary snapshot.
+
+        :param api: Supervisely API client.
+        :type api: Api
+        :param file: Snapshot file path (``.tar.zst``) or in-memory snapshot stream.
+        :type file: Union[str, io.BytesIO]
+        :param workspace_id: Target workspace ID where the project will be created.
+        :type workspace_id: int
+        :param project_name: Optional new project name. If not provided, the name from the snapshot will be used. If the name already exists in the workspace, a free name will be chosen.
+        :type project_name: Optional[str]
+        :param with_custom_data: If True, restore project/dataset/video custom data (when present in the snapshot).
+        :type with_custom_data: bool
+        :param log_progress: If True, shows progress (uses internal tqdm progress bars) when ``progress_cb`` is not provided.
+        :type log_progress: bool
+        :param progress_cb: Optional progress callback. Can be a ``tqdm``-like callable or a function accepting an integer increment.
+        :type progress_cb: Optional[Union[tqdm, Callable]]
+        :param skip_missed: If True, skip videos that are missing on server when restoring by hash.
+        :type skip_missed: bool
+        :return: Info of the newly created project.
+        :rtype: ProjectInfo
+        """
+        if isinstance(file, io.BytesIO):
+            snapshot_bytes = file.getvalue()
+        else:
+            with open(file, "rb") as f:
+                snapshot_bytes = f.read()
+
+        return VideoProject.restore_snapshot(
+            api,
+            snapshot_bytes=snapshot_bytes,
+            workspace_id=workspace_id,
+            project_name=project_name,
+            with_custom_data=with_custom_data,
+            log_progress=log_progress,
+            progress_cb=progress_cb,
+            skip_missed=skip_missed,
+        )
+
+    @staticmethod
+    def build_snapshot(
+        api: Api,
+        project_id: int,
+        dataset_ids: Optional[List[int]] = None,
+        batch_size: int = 50,
+        log_progress: bool = True,
+        progress_cb: Optional[Union[tqdm, Callable]] = None,
+        schema_version: str = DEFAULT_VIDEO_SCHEMA_VERSION,
+    ) -> io.BytesIO:
+        """
+        Create a video project snapshot in Arrow/Parquet+tar.zst format and return it as BytesIO.
+        """
+        try:
+            import pyarrow  # pylint: disable=import-error
+            import pyarrow.parquet as parquet  # pylint: disable=import-error
+        except Exception as e:
+            raise RuntimeError(
+                "pyarrow is required to build video snapshot. Please install pyarrow."
+            ) from e
+
+        project_info = api.project.get_info_by_id(project_id)
+        meta = ProjectMeta.from_json(api.project.get_meta(project_id, with_settings=True))
+        key_id_map = KeyIdMap()
+        snapshot_schema = get_video_snapshot_schema(schema_version)
+
+        tmp_root = tempfile.mkdtemp()
+        payload_dir = os.path.join(tmp_root, "payload")
+        mkdir(payload_dir)
+
+        try:
+            # project_info / meta
+            proj_info_path = os.path.join(payload_dir, "project_info.json")
+            dump_json_file(project_info._asdict(), proj_info_path)
+
+            proj_meta_path = os.path.join(payload_dir, "project_meta.json")
+            dump_json_file(meta.to_json(), proj_meta_path)
+
+            datasets_rows: List[dict] = []
+            videos_rows: List[dict] = []
+            objects_rows: List[dict] = []
+            figures_rows: List[dict] = []
+
+            dataset_ids_filter = set(dataset_ids) if dataset_ids is not None else None
+
+            # api.dataset.tree() doesn't include custom_data
+            ds_custom_data_by_id: Dict[int, dict] = {}
+            try:
+                for ds in api.dataset.get_list(
+                    project_id, recursive=True, include_custom_data=True
+                ):
+                    if getattr(ds, "custom_data", None) is not None:
+                        ds_custom_data_by_id[ds.id] = ds.custom_data
+            except Exception:
+                ds_custom_data_by_id = {}
+
+            for parents, ds_info in api.dataset.tree(project_id):
+                if dataset_ids_filter is not None and ds_info.id not in dataset_ids_filter:
+                    continue
+
+                full_path = Dataset._get_dataset_path(ds_info.name, parents)
+                ds_custom_data = ds_custom_data_by_id.get(ds_info.id)
+                datasets_rows.append(
+                    snapshot_schema.dataset_row_from_ds_info(
+                        ds_info, full_path=full_path, custom_data=ds_custom_data
+                    )
+                )
+
+                videos = api.video.get_list(ds_info.id)
+                ds_progress = progress_cb
+                if log_progress and progress_cb is None:
+                    ds_progress = tqdm_sly(
+                        desc=f"Collecting videos from '{ds_info.name}'",
+                        total=len(videos),
+                    )
+
+                for batch in batched(videos, batch_size):
+                    video_ids = [v.id for v in batch]
+                    ann_jsons = api.video.annotation.download_bulk(ds_info.id, video_ids)
+
+                    for video_info, ann_json in zip(batch, ann_jsons):
+                        if video_info.name != ann_json[ApiField.VIDEO_NAME]:
+                            raise RuntimeError(
+                                "Error in api.video.annotation.download_bulk: broken order"
+                            )
+
+                        videos_rows.append(
+                            snapshot_schema.video_row_from_video_info(
+                                video_info, src_dataset_id=ds_info.id, ann_json=ann_json
+                            )
+                        )
+
+                        video_ann = VideoAnnotation.from_json(ann_json, meta, key_id_map)
+                        obj_key_to_src_id: Dict[str, int] = {}
+                        for obj in video_ann.objects:
+                            src_obj_id = len(objects_rows) + 1
+                            obj_key_to_src_id[obj.key().hex] = src_obj_id
+                            objects_rows.append(
+                                snapshot_schema.object_row_from_object(
+                                    obj, src_object_id=src_obj_id, src_video_id=video_info.id
+                                )
+                            )
+
+                        for frame in video_ann.frames:
+                            for fig in frame.figures:
+                                parent_key = fig.parent_object.key().hex
+                                src_obj_id = obj_key_to_src_id.get(parent_key)
+                                if src_obj_id is None:
+                                    logger.warning(
+                                        f"Figure parent object with key '{parent_key}' "
+                                        f"not found in objects for video '{video_info.name}'"
+                                    )
+                                    continue
+                                figures_rows.append(
+                                    snapshot_schema.figure_row_from_figure(
+                                        fig,
+                                        figure_row_idx=len(figures_rows),
+                                        src_object_id=src_obj_id,
+                                        src_video_id=video_info.id,
+                                        frame_index=frame.index,
+                                    )
+                                )
+
+                    if ds_progress is not None:
+                        ds_progress(len(batch))
+
+            # key_id_map.json
+            key_id_map_path = os.path.join(payload_dir, "key_id_map.json")
+            key_id_map.dump_json(key_id_map_path)
+
+            # Arrow schemas
+            tables_meta = []
+            datasets_schema = snapshot_schema.datasets_schema(pyarrow)
+            videos_schema = snapshot_schema.videos_schema(pyarrow)
+            objects_schema = snapshot_schema.objects_schema(pyarrow)
+            figures_schema = snapshot_schema.figures_schema(pyarrow)
+
+            if datasets_rows:
+                ds_table = pyarrow.Table.from_pylist(datasets_rows, schema=datasets_schema)
+                ds_path = os.path.join(payload_dir, "datasets.parquet")
+                parquet.write_table(ds_table, ds_path)
+                tables_meta.append(
+                    {
+                        "name": "datasets",
+                        "path": "datasets.parquet",
+                        "row_count": ds_table.num_rows,
+                    }
+                )
+
+            if videos_rows:
+                v_table = pyarrow.Table.from_pylist(videos_rows, schema=videos_schema)
+                v_path = os.path.join(payload_dir, "videos.parquet")
+                parquet.write_table(v_table, v_path)
+                tables_meta.append(
+                    {
+                        "name": "videos",
+                        "path": "videos.parquet",
+                        "row_count": v_table.num_rows,
+                    }
+                )
+
+            if objects_rows:
+                o_table = pyarrow.Table.from_pylist(objects_rows, schema=objects_schema)
+                o_path = os.path.join(payload_dir, "objects.parquet")
+                parquet.write_table(o_table, o_path)
+                tables_meta.append(
+                    {
+                        "name": "objects",
+                        "path": "objects.parquet",
+                        "row_count": o_table.num_rows,
+                    }
+                )
+
+            if figures_rows:
+                f_table = pyarrow.Table.from_pylist(figures_rows, schema=figures_schema)
+                f_path = os.path.join(payload_dir, "figures.parquet")
+                parquet.write_table(f_table, f_path)
+                tables_meta.append(
+                    {
+                        "name": "figures",
+                        "path": "figures.parquet",
+                        "row_count": f_table.num_rows,
+                    }
+                )
+
+            manifest = {
+                VersionSchemaField.SCHEMA_VERSION: schema_version,
+                VersionSchemaField.TABLES: tables_meta,
+            }
+            manifest_path = os.path.join(payload_dir, "manifest.json")
+            dump_json_file(manifest, manifest_path)
+
+            tar_path = os.path.join(tmp_root, "snapshot.tar")
+            with tarfile.open(tar_path, "w") as tar:
+                tar.add(payload_dir, arcname=".")
+
+            chunk_size = 1024 * 1024 * 50  # 50 MiB
+            zst_path = os.path.join(tmp_root, "snapshot.tar.zst")
+            # Try streaming compression first, fallback to single-shot
+            try:
+                cctx = zstd.ZstdCompressor()
+                with open(tar_path, "rb") as src, open(zst_path, "wb") as dst:
+                    try:
+                        stream = cctx.stream_writer(dst, closefd=False)
+                    except TypeError:
+                        stream = cctx.stream_writer(dst)
+                    with stream as compressor:
+                        while True:
+                            chunk = src.read(chunk_size)
+                            if not chunk:
+                                break
+                            compressor.write(chunk)
+            # Fallback: single-shot compression
+            except Exception:
+                with open(tar_path, "rb") as src, open(zst_path, "wb") as dst:
+                    dst.write(zstd.compress(src.read()))
+
+            with open(zst_path, "rb") as f:
+                outio = io.BytesIO(f.read())
+            outio.seek(0)
+            return outio
+
+        finally:
+            try:
+                clean_dir(tmp_root)
+            except Exception:
+                pass
+
+    @staticmethod
+    def restore_snapshot(
+        api: Api,
+        snapshot_bytes: bytes,
+        workspace_id: int,
+        project_name: Optional[str] = None,
+        with_custom_data: bool = True,
+        log_progress: bool = True,
+        progress_cb: Optional[Union[tqdm, Callable]] = None,
+        skip_missed: bool = False,
+    ) -> ProjectInfo:
+        """
+        Restore a video project from a snapshot and return ProjectInfo.
+        """
+        try:
+            import pyarrow  # pylint: disable=import-error
+            import pyarrow.parquet as parquet  # pylint: disable=import-error
+        except Exception as e:
+            raise RuntimeError(
+                "pyarrow is required to restore video snapshot. Please install pyarrow."
+            ) from e
+
+        tmp_root = tempfile.mkdtemp()
+        payload_dir = os.path.join(tmp_root, "payload")
+        mkdir(payload_dir)
+
+        try:
+            try:
+                dctx = zstd.ZstdDecompressor()
+                with dctx.stream_reader(io.BytesIO(snapshot_bytes)) as reader:
+                    with tarfile.open(fileobj=reader, mode="r|") as tar:
+                        tar.extractall(payload_dir)
+            except Exception:
+                tar_bytes = zstd.decompress(snapshot_bytes)
+                with tarfile.open(fileobj=io.BytesIO(tar_bytes), mode="r") as tar:
+                    tar.extractall(payload_dir)
+
+            proj_info_path = os.path.join(payload_dir, "project_info.json")
+            proj_meta_path = os.path.join(payload_dir, "project_meta.json")
+            key_id_map_path = os.path.join(payload_dir, "key_id_map.json")
+            manifest_path = os.path.join(payload_dir, "manifest.json")
+
+            project_info_json = load_json_file(proj_info_path)
+            meta_json = load_json_file(proj_meta_path)
+            manifest = load_json_file(manifest_path)
+
+            meta = ProjectMeta.from_json(meta_json)
+            _ = KeyIdMap().load_json(key_id_map_path)
+
+            schema_version = manifest.get(VersionSchemaField.SCHEMA_VERSION) or manifest.get(
+                "schema_version"
+            )
+            try:
+                _ = get_video_snapshot_schema(schema_version)
+            except Exception:
+                raise RuntimeError(
+                    f"Unsupported video snapshot schema_version: {schema_version}"
+                )
+
+            src_project_name = project_info_json.get("name")
+            src_project_desc = project_info_json.get("description")
+            src_project_readme = project_info_json.get("readme")
+            if project_name is None:
+                project_name = src_project_name
+
+            if api.project.exists(workspace_id, project_name):
+                project_name = api.project.get_free_name(workspace_id, project_name)
+
+            project = api.project.create(
+                workspace_id,
+                project_name,
+                ProjectType.VIDEOS,
+                src_project_desc,
+                readme=src_project_readme,
+            )
+            new_meta = api.project.update_meta(project.id, meta.to_json())
+
+            if with_custom_data:
+                src_custom_data = project_info_json.get("custom_data") or {}
+                try:
+                    api.project.update_custom_data(project.id, src_custom_data, silent=True)
+                except Exception:
+                    logger.warning("Failed to restore project custom_data from snapshot")
+
+            if progress_cb is not None:
+                log_progress = False
+
+            # Datasets
+            ds_rows = []
+            datasets_path = os.path.join(payload_dir, "datasets.parquet")
+            if os.path.exists(datasets_path):
+                ds_table = parquet.read_table(datasets_path)
+                ds_rows = ds_table.to_pylist()
+
+                ds_rows.sort(
+                    key=lambda r: (r["parent_src_dataset_id"] is not None, r["parent_src_dataset_id"])
+                )
+
+            dataset_mapping: Dict[int, DatasetInfo] = {}
+            for row in ds_rows:
+                src_ds_id = row["src_dataset_id"]
+                parent_src_id = row["parent_src_dataset_id"]
+                if parent_src_id is not None:
+                    parent_ds = dataset_mapping.get(parent_src_id)
+                    parent_id = parent_ds.id if parent_ds is not None else None
+                else:
+                    parent_id = None
+
+                custom_data = None
+                if with_custom_data:
+                    raw_cd = row.get("custom_data")
+                    if isinstance(raw_cd, str) and raw_cd.strip():
+                        try:
+                            custom_data = json.loads(raw_cd)
+                        except Exception:
+                            logger.warning(
+                                f"Failed to parse dataset custom_data for '{row.get('name')}', skipping it."
+                            )
+                    elif isinstance(raw_cd, dict):
+                        custom_data = raw_cd
+
+                ds = api.dataset.create(
+                    project.id,
+                    name=row["name"],
+                    description=row["description"],
+                    parent_id=parent_id,
+                    custom_data=custom_data,
+                )
+                if with_custom_data and custom_data is not None:
+                    try:
+                        api.dataset.update_custom_data(ds.id, custom_data)
+                    except Exception:
+                        logger.warning(f"Failed to restore custom_data for dataset '{row.get('name')}'")
+                dataset_mapping[src_ds_id] = ds
+
+            # Videos
+            v_rows = []
+            videos_path = os.path.join(payload_dir, "videos.parquet")
+            if os.path.exists(videos_path):
+                v_table = parquet.read_table(videos_path)
+                v_rows = v_table.to_pylist()
+
+            videos_by_dataset: Dict[int, List[dict]] = {}
+            for row in v_rows:
+                src_ds_id = row["src_dataset_id"]
+                videos_by_dataset.setdefault(src_ds_id, []).append(row)
+
+            src_to_new_video: Dict[int, VideoInfo] = {}
+
+            for src_ds_id, rows in videos_by_dataset.items():
+                ds_info = dataset_mapping.get(src_ds_id)
+                if ds_info is None:
+                    logger.warning(
+                        f"Dataset with src id={src_ds_id} not found in mapping. "
+                        f"Skipping its videos."
+                    )
+                    continue
+
+                dataset_id = ds_info.id
+                hashed_rows = [r for r in rows if r.get("hash")]
+                link_rows = [r for r in rows if not r.get("hash") and r.get("link")]
+
+                ds_progress = progress_cb
+                if log_progress and progress_cb is None:
+                    ds_progress = tqdm_sly(
+                        desc=f"Uploading videos to '{ds_info.name}'",
+                        total=len(rows),
+                    )
+
+                if hashed_rows:
+                    if skip_missed:
+                        existing_hashes = api.video.check_existing_hashes(
+                            list({r["hash"] for r in hashed_rows})
+                        )
+                        kept_hashed_rows = [r for r in hashed_rows if r["hash"] in existing_hashes]
+                        if not kept_hashed_rows:
+                            logger.warning(
+                                f"All hashed videos for dataset '{ds_info.name}' "
+                                f"are missing on server; nothing to upload."
+                            )
+                        hashed_rows = kept_hashed_rows
+
+                    hashes = [r["hash"] for r in hashed_rows]
+                    names = [r["name"] for r in hashed_rows]
+                    metas: List[dict] = []
+                    for r in hashed_rows:
+                        meta_dict: dict = {}
+                        if r.get("meta"):
+                            try:
+                                meta_dict.update(json.loads(r["meta"]))
+                            except Exception:
+                                pass
+                        metas.append(meta_dict)
+
+                    if hashes:
+                        new_infos = api.video.upload_hashes(
+                            dataset_id,
+                            names=names,
+                            hashes=hashes,
+                            metas=metas,
+                            progress_cb=ds_progress,
+                        )
+                        for row, new_info in zip(hashed_rows, new_infos):
+                            src_to_new_video[row["src_video_id"]] = new_info
+                            if with_custom_data and row.get("custom_data"):
+                                try:
+                                    cd = json.loads(row["custom_data"])
+                                    api.video.update_custom_data(new_info.id, cd)
+                                except Exception:
+                                    logger.warning(
+                                        f"Failed to restore custom_data for video '{new_info.name}'"
+                                    )
+
+                if link_rows:
+                    links = [r["link"] for r in link_rows]
+                    names = [r["name"] for r in link_rows]
+                    metas: List[dict] = []
+                    for r in link_rows:
+                        meta_dict: dict = {}
+                        if r.get("meta"):
+                            try:
+                                meta_dict.update(json.loads(r["meta"]))
+                            except Exception:
+                                pass
+                        metas.append(meta_dict)
+
+                    new_infos_links = api.video.upload_links(
+                        dataset_id,
+                        links=links,
+                        names=names,
+                        metas=metas,
+                        progress_cb=ds_progress,
+                    )
+                    for row, new_info in zip(link_rows, new_infos_links):
+                        src_to_new_video[row["src_video_id"]] = new_info
+                        if with_custom_data and row.get("custom_data"):
+                            try:
+                                cd = json.loads(row["custom_data"])
+                                api.video.update_custom_data(new_info.id, cd)
+                            except Exception:
+                                logger.warning(
+                                    f"Failed to restore custom_data for video '{new_info.name}'"
+                                )
+
+                if ds_progress is not None:
+                    ds_progress(len(rows))
+
+            # Annotations
+            ann_temp_dir = os.path.join(tmp_root, "anns")
+            mkdir(ann_temp_dir)
+
+            anns_by_dataset: Dict[int, List[Tuple[int, str]]] = {}
+            for row in v_rows:
+                src_vid = row["src_video_id"]
+                new_info = src_to_new_video.get(src_vid)
+                if new_info is None:
+                    continue
+                src_ds_id = row["src_dataset_id"]
+                anns_by_dataset.setdefault(src_ds_id, []).append((new_info.id, row["ann_json"]))
+
+            for src_ds_id, items in anns_by_dataset.items():
+                ds_info = dataset_mapping.get(src_ds_id)
+                if ds_info is None:
+                    continue
+
+                video_ids: List[int] = []
+                ann_paths: List[str] = []
+
+                for vid_id, ann_json_str in items:
+                    video_ids.append(vid_id)
+                    ann_path = os.path.join(ann_temp_dir, f"{vid_id}.json")
+                    try:
+                        parsed = json.loads(ann_json_str)
+                    except Exception:
+                        logger.warning(
+                            f"Failed to parse ann_json for restored video id={vid_id}, "
+                            f"skipping its annotation."
+                        )
+                        continue
+                    dump_json_file(parsed, ann_path)
+                    ann_paths.append(ann_path)
+
+                if not video_ids:
+                    continue
+
+                anns_progress = progress_cb
+                if log_progress and progress_cb is None:
+                    anns_progress = tqdm_sly(
+                        desc=f"Uploading annotations to '{ds_info.name}'",
+                        total=len(video_ids),
+                        leave=False,
+                    )
+                for vid_id, ann_path in zip(video_ids, ann_paths):
+                    try:
+                        ann_json = load_json_file(ann_path)
+                        ann = VideoAnnotation.from_json(
+                            ann_json,
+                            new_meta,
+                            key_id_map=KeyIdMap(),
+                        )
+                    except Exception as e:
+                        logger.warning(
+                            f"Failed to deserialize annotation for restored video id={vid_id}: {e}"
+                        )
+                        continue
+
+                    api.video.annotation.append(vid_id, ann)
+                    if anns_progress is not None:
+                        anns_progress(1)
+
+            return project
+
+        finally:
+            try:
+                clean_dir(tmp_root)
+            except Exception:
+                pass
+
+    # --------------------- #
+
 
 def download_video_project(
     api: Api,
@@ -1492,11 +2176,18 @@ def upload_video_project(
     if project_name is None:
         project_name = project_fs.name
 
+    is_multiview = False
+    try:
+        if project_fs.meta.labeling_interface == LabelingInterface.MULTIVIEW:
+            is_multiview = True
+    except AttributeError:
+        is_multiview = False
+
     if api.project.exists(workspace_id, project_name):
         project_name = api.project.get_free_name(workspace_id, project_name)
 
     project = api.project.create(workspace_id, project_name, ProjectType.VIDEOS)
-    api.project.update_meta(project.id, project_fs.meta.to_json())
+    project_meta = api.project.update_meta(project.id, project_fs.meta.to_json())
 
     if progress_cb is not None:
         log_progress = False
@@ -1564,7 +2255,14 @@ def upload_video_project(
                 leave=False,
             )
         try:
-            api.video.annotation.upload_paths(video_ids, ann_paths, project_fs.meta, anns_progress)
+            if is_multiview:
+                api.video.annotation.upload_paths_multiview(
+                    video_ids, ann_paths, project_meta, anns_progress
+                )
+            else:
+                api.video.annotation.upload_paths(
+                    video_ids, ann_paths, project_fs.meta, anns_progress
+                )
         except Exception as e:
             logger.info(
                 "INFO FOR DEBUGGING",
@@ -1584,7 +2282,7 @@ async def download_video_project_async(
     api: Api,
     project_id: int,
     dest_dir: str,
-    semaphore: Optional[asyncio.Semaphore] = None,
+    semaphore: Optional[Union[asyncio.Semaphore, int]] = None,
     dataset_ids: Optional[List[int]] = None,
     download_videos: Optional[bool] = True,
     save_video_info: Optional[bool] = False,
@@ -1604,7 +2302,7 @@ async def download_video_project_async(
     :param dest_dir: Destination path to local directory.
     :type dest_dir: str
     :param semaphore: Semaphore to limit the number of simultaneous downloads of items.
-    :type semaphore: asyncio.Semaphore, optional
+    :type semaphore: asyncio.Semaphore or int, optional
     :param dataset_ids: Specified list of Dataset IDs which will be downloaded. Datasets could be downloaded from different projects but with the same data type.
     :type dataset_ids: list(int), optional
     :param download_videos: Include videos in the download.
@@ -1643,6 +2341,8 @@ async def download_video_project_async(
     """
     if semaphore is None:
         semaphore = api.get_default_semaphore()
+    elif isinstance(semaphore, int):
+        semaphore = asyncio.Semaphore(semaphore)
 
     key_id_map = KeyIdMap()
 
@@ -1706,7 +2406,6 @@ async def download_video_project_async(
 
     project_fs.set_key_id_map(key_id_map)
 
-
 def _log_warning(
     video: VideoInfo,
     video_file_path: Optional[str] = None,
@@ -1734,7 +2433,7 @@ def _log_warning(
 async def _download_project_item_async(
     api: Api,
     video: VideoInfo,
-    semaphore: asyncio.Semaphore,
+    semaphore: Union[asyncio.Semaphore, int],
     dataset: DatasetInfo,
     dest_dir: str,
     project_fs: Project,
@@ -1749,6 +2448,9 @@ async def _download_project_item_async(
     This function downloads a video item from the project in Supervisely platform asynchronously.
     """
 
+    if isinstance(semaphore, int):
+        semaphore = asyncio.Semaphore(semaphore)
+
     try:
         ann_json = await api.video.annotation.download_async(video.id, video, semaphore=semaphore)
         ann_json = ann_json[0]