Skip to content

Media Annotation

MediaAnnotation(api, subsonic)

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

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

remove_rating(song_id)

Remove the rating entry of a song.

Parameters:

Name Type Description Default
song_id str

The ID of the song which entry should be removed.

 required

Returns:

Type Description
Subsonic

The Subsonic object where this method was called to allow method chaining.
Source code in .venv/lib/python3.11/site-packages/knuckles/_media_annotation.py 
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
def remove_rating(self, song_id: str) -> "Subsonic":
    """Remove the rating entry of a song.

    Args:
        song_id: The ID of the song which entry should
            be removed.

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

    self.api.json_request("setRating", {"id": song_id, "rating": 0})

    return self.subsonic

scrobble(song_id, time, submission=True)

Scrobble (register) that some song have been locally played or is being played.

Parameters:

Name Type Description Default
song_id list[str]

The ID of the song to scrobble.

 required
time list[datetime]

How many times in second the song has been listened.

 required
submission bool

If true it will be registered that the song was played, if false the song will be scrobble as now playing.

 True

Returns:

Type Description
Subsonic

The Subsonic object where this method was called to allow method chaining.
Source code in .venv/lib/python3.11/site-packages/knuckles/_media_annotation.py 
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
def scrobble(
    self, song_id: list[str], time: list[datetime], submission: bool = True
) -> "Subsonic":
    """Scrobble (register) that some song have been locally played or
    is being played.

    Args:
        song_id: The ID of the song to scrobble.
        time: How many times in second the song has been listened.
        submission: If true it will be registered that the song **was
            played**, if false the song will be scrobble as
            **now playing**.

    Returns:
        The Subsonic object where this method was called to allow
            method chaining.
    """
    self.api.json_request(
        "scrobble",
        # Multiply by 1000 because the API uses
        # milliseconds instead of seconds for UNIX time
        {
            "id": song_id,
            "time": [int(seconds.timestamp()) * 1000 for seconds in time],
            "submission": submission,
        },
    )

    return self.subsonic

set_rating(song_id, rating)

The the rating of a song.

Parameters:

Name Type Description Default
song_id str

The ID of the song to set its rating.

 required
rating int

The rating between 1 and 5 (inclusive) to set the rating of the song to.

 required

Raises:

Type Description
InvalidRatingNumber

Raised when a number that is not between 1 and 5 (inclusive) has been pass in into the rating parameter.

Returns:

Type Description
Subsonic

The Subsonic object where this method was called to allow method chaining.
Source code in .venv/lib/python3.11/site-packages/knuckles/_media_annotation.py 
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
def set_rating(self, song_id: str, rating: int) -> "Subsonic":
    """The the rating of a song.

    Args:
        song_id: The ID of the song to set its rating.
        rating: The rating between 1 and 5 (inclusive) to set
            the rating of the song to.

    Raises:
        InvalidRatingNumber: Raised when a number that is not
            between 1 and 5 (inclusive) has been pass in into
            the `rating` parameter.

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

    if rating not in range(1, 6):
        raise InvalidRatingNumber(
            (
                "Invalid rating number, "
                + "only numbers between 1 and 5 (inclusive) are allowed"
            )
        )

    self.api.json_request("setRating", {"id": song_id, "rating": rating})

    return self.subsonic

star_album(album_id)

Star an album from the server.

Parameters:

Name Type Description Default
album_id str

The ID of the album to star.

 required

Returns:

Type Description
Subsonic

The Subsonic object where this method was called to allow method chaining.
Source code in .venv/lib/python3.11/site-packages/knuckles/_media_annotation.py 
36
37
38
39
40
41
42
43
44
45
46
47
48
49
def star_album(self, album_id: str) -> "Subsonic":
    """Star an album from the server.

    Args:
        album_id: The ID of the album to star.

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

    self.api.json_request("star", {"albumId": album_id})

    return self.subsonic

star_artist(artist_id)

Star an artist from the server.

Parameters:

Name Type Description Default
artist_id str

The ID of the artist to star.

 required

Returns:

Type Description
Subsonic

The Subsonic object where this method was called to allow method chaining.
Source code in .venv/lib/python3.11/site-packages/knuckles/_media_annotation.py 
51
52
53
54
55
56
57
58
59
60
61
62
63
64
def star_artist(self, artist_id: str) -> "Subsonic":
    """Star an artist from the server.

    Args:
        artist_id: The ID of the artist to star.

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

    self.api.json_request("star", {"artistId": artist_id})

    return self.subsonic

star_song(song_id)

Star a song from the server.

Parameters:

Name Type Description Default
song_id str

The ID of the song to star.

 required

Returns:

Type Description
Subsonic

The Subsonic object where this method was called to allow method chaining.
Source code in .venv/lib/python3.11/site-packages/knuckles/_media_annotation.py 
21
22
23
24
25
26
27
28
29
30
31
32
33
34
def star_song(self, song_id: str) -> "Subsonic":
    """Star a song from the server.

    Args:
        song_id: The ID of the song to star.

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

    self.api.json_request("star", {"id": song_id})

    return self.subsonic

unstar_album(album_id)

Unstar an album from the server.

Parameters:

Name Type Description Default
album_id str

The ID of the album to unstar.

 required

Returns:

Type Description
Subsonic

The Subsonic object where this method was called to allow method chaining.
Source code in .venv/lib/python3.11/site-packages/knuckles/_media_annotation.py 
81
82
83
84
85
86
87
88
89
90
91
92
93
94
def unstar_album(self, album_id: str) -> "Subsonic":
    """Unstar an album from the server.

    Args:
        album_id: The ID of the album to unstar.

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

    self.api.json_request("unstar", {"albumId": album_id})

    return self.subsonic

unstar_artist(artist_id)

Unstar an artist from the server.

Parameters:

Name Type Description Default
artist_id str

The ID of the artist to unstar.

 required

Returns:

Type Description
Subsonic

The Subsonic object where this method was called to allow method chaining.
Source code in .venv/lib/python3.11/site-packages/knuckles/_media_annotation.py 
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
def unstar_artist(self, artist_id: str) -> "Subsonic":
    """Unstar an artist from the server.

    Args:
        artist_id: The ID of the artist to unstar.

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

    self.api.json_request("unstar", {"artistId": artist_id})

    return self.subsonic

unstar_song(song_id)

Unstar a song from the server.

Parameters:

Name Type Description Default
song_id str

The ID of the song to unstar.

 required

Returns:

Type Description
Subsonic

The Subsonic object where this method was called to allow method chaining.
Source code in .venv/lib/python3.11/site-packages/knuckles/_media_annotation.py 
66
67
68
69
70
71
72
73
74
75
76
77
78
79
def unstar_song(self, song_id: str) -> "Subsonic":
    """Unstar a song from the server.

    Args:
        song_id: The ID of the song to unstar.

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

    self.api.json_request("unstar", {"id": song_id})

    return self.subsonic