Metadata-Version: 2.4
Name: lastfm-url-scrobbler
Version: 0.1.0
Summary: Scrobble tracks, full albums, artist top tracks, or tag charts directly from Last.fm URLs
License: MIT License
        
        Copyright (c) 2026 lorelai@linux.com
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Repository, https://github.com/1orelai/lastfm-url-scrobbler
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pylast>=5.0.0
Requires-Dist: requests>=2.28.0
Requires-Dist: beautifulsoup4>=4.11.0
Dynamic: license-file

# Last.fm URL Scrobbler

Scrobble tracks to Last.fm directly from any Last.fm URL (track, album, artist, or tag).

## Features

- **URL Parsing:** Works with tracks, full albums, artist top tracks, user pages, and tag charts.
- **Custom Timestamps:** Set custom start dates and times in the past or future (e.g., `"2024-05-20 14:30"`).
- **Dry Run:** Preview fetched tracklists and calculated timestamps without submitting scrobbles.

## Prerequisites
- Python 3.8+
- A Last.fm account

## 1. Installation

```bash
pip install git+https://github.com/1orelai/lastfm-url-scrobbler.git
```

This installs two commands, `lastfm-url-scrobbler` and `get-session-key`, onto your `PATH`.

## 2. Set Up Last.fm API Credentials

1. Create a free API application on the [Last.fm API account page](https://www.last.fm/api/account/create).
2. Log in and submit the form (e.g., Application Name: `URLScrobbler`).
3. Copy your **API Key** and **Shared Secret**.

Export them in your terminal:

```bash
export LASTFM_API_KEY="your_api_key_here"
export LASTFM_API_SECRET="your_shared_secret_here"
```

## 3. Authenticate (One-Time)

Generate a write-enabled session key:

```bash
get-session-key
```

1. This opens an authorization URL in your browser.
2. Click **Yes, Allow Access**.
3. Return to the terminal and press **Enter**.
4. Copy the printed session key and export it:

```bash
export LASTFM_SESSION_KEY="your_retrieved_session_key"
```

> **Tip:** Add all three `export` commands to your `~/.zshrc` or `~/.bashrc` so they persist across terminal sessions.

## 4. Usage

```bash
lastfm-url-scrobbler "https://www.last.fm/music/Magazine/Real+Life"
```

### Options

| Flag | Description | Default |
|------|-------------|---------|
| `--dry-run` | Preview tracks and timestamps without submitting scrobbles | `False` |
| `--gap SECONDS` | Gap between tracks, in seconds | `5` |
| `--start DATE` | Start time, e.g. `"2024-05-20 14:30"` or `"2024-05-20"` | Current time |

### Examples

Scrobble a single track:
```bash
lastfm-url-scrobbler "https://www.last.fm/music/The+Beatles/_/Blackbird"
```

Scrobble an artist's top tracks:
```bash
lastfm-url-scrobbler "https://www.last.fm/music/Joni+Mitchell/+tracks"
```

Scrobble an album with a custom start date:
```bash
lastfm-url-scrobbler "https://www.last.fm/music/The+Stooges/Fun+House" --start "2024-05-20 14:30"
```

Preview without sending (dry run):
```bash
lastfm-url-scrobbler "https://www.last.fm/tag/classic+rock" --dry-run
```

## Development

To work on the tool locally instead of installing from GitHub:

```bash
git clone https://github.com/1orelai/lastfm-url-scrobbler.git
cd lastfm-url-scrobbler
pip install -e .
```
The `-e` (editable) install links the commands to your working copy, so changes take effect immediately.
