Metadata-Version: 2.4
Name: scrobbles
Version: 0.1.0
Summary: Fetch, export, and visualize Last.fm listening data — plus create Spotify playlists from your top albums
Project-URL: Homepage, https://github.com/saforem2/scrobbles
Project-URL: Repository, https://github.com/saforem2/scrobbles
Project-URL: Issues, https://github.com/saforem2/scrobbles/issues
Author-email: Sam Foreman <saforem2@gmail.com>
License: MIT
License-File: LICENSE
Keywords: audioscrobbler,last.fm,lastfm,music,scrobble,spotify
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Multimedia :: Sound/Audio
Requires-Python: >=3.12
Requires-Dist: pylast>=7.0.2
Requires-Dist: spotipy>=2.26.0
Description-Content-Type: text/markdown

# scrobbles

Fetch, export, and visualize [Last.fm](https://www.last.fm/) listening data — plus create Spotify playlists from your top albums.

## Setup

### Prerequisites

- Python 3.12+
- [uv](https://docs.astral.sh/uv/) (recommended) or pip

### Install

```bash
pip install scrobbles
# or
uv add scrobbles
```

#### From source

```bash
git clone https://github.com/saforem2/scrobbles.git
cd lastfm
uv sync
```

### Environment Variables

#### Last.fm

Get API credentials at <https://www.last.fm/api/account>.

```bash
export LASTFM_API_KEY="..."
export LASTFM_API_SECRET="..."
export LASTFM_USERNAME="..."
export LASTFM_PASSWORD="..."
```

#### Spotify (optional — only needed for playlist creation)

1. Create an app at <https://developer.spotify.com/dashboard>
2. Add `http://127.0.0.1:8888/callback` as a Redirect URI in your app settings
3. Export your credentials:

```bash
export SPOTIFY_CLIENT_ID="..."       # or SPOTIPY_CLIENT_ID
export SPOTIFY_CLIENT_SECRET="..."   # or SPOTIPY_CLIENT_SECRET
export SPOTIPY_REDIRECT_URI="http://127.0.0.1:8888/callback"
```

Either `SPOTIFY_*` or `SPOTIPY_*` naming works — the library maps them automatically.

## Usage

### CLI

```bash
# Via entry point (after install)
scrobbles top-albums overall --limit 25
scrobbles top-albums 2024
scrobbles dashboard

# Via main.py (development)
uv run python main.py top-albums overall --limit 25
uv run python main.py top-albums 2024
uv run python main.py top-albums last_month

# Export top albums to JSON
uv run python main.py dump-albums 2024 --limit 100

# Generate the HTML dashboard from existing JSON files
uv run python main.py dashboard

# Create Spotify playlists from all top100-YYYY.json files
uv run python main.py spotify-playlists --dry-run
uv run python main.py spotify-playlists --skip 2020 2021
```

### Python API

```python
import scrobbles

# Recent tracks & now playing
scrobbles.get_recent_tracks("username", 10)
print(scrobbles.get_now_playing("username"))

# Top albums — predefined periods
scrobbles.print_top_albums("username", period="7day", limit=20)

# Top albums — arbitrary date ranges
scrobbles.print_top_albums("username", period="2024")       # full year
scrobbles.print_top_albums("username", period="2024-06")    # single month
scrobbles.print_top_albums("username", period="last_week")

# Export to JSON
scrobbles.dump_top_albums("username", period="2024", limit=100)

# Generate interactive HTML dashboard
from scrobbles.albums import build_dashboard
build_dashboard()  # reads data/albums/top100-*.json → data/albums/index.html

# Spotify: create a playlist from any album list
from scrobbles.spotify import create_playlist_from_albums
albums = [{"artist": "Radiohead", "album": "OK Computer", "plays": 50}]
create_playlist_from_albums(albums, "My Playlist", dry_run=True)

# Spotify: bulk-create yearly playlists
from scrobbles.spotify import create_all_playlists
create_all_playlists(dry_run=True)
```

### Supported Period Strings

| Period | Description |
|---|---|
| `overall` | All time |
| `7day`, `1month`, `3month`, `6month`, `12month` | Rolling windows |
| `today`, `yesterday`, `last_week`, `last_month`, `last_year` | Calendar-relative |
| `2024` | Full calendar year |
| `2024-06` | Single month |
| `2024-06-15` | Single day |

## Project Structure

```
lastfm/
├── src/scrobbles/
│   ├── __init__.py      # Network setup, track utils, re-exports
│   ├── albums.py        # Top albums: fetch, format, export, dashboard
│   ├── cli.py           # CLI entry point
│   └── spotify.py       # Spotify playlist creation
├── data/albums/         # Generated JSON + HTML dashboard
│   ├── top100-YYYY.json
│   └── index.html
├── main.py              # Thin shim (calls scrobbles.cli:main)
├── pyproject.toml
└── README.md
```

## Publishing

```bash
# Bump version
uv version --bump patch

# Build
uv build

# Publish to PyPI
uv publish
```
