Scene Marker Operations

Operations for managing scene markers (bookmarks/chapters).

Bases: StashClientProtocol

Mixin for marker-related client methods.

Functions

find_marker async

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 async

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 async

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 async

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 async

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 async

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 async

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 async

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

Bulk update scene markers.

Parameters:

Name	Type	Description	Default
input_data	BulkSceneMarkerUpdateInput | dict[str, Any]	BulkSceneMarkerUpdateInput object or dictionary containing: - ids: List of scene marker IDs to update (optional) - And any fields to update (e.g., primary_tag_id, tag_ids, etc.)	required

Returns:

Type	Description
list[SceneMarker]	List of updated SceneMarker objects

Examples:

Update multiple markers' primary tag:

markers = await client.bulk_scene_marker_update({
    "ids": ["1", "2", "3"],
    "primary_tag_id": "tag123"
})

Add tags to multiple markers:

from stash_graphql_client.types import BulkSceneMarkerUpdateInput, BulkUpdateIds

input_data = BulkSceneMarkerUpdateInput(
    ids=["1", "2", "3"],
    tag_ids=BulkUpdateIds(ids=["tag1", "tag2"], mode="ADD")
)
markers = await client.bulk_scene_marker_update(input_data)

marker_wall async

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 async

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")