muziqa

Analyze your music collection and generate interesting charts using command-line:

Top artists by track count
Tracks by decade
Tracks by year, with a 5-year rolling average of mean tracks per artist
Tracks by country (optional, see below)
Tracks by genre (optional, see below)

muziqa chart

Also create MP3 playlist using Anthropic Claude LLM. The generated playlist is an MP3 file of your songs, picked by AI, per your prompt. Example:

$ muziqa Music --playlist "Playlist of rock tunes where lead guitar is as close as possible to the picking style of Mark Knopfler. Max 1 hour. Max one song per artist." --playlist-output mark.mp3

Install

Linux / Mac:

$ pipx install muziqa

Windows (PowerShell; NOTE: untested):

winget install Python.Python.3   # if Python not already installed
pip install pipx
pipx ensurepath                  # restart terminal after this
pipx install muziqa

Windows + --playlist: also install ffmpeg: winget install ffmpeg

Usage

No API keys, no accounts, no streaming service — just point muziqa to a folder of music files:

$ muziqa /path/to/music

Reads tags from all supported files in the folder and subfolders, and saves two charts:

muziqa.png — top artists + tracks by decade
muziqa_years.png — tracks by year with rolling average

Supported formats: MP3, FLAC, WAV, M4A, OGG

Country and genre charts

$ muziqa /path/to/music --country
$ muziqa /path/to/music --genre
$ muziqa /path/to/music --country --genre

Looks up each artist's country of origin and genre from MusicBrainz and saves additional charts:

muziqa_country.png — tracks by country
muziqa_genre.png — tracks by genre

muziqa chart

Note: The first run with --country or --genre queries MusicBrainz for every unique artist at 1 request/second (required by their API). For a large collection this can take a bit of time. Using both flags together does not double the time — data is fetched in a single pass. Results are cached in muziqa_mb_cache.json so subsequent runs are instant.

Note on "Unknown" genre: This means MusicBrainz either didn't find the artist or has no community-submitted genre tags for them. It does not affect the rest of the chart.

All options

Option	Description
`DIR`	Directory of music files to analyze
`--flat`	Search only the given folder, not subfolders
`--strict`	Skip songs tagged or named as remasters, plus genre `Classical`
`--country`	Fetch artist countries from MusicBrainz and plot by country
`--genre`	Fetch artist genres from MusicBrainz and plot by genre
`--output FILE`	Output image filename (default: `muziqa.png`)
`--top N`	Number of top entries to show (default: 20)
`-playlist DESC`	Create a playlist MP3 matching the given description (requires ANTHROPIC_API_KEY and ffmpeg)
`--playlist-output FILE`	Output file for playlist (default: playlist.mp3)
`--model MODEL`	Claude model for --playlist (default: claude-sonnet-4-6). Tip: use 'llm-models -p Anthropic' to list available models --> github.com/ljbuturovic/llm-models

Examples

$ muziqa ~/Music
$ muziqa ~/Music --flat
$ muziqa ~/Music --country --genre
$ muziqa ~/Music --top 30 --output top30.png

Metadata

Release files for muziqa 1.1.4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for muziqa 1.1.4
File	Size	Uploaded	Provenance
muziqa-1.1.4.tar.gz	13.9 kB	Oct 10, 2026	Without provenance	Details

Built distribution (wheel)

Table of built distributions (wheels) for muziqa 1.1.4
File	Interpreter	ABI	Platform	Reset
muziqa-1.1.4-py3-none-any.whl 14.1 kB Oct 10, 2026 Without provenance	Python 3	none	any	Details

Total release size: 28.0 kB

Release files / muziqa-1.1.4.tar.gz

Download URL	muziqa-1.1.4.tar.gz
Size	13.9 kB
Tags	Source
SHA-256 checksum How to use checksums	`9aede2627f4844c857aadead9c921aa5f24b125f98037631d1f1c085cfb091e7`
BLAKE2b-256 checksum How to use checksums	`e8b3deb0d080258e97d2808402c9ed14ca4e7fa42e5233e691e756def9ee0e63`
Upload date	Oct 10, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.8.4`

Release files / muziqa-1.1.4-py3-none-any.whl

Download URL	muziqa-1.1.4-py3-none-any.whl
Size	14.1 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`72d016ab53c02bf03821d11ccce220ce713352caf9a03fad258d3aa9086843f5`
BLAKE2b-256 checksum How to use checksums	`ae711c64e876122da1f952272cb1594d1aad3e40a8f4a97166084a99693b28b3`
Upload date	Oct 10, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.8.4`

Security for muziqa 1.1.4

Report project as malware

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.