Skip to main content

Generate covers collage from albums listened by a lastfm user.

Project description

lastfm_cg : lastfm collage generator

Codacy Badge Build Status codecov

Generate covers collage from albums listened by a lastfm user.

This utility needs a valid config file with your lastfm API keys (get them at in ~/.config/lastfm_cg/config.ini (the config file will be created at first launch, you can also see config_sample.ini for an example). You can also use the --API_KEY and --API_SECRET argument to set your lastfm API key.

It also caches the image files downloaded thanks to the requests-cache library. If you don't want the script to create an sqlite file in your ~/.local/share/lastfm_cg/ directory, you will have to launch the script with the -d/--disable_cache flag.

A twitter bot and a mastodon bot are also available in the bot_lastfm_cg folder. You can see them in action on my own Twitter and Mastodon accounts.

Some systemd service are also available in the systemd-service directory to run the lastfm_cg script at a given time. You will have to change them to match your configuration, more specifically the WorkingDirectory and ExecStart directive.


  • pylast
  • numpy
  • pillow
  • requests
  • requests-cache
  • tqdm


Classic installation :

pip install lastfm_cg

If you are an Archlinux user, you can install the AUR package lastfm_cg-git.

Run from source

First method (installing the lastfm_cg package)

git clone
cd lastfm_cg
python install
lastfm_cg -h

Second method (installing the lastfm_cg package with pipenv)

git clone
cd lastfm_cg
pipenv install '-e .'
pipenv run lastfm_cg -h


Show the help and the available options.

lastfm_cg -h
usage: lastfm_cg [-h] [--debug] [--timeframe TIMEFRAME] [--rows ROWS]
                 [--columns COLUMNS] [--username USERNAME] [-d] [--top100]
                 [--API_KEY API_KEY] [--API_SECRET API_SECRET]
                 [--output_filename OUTPUT_FILENAME]

Create lastfm album collage for one or several lastfm users.

optional arguments:
  -h, --help            show this help message and exit
  --debug               Display debugging information
  --timeframe TIMEFRAME, -t TIMEFRAME
                        Timeframe (Accepted values : 7day, 1month, 3month,
                        6month, 12month, overall. Default : 7day).
  --rows ROWS, -r ROWS  Number of rows (Default : 5).
  --columns COLUMNS, -c COLUMNS
                        Number of columns (Default : number of rows).
  --username USERNAME, -u USERNAME
                        Usernames to extract, separated by comma.
  -d, --disable_cache   Disable the cache
  --top100              Create a top 100 image. Will override columns/rows.
  --API_KEY API_KEY     Lastfm API key (optional)
                        Lastfm API secret (optional)
  --output_filename OUTPUT_FILENAME
                        Output filename (optional, example: output.png)

Generate a collage for the user USER of the size 5x5 for the last 7 days (default values).

lastfm_cg -u USER
lastfm_cg -u USER -t 7day -r 5

Generate a collage for the user USER of the size 10x8 for the last year.

lastfm_cg -u USER -t 12month -r 10 -c 8

Generate a top 100 collage for the user USER for all its listening history.

lastfm_cg -u USER --top100 -t overall

Generate collages for the users USER and USER2 of the size 3x30 for all their listening history.

lastfm_cg -u USER,USER2 -t overall -r 3 -c 30
lastfm_cg --username USER,USER2 --rows 3 --columns 30 --timeframe overall

Sample results

5 rows x 8 columns

top 100

Systemd service

You will have to change the command executed with the systemd service (ExecStart option) and the working directory (WorkingDirectory option).

cp systemd-service/* ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable --now lastfm_cg_weekly.timer

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

lastfm_cg-1.6.0.tar.gz (7.9 kB view hashes)

Uploaded source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page