Skip to content

VideoSegmentResource

Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/dsp_base_resources.py 
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
@dataclass
class VideoSegmentResource:
    res_id: str
    label: str
    segment_of: str
    segment_bounds: SegmentBounds
    title: str | None = None
    comments: list[str] = field(default_factory=list)
    descriptions: list[str] = field(default_factory=list)
    keywords: list[str] = field(default_factory=list)
    relates_to: list[str] = field(default_factory=list)
    permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS
    migration_metadata: MigrationMetadata | None = None

    @staticmethod
    def create_new(
        res_id: str,
        label: str,
        segment_of: str,
        segment_start: float,
        segment_end: float,
        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
    ) -> VideoSegmentResource:
        """
        Creates a new video segment resource, i.e. a time span of a MovingImageRepresentation.

        [See XML documentation for details](https://docs.dasch.swiss/latest/DSP-TOOLS/file-formats/xml-data-file/#video-segment-and-audio-segment)

        Args:
            res_id: ID of this video segment resource
            label: label of this video segment resource
            segment_of: ID of the video resource that this segment refers to (cardinality 1)
            segment_start: start of the segment in seconds (cardinality 1)
            segment_end: end of the segment in seconds (cardinality 1)
            permissions: permissions of this resource

        Returns:
            A video segment resource
        """
        return VideoSegmentResource(
            res_id=res_id,
            label=label,
            segment_of=segment_of,
            segment_bounds=SegmentBounds(segment_start, segment_end, res_id),
            permissions=permissions,
        )

    def add_title(self, title: str) -> VideoSegmentResource:
        """
        Add a title to the resource.

        Args:
            title: text

        Returns:
            The original resource, with the added title
        """
        if self.title:
            _warn_value_exists(old_value=self.title, new_value=title, value_field="title", res_id=self.res_id)
        self.title = title
        return self

    def add_title_optional(self, title: Any) -> VideoSegmentResource:
        """
        If the value is not empty, add it as title, otherwise return the resource unchanged.

        Args:
            title: text or empty value

        Returns:
            The original resource, with the added title
        """
        if is_nonempty_value(title):
            if self.title:
                _warn_value_exists(old_value=self.title, new_value=title, value_field="title", res_id=self.res_id)
            self.title = title
        return self

    def add_comment(self, comment: str) -> VideoSegmentResource:
        """
        Add a comment to the resource

        Args:
            comment: text

        Returns:
            The original resource, with the added comment
        """
        self.comments.append(comment)
        return self

    def add_comment_multiple(self, comments: Collection[str]) -> VideoSegmentResource:
        """
        Add several comments to the resource

        Args:
            comments: list of texts

        Returns:
            The original resource, with the added comments
        """
        self.comments.extend(comments)
        return self

    def add_comment_optional(self, comment: Any) -> VideoSegmentResource:
        """
        If the value is not empty, add it as comment, otherwise return the resource unchanged.

        Args:
            comment: text or empty value

        Returns:
            The original resource, with the added comment
        """
        if is_nonempty_value(comment):
            self.comments.append(comment)
        return self

    def add_description(self, description: str) -> VideoSegmentResource:
        """
        Add a description to the resource

        Args:
            description: text

        Returns:
            The original resource, with the added description
        """
        self.descriptions.append(description)
        return self

    def add_description_multiple(self, descriptions: Collection[str]) -> VideoSegmentResource:
        """
        Add several descriptions to the resource

        Args:
            descriptions: list of texts

        Returns:
            The original resource, with the added descriptions
        """
        self.descriptions.extend(descriptions)
        return self

    def add_description_optional(self, description: Any) -> VideoSegmentResource:
        """
        If the value is not empty, add it as description, otherwise return the resource unchanged.

        Args:
            description: text or empty value

        Returns:
            The original resource, with the added description
        """
        if is_nonempty_value(description):
            self.descriptions.append(description)
        return self

    def add_keyword(self, keyword: str) -> VideoSegmentResource:
        """
        Add a keyword to the resource

        Args:
            keyword: text

        Returns:
            The original resource, with the added keyword
        """
        self.keywords.append(keyword)
        return self

    def add_keyword_multiple(self, keywords: Collection[str]) -> VideoSegmentResource:
        """
        Add several keywords to the resource

        Args:
            keywords: list of texts

        Returns:
            The original resource, with the added keywords
        """
        self.keywords.extend(keywords)
        return self

    def add_keyword_optional(self, keyword: Any) -> VideoSegmentResource:
        """
        If the value is not empty, add it as keyword, otherwise return the resource unchanged.

        Args:
            keyword: text or empty value

        Returns:
            The original resource, with the added keyword
        """
        if is_nonempty_value(keyword):
            self.keywords.append(keyword)
        return self

    def add_relates_to(self, relates_to: str) -> VideoSegmentResource:
        """
        Add a link to a related resource

        Args:
            relates_to: ID of the related resource

        Returns:
            The original resource, with the added related resource
        """
        self.relates_to.append(relates_to)
        return self

    def add_relates_to_multiple(self, relates_to: Collection[str]) -> VideoSegmentResource:
        """
        Add several links to related resources

        Args:
            relates_to: list of IDs of the related resources

        Returns:
            The original resource, with the added related resources
        """
        self.relates_to.extend(relates_to)
        return self

    def add_relates_to_optional(self, relates_to: Any) -> VideoSegmentResource:
        """
        If the value is not empty, add it as related resource, otherwise return the resource unchanged.

        Args:
            relates_to: ID or the related resource or empty value

        Returns:
            The original resource, with the added related resources
        """
        if is_nonempty_value(relates_to):
            self.relates_to.append(relates_to)
        return self

    def add_migration_metadata(
        self, creation_date: str | None, iri: str | None = None, ark: str | None = None
    ) -> VideoSegmentResource:
        """
        Add metadata from a SALSAH migration.

        Args:
            creation_date: creation date of the resource in SALSAH
            iri: Original IRI in SALSAH
            ark: Original ARK in SALSAH

        Raises:
            InputError: if metadata already exists

        Returns:
            The original resource, with the added metadata
        """
        if self.migration_metadata:
            raise InputError(
                f"The resource with the ID '{self.res_id}' already contains migration metadata, "
                f"no new data can be added."
            )
        self.migration_metadata = MigrationMetadata(creation_date=creation_date, iri=iri, ark=ark, res_id=self.res_id)
        return self

    def serialise(self) -> etree._Element:
        self._check_for_and_convert_unexpected_input()
        res_ele = self._serialise_resource_element()
        res_ele.extend(_serialise_segment_children(self))
        return res_ele

    def _check_for_and_convert_unexpected_input(self) -> None:
        self.comments = _transform_unexpected_input(self.comments, "comments", self.res_id)
        self.descriptions = _transform_unexpected_input(self.descriptions, "descriptions", self.res_id)
        self.keywords = _transform_unexpected_input(self.keywords, "keywords", self.res_id)
        self.relates_to = _transform_unexpected_input(self.relates_to, "relates_to", self.res_id)
        _validate_segment(self)

    def _serialise_resource_element(self) -> etree._Element:
        attribs = {"label": self.label, "id": self.res_id}
        if self.permissions != Permissions.PROJECT_SPECIFIC_PERMISSIONS:
            attribs["permissions"] = self.permissions.value
        return etree.Element(f"{DASCH_SCHEMA}video-segment", attrib=attribs, nsmap=XML_NAMESPACE_MAP)

create_new

Creates a new video segment resource, i.e. a time span of a MovingImageRepresentation.

See XML documentation for details

Parameters:

Name Type Description Default
res_id str

ID of this video segment resource

 required
label str

label of this video segment resource

 required
segment_of str

ID of the video resource that this segment refers to (cardinality 1)

 required
segment_start float

start of the segment in seconds (cardinality 1)

 required
segment_end float

end of the segment in seconds (cardinality 1)

 required
permissions Permissions

permissions of this resource

 PROJECT_SPECIFIC_PERMISSIONS

Returns:

Type Description
VideoSegmentResource

A video segment resource
Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/dsp_base_resources.py 
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
@staticmethod
def create_new(
    res_id: str,
    label: str,
    segment_of: str,
    segment_start: float,
    segment_end: float,
    permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
) -> VideoSegmentResource:
    """
    Creates a new video segment resource, i.e. a time span of a MovingImageRepresentation.

    [See XML documentation for details](https://docs.dasch.swiss/latest/DSP-TOOLS/file-formats/xml-data-file/#video-segment-and-audio-segment)

    Args:
        res_id: ID of this video segment resource
        label: label of this video segment resource
        segment_of: ID of the video resource that this segment refers to (cardinality 1)
        segment_start: start of the segment in seconds (cardinality 1)
        segment_end: end of the segment in seconds (cardinality 1)
        permissions: permissions of this resource

    Returns:
        A video segment resource
    """
    return VideoSegmentResource(
        res_id=res_id,
        label=label,
        segment_of=segment_of,
        segment_bounds=SegmentBounds(segment_start, segment_end, res_id),
        permissions=permissions,
    )

add_title

Add a title to the resource.

Parameters:

Name Type Description Default
title str

text

 required

Returns:

Type Description
VideoSegmentResource

The original resource, with the added title
Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/dsp_base_resources.py 
517
518
519
520
521
522
523
524
525
526
527
528
529
530
def add_title(self, title: str) -> VideoSegmentResource:
    """
    Add a title to the resource.

    Args:
        title: text

    Returns:
        The original resource, with the added title
    """
    if self.title:
        _warn_value_exists(old_value=self.title, new_value=title, value_field="title", res_id=self.res_id)
    self.title = title
    return self

add_title_optional

If the value is not empty, add it as title, otherwise return the resource unchanged.

Parameters:

Name Type Description Default
title Any

text or empty value

 required

Returns:

Type Description
VideoSegmentResource

The original resource, with the added title
Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/dsp_base_resources.py 
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
def add_title_optional(self, title: Any) -> VideoSegmentResource:
    """
    If the value is not empty, add it as title, otherwise return the resource unchanged.

    Args:
        title: text or empty value

    Returns:
        The original resource, with the added title
    """
    if is_nonempty_value(title):
        if self.title:
            _warn_value_exists(old_value=self.title, new_value=title, value_field="title", res_id=self.res_id)
        self.title = title
    return self

add_comment

Add a comment to the resource

Parameters:

Name Type Description Default
comment str

text

 required

Returns:

Type Description
VideoSegmentResource

The original resource, with the added comment
Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/dsp_base_resources.py 
548
549
550
551
552
553
554
555
556
557
558
559
def add_comment(self, comment: str) -> VideoSegmentResource:
    """
    Add a comment to the resource

    Args:
        comment: text

    Returns:
        The original resource, with the added comment
    """
    self.comments.append(comment)
    return self

add_comment_multiple

Add several comments to the resource

Parameters:

Name Type Description Default
comments Collection[str]

list of texts

 required

Returns:

Type Description
VideoSegmentResource

The original resource, with the added comments
Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/dsp_base_resources.py 
561
562
563
564
565
566
567
568
569
570
571
572
def add_comment_multiple(self, comments: Collection[str]) -> VideoSegmentResource:
    """
    Add several comments to the resource

    Args:
        comments: list of texts

    Returns:
        The original resource, with the added comments
    """
    self.comments.extend(comments)
    return self

add_comment_optional

If the value is not empty, add it as comment, otherwise return the resource unchanged.

Parameters:

Name Type Description Default
comment Any

text or empty value

 required

Returns:

Type Description
VideoSegmentResource

The original resource, with the added comment
Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/dsp_base_resources.py 
574
575
576
577
578
579
580
581
582
583
584
585
586
def add_comment_optional(self, comment: Any) -> VideoSegmentResource:
    """
    If the value is not empty, add it as comment, otherwise return the resource unchanged.

    Args:
        comment: text or empty value

    Returns:
        The original resource, with the added comment
    """
    if is_nonempty_value(comment):
        self.comments.append(comment)
    return self

add_description

Add a description to the resource

Parameters:

Name Type Description Default
description str

text

 required

Returns:

Type Description
VideoSegmentResource

The original resource, with the added description
Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/dsp_base_resources.py 
588
589
590
591
592
593
594
595
596
597
598
599
def add_description(self, description: str) -> VideoSegmentResource:
    """
    Add a description to the resource

    Args:
        description: text

    Returns:
        The original resource, with the added description
    """
    self.descriptions.append(description)
    return self

add_description_multiple

Add several descriptions to the resource

Parameters:

Name Type Description Default
descriptions Collection[str]

list of texts

 required

Returns:

Type Description
VideoSegmentResource

The original resource, with the added descriptions
Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/dsp_base_resources.py 
601
602
603
604
605
606
607
608
609
610
611
612
def add_description_multiple(self, descriptions: Collection[str]) -> VideoSegmentResource:
    """
    Add several descriptions to the resource

    Args:
        descriptions: list of texts

    Returns:
        The original resource, with the added descriptions
    """
    self.descriptions.extend(descriptions)
    return self

add_description_optional

If the value is not empty, add it as description, otherwise return the resource unchanged.

Parameters:

Name Type Description Default
description Any

text or empty value

 required

Returns:

Type Description
VideoSegmentResource

The original resource, with the added description
Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/dsp_base_resources.py 
614
615
616
617
618
619
620
621
622
623
624
625
626
def add_description_optional(self, description: Any) -> VideoSegmentResource:
    """
    If the value is not empty, add it as description, otherwise return the resource unchanged.

    Args:
        description: text or empty value

    Returns:
        The original resource, with the added description
    """
    if is_nonempty_value(description):
        self.descriptions.append(description)
    return self

add_keyword

Add a keyword to the resource

Parameters:

Name Type Description Default
keyword str

text

 required

Returns:

Type Description
VideoSegmentResource

The original resource, with the added keyword
Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/dsp_base_resources.py 
628
629
630
631
632
633
634
635
636
637
638
639
def add_keyword(self, keyword: str) -> VideoSegmentResource:
    """
    Add a keyword to the resource

    Args:
        keyword: text

    Returns:
        The original resource, with the added keyword
    """
    self.keywords.append(keyword)
    return self

add_keyword_multiple

Add several keywords to the resource

Parameters:

Name Type Description Default
keywords Collection[str]

list of texts

 required

Returns:

Type Description
VideoSegmentResource

The original resource, with the added keywords
Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/dsp_base_resources.py 
641
642
643
644
645
646
647
648
649
650
651
652
def add_keyword_multiple(self, keywords: Collection[str]) -> VideoSegmentResource:
    """
    Add several keywords to the resource

    Args:
        keywords: list of texts

    Returns:
        The original resource, with the added keywords
    """
    self.keywords.extend(keywords)
    return self

add_keyword_optional

If the value is not empty, add it as keyword, otherwise return the resource unchanged.

Parameters:

Name Type Description Default
keyword Any

text or empty value

 required

Returns:

Type Description
VideoSegmentResource

The original resource, with the added keyword
Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/dsp_base_resources.py 
654
655
656
657
658
659
660
661
662
663
664
665
666
def add_keyword_optional(self, keyword: Any) -> VideoSegmentResource:
    """
    If the value is not empty, add it as keyword, otherwise return the resource unchanged.

    Args:
        keyword: text or empty value

    Returns:
        The original resource, with the added keyword
    """
    if is_nonempty_value(keyword):
        self.keywords.append(keyword)
    return self

add_relates_to

Add a link to a related resource

Parameters:

Name Type Description Default
relates_to str

ID of the related resource

 required

Returns:

Type Description
VideoSegmentResource

The original resource, with the added related resource
Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/dsp_base_resources.py 
668
669
670
671
672
673
674
675
676
677
678
679
def add_relates_to(self, relates_to: str) -> VideoSegmentResource:
    """
    Add a link to a related resource

    Args:
        relates_to: ID of the related resource

    Returns:
        The original resource, with the added related resource
    """
    self.relates_to.append(relates_to)
    return self

add_relates_to_multiple

Add several links to related resources

Parameters:

Name Type Description Default
relates_to Collection[str]

list of IDs of the related resources

 required

Returns:

Type Description
VideoSegmentResource

The original resource, with the added related resources
Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/dsp_base_resources.py 
681
682
683
684
685
686
687
688
689
690
691
692
def add_relates_to_multiple(self, relates_to: Collection[str]) -> VideoSegmentResource:
    """
    Add several links to related resources

    Args:
        relates_to: list of IDs of the related resources

    Returns:
        The original resource, with the added related resources
    """
    self.relates_to.extend(relates_to)
    return self

add_relates_to_optional

If the value is not empty, add it as related resource, otherwise return the resource unchanged.

Parameters:

Name Type Description Default
relates_to Any

ID or the related resource or empty value

 required

Returns:

Type Description
VideoSegmentResource

The original resource, with the added related resources
Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/dsp_base_resources.py 
694
695
696
697
698
699
700
701
702
703
704
705
706
def add_relates_to_optional(self, relates_to: Any) -> VideoSegmentResource:
    """
    If the value is not empty, add it as related resource, otherwise return the resource unchanged.

    Args:
        relates_to: ID or the related resource or empty value

    Returns:
        The original resource, with the added related resources
    """
    if is_nonempty_value(relates_to):
        self.relates_to.append(relates_to)
    return self

add_migration_metadata

Add metadata from a SALSAH migration.

Parameters:

Name Type Description Default
creation_date str | None

creation date of the resource in SALSAH

 required
iri str | None

Original IRI in SALSAH

 None
ark str | None

Original ARK in SALSAH

 None

Returns:

Type Description
VideoSegmentResource

The original resource, with the added metadata
Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/dsp_base_resources.py 
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
def add_migration_metadata(
    self, creation_date: str | None, iri: str | None = None, ark: str | None = None
) -> VideoSegmentResource:
    """
    Add metadata from a SALSAH migration.

    Args:
        creation_date: creation date of the resource in SALSAH
        iri: Original IRI in SALSAH
        ark: Original ARK in SALSAH

    Raises:
        InputError: if metadata already exists

    Returns:
        The original resource, with the added metadata
    """
    if self.migration_metadata:
        raise InputError(
            f"The resource with the ID '{self.res_id}' already contains migration metadata, "
            f"no new data can be added."
        )
    self.migration_metadata = MigrationMetadata(creation_date=creation_date, iri=iri, ark=ark, res_id=self.res_id)
    return self