Library Usage#

The library has two object classes:

  1. Scrobble : Represents a single scrobbles/listen.

  2. ScrobbleLog : Represents a sequence/log of scrobbles/listens.

Read and Parse#

You can use from_lastfmstats() to read JSON/CSV downloads from lastfmstats to create a ScrobbleLog instance. Optionally, you can set a timezone using IANA strings.

In [1]: import memoryfm as mfm

In [2]: sclog = mfm.from_lastfmstats("lastfmstats-demo.csv", file_type="csv", tz="Asia/Kolkata")
---------------------------------------------------------------------------
FileNotFoundError                         Traceback (most recent call last)
Cell In[2], line 1
----> 1 sclog = mfm.from_lastfmstats("lastfmstats-demo.csv", file_type="csv", tz="Asia/Kolkata")

File ~/checkouts/readthedocs.org/user_builds/memoryfm/envs/stable/lib/python3.10/site-packages/memoryfm/io/lastfmstats.py:66, in from_lastfmstats(file, file_type, tz)
     64     data = load_json(file)
     65 elif file_type == "csv":
---> 66     data = load_csv(file)
     67 else:
     68     raise InvalidDataError('Only "json" or "csv" allowed as "file_type"')

File ~/checkouts/readthedocs.org/user_builds/memoryfm/envs/stable/lib/python3.10/site-packages/memoryfm/io/_loaders.py:50, in load_csv(file)
     48     fp = file
     49 elif isinstance(file, PathLike):
---> 50     fp = open(file, "r")
     51 else:
     52     raise FileNotFoundError

FileNotFoundError: [Errno 2] No such file or directory: 'lastfmstats-demo.csv'

See also

See from_lastfm_api() to read scrobbling history using last.fm API, and from_spotify() and from_spotify_zip() for reading Spotify listening history.

Head and Tail#

Like pandas DataFrames, memory.fm ScrobbleLog also have analogous methods: ScrobbleLog.head() and ScrobbleLog.tail().

If no argument is passed, the first (head) or last (tail) 5 scrobbles are extracted.

In [3]: print(sclog.tail())
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
Cell In[3], line 1
----> 1 print(sclog.tail())

NameError: name 'sclog' is not defined

Slicing#

If you are familiar with pandas, the slicing works exactly like pd.DataFrame.iloc. Like most slicing in Python, index starts with 0. The start bound is included, while the end bound is excluded.

In [4]: print(sclog[6:9])
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
Cell In[4], line 1
----> 1 print(sclog[6:9])

NameError: name 'sclog' is not defined

When start or end is omitted, the the corresponding bound doesn’t apply. So if you omit end, all scrobbles from start are included.

In [5]: print(sclog[16:])
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
Cell In[5], line 1
----> 1 print(sclog[16:])

NameError: name 'sclog' is not defined

Filter by Dates#

You can filter a ScrobbleLog by dates using the method ScrobbleLog.filter_by_date(). You may pass the time alongside the date. The end date is included by default.

In [6]: print(sclog.filter_by_date("2025-09-12 10 PM", end="2025-09-13 10:40 AM"))
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
Cell In[6], line 1
----> 1 print(sclog.filter_by_date("2025-09-12 10 PM", end="2025-09-13 10:40 AM"))

NameError: name 'sclog' is not defined

If you’d like to exclude the end date, pass include_end = False to the method.

In [7]: print(sclog.filter_by_date(start="2025-09-12 10 PM", end="2025-09-13", include_end = False))
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
Cell In[7], line 1
----> 1 print(sclog.filter_by_date(start="2025-09-12 10 PM", end="2025-09-13", include_end = False))

NameError: name 'sclog' is not defined

Top Charts#

Using the method ScrobbleLog.top_charts(), you can obtain top n tracks/artists/albums from a ScrobbleLog. The method returns a pandas Series, with name: Scrobbles.

In [8]: print(sclog.top_charts(kind="album").to_markdown())
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
Cell In[8], line 1
----> 1 print(sclog.top_charts(kind="album").to_markdown())

NameError: name 'sclog' is not defined