Scrobble Duplicator

A CLI tool to copy Last.fm scrobble data from one user to another.

Prerequisites

• Node.js 18.0.0 or higher
• pnpm (managed via corepack)
• Last.fm API key

Setup

1. Enable corepack (if not already enabled):

   corepack enable

2. Install dependencies:

   pnpm install

3. Get a Last.fm API key:

   • Visit https://www.last.fm/api/account/create
   • Create an application to get your API key

4. Set up environment variables:

   cp .env.example .env
   # Edit .env and add your Last.fm API key

Development

Build the project:

pnpm build

Run in development mode:

pnpm dev [command] [options]

Run the built CLI:

pnpm start [command] [options]

Usage

Set your API key

You can provide your Last.fm API key in three ways:

1. .env file (recommended):

   cp .env.example .env
   # Edit .env and set your API credentials:
   # LASTFM_API_KEY=your-api-key-here
   # LASTFM_API_SECRET=your-api-secret-here (required for authentication)

2. Environment variable:

   export LASTFM_API_KEY="your-api-key-here"

3. Command line option:

   scrobble-duplicator copy --api-key "your-api-key-here" --api-secret "your-api-secret-here" [other options]

Authentication

The app uses Last.fm's authentication system to securely copy scrobbles to your account. When you run a command that requires authentication (copy, browse, or watch), the app will:

1. Get an authentication token from Last.fm
2. Open your browser to authorize the application
3. Exchange the token for a session key after you authorize

After successful authentication, the app will display your session credentials. You can add these to your .env file to skip the authentication flow in future runs:

LASTFM_SESSION_KEY=your-session-key-here
LASTFM_USERNAME=your-username-here

Note: You need both an API key AND API secret for authentication. The API secret is required to generate secure signatures for authenticated requests.

Commands

Copy scrobbles (simple)

scrobble-duplicator copy --source SOURCE_USERNAME

Copy a limited number of recent scrobbles from source user to your authenticated account.

Options:

• -s, --source <username>: Source Last.fm username to copy from (required)
• -k, --api-key <key>: Last.fm API key (optional if set via environment)
• --api-secret <secret>: Last.fm API secret (required for authentication)
• -d, --dry-run: Show what would be copied without actually copying
• --limit <number>: Limit number of scrobbles to copy (default: 100)

Browse and copy scrobbles

scrobble-duplicator browse --source SOURCE_USERNAME

Browse through recent scrobbles with pagination and select a starting point. Copies all scrobbles from the selected one to the most recent to your authenticated account.

Options:

• -s, --source <username>: Source Last.fm username to copy from (required)
• -k, --api-key <key>: Last.fm API key (optional if set via environment)
• --api-secret <secret>: Last.fm API secret (required for authentication)
• -d, --dry-run: Show what would be copied without actually copying

Watch and copy in real-time

scrobble-duplicator watch --source SOURCE_USERNAME

Continuously monitor the source user for new scrobbles and copy them to your authenticated account in real-time.

Options:

• -s, --source <username>: Source Last.fm username to copy from (required)
• -k, --api-key <key>: Last.fm API key (optional if set via environment)
• --api-secret <secret>: Last.fm API secret (required for authentication)
• -d, --dry-run: Show what would be copied without actually copying
• -i, --interval <seconds>: Check interval in seconds (default: 30)

Validate user

scrobble-duplicator validate --username USERNAME

Options:

• -u, --username <username>: Last.fm username to validate (required)
• -k, --api-key <key>: Last.fm API key (optional if set via environment)

Examples

# Validate a user exists
scrobble-duplicator validate --username alice

# Simple copy - copy recent 50 scrobbles (dry run)
scrobble-duplicator copy --source alice --limit 50 --dry-run

# Browse and select - interactive selection of starting point
scrobble-duplicator browse --source alice --dry-run

# Watch mode - monitor for new scrobbles every 60 seconds
scrobble-duplicator watch --source alice --interval 60

# Watch mode with dry run - see what would be copied without actually copying
scrobble-duplicator watch --source alice --dry-run --interval 30

Development Scripts

• pnpm build - Build TypeScript to JavaScript
• pnpm dev - Run in development mode with tsx
• pnpm test - Run tests with vitest
• pnpm test:watch - Run tests in watch mode
• pnpm lint - Run ESLint
• pnpm lint:fix - Run ESLint with auto-fix
• pnpm format - Format code with Prettier
• pnpm clean - Remove build artifacts

Project Structure

src/
├── cli.ts          # CLI entry point and command definitions
├── index.ts        # Main ScrobbleDuplicator class
└── types/          # TypeScript type definitions (future)

License

MIT