# antisocial-scrobble

i made this wordpress plugin because im a snowflake that suffers from chronic not-invented-here syndrome. it lets you scrobble your music with album cover support and generates monthly album collages.

## installation

- throw the plugin into `wp-content/plugins/`
- activate it in the wordpress admin

## usage

### scrobbling

there's a REST API endpoint to scrobble your songs.

**endpoint:** `POST /wp-json/image-scrobble/v1/scrobble`

**parameters:**

- `song_name` (required)
- `author` (required)
- `album_name` (optional)
- `cover_url` (required if `album_name` isn't provided)
- `length_seconds` (optional)

**authentication:**

you need to include an `Authorization` header: `Bearer YOUR_AUTH_KEY`.

the `AUTH_KEY` is generated when you activate the plugin. you can find it or change it under `settings > image scrobble` in the wordpress admin.

**example:**

```bash
curl -X POST 'https://yourwebsite.com/wp-json/image-scrobble/v1/scrobble' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer YOUR_AUTH_KEY' \
-d '{
    "song_name": "Song Title",
    "author": "Artist Name",
    "album_name": "Album Title",
    "cover_url": "https://example.com/cover.jpg",
    "length_seconds": 240
}'
```

### generating album collage

you can generate a collage of your top albums for any month.

**endpoint:** `GET /wp-json/top-albums/v1/last-month`

**parameters:**

- `month` (optional)
- `year` (optional)
- `overwrite` (optional, default `false`)

if you don't provide `month` and `year`, it defaults to last month.

**example:**

```bash
curl -X GET 'https://yourwebsite.com/wp-json/top-albums/v1/last-month?month=9&year=2023'
```

this returns the collage image. if you want to force regenerate it (maybe you added more scrobbles), set `overwrite=true`.

### notes

- the collage ignores some blacklisted artists. you can change that in the code if you care (`$this->blacklisted_artists`).
- the plugin might break in unexpected ways. use at your own risk.
