Scene class¶

@staticmethod
def current_scene_id() -> int:
    """Returns the current scene id (the current clip's scene)."""
    return george.tv_scene_current_id()

@staticmethod
def current_scene() -> Scene:
    """Returns the current scene of the current project."""
    return Scene(
        scene_id=george.tv_scene_current_id(),
        project=Project.current_project(),
    )

@classmethod
def new(cls, project: Project | None = None, clips: list[str] | None = None) -> Scene:
    """Creates a new scene in the provided project.

    Args:
        project: parent project
        clips: list of clip names to create alongside new scene

    Returns:
        new scene instance
    """
    project = project or Project.current_project()
    project.make_current()

    # TODO commenting this for now until george.tv_scene_create is fixed by TVP devs
    # if not clips or george.is_tvp_version_below_12():
    #     george.tv_scene_new() # noqa: ERA001
    #     new_scene = cls.current_scene() # noqa: ERA001
    #
    #     if clips and george.is_tvp_version_below_12():
    #         for clip_name in clips:
    #             new_scene.add_clip(clip_name) # noqa: ERA001
    #
    #     return new_scene # noqa: ERA001
    #
    # # if here, then we are using tvp 12 or superior
    # scene_id = george.tv_scene_create(clips) # noqa: ERA001
    # return project.get_scene(by_id=scene_id) # noqa: ERA001

    george.tv_scene_new()
    new_scene = cls.current_scene()

    if clips and george.is_tvp_version_below_12():
        for clip_name in clips:
            new_scene.add_clip(clip_name)

    return new_scene

def make_current(self) -> None:
    """Make this scene the current one."""
    if self.is_current:
        return

    # In order to select the scene, we select any child clip inside of it
    first_clip_id = george.tv_clip_enum_id(self.id, 0)
    george.tv_clip_select(first_clip_id)

def get_clip(
    self,
    by_id: int | None = None,
    by_name: str | None = None,
    by_regex: re.Pattern[str] | None = None,
) -> Clip | None:
    """Find a clip by id or by name.

    Args:
        by_id: search by id. Defaults to None.
        by_name: search by name, search is case-insensitive. Defaults to None.
        by_regex: search by name using a compiled regex, case-sensitivity is left to the regex. Defaults to None.

    Raises:
        ValueError: if none of the search arguments where provided

    Returns:
        Clip | None: the searched element or None if search was unsuccessful
    """
    return utils.get_tvp_element(self.clips, by_id=by_id, by_name=by_name, by_regex=by_regex)

@set_as_current
def add_clip(self, clip_name: str) -> Clip:
    """Adds a new clip to the scene."""
    self.make_current()
    return Clip.new(name=clip_name, project=self.project)

def duplicate(self) -> Scene:
    """Duplicate the scene and return it."""
    self.project.make_current()
    george.tv_scene_duplicate(self.id)
    dup_pos = self.position + 1
    dup_id = george.tv_scene_enum_id(dup_pos)
    return Scene(dup_id, self.project)

@george.min_version_compatible(min_version="12")
def split(self) -> list[Scene]:
    """Duplicate the scene and return it."""
    self.project.make_current()
    clip_ids = george.tv_scene_split(self.id)

    new_scenes = []
    for clip_id in clip_ids:
        clip = self.project.get_clip(by_id=clip_id)
        if not clip:
            continue

        new_scenes.append(clip.scene)
    return new_scenes

def remove(self) -> None:
    """Remove the scene and all the clips inside.

    Warning:
        All `Clip` instances will be invalid after removing the scene.
        There's no protection mechanism to prevent accessing clip data that doesn't exist anymore.
    """
    george.tv_scene_close(self._id)
    self.mark_removed()

def refresh(self) -> None:
    """Does a refresh of the object data.

    Raises:
        ValueError: if the object has been mark removed
    """
    if self._is_removed:
        raise ValueError(f"{self.__class__.__name__} has been removed!")

def mark_removed(self) -> None:
    """Marks the object as removed and is therefor not usable."""
    self._is_removed = True