AudioSegmentResource

Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/dsp_base_resources.py

@dataclass
class AudioSegmentResource:
    res_id: str
    label: str
    segment_bounds: SegmentBounds
    values: list[Value]
    permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS
    migration_metadata: MigrationMetadata | None = None

    def __post_init__(self) -> None:
        _check_strings(string_to_check=self.res_id, res_id=self.res_id, field_name="Resource ID")
        check_and_warn_potentially_empty_string(value=self.label, res_id=self.res_id, expected="string", field="label")

    @staticmethod
    def create_new(
        res_id: str,
        label: str,
        segment_of: str,
        segment_start: float | int | str,
        segment_end: float | int | str,
        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
    ) -> AudioSegmentResource:
        """
        Creates a new audio segment resource, i.e. a time span of an AudioRepresentation.

        [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 audio segment resource
            label: label of this audio segment resource
            segment_of: ID of the audio 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:
            An audio segment resource
        """
        segment_of_val = LinkValue.new(
            value=segment_of, prop_name="isSegmentOf", permissions=permissions, comment=None, resource_id=res_id
        )
        return AudioSegmentResource(
            res_id=res_id,
            label=label,
            segment_bounds=SegmentBounds(segment_start, segment_end, permissions, res_id),
            values=[segment_of_val],
            permissions=permissions,
        )

    def add_title(
        self,
        title: str,
        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
        comment: str | None = None,
    ) -> AudioSegmentResource:
        """
        Add a title to the resource.

        Args:
            title: text
            permissions: permissions of the value
            comment: comments on the value

        Returns:
            The original resource, with the added title

        Examples:
            ```python
            audio_segment = audio_segment.add_title("segment title")
            ```
        """
        existing_title = [x for x in self.values if x.prop_name == "hasTitle"]
        if any(existing_title):
            _warn_value_exists(
                old_value=existing_title.pop(0).value, new_value=title, value_field="title", res_id=self.res_id
            )
        self.values.append(
            SimpleText.new(
                value=title,
                prop_name="hasTitle",
                permissions=permissions,
                comment=comment,
                resource_id=self.res_id,
            )
        )
        return self

    def add_title_optional(
        self,
        title: Any,
        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
        comment: str | None = None,
    ) -> AudioSegmentResource:
        """
        If the value is not empty, add it as title, otherwise return the resource unchanged.

        Args:
            title: text or empty value
            permissions: permissions of the value
            comment: comments on the value

        Returns:
            The original resource, with the added title

        Examples:
            ```python
            audio_segment = audio_segment.add_title("segment title")
            ```

            ```python
            audio_segment = audio_segment.add_title(None)
            ```
        """
        if is_nonempty_value(title):
            self.add_title(title, permissions, comment)
        return self

    def add_comment(
        self,
        text: str,
        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
        comment: str | None = None,
        newline_replacement: NewlineReplacement = NewlineReplacement.LINEBREAK,
    ) -> AudioSegmentResource:
        """
        Add a comment to the resource

        Args:
            text: text of the comment
            permissions: optional permissions of this value
            comment: optional comment about this comment
            newline_replacement: options how to deal with `\\n` inside the text value. Default: replace with `<br/>`

        Returns:
            The original resource, with the added comment

        Examples:
            ```python
            audio_segment = audio_segment.add_comment("comment text")
            ```
        """
        self.values.append(
            Richtext.new(
                value=text,
                prop_name="hasComment",
                permissions=permissions,
                comment=comment,
                resource_id=self.res_id,
                newline_replacement=newline_replacement,
            )
        )
        return self

    def add_comment_multiple(
        self,
        texts: Collection[str],
        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
        comment: str | None = None,
        newline_replacement: NewlineReplacement = NewlineReplacement.LINEBREAK,
    ) -> AudioSegmentResource:
        """
        Add several comments to the resource

        Args:
            texts: list of texts
            permissions: optional permissions of these values
            comment: optional comment about these comments
            newline_replacement: options how to deal with `\\n` inside the text value. Default: replace with `<br/>`

        Returns:
            The original resource, with the added comments

        Examples:
            ```python
            audio_segment = audio_segment.add_comment_multiple(["comment 1", "comment 2"])
            ```
        """
        vals = check_and_fix_collection_input(texts, "hasComment", self.res_id)
        for v in vals:
            self.add_comment(v, permissions, comment, newline_replacement)
        return self

    def add_comment_optional(
        self,
        text: Any,
        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
        comment: str | None = None,
        newline_replacement: NewlineReplacement = NewlineReplacement.LINEBREAK,
    ) -> AudioSegmentResource:
        """
        If the value is not empty, add it as comment, otherwise return the resource unchanged.

        Args:
            text: text of the comment (or empty value)
            permissions: optional permissions of this value
            comment: optional comment about this comment
            newline_replacement: options how to deal with `\\n` inside the text value. Default: replace with `<br/>`

        Returns:
            The original resource, with the added comment

        Examples:
            ```python
            audio_segment = audio_segment.add_comment_optional("comment text")
            ```

            ```python
            audio_segment = audio_segment.add_comment_optional(None)
            ```
        """
        if is_nonempty_value(text):
            self.add_comment(text, permissions, comment, newline_replacement)
        return self

    def add_description(
        self,
        description: str,
        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
        comment: str | None = None,
        newline_replacement: NewlineReplacement = NewlineReplacement.LINEBREAK,
    ) -> AudioSegmentResource:
        """
        Add a description to the resource

        Args:
            description: text
            permissions: optional permissions of this value
            comment: optional comment
            newline_replacement: options how to deal with `\\n` inside the text value. Default: replace with `<br/>`

        Returns:
            The original resource, with the added description

        Examples:
            ```python
            audio_segment = audio_segment.add_description("description text")
            ```
        """
        self.values.append(
            Richtext.new(
                value=description,
                prop_name="hasDescription",
                permissions=permissions,
                comment=comment,
                resource_id=self.res_id,
                newline_replacement=newline_replacement,
            )
        )
        return self

    def add_description_multiple(
        self,
        descriptions: Collection[str],
        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
        comment: str | None = None,
        newline_replacement: NewlineReplacement = NewlineReplacement.LINEBREAK,
    ) -> AudioSegmentResource:
        """
        Add several descriptions to the resource

        Args:
            descriptions: list of texts
            permissions: optional permissions of these values
            comment: optional comment
            newline_replacement: options how to deal with `\\n` inside the text value. Default: replace with `<br/>`

        Returns:
            The original resource, with the added descriptions

        Examples:
            ```python
            audio_segment = audio_segment.add_description_multiple(["description 1", "description 2"])
            ```
        """
        vals = check_and_fix_collection_input(descriptions, "description", self.res_id)
        for v in vals:
            self.add_description(v, permissions, comment, newline_replacement)
        return self

    def add_description_optional(
        self,
        description: Any,
        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
        comment: str | None = None,
        newline_replacement: NewlineReplacement = NewlineReplacement.LINEBREAK,
    ) -> AudioSegmentResource:
        """
        If the value is not empty, add it as description, otherwise return the resource unchanged.

        Args:
            description: text or empty value
            permissions: optional permissions of this value
            comment: optional comment
            newline_replacement: options how to deal with `\\n` inside the text value. Default: replace with `<br/>`

        Returns:
            The original resource, with the added description

        Examples:
            ```python
            audio_segment = audio_segment.add_description_optional("description text")
            ```

            ```python
            audio_segment = audio_segment.add_description_optional(None)
            ```
        """
        if is_nonempty_value(description):
            self.add_description(description, permissions, comment, newline_replacement)
        return self

    def add_keyword(
        self,
        keyword: str,
        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
        comment: str | None = None,
    ) -> AudioSegmentResource:
        """
        Add a keyword to the resource

        Args:
            keyword: text
            permissions: optional permissions of this value
            comment: optional comment

        Returns:
            The original resource, with the added keyword

        Examples:
            ```python
            audio_segment = audio_segment.add_keyword("keyword")
            ```
        """
        self.values.append(
            SimpleText.new(
                value=keyword,
                prop_name="hasKeyword",
                permissions=permissions,
                comment=comment,
                resource_id=self.res_id,
            )
        )
        return self

    def add_keyword_multiple(
        self,
        keywords: Collection[str],
        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
        comment: str | None = None,
    ) -> AudioSegmentResource:
        """
        Add several keywords to the resource

        Args:
            keywords: list of texts
            permissions: optional permissions of these values
            comment: optional comment

        Returns:
            The original resource, with the added keywords

        Examples:
            ```python
            audio_segment = audio_segment.add_keyword_multiple(["keyword 1", "keyword 2"])
            ```
        """
        vals = check_and_fix_collection_input(keywords, "keywords", self.res_id)
        for v in vals:
            self.add_keyword(v, permissions, comment)
        return self

    def add_keyword_optional(
        self,
        keyword: Any,
        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
        comment: str | None = None,
    ) -> AudioSegmentResource:
        """
        If the value is not empty, add it as keyword, otherwise return the resource unchanged.

        Args:
            keyword: text or empty value
            permissions: optional permissions of this value
            comment: optional comment

        Returns:
            The original resource, with the added keyword

        Examples:
            ```python
            audio_segment = audio_segment.add_keyword_optional("keyword")
            ```

            ```python
            audio_segment = audio_segment.add_keyword_optional(None)
            ```
        """
        if is_nonempty_value(keyword):
            self.add_keyword(keyword, permissions, comment)
        return self

    def add_relates_to(
        self,
        relates_to: str,
        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
        comment: str | None = None,
    ) -> AudioSegmentResource:
        """
        Add a link to a related resource

        Args:
            relates_to: ID of the related resource
            permissions: optional permissions of this value
            comment: optional comment

        Returns:
            The original resource, with the added related resource

        Examples:
            ```python
            audio_segment = audio_segment.add_relates_to("target_resource_id")
            ```
        """
        self.values.append(
            LinkValue.new(
                value=relates_to,
                prop_name="relatesTo",
                permissions=permissions,
                comment=comment,
                resource_id=self.res_id,
            )
        )
        return self

    def add_relates_to_multiple(
        self,
        relates_to: Collection[str],
        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
        comment: str | None = None,
    ) -> AudioSegmentResource:
        """
        Add several links to related resources

        Args:
            relates_to: list of IDs of the related resources
            permissions: optional permissions of these values
            comment: optional comment

        Returns:
            The original resource, with the added related resources

        Examples:
            ```python
            audio_segment = audio_segment.add_relates_to_multiple(["target_resource_id_1", "target_resource_id_2"])
            ```
        """
        vals = check_and_fix_collection_input(relates_to, "relatesTo", self.res_id)
        for v in vals:
            self.add_relates_to(v, permissions, comment)
        return self

    def add_relates_to_optional(
        self,
        relates_to: Any,
        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
        comment: str | None = None,
    ) -> AudioSegmentResource:
        """
        If the value is not empty, add it as related resource, otherwise return the resource unchanged.

        Args:
            relates_to: ID of the related resource or empty value
            permissions: optional permissions of this value
            comment: optional comment

        Returns:
            The original resource, with the added related resources

        Examples:
            ```python
            audio_segment = audio_segment.add_relates_to_optional("target_resource_id")
            ```

            ```python
            audio_segment = audio_segment.add_relates_to_optional(None)
            ```
        """
        if is_nonempty_value(relates_to):
            self.add_relates_to(relates_to, permissions, comment)
        return self

    def add_migration_metadata(
        self, creation_date: str | None, iri: str | None = None, ark: str | None = None
    ) -> AudioSegmentResource:
        """
        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

        Examples:
            ```python
            audio_segment = audio_segment.add_migration_metadata(
                iri="http://rdfh.ch/4123/DiAmYQzQSzC7cdTo6OJMYA",
                creation_date="1999-12-31T23:59:59.9999999+01:00"
            )
            ```
        """
        if self.migration_metadata:
            msg_info = MessageInfo(
                "This resource already contains migration metadata, no new data can be added.", resource_id=self.res_id
            )
            raise_input_error(msg_info)
        self.migration_metadata = MigrationMetadata(creation_date=creation_date, iri=iri, ark=ark, res_id=self.res_id)
        return self

create_new

Creates a new audio segment resource, i.e. a time span of an AudioRepresentation.

See XML documentation for details

Parameters:

Name	Type	Description	Default
res_id	str	ID of this audio segment resource	required
label	str	label of this audio segment resource	required
segment_of	str	ID of the audio resource that this segment refers to (cardinality 1)	required
segment_start	float | int | str	start of the segment in seconds (cardinality 1)	required
segment_end	float | int | str	end of the segment in seconds (cardinality 1)	required
permissions	Permissions	permissions of this resource	PROJECT_SPECIFIC_PERMISSIONS

Returns:

Type	Description
AudioSegmentResource	An audio segment resource

Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/dsp_base_resources.py

@staticmethod
def create_new(
    res_id: str,
    label: str,
    segment_of: str,
    segment_start: float | int | str,
    segment_end: float | int | str,
    permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
) -> AudioSegmentResource:
    """
    Creates a new audio segment resource, i.e. a time span of an AudioRepresentation.

    [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 audio segment resource
        label: label of this audio segment resource
        segment_of: ID of the audio 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:
        An audio segment resource
    """
    segment_of_val = LinkValue.new(
        value=segment_of, prop_name="isSegmentOf", permissions=permissions, comment=None, resource_id=res_id
    )
    return AudioSegmentResource(
        res_id=res_id,
        label=label,
        segment_bounds=SegmentBounds(segment_start, segment_end, permissions, res_id),
        values=[segment_of_val],
        permissions=permissions,
    )

add_title

Add a title to the resource.

Parameters:

Name	Type	Description	Default
title	str	text	required
permissions	Permissions	permissions of the value	PROJECT_SPECIFIC_PERMISSIONS
comment	str | None	comments on the value	None

Returns:

Type	Description
AudioSegmentResource	The original resource, with the added title

Examples:

audio_segment = audio_segment.add_title("segment title")

Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/dsp_base_resources.py

def add_title(
    self,
    title: str,
    permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
    comment: str | None = None,
) -> AudioSegmentResource:
    """
    Add a title to the resource.

    Args:
        title: text
        permissions: permissions of the value
        comment: comments on the value

    Returns:
        The original resource, with the added title

    Examples:
        ```python
        audio_segment = audio_segment.add_title("segment title")
        ```
    """
    existing_title = [x for x in self.values if x.prop_name == "hasTitle"]
    if any(existing_title):
        _warn_value_exists(
            old_value=existing_title.pop(0).value, new_value=title, value_field="title", res_id=self.res_id
        )
    self.values.append(
        SimpleText.new(
            value=title,
            prop_name="hasTitle",
            permissions=permissions,
            comment=comment,
            resource_id=self.res_id,
        )
    )
    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
permissions	Permissions	permissions of the value	PROJECT_SPECIFIC_PERMISSIONS
comment	str | None	comments on the value	None

Returns:

Type	Description
AudioSegmentResource	The original resource, with the added title

Examples:

audio_segment = audio_segment.add_title("segment title")

audio_segment = audio_segment.add_title(None)

Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/dsp_base_resources.py

def add_title_optional(
    self,
    title: Any,
    permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
    comment: str | None = None,
) -> AudioSegmentResource:
    """
    If the value is not empty, add it as title, otherwise return the resource unchanged.

    Args:
        title: text or empty value
        permissions: permissions of the value
        comment: comments on the value

    Returns:
        The original resource, with the added title

    Examples:
        ```python
        audio_segment = audio_segment.add_title("segment title")
        ```

        ```python
        audio_segment = audio_segment.add_title(None)
        ```
    """
    if is_nonempty_value(title):
        self.add_title(title, permissions, comment)
    return self

add_comment

Add a comment to the resource

Parameters:

Name	Type	Description	Default
text	str	text of the comment	required
permissions	Permissions	optional permissions of this value	PROJECT_SPECIFIC_PERMISSIONS
comment	str | None	optional comment about this comment	None
newline_replacement	NewlineReplacement	options how to deal with \n inside the text value. Default: replace with <br/>	LINEBREAK

Returns:

Type	Description
AudioSegmentResource	The original resource, with the added comment

Examples:

audio_segment = audio_segment.add_comment("comment text")

Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/dsp_base_resources.py

def add_comment(
    self,
    text: str,
    permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
    comment: str | None = None,
    newline_replacement: NewlineReplacement = NewlineReplacement.LINEBREAK,
) -> AudioSegmentResource:
    """
    Add a comment to the resource

    Args:
        text: text of the comment
        permissions: optional permissions of this value
        comment: optional comment about this comment
        newline_replacement: options how to deal with `\\n` inside the text value. Default: replace with `<br/>`

    Returns:
        The original resource, with the added comment

    Examples:
        ```python
        audio_segment = audio_segment.add_comment("comment text")
        ```
    """
    self.values.append(
        Richtext.new(
            value=text,
            prop_name="hasComment",
            permissions=permissions,
            comment=comment,
            resource_id=self.res_id,
            newline_replacement=newline_replacement,
        )
    )
    return self

add_comment_multiple

Add several comments to the resource

Parameters:

Name	Type	Description	Default
texts	Collection[str]	list of texts	required
permissions	Permissions	optional permissions of these values	PROJECT_SPECIFIC_PERMISSIONS
comment	str | None	optional comment about these comments	None
newline_replacement	NewlineReplacement	options how to deal with \n inside the text value. Default: replace with <br/>	LINEBREAK

Returns:

Type	Description
AudioSegmentResource	The original resource, with the added comments

Examples:

audio_segment = audio_segment.add_comment_multiple(["comment 1", "comment 2"])

Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/dsp_base_resources.py

def add_comment_multiple(
    self,
    texts: Collection[str],
    permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
    comment: str | None = None,
    newline_replacement: NewlineReplacement = NewlineReplacement.LINEBREAK,
) -> AudioSegmentResource:
    """
    Add several comments to the resource

    Args:
        texts: list of texts
        permissions: optional permissions of these values
        comment: optional comment about these comments
        newline_replacement: options how to deal with `\\n` inside the text value. Default: replace with `<br/>`

    Returns:
        The original resource, with the added comments

    Examples:
        ```python
        audio_segment = audio_segment.add_comment_multiple(["comment 1", "comment 2"])
        ```
    """
    vals = check_and_fix_collection_input(texts, "hasComment", self.res_id)
    for v in vals:
        self.add_comment(v, permissions, comment, newline_replacement)
    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
text	Any	text of the comment (or empty value)	required
permissions	Permissions	optional permissions of this value	PROJECT_SPECIFIC_PERMISSIONS
comment	str | None	optional comment about this comment	None
newline_replacement	NewlineReplacement	options how to deal with \n inside the text value. Default: replace with <br/>	LINEBREAK

Returns:

Type	Description
AudioSegmentResource	The original resource, with the added comment

Examples:

audio_segment = audio_segment.add_comment_optional("comment text")

audio_segment = audio_segment.add_comment_optional(None)

Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/dsp_base_resources.py

def add_comment_optional(
    self,
    text: Any,
    permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
    comment: str | None = None,
    newline_replacement: NewlineReplacement = NewlineReplacement.LINEBREAK,
) -> AudioSegmentResource:
    """
    If the value is not empty, add it as comment, otherwise return the resource unchanged.

    Args:
        text: text of the comment (or empty value)
        permissions: optional permissions of this value
        comment: optional comment about this comment
        newline_replacement: options how to deal with `\\n` inside the text value. Default: replace with `<br/>`

    Returns:
        The original resource, with the added comment

    Examples:
        ```python
        audio_segment = audio_segment.add_comment_optional("comment text")
        ```

        ```python
        audio_segment = audio_segment.add_comment_optional(None)
        ```
    """
    if is_nonempty_value(text):
        self.add_comment(text, permissions, comment, newline_replacement)
    return self

add_description

Add a description to the resource

Parameters:

Name	Type	Description	Default
description	str	text	required
permissions	Permissions	optional permissions of this value	PROJECT_SPECIFIC_PERMISSIONS
comment	str | None	optional comment	None
newline_replacement	NewlineReplacement	options how to deal with \n inside the text value. Default: replace with <br/>	LINEBREAK

Returns:

Type	Description
AudioSegmentResource	The original resource, with the added description

Examples:

audio_segment = audio_segment.add_description("description text")

Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/dsp_base_resources.py

def add_description(
    self,
    description: str,
    permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
    comment: str | None = None,
    newline_replacement: NewlineReplacement = NewlineReplacement.LINEBREAK,
) -> AudioSegmentResource:
    """
    Add a description to the resource

    Args:
        description: text
        permissions: optional permissions of this value
        comment: optional comment
        newline_replacement: options how to deal with `\\n` inside the text value. Default: replace with `<br/>`

    Returns:
        The original resource, with the added description

    Examples:
        ```python
        audio_segment = audio_segment.add_description("description text")
        ```
    """
    self.values.append(
        Richtext.new(
            value=description,
            prop_name="hasDescription",
            permissions=permissions,
            comment=comment,
            resource_id=self.res_id,
            newline_replacement=newline_replacement,
        )
    )
    return self

add_description_multiple

Add several descriptions to the resource

Parameters:

Name	Type	Description	Default
descriptions	Collection[str]	list of texts	required
permissions	Permissions	optional permissions of these values	PROJECT_SPECIFIC_PERMISSIONS
comment	str | None	optional comment	None
newline_replacement	NewlineReplacement	options how to deal with \n inside the text value. Default: replace with <br/>	LINEBREAK

Returns:

Type	Description
AudioSegmentResource	The original resource, with the added descriptions

Examples:

audio_segment = audio_segment.add_description_multiple(["description 1", "description 2"])

Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/dsp_base_resources.py

def add_description_multiple(
    self,
    descriptions: Collection[str],
    permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
    comment: str | None = None,
    newline_replacement: NewlineReplacement = NewlineReplacement.LINEBREAK,
) -> AudioSegmentResource:
    """
    Add several descriptions to the resource

    Args:
        descriptions: list of texts
        permissions: optional permissions of these values
        comment: optional comment
        newline_replacement: options how to deal with `\\n` inside the text value. Default: replace with `<br/>`

    Returns:
        The original resource, with the added descriptions

    Examples:
        ```python
        audio_segment = audio_segment.add_description_multiple(["description 1", "description 2"])
        ```
    """
    vals = check_and_fix_collection_input(descriptions, "description", self.res_id)
    for v in vals:
        self.add_description(v, permissions, comment, newline_replacement)
    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
permissions	Permissions	optional permissions of this value	PROJECT_SPECIFIC_PERMISSIONS
comment	str | None	optional comment	None
newline_replacement	NewlineReplacement	options how to deal with \n inside the text value. Default: replace with <br/>	LINEBREAK

Returns:

Type	Description
AudioSegmentResource	The original resource, with the added description

Examples:

audio_segment = audio_segment.add_description_optional("description text")

audio_segment = audio_segment.add_description_optional(None)

Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/dsp_base_resources.py

def add_description_optional(
    self,
    description: Any,
    permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
    comment: str | None = None,
    newline_replacement: NewlineReplacement = NewlineReplacement.LINEBREAK,
) -> AudioSegmentResource:
    """
    If the value is not empty, add it as description, otherwise return the resource unchanged.

    Args:
        description: text or empty value
        permissions: optional permissions of this value
        comment: optional comment
        newline_replacement: options how to deal with `\\n` inside the text value. Default: replace with `<br/>`

    Returns:
        The original resource, with the added description

    Examples:
        ```python
        audio_segment = audio_segment.add_description_optional("description text")
        ```

        ```python
        audio_segment = audio_segment.add_description_optional(None)
        ```
    """
    if is_nonempty_value(description):
        self.add_description(description, permissions, comment, newline_replacement)
    return self

add_keyword

Add a keyword to the resource

Parameters:

Name	Type	Description	Default
keyword	str	text	required
permissions	Permissions	optional permissions of this value	PROJECT_SPECIFIC_PERMISSIONS
comment	str | None	optional comment	None

Returns:

Type	Description
AudioSegmentResource	The original resource, with the added keyword

Examples:

audio_segment = audio_segment.add_keyword("keyword")

Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/dsp_base_resources.py

def add_keyword(
    self,
    keyword: str,
    permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
    comment: str | None = None,
) -> AudioSegmentResource:
    """
    Add a keyword to the resource

    Args:
        keyword: text
        permissions: optional permissions of this value
        comment: optional comment

    Returns:
        The original resource, with the added keyword

    Examples:
        ```python
        audio_segment = audio_segment.add_keyword("keyword")
        ```
    """
    self.values.append(
        SimpleText.new(
            value=keyword,
            prop_name="hasKeyword",
            permissions=permissions,
            comment=comment,
            resource_id=self.res_id,
        )
    )
    return self

add_keyword_multiple

Add several keywords to the resource

Parameters:

Name	Type	Description	Default
keywords	Collection[str]	list of texts	required
permissions	Permissions	optional permissions of these values	PROJECT_SPECIFIC_PERMISSIONS
comment	str | None	optional comment	None

Returns:

Type	Description
AudioSegmentResource	The original resource, with the added keywords

Examples:

audio_segment = audio_segment.add_keyword_multiple(["keyword 1", "keyword 2"])

Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/dsp_base_resources.py

def add_keyword_multiple(
    self,
    keywords: Collection[str],
    permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
    comment: str | None = None,
) -> AudioSegmentResource:
    """
    Add several keywords to the resource

    Args:
        keywords: list of texts
        permissions: optional permissions of these values
        comment: optional comment

    Returns:
        The original resource, with the added keywords

    Examples:
        ```python
        audio_segment = audio_segment.add_keyword_multiple(["keyword 1", "keyword 2"])
        ```
    """
    vals = check_and_fix_collection_input(keywords, "keywords", self.res_id)
    for v in vals:
        self.add_keyword(v, permissions, comment)
    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
permissions	Permissions	optional permissions of this value	PROJECT_SPECIFIC_PERMISSIONS
comment	str | None	optional comment	None

Returns:

Type	Description
AudioSegmentResource	The original resource, with the added keyword

Examples:

audio_segment = audio_segment.add_keyword_optional("keyword")

audio_segment = audio_segment.add_keyword_optional(None)

Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/dsp_base_resources.py

def add_keyword_optional(
    self,
    keyword: Any,
    permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
    comment: str | None = None,
) -> AudioSegmentResource:
    """
    If the value is not empty, add it as keyword, otherwise return the resource unchanged.

    Args:
        keyword: text or empty value
        permissions: optional permissions of this value
        comment: optional comment

    Returns:
        The original resource, with the added keyword

    Examples:
        ```python
        audio_segment = audio_segment.add_keyword_optional("keyword")
        ```

        ```python
        audio_segment = audio_segment.add_keyword_optional(None)
        ```
    """
    if is_nonempty_value(keyword):
        self.add_keyword(keyword, permissions, comment)
    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
permissions	Permissions	optional permissions of this value	PROJECT_SPECIFIC_PERMISSIONS
comment	str | None	optional comment	None

Returns:

Type	Description
AudioSegmentResource	The original resource, with the added related resource

Examples:

audio_segment = audio_segment.add_relates_to("target_resource_id")

Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/dsp_base_resources.py

def add_relates_to(
    self,
    relates_to: str,
    permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
    comment: str | None = None,
) -> AudioSegmentResource:
    """
    Add a link to a related resource

    Args:
        relates_to: ID of the related resource
        permissions: optional permissions of this value
        comment: optional comment

    Returns:
        The original resource, with the added related resource

    Examples:
        ```python
        audio_segment = audio_segment.add_relates_to("target_resource_id")
        ```
    """
    self.values.append(
        LinkValue.new(
            value=relates_to,
            prop_name="relatesTo",
            permissions=permissions,
            comment=comment,
            resource_id=self.res_id,
        )
    )
    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
permissions	Permissions	optional permissions of these values	PROJECT_SPECIFIC_PERMISSIONS
comment	str | None	optional comment	None

Returns:

Type	Description
AudioSegmentResource	The original resource, with the added related resources

Examples:

audio_segment = audio_segment.add_relates_to_multiple(["target_resource_id_1", "target_resource_id_2"])

Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/dsp_base_resources.py

def add_relates_to_multiple(
    self,
    relates_to: Collection[str],
    permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
    comment: str | None = None,
) -> AudioSegmentResource:
    """
    Add several links to related resources

    Args:
        relates_to: list of IDs of the related resources
        permissions: optional permissions of these values
        comment: optional comment

    Returns:
        The original resource, with the added related resources

    Examples:
        ```python
        audio_segment = audio_segment.add_relates_to_multiple(["target_resource_id_1", "target_resource_id_2"])
        ```
    """
    vals = check_and_fix_collection_input(relates_to, "relatesTo", self.res_id)
    for v in vals:
        self.add_relates_to(v, permissions, comment)
    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 of the related resource or empty value	required
permissions	Permissions	optional permissions of this value	PROJECT_SPECIFIC_PERMISSIONS
comment	str | None	optional comment	None

Returns:

Type	Description
AudioSegmentResource	The original resource, with the added related resources

Examples:

audio_segment = audio_segment.add_relates_to_optional("target_resource_id")

audio_segment = audio_segment.add_relates_to_optional(None)

Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/dsp_base_resources.py

def add_relates_to_optional(
    self,
    relates_to: Any,
    permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
    comment: str | None = None,
) -> AudioSegmentResource:
    """
    If the value is not empty, add it as related resource, otherwise return the resource unchanged.

    Args:
        relates_to: ID of the related resource or empty value
        permissions: optional permissions of this value
        comment: optional comment

    Returns:
        The original resource, with the added related resources

    Examples:
        ```python
        audio_segment = audio_segment.add_relates_to_optional("target_resource_id")
        ```

        ```python
        audio_segment = audio_segment.add_relates_to_optional(None)
        ```
    """
    if is_nonempty_value(relates_to):
        self.add_relates_to(relates_to, permissions, comment)
    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
AudioSegmentResource	The original resource, with the added metadata

Examples:

audio_segment = audio_segment.add_migration_metadata(
    iri="http://rdfh.ch/4123/DiAmYQzQSzC7cdTo6OJMYA",
    creation_date="1999-12-31T23:59:59.9999999+01:00"
)

Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/dsp_base_resources.py

def add_migration_metadata(
    self, creation_date: str | None, iri: str | None = None, ark: str | None = None
) -> AudioSegmentResource:
    """
    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

    Examples:
        ```python
        audio_segment = audio_segment.add_migration_metadata(
            iri="http://rdfh.ch/4123/DiAmYQzQSzC7cdTo6OJMYA",
            creation_date="1999-12-31T23:59:59.9999999+01:00"
        )
        ```
    """
    if self.migration_metadata:
        msg_info = MessageInfo(
            "This resource already contains migration metadata, no new data can be added.", resource_id=self.res_id
        )
        raise_input_error(msg_info)
    self.migration_metadata = MigrationMetadata(creation_date=creation_date, iri=iri, ark=ark, res_id=self.res_id)
    return self