Scene Marker Operations - Stash Tools & Scrapers

Operations for managing scene markers (bookmarks/chapters). Bases: StashClientProtocol Mixin for marker-related client methods.

Functions

find_marker

find_marker(id: str) -> SceneMarker | None

Find a scene marker by its ID. Parameters:

Name	Type	Description	Default
`id`	`str`	The ID of the marker to find	required

Returns:

Type	Description
`SceneMarker \| None`	SceneMarker object if found, None otherwise

find_markers

find_markers(
    filter_: dict[str, Any] | None = None,
    marker_filter: dict[str, Any] | None = None,
    q: str | None = None,
) -> FindSceneMarkersResultType

Find scene markers matching the given filters. Parameters:

Name	Type	Description	Default
`filter_`	`dict[str, Any] \| None`	Optional general filter parameters: - q: str (search query) - direction: SortDirectionEnum (ASC/DESC) - page: int - per_page: int - sort: str (field to sort by)	`None`
`marker_filter`	`dict[str, Any] \| None`	Optional marker-specific filter	`None`
`q`	`str \| None`	Optional search query (alternative to filter_[“q”])	`None`

Returns:

Type	Description
`FindSceneMarkersResultType`	FindSceneMarkersResultType containing: - count: Total number of matching markers - scene_markers: List of SceneMarker objects

create_marker

create_marker(marker: SceneMarker) -> SceneMarker

Create a new scene marker in Stash. Parameters:

Name	Type	Description	Default
`marker`	`SceneMarker`	SceneMarker object with the data to create. Required fields: - title: Marker title - scene_id: ID of the scene this marker belongs to - seconds: Time in seconds where the marker occurs	required

Returns:

Type	Description
`SceneMarker`	Created SceneMarker object with ID and any server-generated fields

Raises:

Type	Description
`ValueError`	If the marker data is invalid
`TransportError`	If the request fails

scene_marker_tags

scene_marker_tags(scene_id: str) -> list[dict[str, Any]]

Get scene marker tags for a scene. Parameters:

Name	Type	Description	Default
`scene_id`	`str`	Scene ID	required

Returns:

Type	Description
`list[dict[str, Any]]`	List of scene marker tags, each containing: - tag: Tag object - scene_markers: List of SceneMarker objects

update_marker

update_marker(marker: SceneMarker) -> SceneMarker

Update an existing scene marker in Stash. Parameters:

Name	Type	Description	Default
`marker`	`SceneMarker`	SceneMarker object with updated data. Required fields: - id: Marker ID to update Any other fields that are set will be updated. Fields that are None will be ignored.	required

Returns:

Type	Description
`SceneMarker`	Updated SceneMarker object with any server-generated fields

Raises:

Type	Description
`ValueError`	If the marker data is invalid
`TransportError`	If the request fails

scene_marker_destroy

scene_marker_destroy(id: str) -> bool

Delete a scene marker. Parameters:

Name	Type	Description	Default
`id`	`str`	Scene marker ID to delete	required

Returns:

Type	Description
`bool`	True if the scene marker was successfully deleted

Raises:

Type	Description
`ValueError`	If the scene marker ID is invalid
`TransportError`	If the request fails

scene_markers_destroy

scene_markers_destroy(ids: list[str]) -> bool

Delete multiple scene markers. Parameters:

Name	Type	Description	Default
`ids`	`list[str]`	List of scene marker IDs to delete	required

Returns:

Type	Description
`bool`	True if the scene markers were successfully deleted

Raises:

Type	Description
`ValueError`	If any scene marker ID is invalid
`TransportError`	If the request fails

bulk_scene_marker_update

bulk_scene_marker_update(
    input_data: BulkSceneMarkerUpdateInput | dict[str, Any],
) -> list[SceneMarker]

bulk_scene_marker_update(
    input_data: BulkSceneMarkerUpdateInput | dict[str, Any],
    *,
    return_fields: str,
) -> list[dict[str, Any]]

bulk_scene_marker_update(
    input_data: BulkSceneMarkerUpdateInput | dict[str, Any],
    *,
    return_fields: str | None = None,
) -> list[SceneMarker] | list[dict[str, Any]]

Bulk update scene markers. Parameters:

Name	Type	Description	Default
`input_data`	`BulkSceneMarkerUpdateInput \| dict[str, Any]`	BulkSceneMarkerUpdateInput object or dictionary with fields to update.	required
`return_fields`	`str \| None`	If provided, use a minimal inline mutation requesting only these fields (e.g. `"id"`). Returns raw dicts instead of SceneMarker objects.	`None`

Returns:

Type	Description
`list[SceneMarker] \| list[dict[str, Any]]`	List of updated SceneMarker objects (default), or list of dicts when
`list[SceneMarker] \| list[dict[str, Any]]`	`return_fields` is provided.

marker_wall

marker_wall(q: str | None = None) -> list[SceneMarker]

Get marker wall - random markers for display. Parameters:

Name	Type	Description	Default
`q`	`str \| None`	Optional search query to filter markers	`None`

Returns:

Type	Description
`list[SceneMarker]`	List of SceneMarker objects selected for wall display

Examples: Get all wall markers:

markers = await client.marker_wall()
print(f"Found {len(markers)} markers for wall")

Search wall markers:

markers = await client.marker_wall(q="interview")

marker_strings

marker_strings(
    q: str | None = None, sort: str | None = None
) -> list[MarkerStringsResultType]

Get marker title strings with counts. Parameters:

Name	Type	Description	Default
`q`	`str \| None`	Optional search query to filter marker titles	`None`
`sort`	`str \| None`	Optional sort order for results	`None`

Returns:

Type	Description
`list[MarkerStringsResultType]`	List of MarkerStringsResultType objects containing: - id: Marker title ID - title: Marker title string - count: Number of markers with this title

Examples: Get all marker title strings:

strings = await client.marker_strings()
for s in strings:
    print(f"{s.title}: {s.count} markers")

Search and sort marker strings:

strings = await client.marker_strings(q="bj", sort="count")

​Functions

​find_marker

​find_markers

​create_marker

​scene_marker_tags

​update_marker

​scene_marker_destroy

​scene_markers_destroy

​bulk_scene_marker_update

​marker_wall

​marker_strings

Functions

find_marker

find_markers

create_marker

scene_marker_tags

update_marker

scene_marker_destroy

scene_markers_destroy

bulk_scene_marker_update

marker_wall

marker_strings