Skip to content

Bookmarks

Bookmarks(api, subsonic)

Class that contains all the methods needed to interact with the bookmark endpoints in the Subsonic API.

Source code in .venv/lib/python3.11/site-packages/knuckles/_bookmarks.py 
17
18
19
def __init__(self, api: Api, subsonic: "Subsonic") -> None:
    self.api = api
    self.subsonic = subsonic

create_bookmark(song_or_video_id, position, comment=None)

Creates a new bookmark for the authenticated user.

Parameters:

Name Type Description Default
song_or_video_id str

The ID of the song or video to bookmark.

 required
position int

A position in milliseconds to be indicated with the song or video.

 required
comment str | None

A comment to be attached with the song or video.

 None

Returns:

Type Description
Bookmark

An object that contains all the info of the new created bookmark.
Source code in .venv/lib/python3.11/site-packages/knuckles/_bookmarks.py 
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
def create_bookmark(
    self, song_or_video_id: str, position: int, comment: str | None = None
) -> Bookmark:
    """Creates a new bookmark for the authenticated user.

    Args:
        song_or_video_id: The ID of the song or video to bookmark.
        position: A position in milliseconds to be indicated with the song
            or video.
        comment: A comment to be attached with the song or video.

    Returns:
        An object that contains all the info of the new created
            bookmark.
    """

    self.api.json_request(
        "createBookmark",
        {"id": song_or_video_id, "position": position, "comment": comment},
    )

    # Fake the song structure given by in the API.
    return Bookmark(
        self.subsonic, {"id": song_or_video_id}, position=position, comment=comment
    )

delete_bookmark(song_or_video_id)

Deletes a bookmark for the authenticated user.

Parameters:

Name Type Description Default
song_or_video_id str

The ID of the song or video to delete its bookmark.

 required

Returns: The Subsonic object where this method was called to allow method chaining.

Source code in .venv/lib/python3.11/site-packages/knuckles/_bookmarks.py 
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
def delete_bookmark(self, song_or_video_id: str) -> "Subsonic":
    """Deletes a bookmark for the authenticated user.

    Args:
        song_or_video_id: The ID of the song or video to delete its
            bookmark.
    Returns:
        The Subsonic object where this method was called to allow
            method chaining.
    """
    self.api.json_request("deleteBookmark", {"id": song_or_video_id})

    return self.subsonic

get_bookmark(bookmark_id)

Get all the info of a bookmark given its ID.

Parameters:

Name Type Description Default
bookmark_id str

The id of the bookmark to get.

 required

Returns:

Type Description
Bookmark | None

A object that contains all the info of the requested bookmark.
Source code in .venv/lib/python3.11/site-packages/knuckles/_bookmarks.py 
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
def get_bookmark(self, bookmark_id: str) -> Bookmark | None:
    """Get all the info of a bookmark given its ID.

    Args:
        bookmark_id: The id of the bookmark to get.

    Returns:
        A object that contains all the info of the requested bookmark.
    """

    bookmarks = self.get_bookmarks()

    for bookmark in bookmarks:
        if bookmark.song.id == bookmark_id:
            return bookmark

    return None

get_bookmarks()

Get all the bookmarks created by the authenticated user.

Returns:

Type Description
list[Bookmark]

A list containing all the bookmarks for the authenticated user.
Source code in .venv/lib/python3.11/site-packages/knuckles/_bookmarks.py 
21
22
23
24
25
26
27
28
29
30
def get_bookmarks(self) -> list[Bookmark]:
    """Get all the bookmarks created by the authenticated user.

    Returns:
        A list containing all the bookmarks for the authenticated user.
    """

    response = self.api.json_request("getBookmarks")["bookmarks"]["bookmark"]

    return [Bookmark(self.subsonic, **bookmark) for bookmark in response]

get_play_queue()

Get the play queue of the authenticated user.

Returns:

Type Description
PlayQueue

An object that contains all the info of the play queue of the user.
Source code in .venv/lib/python3.11/site-packages/knuckles/_bookmarks.py 
108
109
110
111
112
113
114
115
116
117
118
def get_play_queue(self) -> PlayQueue:
    """Get the play queue of the authenticated user.

    Returns:
        An object that contains all the info of the
            play queue of the user.
    """

    response = self.api.json_request("getPlayQueue")["playQueue"]

    return PlayQueue(self.subsonic, **response)

save_play_queue(song_ids, current_song_id=None, position=None)

Saves a new play queue for the authenticated user.

Parameters:

Name Type Description Default
song_ids list[str]

A list with all the songs to add to the queue.

 required
current_song_id str | None

The ID of the current playing song.

 None
position int | None

A position in milliseconds of where the current song playback it at.

 None

Returns:

Type Description
PlayQueue

An object that contains all the info of the new saved play queue.
Source code in .venv/lib/python3.11/site-packages/knuckles/_bookmarks.py 
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
def save_play_queue(
    self,
    song_ids: list[str],
    current_song_id: str | None = None,
    position: int | None = None,
) -> PlayQueue:
    """Saves a new play queue for the authenticated user.

    Args:
        song_ids: A list with all the songs to add to the queue.
        current_song_id: The ID of the current playing song.
        position: A position in milliseconds of where the current song
            playback it at.

    Returns:
        An object that contains all the info of the new
            saved play queue.
    """

    self.api.json_request(
        "savePlayQueue",
        {"id": song_ids, "current": current_song_id, "position": position},
    )

    # Fake the song structure given by in the API.
    songs = []
    for song_id in song_ids:
        songs.append({"id": song_id})

    return PlayQueue(self.subsonic, songs, current_song_id, position)

update_bookmark(song_or_video_id, position, comment=None)

Updates a bookmark for the authenticated user.

Parameters:

Name Type Description Default
song_or_video_id str

The ID of the song or video to update its bookmark.

 required
position int

A position in milliseconds to be indicated with the song or video.

 required
comment str | None

A comment to be attached with the song or video.

 None

Returns: An object that contains all the info of the new created bookmark.

Source code in .venv/lib/python3.11/site-packages/knuckles/_bookmarks.py 
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
def update_bookmark(
    self, song_or_video_id: str, position: int, comment: str | None = None
) -> Bookmark:
    """Updates a bookmark for the authenticated user.

    Args:
        song_or_video_id: The ID of the song or video to update its
            bookmark.
        position: A position in milliseconds to be indicated with the song
            or video.
        comment: A comment to be attached with the song or video.
    Returns:
        An object that contains all the info of the new created
            bookmark.
    """

    return self.create_bookmark(song_or_video_id, position, comment)